gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit a7de9116be710ce20a37e7198716a3d2d4b0b949 parent a2f4ed758312adefe771a5c38ad545e2a8651be5 Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Thu, 18 Feb 2021 11:04:49 +0300 Merge pull request #144 from bbbbbr/docs_work Docs updates Diffstat:
| M | README.md | 3 | +++ |
| M | docs/pages/banking_mbcs.md | 5 | ++++- |
| M | docs/pages/toolchain.md | 1 | + |
| M | gbdk-support/ChangeLog | 28 | ++++++++++++++-------------- |
| M | gbdk-support/README | 281 | ++++++++++++++++--------------------------------------------------------------- |
5 files changed, 77 insertions(+), 241 deletions(-)
diff --git a/README.md b/README.md @@ -6,6 +6,9 @@ You don't need the sources, unless you wish to compile GBDK-2020 yourself. Downl # Docs Online documentation is avaliable [HERE](https://zal0.github.io/gbdk-2020/docs/api) +A good place to start is the [Getting Started Section](https://zal0.github.io/gbdk-2020/docs/api/docs_getting_started.html) + + # gbdk-2020 [GBDK](http://gbdk.sourceforge.net/) A C compiler, assembler, linker and set of libraries for the Z80 like Nintendo Gameboy. diff --git a/docs/pages/banking_mbcs.md b/docs/pages/banking_mbcs.md @@ -205,7 +205,10 @@ Limitations: # Errors related to banking (overflow, multiple writes to same location) A _bank overflow_ during compile/link time (in @ref makebin) is when more code and data are allocated to a ROM bank than it has capacity for. The address for any overflowed data will be incorrect and the data is potentially unreachable since it now resides at the start of a different bank instead of the end of the expected bank. -The current toolchain can only detect and warn (using @ref ihxcheck) when one bank overflows into another bank that has data at its start. It cannot warn if a bank overflows into an empty one. For more complete detection , you can use the third-party @ref romusage tool. +See the @ref faq_bank_overflow_errors "FAQ entry about bank overflow errors". + +The current toolchain can only detect and warn (using @ref ihxcheck) when one bank overflows into another bank that has data at its start. It cannot warn if a bank overflows into an empty one. For more complete detection, you can use the third-party @ref romusage tool. + # Bank space usage diff --git a/docs/pages/toolchain.md b/docs/pages/toolchain.md @@ -32,6 +32,7 @@ To see individual arguments and options for a tool, run that tool from the comma - See @ref setting_mbc_and_rom_ram_banks <!-- --> +@anchor faq_bank_overflow_errors - What do these kinds of warnings / errors mean? `WARNING: possibly wrote twice at addr 4000 (93->3E)` `Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)` diff --git a/gbdk-support/ChangeLog b/gbdk-support/ChangeLog @@ -1,4 +1,4 @@ -gbdk3-4.0.2 +gbdk-4.0.2 - Updated documentation - Library was improved - Linking with stdio.h does not require that much rom now @@ -8,7 +8,7 @@ gbdk3-4.0.2 - New bankpack feature, allows automatic bank allocation for data and code, see banks_autobank example, feature is in beta state, use with care - Lcc improvements -gbdk3-4.0.1 +gbdk-4.0.1 - Updated documentation - IHX is checked for correctness before the makebin stage. That allows to warn about overwriting the same ROM addresses (SDCC toolchain does not check this anymore). - Library was improved @@ -22,7 +22,7 @@ gbdk3-4.0.1 - Reorganized examples: each example is in separate folder now, that simplifies understanding. - Lcc improvements -gbdk3-4.0 +gbdk-4.0 - GBDK now requires SDCC 4.0.3 or higher, that has fully working toolchain. Old link-gbz80 linker is not used anymore, sdldgb and makebin are used to link objects and produce binary roms; maccer tool is no longer needed either - SDCC 4.0.3 has much better code generator which produces smaller and faster code. Code is twice faster - SOURCE LEVEL DEBUGGING is possible now! Native toolchain produces *.CDB files that contain detailed debug info. Look for EMULICIOUS extension for vs.code. It supports breakpoints, watches, inspection of local variables, and more! @@ -43,12 +43,12 @@ gbdk3-4.0 - it works with the latest version of sdcc - quoted paths with spaces are working now -gbdk3-3.2 +gbdk-3.2 - support for BCD numbers - support for far pointers, that allow to call functions in other banks by pointer - some useful parts of native SDCC library are merged into GBDK (stdint, limits, stdbool, setjmp, stdatomic and so on) -gbdk3-3.1 +gbdk-3.1 - Banked functions are working! - Check this [post](https://gbdev.gg8.se/forums/viewtopic.php?id=700) for more info - Check the examples/gb/banked code for basic usage @@ -60,7 +60,7 @@ gbdk3-3.1 - Basic support including <gb/bgb_emu.h> and using the macros BGB_PROFILE_BEGIN and BGB_PROFILE_END. More info in this [post](https://gbdev.gg8.se/forums/viewtopic.php?id=703) - For full profiling [check this repo](https://github.com/untoxa/bgb_profiling_toolkit/blob/master/readme.md) and this [post](https://gbdev.gg8.se/forums/viewtopic.php?id=710) -gbdk3-3.00 +gbdk-3.00 Updated SDCC to v4.0 The new linker is not working so the old version is still there There is an issue with sdagb compiling drawing.s (the JP in @@ -69,13 +69,13 @@ gbdk3-3.00 Because of this, all .s files in libc have been assembled with the old as-gbz80 and that's why it is still included -gbdk3-2.96 +gbdk-2.96 * Many changes. Code generated is now much more reliable and passes all of sdcc's regression suite. Added support for large sets of local variables (>127 bytes). Added full 32 bit long support. Still no floating pt support. -gbdk3-2.95-3 +gbdk-2.95-3 * Stopped lcc with sdcc from leaking .cdb files all across /tmp. * Optimised < and > for 16 bit varibles. @@ -83,7 +83,7 @@ gbdk3-2.95-3 initalised arrays takes 31% of the time (well, at least samptest.c does :) -gbdk3-2.95-2 +gbdk-2.95-2 * Added model switching support --model-medium uses near (16 bit) pointers for data, and banked calls for anything not declared as 'nonbanked' @@ -97,7 +97,7 @@ gbdk3-2.95-2 * Turned on the optimisations in flex. Large constant arrays like tile data should compile a bit faster. -gbdk3-2.95 +gbdk-2.95 * Fixed 'a >> c' for c = [9..15] * Fixed 'a << c' for c = [9..15] * no$gmb doesn't support labels of > 32 chars. The linker now @@ -128,7 +128,7 @@ gbdk3-2.95 a go :) * Ran a spell checker across the README and ChangeLog -gbdk3-2.94 +gbdk-2.94 * Fixed #define BLAH 7 // Unterminated ' error in sdcpp @@ -153,7 +153,7 @@ gbdk3-2.94 seperatly. * Two dimensional arrays seem to be broken. -gbdk3-2.93 +gbdk-2.93 * Added multi-bank support into the compiler - The old -Wf-boxx and -Wf-baxx options now work * Has preliminary support for generating rgbds and ISAS compatible @@ -171,7 +171,7 @@ gbdk3-2.93 something appropriate as 'volatile' to stop the value being cached. See dscan.c/bombs() for an example. -gbdk3-2.92-2: +gbdk-2.92-2: * win32 only. Takes care of some of the install bugs, including: - Now auto detects where it is installed. This can be overridden using set GBDKDIR=... @@ -184,7 +184,7 @@ gbdk3-2.92-2: - I've reverted to using WORD for signed 16 bit etc. GBDK_2_COMPAT is no longer required. -gbdk3-2.92: +gbdk-2.92: * All the examples now work (with a little bit of patching :) * Fixed problem with registers being cached instead of being marked volatile. diff --git a/gbdk-support/README b/gbdk-support/README @@ -1,260 +1,89 @@ - gbdk-3.1 - https://github.com/Zal0/gbdk-2020/releases - ---------------------------------------- - (C) 2001 Michael Hope <michaelh@juju.net.nz> -Short story: + ------------------------------------------------------ + GBDK-2020 - https://github.com/Zal0/gbdk-2020 + ------------------------------------------------------ + +What's New ------------ -win32: -* Unzip using WinZip or similar (which you've probably already done :) - e.g use WinZip to extract to d:\gbstuff\gbdk -* Add the 'bin' directory to your path if required. - e.g Add 'PATH=%PATH%;d:\gbstuff\gbdk\bin' to autoexec.bat, or - through the System control panel on Windows NT or 2000. -* Restart if needed. -* GBDK is ready to go - there is no need to compile the libraries or - to set environment variables. You may want to remove the - GBDKDIR line from autoexec.bat that an older version of gbdk may - have put there. - See the ChangeLog for more information. -* You can compile the examples by running 'make.bat' in examples\gb - e.g d:, cd \gbstuff\gbdk\examples\gb, make - -Linux: -* Very similar to win32 -* Extract the archive somewhere (normally /opt/gbdk) -* Set GBDKDIR to where you installed with a trailing / - e.g. export GBDKDIR=/home/michaelh/gbdk/ -* Try compiling the examples as above - -Special note: -------------- -I've reverted the WORD to 16 bit unsigned change that required --DGBDK_2_COMPAT=1. You can use BYTE_IS_UNSIGNED if you, like me, -really want WORD to be unsigned :) +See the "ChangeLog" included in the root folder of the GBDK install. -Reporting problems and feature requests ---------------------------------------- -1. Make sure that you have read this README fully. -2. Have a read of the gbdk homepage - http://gbdk.sourceforge.net/ -3. Read the latest copy of this README - http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/~checkout~/gbdk-support/README?cvsroot=gbdk -4. Make sure you have the latest version - http://sourceforge.net/project/?group_id=1249 -5. Check if anyone else has reported the problem - http://sourceforge.net/bugs/?group_id=1249 -To download the latest source, get the tarball on sourceforge, -extract, and type: -make -f update.mak update +New Releases +------------ +Check for new releases online: +https://github.com/Zal0/gbdk-2020/releases -The Linux binary is normally installed in /opt/gbdk. If you -install somewhere else, set GBDKDIR to the appropriate path. -eg. - export GBDKDIR=/opt/gbdk/ -Note the trailing slash. -Documentation -------------- -Latest version of this README: - http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/~checkout~/gbdk-support/README?cvsroot=gbdk +Setup: +------------ -Library documentation: - http://gbdk.sourceforge.net/doc/html/index.html -This was generated from include/*.h by doxygen +=== Windows === -General Gameboy information: - http://www.devrs.com/gb/ +* Unzip to a folder of your choice (which you've probably already done) + Suggested location: c:\gbdk\ -GeeBee FAQ: - http://www.devrs.com/gb/files/faqs.html +* Recommended but not required: Add the gbdk 'bin' sub-directory to your + system path using the Windows System control panel -GBSpec aka Pan doc - http://www.devrs.com/gb/files/gbspec.txt +* Open a command line and compile the examples by running "make.bat" in + the "examples\gb" sub-directory: + cd c:\gbdk\examples\gb + make.bat -Banked function support ------------------------ -2.95 and above supports banked functions. The rules are: -* Any function with the attribute 'nonbanked' ie +=== Linux === - int puts(const char *sz) nonbanked; +* Unzip to a folder of your choice (which you've probably already done) + Suggested location: /opt/gbdk/ - will be put into HOME. +* Recommended but not required: Add the gbdk 'bin' sub-directory to your shell path + Run from command line (only lasts for that session): export GBDKDIR=/opt/gbdk + Or add that to your shell defaults (permanent) -* Any function with the 'banked' attribute can be called from any bank - A banked call has four extra bytes of stack overhead and adds 56 - m-cycles to each call. If anyone can suggest a faster method, I'd - love to hear it. +* Open a command line and compile the examples by running "make.bat" in + the "examples\gb" sub-directory: + cd /opt/gbdk/examples/gb + make -* Any static function will be treated as 'near' and not have the - overhead of a banked call. -* If you specify 'banked' with either static or nonbanked, the function - will be non-banked. -* The model used sets whether 'normal' functions (without the banked, - nonbanked, or static modifiers) are banked or not. The currently supported - options are: - --model-medium Functions are by default banked - --model-small Functions are by default nonbanked - The default is model is small. The compiler defines SDCC_MODEL_SMALL - or SDCC_MODEL_MEDIUM depending on the current model. Libraries for both - models are provided in lib/small and lib/medium +GBDK is now ready for use. -* types.h defines BANKED and NONBANKED to 'banked' and 'nonbanked' - respectively. I recommend using these for future compatibility and - for portability. +It's recommended to check out the Getting Started docs: +https://zal0.github.io/gbdk-2020/docs/api/docs_getting_started.html -Some notes: - * Currently only works with rgbds and isas. asxxxx doesn't support - resolving the bank of a function at link time - * Pointers _will not_ pass correctly across banked functions. For - speeds sake pointers are still 16 bit, so if you call a banked - function with a pointer that is in your bank, the pointer will - become invalid when your bank disappears. Be warned. Note that - calls within the same bank will still work. Some ways of getting - around this problem are: - o Put heavily used functions or functions that take pointers - in HOME. Then the pointer will remain valid. - o Calls within the same module (ie file) should be in the same - bank. Id like to say will, which is true in asxxxx, but I - haven't confirmed it. +Reporting problems and feature requests +--------------------------------------- +1. Make sure that you have read this README fully. - * A banked call adds an extra 4 bytes to the stack and quite a few - extra cycles to the call. Don't use it for heavily used functions - and avoid it where possible by grouping dependent functions into - one bank to make them 'near' +2. Check the online docs, including the Getting Started section + https://zal0.github.io/gbdk-2020/docs/api + https://zal0.github.io/gbdk-2020/docs/api/docs_links_and_tools.html#links_help_and_community - * Assembly functions and functions that don't take parameters (ie - functions that don't care if a few extra bytes are added to their - call stack) can be treated as both 'banked' and non-banked. This - is due to how the return address of the calling function is - mangled. +3. Make sure you have the latest version + https://github.com/Zal0/gbdk-2020/releases - * Only non-banked (this includes static) functions may be used as - parameters or have their address taken. If you don't know what - this means then you should be OK :) +4. Check if anyone else has already reported or solved the problem + https://github.com/Zal0/gbdk-2020/issues?q=is%3Aissue+is%3Aclosed -I have made some of the library functions banked. More will follow. -Using the banked attribute under asxxxx will cause no harm, but you -are limited to being in the first two banks (32k) +5. Ask for help online + https://github.com/Zal0/gbdk-2020#discord-servers -#pragma bank=[xx] has been extended. Using [xx] = a number (1, 2..) -is assembler independent. The special banks HOME and BASE are also -assembler independent. Note that the last #pragma bank= will be the -one that applies for the whole file. -One more thing. As banked and non-banked functions may be mixed the -compiler commits any constant data at the end of each function. One -side affect is that code like this: +Documentation +------------- -const int array[] = { 1, 2, 3, 4 }; +Library documentation: + https://zal0.github.io/gbdk-2020/docs/api -void foo(void) nonbanked { ... }; +Pandocs + https://gbdev.io/pandocs/ -will associate array[] with foo() and as foo is in HOME so will be -array. This only occurs when a constant inialised array is declared -immediately before a nonbanked function. +Other useful links: + https://zal0.github.io/gbdk-2020/docs/api/docs_links_and_tools.html#links_help_and_community + -rgbds support -------------- -2.95 added decent rgbds support. Basically: - o Use "sdcc -mgbz80 --asm=rgbds file.c" for each file.c - o Use "sdcc -mgbz80 --asm=rgbds crt0.o gbz80.lib gb.lib file1.o file2.o..." -crt0.o, gbz80.lib, and gb.lib are in lib/rgbds. The missing parts are -currently: - * lcc does not work with rgbds. You have to call sdcc directly, setting - up the include path and making the libraries local as appropriate. - - * sdcc does not support the concept of an output file name when - linking. This means that your cart will be called 'a.gb', the - .sym file 'a.sym' etc. - - * The libraries are generated directly from gbdk-lib by - tools/astorgb.pl. The converter may have bugs which passed on - through to the libs. Be cautious of any assembler library functions. - - * I don't know why, but xlink seems to load all of the libraries - instead of just the ones that are required, adding a significant - overhead. this is being investigated. - - * Static initialised data like: - - int data[] = { 1, 2, 3, 4 }; - currently isn't supported. sdcc pulls some tricks with the way that - sections are allocated to support the initialisation code which rgbds - doesn't support. In any case, static inited data is normally a bug - - most people normally mean: - const int data[] = { ... }; - This is especially the case with tile data etc on the gb. - -Some of the examples don't yet work. For now you need a make utility like -GNU make (see below) to compile them. - -Differences between this and gbdk-2.1.5 ---------------------------------------- -* It now uses sdcc <http://sdcc.sourceforge.net/> as the C compiler - which should lead to better code but unfortunately will generate - a whole new set of bugs :) Most of the differences below are due - to this change-over. - -* sdcc _does not_ automatically promote variables to int's. This is - a 'good thing' as normally the promotion is unwanted on an eight - bit system, but in some places you may get the wrong result. If - so, try promoting the variable manually i.e. (int)foo*20; - -* If funny things happen when you access registers, try declaring them - as volatile. See <hardware.h> for an example. sdcc normally caches - variables for speed, but this causes trouble when accessing registers. - -* The basic types have changed. The sizes are now: - char 8 bits - int 16 bits - long 32 bits - long long Doesn't exist - -* Float support is there but unconnected. - -* gbdk has an alternitave set of typedefs for those who like me like - their WORDs to be unsigned. Define BYTE_IS_UNSIGNED=1 to use the new - typedefs. - Before With Or Size - BYTE INT8 8 signed - UBYTE BYTE UINT8 8 unsigned - WORD INT16 16 signed - UWORD WORD UINT16 16 unsigned - DWORD INT32 32 signed - UDWORD DWORD UINT32 32 unsigned - -* There is now real initialised static data support. You can now use - BYTE abModifyMeLater[] = { 5, 6, 7, 8 }; - - void foo(void) - { - abModifyMeLater[2] = 12; - } - and it will work. Currently this is very inefficient but it will - be improved. See const in the next section - -* Constant global structs (ie tile data, sprites) SHOULD be declared - as 'const' If they are not declared const, not only do they get copied - into ram at startup but they take up about 6x the rom space. - -References ----------- -Jeff's gbdev page -http://www.devrs.com/ - -rgbds -http://www.otakunozoku.com/ - -GNU make -ftp://agnes.dida.physik.uni-essen.de/home/janjaap/mingw32/newnew/ - --- Michael Hope - <michaelh@juju.net.nz> <nz_michaelh@yahoo.com>
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.