gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 4f90a5eb8353537bfbc0547db239519cc7d0505d parent cef7bbed602c880eba4920711eb699e8222c7ba7 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Mon, 14 Nov 2022 19:55:48 -0800 Merge pull request #453 from bbbbbr/docs_4_1_1 Docs: Banked calling convention Diffstat:
| M | docs/pages/04_coding_guidelines.md | 72 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
| M | docs/pages/05_banking_mbcs.md | 11 | +++++------ |
2 files changed, 61 insertions(+), 22 deletions(-)
diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -239,24 +239,8 @@ Also See: # When C isn't fast enough -@todo Update and verify this section for the modernized SDCC and toolchain - For many applications C is fast enough but in intensive functions are sometimes better written in assembly. This section deals with interfacing your core C program with fast assembly sub routines. - -@anchor sdcc_calling_convention -## Calling convention - -SDCC in common with almost all C compilers prepends a `_` to any function names. For example the function `printf(...)` begins at the label `_printf::.` Note that all functions are declared global. - -Functions can be marked with `OLDCALL` which will cause them to use the `__sdcccall(0)` calling convention (the format used prior to in SDCC 4.2 & GBDK-2020 4.1.0). - -Starting with SDCC 4.2 and GBDK-2020 4.1.0 the new default calling convention is`__sdcccall(1)`. - -For details about the calling convetions, see sections `SM83 calling conventions` and `Z80, Z180 and Z80N calling conventions` in the SDCC manual. - - http://sdcc.sourceforge.net/doc/sdccman.pdf - - ## Variables and registers <!-- C normally expects registers to be preserved across a function call. However in the case above as DE is used as the return value and HL is used for anything, only BC needs to be preserved. --> @@ -287,3 +271,59 @@ The use of segments/areas for code, data and variables is more noticeable in ass - `_HEAP`: placed after `_INITIALIZED` so that all spare memory is available for the malloc routines. - `STACK`: at the end of WRAM +@anchor sdcc_calling_convention +## Calling convention + +SDCC in common with almost all C compilers prepends a `_` to any function names. For example the function `printf(...)` begins at the label `_printf::.` Note that all functions are declared global. + +Functions can be marked with `OLDCALL` which will cause them to use the `__sdcccall(0)` calling convention (the format used prior to SDCC 4.2 & GBDK-2020 4.1.0). + +Starting with SDCC 4.2 and GBDK-2020 4.1.0 the new default calling convention is`__sdcccall(1)`. + +For additional details about the calling convetions, see sections `SM83 calling conventions` and `Z80, Z180 and Z80N calling conventions` in the SDCC manual. + - http://sdcc.sourceforge.net/doc/sdccman.pdf + - Section 4.3.9 isn't specific about it, but `gbz80`/`sm83` generally share this subheading with `z80` (Game Boy is partially a sub-port of z80 in SDCC). https://sdcc.sourceforge.net/doc/sdccman.pdf#subsection.4.3.9 + + +@anchor banked_calling_convention +### Banked Calling Convention +_The following is primarily oriented toward the Game Boy and related clones (sm83 devices), other targets such as sms/gg may vary._ + +Key Points: + - Function arguments (if present) are always placed on the stack, right to left without particular alignment + - A fixed stack offset (sm83:+4, z80:+3) is added by the `Callee` (to skip the pushed `Caller` Bank and additional `Trampoline` Return Address) + - Return values follow the calling convention (`__sdcccall(1)`, or `__sdcccall(0)` for `OLDCALL`) + +Terminology: +- `Caller`: the code which is calling the requested function +- `Callee`: the function to be called (declared as `BANKED` or `__banked`) +- `Trampoline`: The intermediary which performs the bank switching and does hand-off between `Caller` and `Callee` during the call and then return. + +Banked Call Trampoline + - Banked calls are performed via a trampoline in the non-banked region 0000-3ffff + - The `__sdcc_bcall_ehl` trampoline is used by default + - With it both calling conventions are supported: `__sdcccall(1)` (default) or `__sdcccall(0)` for `OLDCALL` + - If `--legacy-banking` is specified to SDCC the `__sdcc_bcall` trampoline is used. + - This may only be used with `__sdcccall(0)` + +Process for a banked call (`using __sdcc_bcall_ehl`, the default) +1. The Caller + - Function arguments (if present) are always placed on the stack, right to left without particular alignment + - The Bank of Callee function is placed into register E + - The Address of Callee function is placed in HL + - Calls the bank switch Trampoline (which adds Caller return address to the stack) +2. The Trampoline + - Saves the Current Bank onto the stack (pushed as AF, so 16 bits) + - Switches to the Bank of Callee function (in register E) + - Calls the Callee function address in HL (which adds Trampoline return address to the stack) +3. The Callee Function + - SDCC will use an offset to skip the first N bytes of the stack + - For `sm83` (GB/AP/DUCK): skip first 4 bytes + - For `z80` (GG/SMS/etc): skip first 3 bytes + - Return values follow the calling convention (`__sdcccall(1)`, or `__sdcccall(0)` for `OLDCALL`) + - Executes a return to Trampoline +4. The Trampoline + - Switches to the Bank of the Caller saved on the stack (and moves Stack Pointer past it) + - Executes a return to Caller +5. The Caller + - Cleans up the stack and uses return value (if present) diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md @@ -81,7 +81,7 @@ The MBC settings below are available when using the makebin `-Wl-yt<N>` switch. Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type "Pandocs") -# MBC Type Chart +## MBC Type Chart ``` 0147: Cartridge type: 0x00: ROM ONLY 0x12: ROM+MBC3+RAM @@ -146,9 +146,6 @@ Source: Pandocs. Additional details available at [Pandocs](https://gbdev.io/pand - - - ## Getting Bank Numbers The bank number for a banked function, variable or source file can be stored and retrieved using the following macros: - @ref BANKREF(): create a reference for retrieving the bank number of a variable or function @@ -173,7 +170,7 @@ The bank number for a banked function, variable or source file can be stored and @anchor banked_calls ### Banked Function Calls -Banked functions can be called as follows: +Functions in banks can be called as follows: - When defined with the `BANKED` keyword. Example: `void my_function() BANKED { do stuff }` in a source file which has had its bank set (see above). - Using @ref far_pointers - When defined with an area set up using the `__addressmod` keyword (see the `banks_new` example project and the SDCC manual for details). @@ -188,12 +185,14 @@ Banked functions (located in a switchable ROM bank) - May call `BANKED` functions in any bank: __YES__ - The compiler and library will manage the bank switching automatically using the bank switching trampoline. - May use data in any bank: __NO__ - - May only use data from Bank 0 and the currently active bank. + - May only use data from fixed Bank 0 and the currently active bank. - A @ref wrapped_function_for_banked_data "NONBANKED wrapper function" may be used to access data in other banks. Limitations: - SDCC banked calls and far_pointers in GBDK only save one byte for the ROM bank. So, for example, they are limited to __bank 31__ max for MBC1 and __bank 255__ max for MBC5. This is due to the bank switching for those MBCs requiring a second, additional write to select the upper bits for more banks (banks 32+ in MBC1 and banks 256+ in MBC5). +Calling Convention: + - For details see @ref banked_calling_convention "Banked Calling Convention" ## Const Data (Variables in ROM) Data declared as `const` (read only) will be stored in ROM in the bank associated with it's source file (if none is specified it defaults to Bank 0). If that bank is a switchable bank then the data is only accesible while the given bank is active.
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.