diff --git a/GB_get_direct_access.md b/GB_get_direct_access.md index 6a07472..a16a399 100644 --- a/GB_get_direct_access.md +++ b/GB_get_direct_access.md @@ -17,14 +17,45 @@ typedef enum { } GB_direct_access_t; ``` -void *GB_get_direct_access([[GB_gameboy_t]] *gb, [[GB_direct_access_t]] access, size_t *size, uint16_t *bank); +void *GB_get_direct_access([[GB_gameboy_t]] *gb, GB_direct_access_t access, size_t *size, uint16_t *bank); In `gb.h` ## Description -TBD +Returns a pointer to various memory regions of the emulated instance that can be freely read and modified. It will also return the size of that memory region via the `size` output argument, and on applicable regions, the currently mapped bank as well via the `bank` output argument. You may set `bank` and/or `size` to `NULL` if you don't require them. + +The regions supported by this function are: + + * `GB_DIRECT_ACCESS_ROM`: Returns a pointer to the ROM and its size. Will return the ROM bank number mapped at `$4000-$7fff`. + * `GB_DIRECT_ACCESS_ROM0`: Similar to `GB_DIRECT_ACCESS_ROM`, but will return the ROM bank number mapped at `$0000-$3fff` instead. (Useful when emulating MBCs that can bank-switch within this region, such as MMM01) + * `GB_DIRECT_ACCESS_RAM`: Returns a pointer to the RAM and its size (either `0x8000` bytes for CGB and newer, or `0x2000` for older models). Will return the RAM bank number mapped at `$d000-$dfff`. + * `GB_DIRECT_ACCESS_CART_RAM`: Returns a pointer to the cartridge RAM and its size. Will return the number of the currently mapped cartridge RAM bank. + * `GB_DIRECT_ACCESS_VRAM`: Returns a pointer to VRAM and its size (either `0x4000` bytes for CGB and newer, or `0x2000` for older models). Will return the currently mapped VRAM bank. + * `GB_DIRECT_ACCESS_HRAM`: Returns a pointer to HRAM and its size (always `0x7f`). + * `GB_DIRECT_ACCESS_IO`: Returns a pointer to MMIO (see [[Notes|GB_get_direct_access#Notes]]) and its size (always `0x80`). + * `GB_DIRECT_ACCESS_BOOTROM`: Returns a pointer to the boot ROM and its size (either `0x900` bytes for CGB and newer, or `0x100` for older models). Bytes `0x100` to `0x1ff` are not used in this buffer. + * `GB_DIRECT_ACCESS_OAM`: Returns a pointer to OAM and its size (always `0xa0`). + * `GB_DIRECT_ACCESS_BGP`: Returns a pointer to background palette RAM, and its size (always `0x40`). + * `GB_DIRECT_ACCESS_OBP`: Returns a pointer to object palette RAM, and its size (always `0x40`). + * `GB_DIRECT_ACCESS_IE`: Returns a pointer to IE register, and its size (always `1`). ## Thread Safety `GB_get_direct_access` is thread-safe and can be called from any thread and context. + +## Notes + +The pointers returned by this function may become invalid upon calling a function that loads a different ROM (e.g. [[GB_load_rom]]) or by [[switching the emulated model|GB_switch_model_and_reset]]. Make sure to not retain pointers to these buffers after they stop being valid. + +Some MMIO registers will not appear in the `GB_DIRECT_ACCESS_IO` region in the same way they actually appear in the emulator instance's memory, and writes to this region might not always have the desired effect. It is recommended to use [[GB_read_memory]] and [[GB_write_memory]] to access this region, when possible. + +Writes to `GB_DIRECT_ACCESS_IE` can have unexpected results and needs to be avoided. + +Writes to the `GB_DIRECT_ACCESS_BGP` and `GB_DIRECT_ACCESS_OBP` regions might not have an immediate visual effect. + +## See Also + +* [[GB_read_memory]] +* [[GB_safe_read_memory]] +* [[GB_write_memory]] \ No newline at end of file