gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 288e4aed83c90bdd2ad11e4f46bb20f93cb4dbe7 parent b788195f08410aa5aa576d49ae3d934c2f2c879e Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Wed, 4 Nov 2020 14:11:06 +0300 Merge pull request #74 from bbbbbr/develop_docs_inmainrepo_edits Docs: Update and add doxygen compatible header file comments (no functional source code edits) Diffstat:
| M | gbdk-lib/include/bcd.h | 39 | +++++++++++++++++++++++++++++++++++---- |
| M | gbdk-lib/include/ctype.h | 21 | +++++++++++++++++++++ |
| M | gbdk-lib/include/gb/gb.h | 106 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- |
| M | gbdk-lib/include/gb/sgb.h | 77 | +++++++++++++++++++++++++++++++++++++++++++++++------------------------------ |
| M | gbdk-lib/include/gbdk-lib.h | 2 | +- |
| M | gbdk-lib/include/rand.h | 38 | +++++++++++++++++++++++++++++--------- |
| M | gbdk-lib/include/stdio.h | 40 | ++++++++++++++++++++++++++-------------- |
| M | gbdk-lib/include/stdlib.h | 66 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- |
| M | gbdk-lib/include/string.h | 115 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------- |
| M | gbdk-lib/include/time.h | 24 | ++++++++++++++++++++---- |
10 files changed, 403 insertions(+), 125 deletions(-)
diff --git a/gbdk-lib/include/bcd.h b/gbdk-lib/include/bcd.h @@ -5,19 +5,50 @@ // macro for creating BCD constants #define BCD_HEX(v) ((BCD)(v)) + +/** Converts an integer value into BCD format + + A maximum of 8 digits may be used +*/ #define MAKE_BCD(v) BCD_HEX(0x ## v) typedef unsigned long BCD; -// converts into into BCD +/** Converts integer __i__ into BCD format (Binary Coded Decimal) + @param i Numeric value to convert + @param value Pointer to a BCD variable to store the converted result +*/ void uint2bcd(unsigned int i, BCD * value); -// adding BCD numbers: sour += value +/** Adds two numbers in BCD format: __sour__ += __value__ + @param sour Pointer to a BCD value to add to (and where the result is stored) + @param value Pointer to the BCD value to add to __sour__ +*/ void bcd_add(BCD * sour, const BCD * value); -// subtracting BCD numbers: sour -= value + +/** Subtracts two numbers in BCD format: __sour__ -= __value__ + @param sour Pointer to a BCD value to subtract from (and where the result is stored) + @param value Pointer to the BCD value to subtract from __sour__ +*/ void bcd_sub(BCD * sour, const BCD * value); -// convert the BCD number into asciiz string and return the length +/** Convert a BCD number into an asciiz (null terminated) string and return the length + @param bcd Pointer to BCD value to convert + @param tile_offset Optional per-character offset value to add (use 0 for none) + @param buffer Buffer to store the result in + + Returns: Length in characters (always 8) + + __buffer__ should be large enough to store the converted string + (9 bytes: 8 characters + 1 for terminator) + + There are a couple different ways to use __tile_offset__. + For example: + \li It can be the Index of the Font Tile '0' in VRAM to + allow the buffer to be used directly with @ref set_bkg_tiles. + \li It can also be set to the ascii value for character '0' + so that the buffer is a normal string that can be passed to @ref printf. +*/ UBYTE bcd2text(const BCD * bcd, UBYTE tile_offset, unsigned char * buffer); #endif diff --git a/gbdk-lib/include/ctype.h b/gbdk-lib/include/ctype.h @@ -6,24 +6,45 @@ #include <types.h> +/** Returns TRUE if the character __c__ is a letter (a-z, A-Z), otherwise FALSE + @param c Character to test +*/ BOOLEAN isalpha(char c); +/** Returns TRUE if the character __c__ is an uppercase letter (A-Z), otherwise FALSE + @param c Character to test +*/ BOOLEAN isupper(char c); +/** Returns TRUE if the character __c__ is a lowercase letter (a-z), otherwise FALSE + @param c Character to test +*/ BOOLEAN islower(char c); +/** Returns TRUE if the character __c__ is a digit (0-9), otherwise FALSE + @param c Character to test +*/ BOOLEAN isdigit(char c); +/** Returns TRUE if the character __c__ is a space (' '), tab (\\t), or newline (\\n) character, otherwise FALSE + @param c Character to test +*/ BOOLEAN isspace(char c); +/** Returns uppercase version of character __c__ if it is a letter (a-z), otherwise it returns the input value unchanged. + @param c Character to test +*/ char toupper(char c); +/** Returns lowercase version of character __c__ if it is a letter (A-Z), otherwise it returns the input value unchanged. + @param c Character to test +*/ char tolower(char c); diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -120,8 +120,9 @@ */ typedef void (*int_handler)(void) NONBANKED; -/** The remove functions will remove any interrupt - handler. A handler of NULL will cause bad things +/** The remove functions will remove any interrupt handler. + + A handler of NULL will cause bad things to happen if the given interrupt is enabled. Removes the VBL interrupt handler. @see add_VBL() @@ -138,8 +139,17 @@ void remove_LCD(int_handler h) NONBANKED; */ void remove_TIM(int_handler h) NONBANKED; -/** Removes the SIO interrupt handler. +/** Removes the Serial Link / SIO interrupt handler. @see add_SIO(), @see remove_VBL() + + The default SIO ISR gets installed automatically if + any of the standard SIO calls are used. These calls + include @ref add_SIO(), @ref remove_SIO(), + @ref send_byte(), @ref receive_byte(). + + The default SIO ISR cannot be removed once installed. + Only secondary chained SIO ISRs (added with @ref add_SIO() ) + can be removed. */ void remove_SIO(int_handler h) NONBANKED; @@ -149,21 +159,26 @@ void remove_SIO(int_handler h) NONBANKED; void remove_JOY(int_handler h) NONBANKED; /** Adds a V-blank interrupt handler. - The handler 'h' will be called whenever a V-blank - interrupt occurs. Up to 4 handlers may be added, - with the last added being called last. If the remove_VBL - function is to be called, only three may be added. - @see remove_VBL + + @param h The handler to be called whenever a V-blank + interrupt occurs. + + Up to 4 handlers may be added, with the last added being + called last. If the @ref remove_VBL function is to be called, + only three may be added. + + Note: The default VBL is installed automatically. */ void add_VBL(int_handler h) NONBANKED; /** Adds a LCD interrupt handler. + Called when the LCD interrupt occurs, which is normally when @ref LY_REG == @ref LYC_REG. From pan/k0Pa: There are various reasons for this interrupt to occur - as described by the STAT register ($FF40). One very + as described by the @ref STAT_REG register ($FF41). One very popular reason is to indicate to the user when the video hardware is about to redraw a given LCD line. This can be useful for dynamically controlling the @@ -185,18 +200,20 @@ void add_LCD(int_handler h) NONBANKED; */ void add_TIM(int_handler h) NONBANKED; -/** Adds a serial transmit complete interrupt handler. + +/** Adds a Serial Link transmit complete interrupt handler. From pan/k0Pa: This interrupt occurs when a serial transfer has completed on the game link port. - @see send_byte, receive_byte, add_VBL + @see send_byte, receive_byte(), add_VBL() @see set_interrupts() with SIO_IFLAG */ void add_SIO(int_handler h) NONBANKED; -/** Adds a pad tranisition interrupt handler. + +/** Adds a joypad button change interrupt handler. From pan/k0Pa: This interrupt occurs on a transition of any of the @@ -206,21 +223,42 @@ void add_SIO(int_handler h) NONBANKED; or more times for every button press and one or more times for every button release. - @see joypad + + + @see joypad() */ void add_JOY(int_handler h) NONBANKED; + /** Interrupt handler chain terminator that does __not__ wait for .STAT You must add this handler last in every interrupt handler chain if you want to change the default interrupt handler behaviour that waits for LCD controller mode to become 1 or 0 before return from the interrupt. + + Example: + \code{.c} + __critical { + add_SIO(nowait_int_handler); // Disable wait on VRAM state before returning from SIO interrupt + } + \endcode + @see wait_int_handler() */ void nowait_int_handler(void) NONBANKED; -/** Interrupt handler chain terminator that waits for .STAT and - returns in the BEGINNING of mode0 or mode1 ONLY + +/** Default Interrupt handler chain terminator that waits for + @see STAT_REG and __only__ returns at the BEGINNING of + either Mode 0 or Mode 1. + + Used by default at the end of interrupt chains to help + prevent graphical glitches. The glitches are caused when an + ISR interrupts a graphics operation in one mode but returns + in a different mode for which that graphics operation is not + allowed. + + @see nowait_int_handler() */ void wait_int_handler(void) NONBANKED; @@ -256,6 +294,8 @@ extern UINT8 _cpu; /** Global Time Counter in VBL periods (60Hz) Increments once per Frame + + Will wrap around every ~18 minutes (unsigned 16 bits = 65535 / 60 / 60 = 18.2) */ extern volatile UINT16 sys_time; @@ -263,18 +303,18 @@ extern volatile UINT16 sys_time; /** Serial Link: Send the byte in @ref _io_out out through the serial port - Make sure to add the ISR and enable interrupts for the + Make sure to enable interrupts for the Serial Link before trying to transfer data. - @see add_SIO() + @see add_SIO(), remove_SIO() @see set_interrupts() with @ref SIO_IFLAG */ void send_byte(void); /** Serial Link: Receive a byte from the serial port into @ref _io_in - Make sure to add the ISR and enable interrupts for the + Make sure to enable interrupts for the Serial Link before trying to transfer data. - @see add_SIO() + @see add_SIO(), remove_SIO() @see set_interrupts() with @ref SIO_IFLAG */ void receive_byte(void); @@ -325,7 +365,8 @@ extern volatile UINT8 _io_out; */ __REG _current_bank; -/** Forces MBC1 and compatible to switch the active ROM bank +/** Forces MBC1 and compatible to switch the active ROM bank + @param b Bank to switch to */ #define SWITCH_ROM_MBC1(b) \ _current_bank = (b), *(unsigned char *)0x2000 = (b) @@ -346,6 +387,7 @@ __REG _current_bank; *(unsigned char *)0x6000 = 0x01 /** Forces MBC5 to switch the active ROM bank; only 4M roms are supported, @see SWITCH_ROM_MBC5_8M() + Note the order used here. Writing the other way around on a MBC1 always selects bank 1 */ #define SWITCH_ROM_MBC5(b) \ @@ -355,6 +397,7 @@ __REG _current_bank; /** Forces MBC5 to switch the active ROM bank; active bank number is not tracked by _current_bank if you use this macro @see _current_bank + Note the order used here. Writing the other way around on a MBC1 always selects bank 1 */ #define SWITCH_ROM_MBC5_8M(b) \ @@ -1145,20 +1188,27 @@ void get_tiles(UINT8 x, /* ************************************************************ */ -/** Initializes window tile table with c - @param c Tile number + +/** Initializes the entire Window Tile Map with Tile Number __c__ + @param c Tile number to fill with + + Note: This function avoids writes during modes 2 & 3 */ void init_win(UINT8 c) NONBANKED __preserves_regs(b, c); -/** Initializes background tile table with c - @param c Tile number +/** Initializes the entire Background Tile Map with Tile Number __c__ + @param c Tile number to fill with + + Note: This function avoids writes during modes 2 & 3 */ void init_bkg(UINT8 c) NONBANKED __preserves_regs(b, c); -/** Fills the VRAM memory region s of size n with c - @param s Start address - @param c Value to fill with - @param n Size of memory region +/** Fills the VRAM memory region __s__ of size __n__ with Tile Number __c__ + @param s Start address in VRAM + @param c Tile number to fill with + @param n Size of memory region (in bytes) to fill + + Note: This function avoids writes during modes 2 & 3 */ void vmemset (void *s, UINT8 c, size_t n) NONBANKED __preserves_regs(b, c); diff --git a/gbdk-lib/include/gb/sgb.h b/gbdk-lib/include/gb/sgb.h @@ -4,40 +4,57 @@ #ifndef _SGB_H #define _SGB_H -#define SGB_PAL_01 0x00U -#define SGB_PAL_23 0x01U -#define SGB_PAL_03 0x02U -#define SGB_PAL_12 0x03U -#define SGB_ATTR_BLK 0x04U -#define SGB_ATTR_LIN 0x05U -#define SGB_ATTR_DIV 0x06U -#define SGB_ATTR_CHR 0x07U -#define SGB_SOUND 0x08U -#define SGB_SOU_TRN 0x09U -#define SGB_PAL_SET 0x0AU -#define SGB_PAL_TRN 0x0BU -#define SGB_ATRC_EN 0x0CU -#define SGB_TEST_EN 0x0DU -#define SGB_ICON_EN 0x0EU -#define SGB_DATA_SND 0x0FU -#define SGB_DATA_TRN 0x10U -#define SGB_MLT_REQ 0x11U -#define SGB_JUMP 0x12U -#define SGB_CHR_TRN 0x13U -#define SGB_PCT_TRN 0x14U -#define SGB_ATTR_TRN 0x15U -#define SGB_ATTR_SET 0x16U -#define SGB_MASK_EN 0x17U -#define SGB_OBJ_TRN 0x18U - - -/** Return a non-null value if running on Super GameBoy */ +#define SGB_PAL_01 0x00U /**< SGB Command: Set SGB Palettes 0 & 1 */ +#define SGB_PAL_23 0x01U /**< SGB Command: Set SGB Palettes 2 & 3 */ +#define SGB_PAL_03 0x02U /**< SGB Command: Set SGB Palettes 0 & 3 */ +#define SGB_PAL_12 0x03U /**< SGB Command: Set SGB Palettes 1 & 2 */ +#define SGB_ATTR_BLK 0x04U /**< SGB Command: Set color attributes for rectangular regions */ +#define SGB_ATTR_LIN 0x05U /**< SGB Command: Set color attributes for horizontal or vertical character lines */ +#define SGB_ATTR_DIV 0x06U /**< SGB Command: Split screen in half and assign separate color attribes to each side and the divider */ +#define SGB_ATTR_CHR 0x07U /**< SGB Command: Set color attributes for separate charactersSet SGB Palette 0,1 Data */ +#define SGB_SOUND 0x08U /**< SGB Command: Start and stop a internal sound effect, and sounds using internal tone data */ +#define SGB_SOU_TRN 0x09U /**< SGB Command: Transfer sound code or data to the SNES APU RAM */ +#define SGB_PAL_SET 0x0AU /**< SGB Command: Apply (previously transferred) SGB system color palettes to actual SNES palettes */ +#define SGB_PAL_TRN 0x0BU /**< SGB Command: Transfer palette data into SGB system color palettes */ +#define SGB_ATRC_EN 0x0CU /**< SGB Command: Enable/disable Attraction mode. It is enabled by default */ +#define SGB_TEST_EN 0x0DU /**< SGB Command: Enable/disable test mode for "SGB-CPU variable clock speed function" */ +#define SGB_ICON_EN 0x0EU /**< SGB Command: Enable/disable ICON functionality */ +#define SGB_DATA_SND 0x0FU /**< SGB Command: Write one or more bytes into SNES Work RAM */ +#define SGB_DATA_TRN 0x10U /**< SGB Command: Transfer code or data into SNES RAM */ +#define SGB_MLT_REQ 0x11U /**< SGB Command: Request multiplayer mode (input from more than one joypad) */ +#define SGB_JUMP 0x12U /**< SGB Command: Set the SNES program counter and NMI (vblank interrupt) handler to specific addresses */ +#define SGB_CHR_TRN 0x13U /**< SGB Command: Transfer tile data (characters) to SNES Tile memory */ +#define SGB_PCT_TRN 0x14U /**< SGB Command: Transfer tile map and palette data to SNES BG Map memory */ +#define SGB_ATTR_TRN 0x15U /**< SGB Command: Transfer data to (color) Attribute Files (ATFs) in SNES RAM */ +#define SGB_ATTR_SET 0x16U /**< SGB Command: Transfer attributes from (color) Attribute Files (ATF) to the Game Boy window */ +#define SGB_MASK_EN 0x17U /**< SGB Command: Modify Game Boy window mask settings */ +#define SGB_OBJ_TRN 0x18U /**< SGB Command: Transfer OBJ attributes to SNES OAM memory */ + + +/** Returns a non-null value if running on Super GameBoy */ UINT8 sgb_check(void); -/** Transfers SGB packet */ +/** Transfer a SGB packet + + @param packet Pointer to buffer with SGB packet data. + + The first byte of __packet__ should be a SGB command, + then up to 15 bytes of command parameter data. + + See the `sgb_border` GBDK example project for a + demo of how to use these the sgb functions. + + @see sgb_check() +*/ void sgb_transfer(unsigned char * packet); -/** Transfers SGB packet without waiting */ +/** Transfer a SGB packet without the 60 ms / 4 frame delay at the end + (the delay time is required between consecutive SGB packets) + + @param packet Pointer to buffer with SGB packet data. + + @see sgb_transfer() +*/ void sgb_transfer_nowait(unsigned char * packet); #endif /* _SGB_H */ diff --git a/gbdk-lib/include/gbdk-lib.h b/gbdk-lib/include/gbdk-lib.h @@ -7,7 +7,7 @@ They were automatically generated from the header files using Doxygen. - For the rest of the documentation, see <a href="https://gbdev.io/">gbdev.io</a> + For the rest of the documentation, see (link to main GBDK docs here) - - - - - - __Historical Information and Links from the original doc authors:__ diff --git a/gbdk-lib/include/rand.h b/gbdk-lib/include/rand.h @@ -8,33 +8,53 @@ #include <types.h> -/** Initalise the random number generator. - seed needs to be different each time, else the same sequence will be - generated. A good source is the DIV register. +/** Initalise the pseudo-random number generator. + + @param seed The value for initializing the random number generator. + + The seed should be different each time, otherwise the same pseudo-random + sequence will be generated. + + The DIV Register (@ref DIV_REG) is sometimes used as a seed, + particularly if read at some variable point in time (such + as when the player presses a button). + + Only needs to be called once to initialize, buy may be called + again to re-initialize with the same or a different seed. + @see rand(), randw() */ void initrand(UINT16 seed) NONBANKED; /* Non-banked as called from asm in arand.s */ -/** Returns a random value. +/** Returns a random byte (8 bit) value. + + @ref initrand() should be used to initialize the random number generator before using rand() */ INT8 rand(void); -/** Returns a random word. +/** Returns a random word (16 bit) value. + + @ref initrand() should be used to initialize the random number generator before using rand() */ UINT16 randw(void); /** Random generator using the linear lagged additive method - Note that 'initarand()' calls 'initrand()' with the same seed value, and - uses 'rand()' to initialize the random generator. - @author Luc Van den Borre + @param seed The value for initializing the random number generator. + + Note: initarand() calls @ref initrand() with the same seed value, and + uses @ref rand() to initialize the random generator. + + @see initrand() for suggestions about seed values, arand() */ void initarand(UINT16 seed); -/** Generates a random number using the linear lagged additive method. +/** Returns a random number generated with the linear lagged additive method. + + @ref initarand() should be used to initialize the random number generator before using arand() */ INT8 arand(void); diff --git a/gbdk-lib/include/stdio.h b/gbdk-lib/include/stdio.h @@ -9,39 +9,51 @@ #if STRICT_ANSI void putchar(int c); #else -/** Put the character 'c' to stdout. */ +/** Write the character __c__ to stdout. +*/ void putchar(char c); #endif /** Print the string and arguments given by format to stdout. - Currently supported: \%c (character), \%u (unsigned int), - \%d (signed int), \%x (unsigned int as hex), and \%s (string). + + @param format The format string as per printf + Does not return the number of characters printed. + + Currently supported: + \li \%c (character) + \li \%u (unsigned int) + \li \%d (signed int) + \li \%x (unsigned int as hex) + \li \%s (string) */ void printf(const char *format, ...) NONBANKED; /** Print the string and arguments given by format to a buffer. - Currently supported: \%c (character), \%u (unsigned int), - \%d (signed int), \%x (unsigned int as hex), and \%s (string). - Does not return the number of characters printed. - @param str The buffer to print into. - @param format The format string as per printf. + @param str The buffer to print into + @param format The format string as per @ref printf + + Does not return the number of characters printed. */ void sprintf(char *str, const char *format, ...) NONBANKED; -/** puts() writes the string s and a trailing newline to std - out. +/** puts() writes the string __s__ and a trailing newline to stdout. */ void puts(const char *s) NONBANKED; -/** gets() reads a line from stdin into the buffer pointed to by s until - either a terminating newline or EOF, which it replaces with '\0'. No - check for buffer overrun is per formed. +/** gets() Reads a line from stdin into a buffer pointed to by __s__. + + @param s Buffer to store string in + + Reads until either a terminating newline or an EOF, which it replaces with '\0'. No + check for buffer overrun is performed. + + Returns: Buffer pointed to by __s__ */ char *gets(char *s); -/** getchar() gets a single character from stdin. +/** getchar() Reads and returns a single character from stdin. */ char getchar(void); diff --git a/gbdk-lib/include/stdlib.h b/gbdk-lib/include/stdlib.h @@ -22,44 +22,100 @@ void exit(int status) NONBANKED; int getkey(void); #endif -/** Returns the absolute value of a int. +/** Returns the absolute value of int __i__ + @param i Int to obtain absolute value of + If i is negative, returns -i; else returns i. */ int abs(int i); -/** Returns the absolute value of a long. + +/** Returns the absolute value of long int __num__ + + @param num Long integer to obtain absolute value of */ long labs(long num); -/** Converts an ASCII string to an int. - The string may be of the format [\s]*[+-][\d]+[\D]* i.e. any number - of spaces, an optional + or -, then an arbitrary number of digits. + +/** Converts an ASCII string to an int + + @param s String to convert to an int + + The string may be of the format + \code{.c} + [\s]*[+-][\d]+[\D]* + \endcode + i.e. any number of spaces, an optional + or -, then an + arbitrary number of digits. + The result is undefined if the number doesnt fit in an int. + + Returns: Int value of string */ int atoi(const char *s); + /** Converts an ASCII string to a long. + @param s String to convert to an long int + @see atoi() + + Returns: Long int value of string */ long atol(const char *s); /** Converts an int into a base 10 ASCII string. + @param n Int to convert to a string + @param s String to store the converted number + + Returns: Pointer to converted string */ char *itoa(int n, char *s); /** Converts an unsigned int into a base 10 ASCII string. + @param n Unsigned Int to convert to a string + @param s String to store the converted number + + Returns: Pointer to converted string */ char *utoa(unsigned int n, char *s); /** Converts a long into a base 10 ASCII string. + @param n Long int to convert to a string + @param s String to store the converted number + + Returns: Pointer to converted string */ char *ltoa(long n, char *s); /** Converts an unsigned long into a base 10 ASCII string. + @param n Unsigned Long Int to convert to a string + @param s String to store the converted number + + Returns: Pointer to converted string */ char *ultoa(unsigned long n, char *s); + /* Searching and sorting utilities (ISO C11 7.22.5) */ +/** search a sorted array of __nmemb__ items + @param key Pointer to object that is the key for the search + @param base Pointer to first object in the array to search + @param nmemb Number of elements in the array + @param size Size in bytes of each element in the array + @param compar Function used to compare two elements of the array + + Returns: Pointer to array entry that matches the search key. + If key is not found, NULL is returned. +*/ extern void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *) __reentrant); + + +/** Sort an array of __nmemb__ items + @param base Pointer to first object in the array to sort + @param nmemb Number of elements in the array + @param size Size in bytes of each element in the array + @param compar Function used to compare and sort two elements of the array +*/ extern void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *) __reentrant); #endif diff --git a/gbdk-lib/include/string.h b/gbdk-lib/include/string.h @@ -6,66 +6,121 @@ #include <types.h> -/** Copies the string pointed to be src (including the terminating - `\0' character) to the array pointed to by dest. +/** Copies the string pointed to by __src__ (including the terminating + `\0' character) to the array pointed to by __dest__. + The strings may not overlap, and the destination string dest must be large enough to receive the copy. - @param dest Array to copy into. - @param src Array to copy from. - @return A pointer to dest. + @param dest Array to copy into + @param src Array to copy from + + @return A pointer to dest */ char *strcpy(char *dest, const char *src) NONBANKED; -/** Compares the two strings s1 and s2. - It returns an integer less than, equal to, or greater than zero if - s1 is found, respectively, to be less than, to match, or be - greater than s2. +/** Compares strings + + @param s1 First string to compare + @param s2 Second string to compare + + Returns: + \li > 0 if __s1__ > __s2__ + \li 0 if __s1__ == __s2__ + \li < 0 if __s1__ < __s2__ */ int strcmp(const char *s1, const char *s2) NONBANKED; -/** Copies n bytes from memory area src to memory area dest. +/** Copies n bytes from memory area src to memory area dest. + The memory areas may not overlap. - @param dest Array to copy into. - @param src Array to copy from. - @param len The length in bytes of src. - @return A pointer to dest. -*/ + @param dest Buffer to copy into + @param src Buffer to copy from + @param len Number of Bytes to copy +*/ void *memcpy(void *dest, const void *src, size_t len) NONBANKED; -/** Fills the memory region s of size n with c +/** Fills the memory region __s__ with __n__ bytes using value __c__ + + @param s Buffer to fill + @param c char value to fill with (truncated from int) + @param n Number of bytes to fill */ void *memset (void *s, int c, size_t n); -/** Reverses the characters in the string. - For example 'abcdefg' will become 'gfedcba'. Banked as the string - must be modifiable. +/** Reverses the characters in a string + + @param s Pointer to string to reverse. + + For example 'abcdefg' will become 'gfedcba'. + + Banked as the string must be modifiable. + + Returns: Pointer to __s__ */ char *reverse(char *s); +/** Concatenate Strings. Appends string __s2__ to the end of string __s1__ + + @param s1 String to append onto + @param s2 String to copy from + + For example 'abc' and 'def' will become 'abcdef'. + + String __s1__ must be large enough to store both __s1__ and __s2__. + + Returns: Pointer to __s1__ +*/ char *strcat(char *s1, const char *s2) NONBANKED; -/** Calculates the length of the string, not including the terminating - `\0' character. +/** Calculates the length of a string + + @param s String to calculate length of + + Returns: Length of string not including the terminating `\0' character. */ int strlen(const char *s) NONBANKED; -/**Concatenate s2 on the end of s1. - s1 must be large enough. At most n characters are moved. +/**Concatenate at most __n__ characters from string __s2__ onto the end of __s1__. + + @param s1 String to append onto + @param s2 String to copy from + @param n Max number of characters to copy from __s2__ + + String __s1__ must be large enough to store both __s1__ and __n__ characters of __s2__ + + Returns: Pointer to __s1__ */ char *strncat(char *s1, const char *s2, int n) NONBANKED; -/** Compare strings (at most n bytes): - s1>s2: >0 - s1==s2: 0 - s1<s2: <0 +/** Compare strings (at most n characters): + + @param s1 First string to compare + @param s2 Second string to compare + @param n Max number of characters to compare + + Returns: + \li > 0 if __s1__ > __s2__ + \li 0 if __s1__ == __s2__ + \li < 0 if __s1__ < __s2__ */ int strncmp(const char *s1, const char *s2, int n) NONBANKED; -/** Copy s2 to s1, truncating or null-padding to always copy n bytes. - If there is no \0 in the first n bytes of s2 then s1 will not be - null terminated. +/** Copy __n__ characters from string __s2__ to __s1__ + + + @param s1 String to copy into + @param s2 String to copy from + @param n Max number of characters to copy from __s2__ + + If __s2__ is shorter than __n__, the remaining + bytes in __s1__ are filled with \0. + + Warning: If there is no \0 in the first __n__ bytes of __s2__ then __s1__ + will not be null terminated. + + Returns: Pointer to __s1__ */ char *strncpy(char *s1, const char *s2, int n) NONBANKED; diff --git a/gbdk-lib/include/time.h b/gbdk-lib/include/time.h @@ -10,13 +10,29 @@ typedef UINT16 time_t; -/** The clock() function returns an approximation of processor time - used by the program. The value returned is the CPU time used so far - as a clock_t; to get the number of seconds used, divide by - CLOCKS_PER_SEC. +/** 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. + + 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; +/** Converts clock() time to Seconds + + @param t If pointer __t__ is not NULL, it's value will be set to the same seconds calculation as returned by the function. + + The calculation is clock() / CLOCKS_PER_SEC + + Returns: time in seconds + @see sys_time, clock() +*/ time_t time(time_t *t); #endif
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.