gbdk-2.96 - http://gbdk.sourceforge.net/ ---------------------------------------- (C) 2001 Michael Hope This is a early-release beta. Please report any bugs :) Short story: ------------ 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 Notes for this release: ----------------------- 2.96 is a special maintenance release which includes all of the bug fixes from a year of development of sdcc. The code generated should now be more reliable, and all examples run correctly. Banked functions, the 'sfr' keyword, and targeting assemblers other than asxxxx is unsupported in this release, but will be in the next. All testing was done with xgnuboy on Linux/ppc - thanks to them for making a cross platform emulator. 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 :) 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 6. Submit a new bug using the link above. It is _very_ helpful if you can show how to reproduce the bug and/or give me the source to try and/or use the --dumpall (lcc -Wf--dumpall) option and send me all of the *.dump files. Use the email address below. To download the latest source, get the tarball on sourceforge, extract, and type: make -f update.mak update 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 Library documentation: http://gbdk.sourceforge.net/doc/html/index.html This was generated from include/*.h by doxygen General Gameboy information: http://www.devrs.com/gb/ GeeBee FAQ: http://www.devrs.com/gb/files/faqs.html GBSpec aka Pan doc http://www.devrs.com/gb/files/gbspec.txt Banked function support ----------------------- 2.95 and above supports banked functions. The rules are: * Any function with the attribute 'nonbanked' ie int puts(const char *sz) nonbanked; will be put into HOME. * 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. * 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 * types.h defines BANKED and NONBANKED to 'banked' and 'nonbanked' respectively. I recommend using these for future compatibility and for portability. 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. * 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' * 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. * 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 :) 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) #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: const int array[] = { 1, 2, 3, 4 }; void foo(void) nonbanked { ... }; 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. 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 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 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