add developer documentation to ppusim/ppu interface

11 files changed, 82 insertions, 28 deletions

diff --git a/src/.gitignore b/src/.gitignore
index 67661d0..d8325cf 100644
--- a/src/.gitignore
+++ b/src/.gitignore
@@ -3,3 +3,4 @@ main.elf
 main.bin
 main
 main.exe
+static/
diff --git a/src/ppu/consts.h b/src/ppu/consts.h
index 0e8fba4..a27b7b7 100644
--- a/src/ppu/consts.h
+++ b/src/ppu/consts.h
@@ -18,9 +18,9 @@
 #define HH_PPU_SCREEN_WIDTH 320
 /** @brief screen height in pixels */
 #define HH_PPU_SCREEN_HEIGHT 240
-/** @brief amount of horizontal backgorund tiles on background canvas */
+/** @brief amount of horizontal background tiles on background canvas */
 #define HH_PPU_BG_CANVAS_TILES_H 40
-/** @brief amount of vertical backgorund tiles on background canvas */
+/** @brief amount of vertical background tiles on background canvas */
 #define HH_PPU_BG_CANVAS_TILES_V 30
 
 #include "ppu/types.h"
diff --git a/src/ppu/internals.c b/src/ppu/internals.c
index e4817f1..1c95a5a 100644
--- a/src/ppu/internals.c
+++ b/src/ppu/internals.c
@@ -4,9 +4,12 @@
 #include "ppu/internals.h"
 
 bool hh_ppu_vram_valid_address(hh_ppu_addr_t addr) {
-	#warning unimlemented 
-	(void) addr; // compiler bruh
-	return true;
+	if (addr >= HH_PPU_VRAM_TMM_OFFSET && addr <= HH_PPU_VRAM_TMM_OFFSET + HH_PPU_VRAM_TMM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_BAM_OFFSET && addr <= HH_PPU_VRAM_BAM_OFFSET + HH_PPU_VRAM_BAM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_FAM_OFFSET && addr <= HH_PPU_VRAM_FAM_OFFSET + HH_PPU_VRAM_FAM_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_PAL_OFFSET && addr <= HH_PPU_VRAM_PAL_OFFSET + HH_PPU_VRAM_PAL_SIZE) return true;
+	if (addr >= HH_PPU_VRAM_AUX_OFFSET && addr <= HH_PPU_VRAM_AUX_OFFSET + HH_PPU_VRAM_AUX_SIZE) return true;
+	return false;
 }
 
 void hh_ppu_vram_write(hh_s_ppu_vram_data data) {
diff --git a/src/ppu/internals.h b/src/ppu/internals.h
index 8f50c52..4a1726e 100644
--- a/src/ppu/internals.h
+++ b/src/ppu/internals.h
@@ -9,6 +9,7 @@
 /** @brief resize `in` to `upper downto lower` like in vhdl */
 #define HH_RESIZE(in, upper, lower) ((((hh_ppu_data_t)(in)) & (HH_MASK(upper+1-lower) << lower)) >> lower)
 
+/** @brief memory word(s) that can be placed into vram */
 typedef struct {
 	hh_ppu_addr_t offset;
 	hh_ppu_addr_t size;
@@ -22,9 +23,14 @@ void hh_ppu_vram_dwrite(hh_ppu_addr_t addr, hh_ppu_data_t data);
 /** @brief write data block into vram */
 void hh_ppu_vram_write(hh_s_ppu_vram_data data);
 
+/** @brief convert local background attribute memory entry to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_bam(hh_s_ppu_loc_bam_entry);
+/** @brief convert local foreground attribute memory entry to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_fam(hh_s_ppu_loc_fam_entry);
+/** @brief convert local AUX memory copy to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_aux(hh_s_ppu_loc_aux);
+/** @brief convert local sprite to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_sprite(const hh_ppu_loc_sprite_data_t);
+/** @brief convert local RGB color to PPU format */
 hh_s_ppu_vram_data hh_ppu_2nat_color(hh_ppu_rgb_color_t);
 
diff --git a/src/ppu/ppu.h b/src/ppu/ppu.h
index cab0e30..75d97c1 100644
--- a/src/ppu/ppu.h
+++ b/src/ppu/ppu.h
@@ -2,21 +2,24 @@
 
 #include "ppu/types.h"
 
+/** @brief vblank interrupt (game main loop) */
 void hh_ppu_vblank_interrupt();
+/** @brief initialize ppu interface */
 void hh_ppu_init();
+/** @brief deinitialize ppu interface */
 void hh_ppu_deinit();
 
-/* @brief update single foreground sprite */
+/** @brief update single foreground sprite */
 void hh_ppu_update_foreground(unsigned index, hh_s_ppu_loc_fam_entry e);
-/* @brief update single background sprite */
+/** @brief update single background sprite */
 void hh_ppu_update_background(unsigned index, hh_s_ppu_loc_bam_entry e);
-/* @brief update aux register */
+/** @brief update aux register */
 void hh_ppu_update_aux(hh_s_ppu_loc_aux aux);
-/* @brief update single sprite */
+/** @brief update single sprite */
 void hh_ppu_update_sprite(unsigned tilemap_index, const hh_s_ppu_loc_sprite sprite);
-/* @brief update entire palette table */
+/** @brief update entire palette table */
 void hh_ppu_update_palette_table(hh_ppu_loc_palette_table_t table);
-/* @brief update single palette */
+/** @brief update single palette */
 void hh_ppu_update_palette(unsigned palette_index, hh_ppu_loc_palette_data_t palette);
-/* @brief update single color in palette */
+/** @brief update single color in palette */
 void hh_ppu_update_color(unsigned palette_index, unsigned color_index, hh_ppu_rgb_color_t color);
diff --git a/src/ppu/types.h b/src/ppu/types.h
index 08bef13..fa776e5 100644
--- a/src/ppu/types.h
+++ b/src/ppu/types.h
@@ -5,38 +5,46 @@
 
 #include "ppu/consts.h"
 
+/** @brief PPU VRAM address */
 typedef uint16_t hh_ppu_addr_t;
+/** @brief PPU VRAM data word */
 typedef uint16_t hh_ppu_data_t;
 
+/** @brief local RGB color */
 typedef uint8_t hh_ppu_rgb_color_t[3];
 
+/** @brief local palette */
 typedef hh_ppu_rgb_color_t hh_ppu_loc_palette_data_t[HH_PPU_PALETTE_COLOR_COUNT];
+/** @brief local palette table */
 typedef hh_ppu_loc_palette_data_t hh_ppu_loc_palette_table_t[HH_PPU_PALETTE_COUNT];
 
+/** @brief local sprite */
 typedef uint8_t hh_ppu_loc_sprite_data_t[HH_PPU_SPRITE_WIDTH * HH_PPU_SPRITE_HEIGHT];
 typedef hh_ppu_loc_sprite_data_t hh_s_ppu_loc_sprite;
 
+/** @brief local background attribute memory entry */
 typedef struct {
-	bool horizontal_flip;
-	bool vertical_flip;
-	uint8_t palette_index;
-	uint8_t tilemap_index;
+	bool horizontal_flip; /** @brief flip sprite horizontally */
+	bool vertical_flip; /** @brief flip sprite vertically */
+	uint8_t palette_index; /** @brief index of palette to use */
+	uint8_t tilemap_index; /** @brief index of sprite to use */
 } hh_s_ppu_loc_bam_entry;
 
+/** @brief local foreground attribute memory entry */
 typedef struct {
-	bool horizontal_flip;
-	bool vertical_flip;
-	int32_t position_x;
-	int32_t position_y;
-	uint8_t palette_index;
-	uint8_t tilemap_index;
+	bool horizontal_flip; /** @brief flip sprite horizontally */
+	bool vertical_flip; /** @brief flip sprite vertically */
+	int32_t position_x; /** @brief horizontal position from left edge of sprite to left edge of screen (-16 to 320), relative to viewport */
+	int32_t position_y; /** @brief vertical position from top edge of sprite to top edge of screen (-16 to 240), relative to viewport */
+	uint8_t palette_index; /** @brief index of palette to use */
+	uint8_t tilemap_index; /** @brief index of sprite to use */
 } hh_s_ppu_loc_fam_entry;
 
+/** @brief local copy of auxiliary memory */
 typedef struct {
-	bool sysreset;
-	bool fg_fetch;
-	uint16_t bg_shift_x;
-	uint16_t bg_shift_y;
+	bool sysreset; /** @brief enable sysreset, self-resets */
+	bool fg_fetch; /** @brief enable foreground fetch, self-resets */
+	uint16_t bg_shift_x; /** @brief shift background canvas left (0 to 320) */
+	uint16_t bg_shift_y; /** @brief shift background canvas down (0 to 240) */
 } hh_s_ppu_loc_aux;
 
-typedef uint16_t hh_ppu_native_color_t;
diff --git a/src/ppusim/mem.h b/src/ppusim/mem.h
index 72f40be..bc36d98 100644
--- a/src/ppusim/mem.h
+++ b/src/ppusim/mem.h
@@ -1,4 +1,5 @@
 #include "ppu/types.h"
 
+/** @brief PPUSIM internal VRAM */
 extern hh_ppu_data_t *g_hh_ppusim_vram;
 
diff --git a/src/ppusim/pixel.h b/src/ppusim/pixel.h
index 475fe11..7b26ee6 100644
--- a/src/ppusim/pixel.h
+++ b/src/ppusim/pixel.h
@@ -2,5 +2,6 @@
 
 #include "ppusim/work.h"
 
+/** @brief calculate color for pixel (`x`,`y`), and put into `unsigned short s[3]` */
 void hh_ppusim_pixel(uint8_t* s, unsigned x, unsigned y);
 
diff --git a/src/ppusim/sim.h b/src/ppusim/sim.h
index e161746..73f4b23 100644
--- a/src/ppusim/sim.h
+++ b/src/ppusim/sim.h
@@ -1,4 +1,6 @@
 #pragma once
 
+/** @brief pixel-perfect upscale factor for PPUSIM */
 #define HH_PPUSIM_UPSCALE_FACTOR 3
+/** @brief max framerate for PPUSIM */
 #define HH_PPUSIM_FRAMERATE 60
diff --git a/src/ppusim/work.h b/src/ppusim/work.h
index c1a5148..6f72357 100644
--- a/src/ppusim/work.h
+++ b/src/ppusim/work.h
@@ -4,14 +4,21 @@
 
 #include "ppu/consts.h"
 
+/** @brief logical core count, used for multithreading in `hh_ppusim_draw_frame` */
 extern unsigned g_hh_ppusim_core_count;
+/** @brief thread handles, used for multithreading in `hh_ppusim_draw_frame` */
 extern pthread_t* g_hh_ppusim_threads;
 
+/** @brief ppusim color (24-bit RGB) */
 typedef uint8_t hh_s_ppusim_color[3];
+/** @brief ppusim screen scanline */
 typedef hh_s_ppusim_color hh_s_ppusim_scanline[HH_PPU_SCREEN_WIDTH];
+/** @brief ppusim complete screen buffer */
 typedef hh_s_ppusim_scanline hh_s_ppusim_screen[HH_PPU_SCREEN_HEIGHT];
 
-void* hh_ppusim_draw_thread(void*);
+/** @brief draw `core`'s work portion to `hh_s_ppusim_screen` */
+void* hh_ppusim_draw_thread(void* core);
 
+/** @brief spawn threads to draw frame, join threads and draw to `SDL_Renderer` */
 void hh_ppusim_draw_frame(SDL_Renderer*);
 
diff --git a/src/readme.md b/src/readme.md
new file mode 100644
index 0000000..bfbc6e9
--- /dev/null
+++ b/src/readme.md
@@ -0,0 +1,22 @@
+# src (game source files)
+
+- the game can be built for the stm32 with fpga, or for desktop (windows and
+  linux tested), by editing the `PLATFORM` variable in `makefile`
+- stm-specific sources should be in the stm32 folder (setup/configuration code
+  using HAL or FreeRTOS), or in `stm32.c` in any subfolder (when used as
+  interface implementation)
+- stm-specific sources should be declared in `stm32.mk`
+- desktop-specific sources should be declared in `ds.mk`
+- other source files (both platforms) should be declared in `makefile`
+- for small sections of platform specific code, `#ifdef` macro's can be used.
+  either `HH_TARGET_STM32` or `HH_TARGET_DESKTOP` is defined.
+
+## directory structure
+
+|name|description|
+|apu|APU interface functions|
+|lib|libraries (stm system headers, HAL, FreeRTOS)|
+|ppusim|PPU simulation code (desktop only)|
+|ppu|PPU interface functions|
+|static|static game assets (binary files)|
+|stm32|STM32 specific setup (HAL, FreeRTOS)|