gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit a8c9f4770196accc5d759a22ea15759b7ca8a351 parent 484fff9209cd22bcf863a033269e3d9f0dbcaf1f Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Fri, 20 Nov 2020 18:34:11 +0300 Merge pull request #99 from bbbbbr/develop_docs_work_1 Docs: Lots of doxygen formatted API header updates Diffstat:
| M | gbdk-lib/include/bcd.h | 6 | ++++++ |
| M | gbdk-lib/include/gb/bgb_emu.h | 100 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | gbdk-lib/include/gb/cgb.h | 103 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- |
| M | gbdk-lib/include/gb/console.h | 19 | +++++++++++++++---- |
| M | gbdk-lib/include/gb/crash_handler.h | 18 | ++++++++++++++++++ |
| M | gbdk-lib/include/gb/drawing.h | 91 | +++++++++++++++++++++++++++++++++++++++++++++++++++++-------------------------- |
| M | gbdk-lib/include/gb/far_ptr.h | 63 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | gbdk-lib/include/gb/font.h | 36 | ++++++++++++++++++++++++++---------- |
| M | gbdk-lib/include/gb/gb.h | 13 | ++++++++----- |
| M | gbdk-lib/include/gb/malloc.h | 7 | ++++--- |
| M | gbdk-lib/include/gb/sgb.h | 2 | ++ |
| M | gbdk-lib/include/stdio.h | 5 | +++++ |
| M | gbdk-lib/include/time.h | 3 | +-- |
13 files changed, 399 insertions(+), 67 deletions(-)
diff --git a/gbdk-lib/include/bcd.h b/gbdk-lib/include/bcd.h @@ -3,6 +3,12 @@ #include <asm/types.h> +/** @file bcd.h + Support for working with BCD (Binary Coded Decimal) + + See the example BCD project for additional details. +*/ + // macro for creating BCD constants #define BCD_HEX(v) ((BCD)(v)) diff --git a/gbdk-lib/include/gb/bgb_emu.h b/gbdk-lib/include/gb/bgb_emu.h @@ -1,9 +1,47 @@ +/** @file gb/bgb_emu.h + + Debug window logging and profiling support for the BGB emulator. + + Also see the `bgb_debug` example project included with gbdk. + + See the BGB Manual for more information + ("expressions, breakpoint conditions, and debug messages") + http://bgb.bircd.org/manual.html#expressions + +*/ #ifndef __BGB_EMU_INCLUDE #define __BGB_EMU_INCLUDE +/// \cond DOXYGEN_DO_NOT_DOCUMENT #define BGB_ADD_DOLLARD(A) BGB_ADD_DOLLARD1 (A) #define BGB_ADD_DOLLARD1(A) A##00$ +/// \endcond DOXYGEN_DO_NOT_DOCUMENT + +/** Macro to display a message in the BGB emulator debug message window + + @param message_text Quoted text string to display in the debug message window + + The following special parameters can be + used when bracketed with "%" characters. + \li CPU registers: AF, BC, DE, HL, SP, PC, B, C, D, + E, H, L, A, ZERO, ZF, Z, CARRY, CY, IME, ALLREGS + \li Other state values: ROMBANK, XRAMBANK, SRAMBANK, + WRAMBANK, VRAMBANK, TOTALCLKS, LASTCLKS, CLKS2VBLANK + + Example: print a message along with the currently active ROM bank. + \code{.c} + BGB_MESSAGE("Current ROM Bank is: %ROMBANK%"); + \endcode + + + See the BGB Manual for more information + ("expressions, breakpoint conditions, and debug messages") + http://bgb.bircd.org/manual.html#expressions + + @see BGB_PROFILE_BEGIN(), BGB_PROFILE_END() + */ #define BGB_MESSAGE(message_text) BGB_MESSAGE1(BGB_ADD_DOLLARD(__LINE__), message_text) +/// \cond DOXYGEN_DO_NOT_DOCUMENT #define BGB_MESSAGE1(lbl, message_text) \ __asm \ ld d, d \ @@ -17,8 +55,27 @@ __endasm #define BGB_HASH # #define BGB_ADD_HASH(x) x #define BGB_MAKE_LABEL(a) BGB_ADD_HASH(BGB_HASH)a +/// \endcond DOXYGEN_DO_NOT_DOCUMENT + +/** Macro to display a sprintf formatted message in the BGB emulator debug message window + + @param buf Pointer to a globally defined char buffer + @param ... VA Args list of sprintf parameters + + To avoid buffer overflows __buf__ must be large + enough to store the entire printed message. + Example: + \code{.c} + char mybuf[100]; // should be globally defined + + BGB_MESSAGE_FMT(mybuf, "An integer:%d, a string: %s", 12345, "hello bgb") + \endcode + + @see BGB_MESSAGE() + */ #define BGB_MESSAGE_FMT(buf, ...) sprintf(buf, __VA_ARGS__);BGB_MESSAGE2(BGB_ADD_DOLLARD(__LINE__), BGB_MAKE_LABEL(_##buf)); +/// \cond DOXYGEN_DO_NOT_DOCUMENT #define BGB_MESSAGE2(lbl, buf) \ __asm \ ld d, d \ @@ -32,11 +89,54 @@ __endasm #define BGB_STR(A) #A #define BGB_CONCAT(A,B) BGB_STR(A:B) +/// \endcond DOXYGEN_DO_NOT_DOCUMENT + +/** Macro to __Start__ a profiling block for the BGB emulator + + @param MSG Quoted text string to display in the debug message window + + To complete the profiling block and print + the result call @ref BGB_PROFILE_END. + + @see BGB_PROFILE_END(), BGB_MESSAGE() + */ #define BGB_PROFILE_BEGIN(MSG) BGB_MESSAGE(BGB_CONCAT(MSG,%ZEROCLKS%)); +/** Macro to __End__ a profiling block and print the results in the BGB emulator debug message window + + @param MSG Quoted text string to display in the + debug message window along with the result + + This should only be called after a previous call + to @ref BGB_PROFILE_BEGIN() + + The results are in BGB clock units, which are + "1 nop in [CGB] doublespeed mode". + + So when running in Normal Speed mode (i.e. non-CGB doublespeed) + the printed result should be __divided by 2__ to get the actual + ellapsed cycle count. + + If running in CB Double Speed mode use the below call instead, + it correctly compensates for the speed difference. In this + scenario, the result does __not need to be divided by 2__ to + get the ellapsed cycle count. + \code{.c} + BGB_MESSAGE("NOP TIME: %-4+LASTCLKS%"); + \endcode + + @see BGB_PROFILE_BEGIN(), BGB_MESSAGE() + */ #define BGB_PROFILE_END(MSG) BGB_MESSAGE(BGB_CONCAT(MSG,%-8+LASTCLKS%)); #define BGB_TEXT(MSG) BGB_MESSAGE(BGB_STR(MSG)) +/** Display preset debug information in the BGB debug messages window. + + This function is equivalent to: + \code{.c} + BGB_MESSAGE("PROFILE,%(SP+$0)%,%(SP+$1)%,%A%,%TOTALCLKS%,%ROMBANK%,%WRAMBANK%"); + \endcode +*/ void BGB_profiler_message(); static void * __BGB_PROFILER_INIT = &BGB_profiler_message; diff --git a/gbdk-lib/include/gb/cgb.h b/gbdk-lib/include/gb/cgb.h @@ -1,11 +1,31 @@ /** @file gb/cgb.h - Support for Color GameBoy. + Support for the Color GameBoy (CGB). + + __Enabling CGB features__ + + To unlock and use CGB features and registers you need to + change byte 0143h in the cartridge header. Otherwise, the CGB + will operate in monochrome "Non CGB" compatibility mode. + \li Use a value of __80h__ for games that support CGB and monochrome gameboys + \n (with Lcc: __-Wm-yc__, or makebin directly: __-yc__) + \li Use a value of __C0h__ for CGB only games. + \n (with Lcc: __-Wm-yC__, or makebin directly: __-yC__) + + See the Pan Docs for more information CGB features. */ #ifndef _CGB_H #define _CGB_H -/** Macro to create a palette entry out of the color components. +/** Macro to create a CGB palette color entry out of the color components. + + @param r Red Component, range 0 - 31 (31 brightest) + @param g Green Component, range 0 - 31 (31 brightest) + @param b Blue Component, range 0 - 31 (31 brightest) + + The resulting format is BGR 15bpp. + + @see set_bkg_palette(), set_sprite_palette() */ #define RGB(r, g, b) \ ((((UINT16)(b) & 0x1f) << 10) | (((UINT16)(g) & 0x1f) << 5) | (((UINT16)(r) & 0x1f) << 0)) @@ -34,49 +54,106 @@ #define RGB_ORANGE RGB(30, 20, 0) #define RGB_TEAL RGB(15, 15, 0) -/** Set bkg palette(s). +/** Set CGB background palette(s). + + @param first_palette Index of the first palette to write (0-7) + @param nb_palettes Number of palettes to write (1-8, max depends on first_palette) + @param rgb_data Pointer to source palette data + + Writes __nb_palettes__ to background palette data starting + at __first_palette__, Palette data is sourced from __rgb_data__. + + \li Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry. + \li Each color (4 per palette) is packed as BGR 15bpp format (1:5:5:5, MSBit [15] is unused). + \li Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest. + + @see RGB(), set_bkg_palette_entry() */ void set_bkg_palette(UINT8 first_palette, UINT8 nb_palettes, UINT16 *rgb_data) NONBANKED; -/** Set sprite palette(s). +/** Set CGB sprite palette(s). + + @param first_palette Index of the first palette to write (0-7) + @param nb_palettes Number of palettes to write (1-8, max depends on first_palette) + @param rgb_data Pointer to source palette data + + Writes __nb_palettes__ to sprite palette data starting + at __first_palette__, Palette data is sourced from __rgb_data__. + + \li Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry. + \li Each color (4 per palette) is packed as BGR 15bpp format (1:5:5:5, MSBit [15] is unused). + \li Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest. + + @see RGB(), set_sprite_palette_entry() */ void set_sprite_palette(UINT8 first_palette, UINT8 nb_palettes, UINT16 *rgb_data) NONBANKED; -/** Set a bkg palette entry. +/** Sets a single color in the specified CGB background palette. + + @param palette Index of the palette to modify (0-7) + @param entry Index of color in palette to modify (0-3) + @param rgb_data New color data in BGR 15bpp format. + + @see set_bkg_palette(), RGB() */ + void set_bkg_palette_entry(UINT8 palette, UINT8 entry, UINT16 rgb_data); -/** Set a sprite palette entry. +/** Sets a single color in the specified CGB sprite palette. + + @param palette Index of the palette to modify (0-7) + @param entry Index of color in palette to modify (0-3) + @param rgb_data New color data in BGR 15bpp format. + + @see set_sprite_palette(), RGB() */ void set_sprite_palette_entry(UINT8 palette, UINT8 entry, UINT16 rgb_data); -/** Set CPU speed to slow operation. - Make sure interrupts are disabled before call. +/** Set CPU speed to slow (Normal Speed) operation. + + Interrupts are temporarily disabled and then re-enabled during this call. - @see cpu_fast + In this mode the CGB operates at the same speed as the DMG/Pocket/SGB models. + + \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function. + + @see cpu_fast() */ void cpu_slow(void); -/** Set CPU speed to fast operation. - Make sure interrupts are disabled before call. +/** Set CPU speed to fast (CGB Double Speed) operation. + + On startup the CGB operates in Normal Speed Mode and can be switched + into Double speed mode (faster processing but also higher power consumption). + See the Pan Docs for more information about which hardware features + operate faster and which remain at Normal Speed. - @see cpu_slow + \li Interrupts are temporarily disabled and then re-enabled during this call. + \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function. + + @see cpu_slow(), _cpu */ void cpu_fast(void); -/** Set defaults compatible with normal GameBoy. +/** Set defaults compatible with the normal GameBoy models. + + The default/first CGB palettes for sprites and backgrounds are + set to a similar default appearance as on the DMG/Pocket/SGB models. + (White, Light Gray, Dark Gray, Black) + + \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function. */ void cgb_compatibility(void); diff --git a/gbdk-lib/include/gb/console.h b/gbdk-lib/include/gb/console.h @@ -1,27 +1,38 @@ /** @file gb/console.h Console functions that work like Turbo C's. - Note that the font is 8x8, making the screen 20x18 characters. + + The font is 8x8, making the screen 20x18 characters. */ #ifndef _CONSOLE_H #define _CONSOLE_H #include <types.h> -/** Move the cursor to an absolute position. +/** Move the cursor to an absolute position at __x, y__. + + __x__ and __y__ have units of tiles (8 pixels per unit) + @see setchar() */ void gotoxy(UINT8 x, UINT8 y); -/** Get the current X position of the cursor. +/** Returns the current X position of the cursor. + + @see gotoxy() */ UINT8 posx(void); -/** Get the current Y position of the cursor. +/** Returns the current Y position of the cursor. + + @see gotoxy() */ UINT8 posy(void); /** Writes out a single character at the current cursor position. + Does not update the cursor or interpret the character. + + @see gotoxy() */ void setchar(char c); diff --git a/gbdk-lib/include/gb/crash_handler.h b/gbdk-lib/include/gb/crash_handler.h @@ -1,6 +1,24 @@ +/** @file gb/crash_handler.h + + When crash_handler.h is included, a crash dump screen + will be displayed if the CPU executes uninitalized + memory (with a value of 0xFF, the opcode for RST 38). + A handler is installed for RST 38 that calls + @ref __HandleCrash(). + + \code{.c} + #include <gb/crash_handler.h> + \endcode + + Also see the `crash` example project included with gbdk. +*/ #ifndef __CRASH_HEANDLER_INCLUDE #define __CRASH_HEANDLER_INCLUDE +/** Display the crash dump screen. + + See the intro for this file for more details. +*/ void __HandleCrash(); static void * __CRASH_HEANDLER_INIT = &__HandleCrash; diff --git a/gbdk-lib/include/gb/drawing.h b/gbdk-lib/include/gb/drawing.h @@ -44,71 +44,102 @@ #include <types.h> -/** Print the string 'str' with no interpretation */ +/** Print the string 'str' with no interpretation + @see gotogxy() +*/ void gprint(char *str) NONBANKED; -/** Print the long number 'number' in radix 'radix'. signed_value should - be set to SIGNED or UNSIGNED depending on whether the number is signed - or not */ +/** Print 16 bit __number__ in __radix__ (base) in the default font at the current text position. + + @param number number to print + @param radix radix (base) to print with + @param signed_value should be set to SIGNED or UNSIGNED depending on whether the number is signed or not + + The current position is advanced by the numer of characters printed. + @see gotogxy() +*/ void gprintln(INT16 number, INT8 radix, INT8 signed_value); -/** Print the number 'number' as in 'gprintln' */ -void +/** Print 8 bit __number__ in __radix__ (base) in the default font at the current text position. + + @see gprintln(), gotogxy() +*/ +void gprintn(INT8 number, INT8 radix, INT8 signed_value); -/** Print the formatted string 'fmt' with arguments '...' */ -INT8 +/** Print the string and arguments given by __fmt__ with arguments __...__ + + @param fmt The format string as per printf + @param ... params + + Currently supported: + \li \%c (character) + \li \%u (int) + \li \%d (INT8) + \li \%o (INT8 as octal) + \li \%x (INT8 as hex) + \li \%s (string) + + @return Returns the number of items printed, or -1 if there was an error. + @see gotogxy() +*/ +INT8 gprintf(char *fmt,...) NONBANKED; -/** Old style plot - try plot_point() */ +/** Old style plot - try @ref plot_point() */ void plot(UINT8 x, UINT8 y, UINT8 colour, UINT8 mode); -/** Plot a point in the current drawing mode and colour at (x,y) */ -void +/** Plot a point in the current drawing mode and colour at __x,y__ */ +void plot_point(UINT8 x, UINT8 y); -/** Exchanges the tile on screen at x,y with the tile pointed by src, original tile +/** Exchanges the tile on screen at x,y with the tile pointed by src, original tile is saved in dst. Both src and dst may be NULL - saving or copying to screen is not performed in this case. */ void switch_data(UINT8 x, UINT8 y, unsigned char *src, unsigned char *dst) NONBANKED; -/** Ditto */ -void +/** Draw a full screen image at __data__ */ +void draw_image(unsigned char *data) NONBANKED; -/** Draw a line in the current drawing mode and colour from (x1,y1) to (x2,y2) */ -void +/** Draw a line in the current drawing mode and colour from __x1,y1__ to __x2,y2__ */ +void line(UINT8 x1, UINT8 y1, UINT8 x2, UINT8 y2); -/** Draw a box (rectangle) with corners (x1,y1) and (x2,y2) using fill mode - 'style' (one of NOFILL or FILL */ -void +/** Draw a box (rectangle) with corners __x1,y1__ and __x2,y2__ using fill mode + __style__ (one of NOFILL or FILL) */ +void box(UINT8 x1, UINT8 y1, UINT8 x2, UINT8 y2, UINT8 style); -/** Draw a circle with centre at (x,y) and radius 'radius'. 'style' sets - the fill mode */ -void +/** Draw a circle with centre at __x,y__ and __radius__ using fill mode + __style__ (one of NOFILL or FILL)*/ +void circle(UINT8 x, UINT8 y, UINT8 radius, UINT8 style); -/** Returns the current colour of the pixel at (x,y) */ -UINT8 +/** Returns the current colour of the pixel at __x,y__ */ +UINT8 getpix(UINT8 x, UINT8 y); -/** Prints the character 'chr' in the default font at the current position */ -void +/** Prints the character __chr__ in the default font at the current text position. + + The current position is advanced by 1 after the character is printed. + @see gotogxy() */ +void wrtchr(char chr); -/** Sets the current text position to (x,y). Note that x and y have units - of cells (8 pixels) */ +/** Sets the current text position to __x,y__. + + Note: __x__ and __y__ have units of tiles (8 pixels per unit) + @see wrtchr() */ void gotogxy(UINT8 x, UINT8 y); -/** Set the current foreground colour (for pixels), background colour, and - draw mode */ +/** Set the current __foreground__ colour (for pixels), __background__ colour, and + draw __mode__ */ void color(UINT8 forecolor, UINT8 backcolor, UINT8 mode); #endif /* __DRAWING_H */ diff --git a/gbdk-lib/include/gb/far_ptr.h b/gbdk-lib/include/gb/far_ptr.h @@ -1,16 +1,72 @@ +/** @file gb/far_ptr.h + + Far pointers include a segment (bank) selector so they are + able to point to addresses (functions or data) outside + of the current bank (unlike normal pointers which are not + bank-aware). + + See the `banks_farptr` example project included with gbdk. + + @todo Add link to a discussion about banking (such as, how to assign code and variables to banks) +*/ + #ifndef __FAR_PTR_H_INCLUDE #define __FAR_PTR_H_INCLUDE +/** Macro to obtain a far pointer at compile-time + @param ofs Memory address within the given Segment (Bank) + @param seg Segment (Bank) number + + @returns A far pointer (type @ref FAR_PTR) +*/ #define TO_FAR_PTR(ofs, seg) (((FAR_PTR)seg << 16) | (FAR_PTR)ofs) +/** Macro to get the Segment (Bank) number of a far pointer + @param ptr A far pointer (type @ref FAR_PTR) + + @returns Segment (Bank) of the far pointer (type unsigned int) +*/ #define FAR_SEG(ptr) (((union __far_ptr *)&ptr)->segofs.seg) + +/** Macro to get the Offset (address) of a far pointer + @param ptr A far pointer (type @ref FAR_PTR) + + @returns Offset (address) of the far pointer (type void *) +*/ #define FAR_OFS(ptr) (((union __far_ptr *)&ptr)->segofs.ofs) + #define FAR_FUNC(ptr, typ) ((typ)(((union __far_ptr *)&ptr)->segfn.fn)) +/** Macro to call a function at far pointer __ptr__ of type __typ__ + @param ptr Far pointer of a function to call (type @ref FAR_PTR) + @param typ Type to cast the function far pointer to. + @param ... VA Args list of parameters for the function + + __type__ should match the definition of the function being called. For example: + \code{.c} + // A function in bank 2 + #pragma bank 2 + int some_function(int param1, int param2) __banked { return 1; }; + + ... + // Code elsewhere, such as unbanked main() + // This type declaration should match the above function + typedef int (*some_function_t)(int, int) __banked; + + // Using FAR_CALL() with the above as *ptr*, *typ*, and two parameters. + result = FAR_CALL(some_function, some_function_t, 100, 50); + \endcode + + @returns Value returned by the function (if present) +*/ #define FAR_CALL(ptr, typ, ...) (__call_banked_ptr=ptr,((typ)(&__call__banked))(__VA_ARGS__)) +/** Type for storing a FAR_PTR +*/ typedef unsigned long FAR_PTR; +/** Union for working with members of a FAR_PTR +*/ union __far_ptr { FAR_PTR ptr; struct { @@ -28,6 +84,13 @@ extern volatile void * __call_banked_addr; extern volatile unsigned char __call_banked_bank; void __call__banked(); + +/** Obtain a far pointer at runtime + @param ofs Memory address within the given Segment (Bank) + @param seg Segment (Bank) number + + @returns A far pointer (type @ref FAR_PTR) +*/ long to_far_ptr(void* ofs, int seg); #endif diff --git a/gbdk-lib/include/gb/font.h b/gbdk-lib/include/gb/font.h @@ -18,41 +18,57 @@ /* See gb.h/M_NO_SCROLL and gb.h/M_NO_INTERP */ -/** font_t is a handle to a font loaded by font_load() */ +/** font_t is a handle to a font loaded by font_load(). + It can be used with @ref font_set() */ typedef UINT16 font_t; + +/*! \defgroup gbdk_fonts List of gbdk fonts + @{ +*/ + /** The default fonts */ extern UINT8 font_spect[], font_italic[], font_ibm[], font_min[]; /** Backwards compatible font */ extern UINT8 font_ibm_fixed[]; -/** Init the font system. - Should be called first. + /*! @} End of gbdk_fonts */ + + +/** Initializes the font system. + Should be called before other font functions. */ void font_init(void) NONBANKED; -/** Load the font 'font'. - Sets the current font to the newly loaded font. +/** Load a font and set it as the current font. + @param font Pointer to a font to load (usually a gbdk font) + + @return Handle to the loaded font, which can be used with @ref font_set() + @see font_init(), font_set(), gbdk_fonts */ font_t font_load( void *font ) NONBANKED; -/** Set the current font to 'font_handle', which was returned - from an earlier font_load(). +/** Set the current font. + @param font_handle handle of a font returned by @ref font_load() + @return The previously used font handle. + @see font_init(), font_load() */ font_t font_set( font_t font_handle ) NONBANKED; /* Use mode() and color() to set the font modes and colours */ -/** Internal representation of a font. +/** Internal representation of a font. What a font_t really is */ typedef struct sfont_handle mfont_handle; typedef struct sfont_handle *pmfont_handle; +/** Font handle structure +*/ struct sfont_handle { - UINT8 first_tile; /* First tile used */ - void *font; /* Pointer to the base of the font */ + UINT8 first_tile; /**< First tile used for font */ + void *font; /**< Pointer to the base of the font */ }; #endif /* __FONT_H */ diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -277,7 +277,10 @@ void mode(UINT8 m) NONBANKED; */ UINT8 get_mode(void) NONBANKED __preserves_regs(b, c); -/** GB type (GB, PGB, CGB) */ +/** GB CPU type + + @see DMG_TYPE, MGB_TYPE, CGB_TYPE, cpu_fast(), cpu_slow() +*/ extern UINT8 _cpu; /** Hardware Model: Original GB or Super GB. @see _cpu @@ -342,12 +345,12 @@ extern volatile UINT8 _io_out; /** Tracks current active ROM bank @see SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5() - This variable is updated automatically when you call SWITCH_ROM_MBC1 or + This variable is updated automatically when you call SWITCH_ROM_MBC1 or SWITCH_ROM_MBC5, or call a BANKED function. */ __REG _current_bank; -/** Makes MBC1 and other compatible MBCs to switch the active ROM bank +/** Makes MBC1 and other compatible MBCs switch the active ROM bank @param b ROM bank to switch to */ #define SWITCH_ROM_MBC1(b) \ @@ -375,7 +378,7 @@ __REG _current_bank; #define SWITCH_4_32_MODE_MBC1 \ *(unsigned char *)0x6000 = 0x01 -/** Makes MBC5 to switch the active ROM bank; only 4M roms are supported, @see SWITCH_ROM_MBC5_8M() +/** Makes MBC5 switch to the active ROM bank; only 4M roms are supported, @see SWITCH_ROM_MBC5_8M() @param b ROM bank to switch to Note the order used here. Writing the other way around on a MBC1 always selects bank 1 @@ -470,7 +473,7 @@ typedef struct { @param joypads pointer to joypads_t structure to be initialized Only required for @ref joypad_ex, not required for calls to regular @ref joypad() - Returns number of joypads avaliable + @returns number of joypads avaliable @see joypad_ex(), joypads_t */ UINT8 joypad_init(UINT8 npads, joypads_t * joypads); diff --git a/gbdk-lib/include/gb/malloc.h b/gbdk-lib/include/gb/malloc.h @@ -1,7 +1,8 @@ /** @file gb/malloc.h - Header for a simple implementation of malloc(). This library - may currently be broken. + Header for a simple implementation of malloc(). + + @todo: This library may currently be broken. */ #ifndef __SYS_MALLOC_H #define __SYS_MALLOC_H @@ -15,7 +16,7 @@ #define MALLOC_FREE 1 #define MALLOC_USED 2 -/** Magic number of a header. Gives us some chance of +/** Magic number of a header. Gives us some chance of surviving if the list is corrupted*/ #define MALLOC_MAGIC 123 diff --git a/gbdk-lib/include/gb/sgb.h b/gbdk-lib/include/gb/sgb.h @@ -1,5 +1,7 @@ /** @file gb/sgb.h Super Gameboy definitions. + + See the example SGB project for additional details. */ #ifndef _SGB_H #define _SGB_H diff --git a/gbdk-lib/include/stdio.h b/gbdk-lib/include/stdio.h @@ -1,5 +1,10 @@ /** @file stdio.h Basic file/console input output functions. + + Including stdio.h will use a large number of the + background tiles for font characters. If stdio.h + is not included then that space will be available + for use with other tiles instead. */ #ifndef STDIO_INCLUDE #define STDIO_INCLUDE diff --git a/gbdk-lib/include/time.h b/gbdk-lib/include/time.h @@ -12,14 +12,13 @@ typedef UINT16 time_t; /** Returns an approximation of processor time used by the program in Clocks - The value returned is the CPU time used so far as a @ref clock_t. + The value returned is the CPU time (ticks) used so far as a @ref clock_t. To get the number of seconds used, divide by @ref CLOCKS_PER_SEC. This is based on @ref sys_time, which will wrap around every ~18 minutes. (unsigned 16 bits = 65535 / 60 / 60 = 18.2) - @todo: Why is CLOCKS_PER_SEC 100 instead of 60 if clock() uses @ref sys_time which is updated once per VBL? @see sys_time, time() */ clock_t clock(void) NONBANKED;
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.