From 779ad2408cf97687878f816ddff2b04f22f5172d Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 25 Feb 2023 16:48:01 +0100 Subject: add developer documentation to ppusim/ppu interface --- src/.gitignore | 1 + src/ppu/consts.h | 4 ++-- src/ppu/internals.c | 9 ++++++--- src/ppu/internals.h | 6 ++++++ src/ppu/ppu.h | 17 ++++++++++------- src/ppu/types.h | 38 +++++++++++++++++++++++--------------- src/ppusim/mem.h | 1 + src/ppusim/pixel.h | 1 + src/ppusim/sim.h | 2 ++ src/ppusim/work.h | 9 ++++++++- src/readme.md | 22 ++++++++++++++++++++++ 11 files changed, 82 insertions(+), 28 deletions(-) create mode 100644 src/readme.md 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)| -- cgit v1.2.3