gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 44066c2431604fb391508ff7500809cf2c1d1d63 parent 76c607a52fa44b78ae36620daef26538eb195f12 Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Thu, 25 Mar 2021 10:45:55 +0300 Merge pull request #160 from bbbbbr/docs_work Docs updates Diffstat:
| M | Makefile | 66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | docs/gbdk_manual.pdf | 0 | |
| M | docs/pages/04_coding_guidelines.md | 12 | +++++++----- |
| M | docs/pages/06_toolchain.md | 24 | ++++++++++++++++++++++-- |
| M | docs/pages/07_sample_programs.md | 14 | +++++++++++++- |
| M | docs/pages/10_release_notes.md | 6 | +++--- |
| A | docs/pages/20_toolchain_settings.md | 543 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | docs/pages/docs_index.md | 1 | + |
| M | gbdk-lib/examples/gb/gbdecompress/Readme.md | 5 | +++++ |
| A | gbdk-lib/examples/gb/large_map/Readme.md | 14 | ++++++++++++++ |
| M | gbdk-lib/examples/gb/metasprites/Makefile | 3 | +++ |
| M | gbdk-lib/examples/gb/metasprites/Readme.md | 10 | ++++++---- |
| M | gbdk-lib/include/gb/drawing.h | 4 | ++++ |
| M | gbdk-lib/include/gb/gbdecompress.h | 2 | +- |
| M | gbdk-lib/include/gb/metasprites.h | 2 | +- |
15 files changed, 689 insertions(+), 17 deletions(-)
diff --git a/Makefile b/Makefile @@ -59,6 +59,7 @@ docs: doxygen-generate docspdf: doxygen-generate-with-pdf docsclean: doxygen-clean docsreset: doxygen-reset +docstools: docs-toolchain-generate # Build rule for michaelh's machine to spin a release sapphire-full-build: native-build binary cross-clean cross-linux-mingw32-build @@ -248,6 +249,7 @@ doxygen-generate: ifeq ($(shell expr "$(DOXYGEN_VER_HAS)" \< "$(DOXYGEN_VER_REQ)"), 1) $(error Doxygen version $(DOXYGEN_VER_HAS) is too old! Minimum version is $(DOXYGEN_VER_REQ)) endif +#Run Doxygen rm -rf $(GBDKDOCSDIR)/api; \ cd "$(GBDKLIBDIR)/include"; \ GBDKDOCSDIR="$(GBDKDOCSDIR)" GBDKLIBDIR="$(GBDKLIBDIR)" $(DOXYGENCMD) "$(GBDKDOCSDIR)/config/gbdk-2020-doxyfile" @@ -270,6 +272,70 @@ endif doxygen-generate-with-pdf: DOCS_PDF_ON=YES doxygen-generate-with-pdf: doxygen-generate + +# Generate toolchain settings markdown file (if possible) +docs-toolchain-generate: TOOLCHAIN_DOCS_FILE=$(GBDKDOCSDIR)/pages/20_toolchain_settings.md +docs-toolchain-generate: +ifneq (,$(wildcard $(BUILDDIR)/bin/)) + echo \@page docs_toolchain_settings Toolchain settings > $(TOOLCHAIN_DOCS_FILE) +# lcc + echo \@anchor lcc-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# lcc settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + cd "$(BUILDDIR)/bin/"; \ + ./lcc >> $(TOOLCHAIN_DOCS_FILE) 2>&1 + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# sdcc + echo \@anchor sdcc-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# sdcc settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/sdcc -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 +# sdasgb + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + echo \@anchor sdasgb-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# sdasgb settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/sdasgb -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# bankpack + echo \@anchor bankpack-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# bankpack settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/bankpack -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# sdldgb + echo \@anchor sdldgb-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# sdldgb settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/sdldgb >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# ihxcheck + echo \@anchor ihxcheck-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# ihxcheck settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/ihxcheck -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# makebin + echo \@anchor makebin-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# makebin settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/makebin -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# gbcompress + echo \@anchor gbcompress-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# gbcompress settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/gbcompress -h >> $(TOOLCHAIN_DOCS_FILE) 2>&1 || true + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); +# png2mtspr + echo \@anchor png2mtspr-settings >> $(TOOLCHAIN_DOCS_FILE); + echo \# png2mtspr settings >> $(TOOLCHAIN_DOCS_FILE); + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE); + $(BUILDDIR)/bin/png2mtspr >> $(TOOLCHAIN_DOCS_FILE) 2>&1 + echo \`\`\` >> $(TOOLCHAIN_DOCS_FILE) +endif + + doxygen-clean: rm -rf $(GBDKDOCSDIR)/api diff --git a/docs/gbdk_manual.pdf b/docs/gbdk_manual.pdf Binary files differ. diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -41,7 +41,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti - Use 8-bit values as much as possible. They will be much more efficient and compact than 16 and 32 bit types. - - Prefer unsigned variables to signed ones: The code generated will be generally more efficient, espacially when comparing two values. + - Prefer unsigned variables to signed ones: The code generated will be generally more efficient, especially when comparing two values. - Use explicit types so you always know the size of your variables. `INT8, UINT8, INT16, UINT16, INT32, UINT32` or `BYTE, UBYTE, WORD, UWORD, LWORD, ULWORD`. Types are defined in @ref asm/types.h and @ref asm/gbz80/types.h @@ -68,9 +68,10 @@ If you wish to use the original tools, you must add the `const` keyword every ti - When procesing for a given frame is done and it is time to wait before starting the next frame, @ref wait_vbl_done() can be used. It uses HALT to put the CPU into a low power state until processing resumes. The CPU will wake up and resume processing at the end of the current frame when the Vertical Blanking interrupt is triggered. - - Minimize use of multiplication, modulo and division. These operations have no corresponding CPU instructions (software functions), and hence are time costly. Division by powers of 2 are better, they have specific SDCC optimizations. - - Alternatives to modulo: - - When using power of 2 you can use bit masks. Example: `(n % 8)` can be achieved with `(n & 0x7)` + - Minimize use of multiplication, modulo with non-powers of 2, and division with non-powers of 2. These operations have no corresponding CPU instructions (software functions), and hence are time costly. + - SDCC has some optimizations for: + - Division by powers of 2. For example `n /= 4u` will be optimized to `n >>= 2`. + - Modulo by powers of 2. For example: `(n % 8)` will be optimized to `(n & 0x7)`. - If you need decimal numbers to count or display a score, you can use the GBDK BCD ([binary coded decimal](https://en.wikipedia.org/wiki/Binary-coded_decimal)) number functions. See: @ref bcd.h and the `BCD` example project included with GBDK. - Avoid long lists of function parameters. Passing many parameters can add overhead, especially if the function is called often. When applicable globals and local static vars can be used instead. @@ -78,6 +79,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti - Use inline functions if the function is short. (with the `inline` keyword, such as `inline UINT8 myFunction() { ... }`) - Do not use recursive functions +<!-- This entry needs re-work. Signed vs unsigned, current SDCC optimizations... - Prefer `==` and `!=` comparison operators to `<`, `<=`, `>`, and `>=`. The code will be shorter and quicker. @@ -94,7 +96,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti and if possible, even better: for(i = 10; i != 0; i--) - +--> ## GBDK API/Library diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -111,6 +111,9 @@ https://www.tutorialspoint.com/makefile/index.htm @anchor lcc ## lcc lcc is the compiler driver (front end) for the GBDK/sdcc toolchain. + +For detailed settings see @ref lcc-settings + It can be used to invoke all the tools needed for building a rom. If preferred, the individual tools can be called directly. - the `-v` flag can be used to show the exact steps lcc executes for a build @@ -125,12 +128,17 @@ If preferred, the individual tools can be called directly. @anchor sdcc ## sdcc SDCC C Source compiler -- Arguments can be passed to it through @ref lcc using `-Wf-<argument>` and `-Wp-<argument>` (pre-processor) +For detailed settings see @ref sdcc-settings + +- Arguments can be passed to it through @ref lcc using `-Wf-<argument>` and `-Wp-<argument>` (pre-processor) @anchor sdasgb ## sdasgb SDCC Assembler for the gameboy + +For detailed settings see @ref sdasgb-settings + - Arguments can be passed to it through @ref lcc using `-Wa-<argument>` @@ -138,6 +146,8 @@ SDCC Assembler for the gameboy ## bankpack Automatic Bank packer +For detailed settings see @ref bankpack-settings + When enabled, automatically assigns banks for object files where bank has been set to `255`, see @ref rom_autobanking. Unless an alternative output is specified the given object files are updated with the new bank numbers. - Can be enabled by using the `-autobank` argument with @ref lcc. @@ -153,6 +163,8 @@ Limitations ## sdldgb The SDCC linker for the gameboy. +For detailed settings see @ref sdldgb-settings + Links object files (.o) into a .ihx file which can be processed by @ref makebin - Arguments can be passed to it through @ref lcc using `-Wl-<argument>` @@ -161,6 +173,8 @@ Links object files (.o) into a .ihx file which can be processed by @ref makebin ## ihxcheck IHX file validator +For detailed settings see @ref ihxcheck-settings + Checks .ihx files produced by @ref sdldgb for correctness. - It will warn if there are multiple writes to the same ROM address. This may indicate mistakes in the code or ROM bank overflows - Arguments can be passed to it through @ref lcc using `-Wi-<argument>` @@ -170,6 +184,8 @@ Checks .ihx files produced by @ref sdldgb for correctness. ## makebin IHX to ROM converter +For detailed settings see @ref makebin-settings + Converts .ihx files produced by @ref sdldgb into ROM files (.gb, .gbc). - Arguments can be passed to it through @ref lcc using `-Wm-<argument>` @@ -182,11 +198,15 @@ Converts .ihx files produced by @ref sdldgb into ROM files (.gb, .gbc). ## GBCompress Compresssion utility +For detailed settings see @ref gbcompress-settings + Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see @ref gb_decompress(). -@anchor png2mtspr +@anchor utility_png2mtspr ## PNG to Metasprite Tool for converting PNGs into GBDK format MetaSprites +For detailed settings see @ref png2mtspr-settings + @todo Document png2mtspr diff --git a/docs/pages/07_sample_programs.md b/docs/pages/07_sample_programs.md @@ -50,12 +50,24 @@ A C translation of the space.s assembly program. The gb-dtmf, written by Osamu Ohashi, is a Dual Tone Multi-Frequency (DTMF) generator. +# gbdecompress +Demonstrates using gbdecompress to load a compressed tile set into vram. + + # irq Illustrates how to install interrupt handlers. # large map -Shows how to scroll with maps larger than 32 x 32 tiles using set_bkg_submap(). It fills rows and columns at the edges of the visible viewport (of the hardware Background Map) as it scrolls from the desired sub-region of the large map. +Shows how to scroll with maps larger than 32 x 32 tiles using set_bkg_submap(). It fills rows and columns at the edges of the visible viewport (of the hardware Background Map) with the desired sub-region of the large map as it scrolls. + + +# metasprites +Demonstrates using the metasprite features to move and animate a large sprite. +* Press A button to show / hide the metasprite +* Press B button to cycle through the metasprite animations +* Press SELECT button to cycle the metasprite through Normal / Flip-Y / Flip-XY / Flip-X +* Up / Down / Left / Right to move the metasprite # lcd isr wobble diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -12,7 +12,7 @@ https://github.com/Zal0/gbdk-2020/releases - Added @ref set_vram_byte() - Added @ref set_bkg_tile_xy() / @ref set_win_tile_xy() - Added @ref get_bkg_xy_addr() / @ref get_win_xy_addr() - - Added @ref get_bkg_submap() / @ref get_win_submap() + - Added @ref set_bkg_submap() / @ref set_win_submap() - Added metasprite api support - Added gb_decompress support - Added @ref calloc / @ref malloc / @ref realloc / @ref free and generic @ref memmove @@ -27,8 +27,8 @@ https://github.com/Zal0/gbdk-2020/releases - Fixed build issue with banks_autobank example - Improved sgb_border - Toolchain / Utilities - - Added @ref gbcompress utility - - Added @ref png2metaspr metasprite utility + - Added @ref utility_gbcompress utility + - Added @ref utility_png2mtspr metasprite utility - Docs - Added extensive documentation (some of which is imported and updated from the old gbdk docs) - Added PDF version of docs diff --git a/docs/pages/20_toolchain_settings.md b/docs/pages/20_toolchain_settings.md @@ -0,0 +1,543 @@ +@page docs_toolchain_settings Toolchain settings +@anchor lcc-settings +# lcc settings +``` +./lcc [ option | file ]... + except for -l, options are processed left-to-right before files + unrecognized options are taken to be linker options +-A warn about nonANSI usage; 2nd -A warns more +-b emit expression-level profiling code; see bprint(1) +-Bdir/ use the compiler named `dir/rcc' +-c compile only +-dn set switch statement density to `n' +-debug turn on --debug for compiler, -y (.cdb) and -j (.noi) for linker +-Dname -Dname=def define the preprocessor symbol `name' +-E run only the preprocessor on the named C programs and unsuffixed files +-g produce symbol table information for debuggers +-help or -? print this message +-Idir add `dir' to the beginning of the list of #include directories +-K don't run ihxcheck test on linker ihx output +-lx search library `x' +-N do not search the standard directories for #include files +-n emit code to check for dereferencing zero pointers +-O is ignored +-o file leave the output in `file' +-P print ANSI-style declarations for globals +-p -pg emit profiling code; see prof(1) and gprof(1) +-S compile to assembly language +-autobank auto-assign banks set to 255 (bankpack) +-static specify static libraries (default is dynamic) +-t -tname emit function tracing calls to printf or to `name' +-target name is ignored +-tempdir=dir place temporary files in `dir/'; default=/tmp +-Uname undefine the preprocessor symbol `name' +-v show commands as they are executed; 2nd -v suppresses execution +-w suppress warnings +-Woarg specify system-specific `arg' +-W[pfablim]arg pass `arg' to the preprocessor, compiler, assembler, bankpack, linker, ihxcheck, or makebin +``` +@anchor sdcc-settings +# sdcc settings +``` +SDCC : mcs51/z80/z180/r2k/r2ka/r3ka/gbz80/tlcs90/ez80_z80/z80n/ds390/pic16/pic14/TININative/ds400/hc08/s08/stm8/pdk13/pdk14/pdk15 4.1.0 #12069 (Linux) +published under GNU General Public License (GPL) +Usage : sdcc [options] filename +Options :- + +General options: + --help Display this help + -v --version Display sdcc's version + --verbose Trace calls to the preprocessor, assembler, and linker + -V Execute verbosely. Show sub commands as they are run + -d Output list of macro definitions in effect. Use with -E + -D Define macro as in -Dmacro + -I Add to the include (*.h) path, as in -Ipath + -A + -U Undefine macro as in -Umacro + -M Preprocessor option + -W Pass through options to the pre-processor (p), assembler (a) or linker (l) + -S Compile only; do not assemble or link + -c --compile-only Compile and assemble, but do not link + -E --preprocessonly Preprocess only, do not compile + --c1mode Act in c1 mode. The standard input is preprocessed code, the output is assembly code. + -o Place the output into the given path resp. file + -x Optional file type override (c, c-header or none), valid until the next -x + --print-search-dirs display the directories in the compiler's search path + --vc messages are compatible with Micro$oft visual studio + --use-stdout send errors to stdout instead of stderr + --nostdlib Do not include the standard library directory in the search path + --nostdinc Do not include the standard include directory in the search path + --less-pedantic Disable some of the more pedantic warnings + --disable-warning <nnnn> Disable specific warning + --Werror Treat the warnings as errors + --debug Enable debugging symbol output + --cyclomatic Display complexity of compiled functions + --std-c89 Use ISO C90 (aka ANSI C89) standard (slightly incomplete) + --std-sdcc89 Use ISO C90 (aka ANSI C89) standard with SDCC extensions + --std-c95 Use ISO C95 (aka ISO C94) standard (slightly incomplete) + --std-c99 Use ISO C99 standard (incomplete) + --std-sdcc99 Use ISO C99 standard with SDCC extensions + --std-c11 Use ISO C11 standard (incomplete) + --std-sdcc11 Use ISO C11 standard with SDCC extensions (default) + --std-c2x Use ISO C2X standard (incomplete) + --std-sdcc2x Use ISO C2X standard with SDCC extensions + --fdollars-in-identifiers Permit '$' as an identifier character + --fsigned-char Make "char" signed by default + --use-non-free Search / include non-free licensed libraries and header files + +Code generation options: + -m Set the port to use e.g. -mz80. + -p Select port specific processor e.g. -mpic14 -p16f84 + --stack-auto Stack automatic variables + --xstack Use external stack + --int-long-reent Use reentrant calls on the int and long support functions + --float-reent Use reentrant calls on the float support functions + --xram-movc Use movc instead of movx to read xram (xdata) + --callee-saves <func[,func,...]> Cause the called function to save registers instead of the caller + --profile On supported ports, generate extra profiling information + --fomit-frame-pointer Leave out the frame pointer. + --all-callee-saves callee will always save registers used + --stack-probe insert call to function __stack_probe at each function prologue + --no-xinit-opt don't memcpy initialized xram from code + --no-c-code-in-asm don't include c-code as comments in the asm file + --no-peep-comments don't include peephole optimizer comments + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + +Optimization options: + --nooverlay Disable overlaying leaf function auto variables + --nogcse Disable the GCSE optimisation + --nolabelopt Disable label optimisation + --noinvariant Disable optimisation of invariants + --noinduction Disable loop variable induction + --noloopreverse Disable the loop reverse optimisation + --no-peep Disable the peephole assembly file optimisation + --no-reg-params On some ports, disable passing some parameters in registers + --peep-asm Enable peephole optimization on inline assembly + --peep-return Enable peephole optimization for return instructions + --no-peep-return Disable peephole optimization for return instructions + --peep-file <file> use this extra peephole file + --opt-code-speed Optimize for code speed rather than size + --opt-code-size Optimize for code size rather than speed + --max-allocs-per-node Maximum number of register assignments considered at each node of the tree decomposition + --nolospre Disable lospre + --allow-unsafe-read Allow optimizations to read any memory location anytime + --nostdlibcall Disable optimization of calls to standard library + +Internal debugging options: + --dump-ast Dump front-end AST before generating i-code + --dump-i-code Dump the i-code structure at all stages + --dump-graphs Dump graphs (control-flow, conflict, etc) + --i-code-in-asm Include i-code as comments in the asm file + --fverbose-asm Include code generator comments in the asm output + +Linker options: + -l Include the given library in the link + -L Add the next field to the library search path + --lib-path <path> use this path to search for libraries + --out-fmt-ihx Output in Intel hex format + --out-fmt-s19 Output in S19 hex format + --xram-loc <nnnn> External Ram start location + --xram-size <nnnn> External Ram size + --iram-size <nnnn> Internal Ram size + --xstack-loc <nnnn> External Stack start location + --code-loc <nnnn> Code Segment Location + --code-size <nnnn> Code Segment size + --stack-loc <nnnn> Stack pointer initial value + --data-loc <nnnn> Direct data start location + --idata-loc + --no-optsdcc-in-asm Do not emit .optsdcc in asm + +Special options for the mcs51 port: + --model-small internal data space is used (default) + --model-medium external paged data space is used + --model-large external data space is used + --model-huge functions are banked, data in external space + --stack-size Tells the linker to allocate this space for stack + --parms-in-bank1 use Bank1 for parameter passing + --acall-ajmp Use acall/ajmp instead of lcall/ljmp + --no-ret-without-call Do not use ret independent of acall/lcall + +Special options for the z80 port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the z180 port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the r2k port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the r2ka port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the r3ka port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the gbz80 port: + -bo <num> use code bank <num> + -ba <num> use data bank <num> + --callee-saves-bc Force a called function to always save BC + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --legacy-banking Use legacy method to call banked functions + +Special options for the tlcs90 port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the ez80_z80 port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the z80n port: + --callee-saves-bc Force a called function to always save BC + --portmode= Determine PORT I/O mode (z80/z180) + --asm= Define assembler name (rgbds/asxxxx/isas/z80asm/gas) + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --dataseg <name> use this name for the data segment + --no-std-crt0 For the z80/gbz80 do not link default crt0.rel + --reserve-regs-iy Do not use IY (incompatible with --fomit-frame-pointer) + --oldralloc Use old register allocator + --fno-omit-frame-pointer Do not omit frame pointer + --emit-externs Emit externs list in generated asm + --legacy-banking Use legacy method to call banked functions + --nmos-z80 Generate workaround for NMOS Z80 when saving IFF2 + +Special options for the ds390 port: + --model-flat24 use the flat24 model for the ds390 (default) + --stack-8bit use the 8bit stack for the ds390 (not supported yet) + --stack-size Tells the linker to allocate this space for stack + --stack-10bit use the 10bit stack for ds390 (default) + --use-accelerator generate code for ds390 arithmetic accelerator + --protect-sp-update will disable interrupts during ESP:SP updates + --parms-in-bank1 use Bank1 for parameter passing + +Special options for the pic16 port: + --pstack-model= use stack model 'small' (default) or 'large' + -y --extended enable Extended Instruction Set/Literal Offset Addressing mode + --pno-banksel do not generate BANKSEL assembler directives + --obanksel= set banksel optimization level (default=0 no) + --denable-peeps explicit enable of peepholes + --no-optimize-goto do NOT use (conditional) BRA instead of GOTO + --optimize-cmp try to optimize some compares + --optimize-df thoroughly analyze data flow (memory and time intensive!) + --asm= Use alternative assembler + --mplab-comp enable compatibility mode for MPLAB utilities (MPASM/MPLINK) + --link= Use alternative linker + --preplace-udata-with= Place udata variables at another section: udata_acs, udata_ovr, udata_shr + --ivt-loc= Set address of interrupt vector table. + --nodefaultlibs do not link default libraries when linking + --use-crt= use <crt-o> run-time initialization module + --no-crt do not link any default run-time initialization module + --debug-xtra show more debug info in assembly output + --debug-ralloc dump register allocator debug file *.d + --pcode-verbose dump pcode related info + --calltree dump call tree in .calltree file + --gstack trace stack pointer push/pop to overflow + --no-warn-non-free suppress warning on absent --use-non-free option + +Special options for the pic14 port: + --debug-xtra show more debug info in assembly output + --no-pcode-opt disable (slightly faulty) optimization on pCode + --stack-size sets the size if the argument passing stack (default: 16, minimum: 4) + --no-extended-instructions forbid use of the extended instruction set (e.g., ADDFSR) + --no-warn-non-free suppress warning on absent --use-non-free option + +Special options for the TININative port: + --model-flat24 use the flat24 model for the ds390 (default) + --stack-8bit use the 8bit stack for the ds390 (not supported yet) + --stack-size Tells the linker to allocate this space for stack + --stack-10bit use the 10bit stack for ds390 (default) + --use-accelerator generate code for ds390 arithmetic accelerator + --protect-sp-update will disable interrupts during ESP:SP updates + --parms-in-bank1 use Bank1 for parameter passing + --tini-libid <nnnn> LibraryID used in -mTININative + +Special options for the ds400 port: + --model-flat24 use the flat24 model for the ds400 (default) + --stack-8bit use the 8bit stack for the ds400 (not supported yet) + --stack-size Tells the linker to allocate this space for stack + --stack-10bit use the 10bit stack for ds400 (default) + --use-accelerator generate code for ds400 arithmetic accelerator + --protect-sp-update will disable interrupts during ESP:SP updates + --parms-in-bank1 use Bank1 for parameter passing + +Special options for the hc08 port: + --model-small 8-bit address space for data + --model-large 16-bit address space for data (default) + --out-fmt-elf Output executable in ELF format + --oldralloc Use old register allocator + +Special options for the s08 port: + --model-small 8-bit address space for data + --model-large 16-bit address space for data (default) + --out-fmt-elf Output executable in ELF format + --oldralloc Use old register allocator + +Special options for the stm8 port: + --model-medium 16-bit address space for both data and code (default) + --model-large 16-bit address space for data, 24-bit for code + --codeseg <name> use this name for the code segment + --constseg <name> use this name for the const segment + --out-fmt-elf Output executable in ELF format +``` +@anchor sdasgb-settings +# sdasgb settings +``` + +sdas Assembler V02.00 + NoICE + SDCC mods (GameBoy Z80-like CPU) + + +Copyright (C) 2012 Alan R. Baldwin +This program comes with ABSOLUTELY NO WARRANTY. + +Usage: [-Options] file +Usage: [-Options] outfile file1 [file2 file3 ...] + -d Decimal listing + -q Octal listing + -x Hex listing (default) + -g Undefined symbols made global + -a All user symbols made global + -b Display .define substitutions in listing + -bb and display without .define substitutions + -c Disable instruction cycle count in listing + -j Enable NoICE Debug Symbols + -y Enable SDCC Debug Symbols + -l Create list file/outfile[.lst] + -o Create object file/outfile[.rel] + -s Create symbol file/outfile[.sym] + -p Disable automatic listing pagination + -u Disable .list/.nlist processing + -w Wide listing format for symbol table + -z Disable case sensitivity for symbols + -f Flag relocatable references by ` in listing file + -ff Flag relocatable references by mode in listing file + -I Add the named directory to the include file + search path. This option may be used more than once. + Directories are searched in the order given. + +removing +``` +@anchor bankpack-settings +# bankpack settings +``` +bankalloc [options] objfile1 objfile2 etc +Use: Read .o files and auto-assign areas with bank=255. + Typically called by Lcc compiler driver before linker. + +Options +-h : Show this help +-yt<hexbyte> : Set MBC type per ROM byte 149 in Hex (see pandocs) +-mbc=N : Similar to -yt, but sets MBC type directly to N instead + of by intepreting ROM byte 149 + mbc1 will exclude banks {0x20,0x40,0x60} max=127, + mbc2 max=15, mbc3 max=127, mbc5 max=255 (not 511!) +-min=N : Min assigned ROM bank is N (default 1) +-max=N : Max assigned ROM bank is N, error if exceeded +-ext=<.ext> : Write files out with <.ext> instead of source extension +-path=<path> : Write files out to <path> (<path> *MUST* already exist) +-sym=<prefix>: Add symbols starting with <prefix> to match + update list. + Default entry is "___bank_" (see below) +-cartsize : Print min required cart size as "autocartsize:<NNN>" +-v : Verbose output, show assignments + +Example: "bankpack -ext=.rel -path=some/newpath/ file1.o file2.o" +Unless -ext or -path specify otherwise, input files are overwritten. + +Default MBC type is not set. It *must* be specified by -mbc= or -yt! + +The following will have FF and 255 replaced with the assigned bank: +A _CODE_255 size <size> flags <flags> addr <address> +S b_<function name> Def0000FF +S ___bank_<const name> Def0000FF + (Above can be made by: const void __at(255) __bank_<const name>; +``` +@anchor sdldgb-settings +# sdldgb settings +``` + +sdld Linker V03.00 + NoICE + sdld + +Usage: [-Options] [-Option with arg] file +Usage: [-Options] [-Option with arg] outfile file1 [file2 ...] +Startup: + -p Echo commands to stdout (default) + -n No echo of commands to stdout +Alternates to Command Line Input: + -c ASlink >> prompt input + -f file[.lk] Command File input +Libraries: + -k Library path specification, one per -k + -l Library file specification, one per -l +Relocation: + -b area base address = expression + -g global symbol = expression +Map format: + -m Map output generated as (out)file[.map] + -w Wide listing format for map file + -x Hexadecimal (default) + -d Decimal + -q Octal +Output: + -i Intel Hex as (out)file[.ihx] + -s Motorola S Record as (out)file[.s19] + -j NoICE Debug output as (out)file[.noi] + -y SDCDB Debug output as (out)file[.cdb] +List: + -u Update listing file(s) with link data as file(s)[.rst] +Case Sensitivity: + -z Disable Case Sensitivity for Symbols +End: + -e or null line terminates input + +``` +@anchor ihxcheck-settings +# ihxcheck settings +``` +ihx_check input_file.ihx [options] + +Options +-h : Show this help +-e : Treat warnings as errors + +Use: Read a .ihx and warn about overlapped areas. +Example: "ihx_check build/MyProject.ihx" +``` +@anchor makebin-settings +# makebin settings +``` +makebin: convert a Intel IHX file to binary or GameBoy format binary. +Usage: makebin [options] [<in_file> [<out_file>]] +Options: + -p pack mode: the binary file size will be truncated to the last occupied byte + -s romsize size of the binary file (default: rom banks * 16384) + -Z genarate GameBoy format binary file +GameBoy format options (applicable only with -Z option): + -yo n number of rom banks (default: 2) (autosize: A) + -ya n number of ram banks (default: 0) + -yt n MBC type (default: no MBC) + -yl n old licensee code (default: 0x33) + -yk cc new licensee string (default: 00) + -yn name cartridge name (default: none) + -yc GameBoy Color compatible + -yC GameBoy Color only + -ys Super GameBoy + -yS Convert .noi file named like input file to .sym + -yj set non-Japanese region flag + -yp addr=value Set address in ROM to given value (address 0x100-0x1FE) +Arguments: + <in_file> optional IHX input file, '-' means stdin. (default: stdin) + <out_file> optional output file, '-' means stdout. (default: stdout) +``` +@anchor gbcompress-settings +# gbcompress settings +``` +gbcompress [options] infile outfile +Use: Gbcompress a binary file and write it out. + +Options +-h : Show this help screen +-d : Decompress (default is compress) +-v : Verbose output +Example: "gbcompress binaryfile.bin compressed.bin" +Example: "gbcompress -d compressedfile.bin decompressed.bin" +``` +@anchor png2mtspr-settings +# png2mtspr settings +``` +usage: png2mtspr <file>.png [options] +-c ouput file (default: <png file>.c) +-sw <width> metasprites width size (default: png width) +-sh <height> metasprites height size (default: png height) +-px <x coord> metasprites pivot x coordinate (default: metasprites width / 2) +-py <y coord> metasprites pivot y coordinate (default: metasprites height / 2) +-spr8x8 use SPRITES_8x8 (default: SPRITES_8x16) +-spr8x16 use SPRITES_8x16 (default: SPRITES_8x16) +-b <bank> bank (default 0) +``` diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md @@ -11,6 +11,7 @@ - @subpage docs_faq - @subpage docs_migrating_versions - @subpage docs_releases +- @subpage docs_toolchain_settings diff --git a/gbdk-lib/examples/gb/gbdecompress/Readme.md b/gbdk-lib/examples/gb/gbdecompress/Readme.md @@ -1,3 +1,8 @@ +GBDecompress +============ + Demonstrates using gbdecompress to load a compressed tile set into vram. +The tileset was compressed during export from GBTD by checking the +GB-compress checkbox in the export settings panel. diff --git a/gbdk-lib/examples/gb/large_map/Readme.md b/gbdk-lib/examples/gb/large_map/Readme.md @@ -0,0 +1,14 @@ + +Large Map +========= + +Shows how to scroll with maps larger than 32 x 32 tiles using set_bkg_submap(). + +It fills rows and columns at the edges of the visible viewport (of the hardware +Background Map) with the desired sub-region of the large map as it scrolls. + + +Overworld Map and Tiles are by ArMM1998: +https://opengameart.org/content/gameboy-tileset +License(s): CC0 + diff --git a/gbdk-lib/examples/gb/metasprites/Makefile b/gbdk-lib/examples/gb/metasprites/Makefile @@ -21,6 +21,9 @@ make.bat: Makefile @make -sn | sed y/\\//\\\\/ | grep -v make >> make.bat # Use png2mtspr to convert the png into C formatted metasprite data +# -sh 48 : Sets sprite height to 48 (width remains automatic) +# -spr8x16 : Use 8x16 hardware sprites +# -c ... : Set C output file %.c: %.png $(PNG2MTSPR) $< -sh 48 -spr8x16 -c $@ diff --git a/gbdk-lib/examples/gb/metasprites/Readme.md b/gbdk-lib/examples/gb/metasprites/Readme.md @@ -1,11 +1,13 @@ -Metasprite example +Metasprite Example ================== -* Press A button to show/hide the metasprite +Demonstrates using the metasprite features to move and animate a large sprite. + +* Press A button to show / hide the metasprite * Press B button to cycle through the metasprite animations -* Press SELECT button to cycle the metasprite through Normal/Flip-Y/Flip-XY/Flip-X -* Up/Down/Left/Right to move the metasprite +* Press SELECT button to cycle the metasprite through Normal / Flip-Y / Flip-XY / Flip-X +* Up / Down / Left / Right to move the metasprite In this example the move_metasprite...() functions are called every frame to simplify the example code, regardless of whether the updates diff --git a/gbdk-lib/include/gb/drawing.h b/gbdk-lib/include/gb/drawing.h @@ -11,6 +11,10 @@ Note: Using drawing.h will cause it's custom VBL and LCD ISRs (`drawing_vbl` and `drawing_lcd`) to be installed. + The valid coordinate ranges are from (x,y) 0,0 to 159,143. + There is no built-in clipping, so drawing outside valid + coordinates will likely produce undesired results (wrapping/etc). + ---- __Important note for the drawing API :__ diff --git a/gbdk-lib/include/gb/gbdecompress.h b/gbdk-lib/include/gb/gbdecompress.h @@ -1,4 +1,4 @@ -/** @file gb/gbcompress.h +/** @file gb/gbdecompress.h GB-Compress decompressor Compatible with the compression used in GBTD diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -16,7 +16,7 @@ to be in the upper left-hand corner as with regular hardware sprites. - Use the @ref png2mtspr utility to convert single + Use the @ref utility_png2mtspr tool to convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.