gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit a41adc069ef10dc9b2d7620315dba62fd7cbc44b parent 17dadbc67f8adbe298b704ddf7b6ea6b719964d8 Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Fri, 5 Feb 2021 11:06:25 +0300 Merge pull request #127 from bbbbbr/docs_merge Docs updates Diffstat:
| M | docs/pages/banking_mbcs.md | 25 | +++++++++++++++++++------ |
| M | docs/pages/links_and_tools.md | 9 | +++++++++ |
| M | docs/pages/toolchain.md | 9 | +++++++++ |
| M | gbdk-lib/examples/gb/banks_autobank/Makefile | 24 | ++++++++++++++++++------ |
| D | gbdk-lib/include/Makefile | 14 | -------------- |
| D | gbdk-lib/include/libc.dox | 5 | ----- |
6 files changed, 55 insertions(+), 31 deletions(-)
diff --git a/docs/pages/banking_mbcs.md b/docs/pages/banking_mbcs.md @@ -123,14 +123,15 @@ Note: You can only do a switch_rom_bank call from unbanked `_CODE` since otherwi ## Bank switching inside an Interrupt Service Routine (ISR) -If a banked function call is made inside an ISR, then the @ref _current_bank variable should be saved and then restored. +If a function call is made inside an ISR which changes the bank *without* restoring it, then the @ref _current_bank variable should be saved and then restored. For example, __instead__ of this code: ``` void vbl_music_isr(void) { - // some_banked_function() causes the bank to change - some_banked_function(); + // A function which changes the bank and + // *doesn't* restore it after changing. + some_function(); } ``` It should be: @@ -140,8 +141,9 @@ void vbl_music_isr(void) // Save the current bank UBYTE _saved_bank = _current_bank; - // some_banked_function() causes the bank to change - some_banked_function(); + // A function which changes the bank and + // *doesn't* restore it after changing. + some_function(); // Now restore the current bank SWITCH_ROM_MBC5(_saved_bank); @@ -182,9 +184,20 @@ Accessing that data: main.c Features and Notes: - Fixed banked source files can be used in the same project as auto-banked source files. The bankpack tool will attempt to pack the auto-banked source files as efficiently as possible around the fixed-bank ones. - - Sometimes a `clean rebuild` of a project may be needed to reorganize and sort the banks. This is because an auto-banked source file will remain in the same bank until it is re-compiled (due to changes or due to a `clean build`). An example of when this might happen is a fixed-bank source file growing too large to share a bank with an auto-banked source file that was previously assigned to it. + +Making sure bankpack checks all files: + - In order to correctly calculate the bank for all files every time, it is best to use the `-ext=` flag and save the auto-banked output to a different extension (such as `.rel`) and then pass the modified files to the linker. That way all object files will be processed each time the program is compiled. + + Recommended: + .c and .s -> (compiler) .o -> (bankpack) -> .rel -> (linker) ... -> .gb + + - It is important because when bankpack assigns a bank for an autobanked (bank=255) object file (.o) it rewrites the bank and will then no longer see the file as one that needs to be auto-banked. That file will then remain in it's previously assigned bank until a source change causes the compiler to rebuild it to an object file again which resets it's bank to 255. + + - For example consider a fixed-bank source file growing too large to share a bank with an auto-banked source file that was previously assigned to it. To avoid a bank overflow it would be important to have the auto-banked file check every time whether it can share that bank or not. + - See @ref bankpack for more options and settings + Limitations: - At this time, the constant entries that get rewritten with the assigned bank (const void __at(255) __bank_<name-you-want-to-use-for-that-source-file>;) __cannot__ be used from the source file they are declared in. In that case SDCC converts the bank number before @ref bankpack has a chance to rewrite it. It may be referenced from any other source file, but not it's own. diff --git a/docs/pages/links_and_tools.md b/docs/pages/links_and_tools.md @@ -23,6 +23,15 @@ This is a brief list of useful tools and information. It is not meant to be comp https://gbdev.io/list.html +@anchor links_tutorials +# Tutorials + - @anchor tutorials_gamingmonsters + __Gaming Monsters Tutorials__ + Several video tutorials and code for making games with GBDK/GBDK-2020. + https://www.youtube.com/playlist?list=PLeEj4c2zF7PaFv5MPYhNAkBGrkx4iPGJo + https://github.com/gingemonster/GamingMonstersGameBoySampleCode + + @anchor links_graphic # Graphics Tools - @anchor gbmb diff --git a/docs/pages/toolchain.md b/docs/pages/toolchain.md @@ -30,6 +30,15 @@ To see individual arguments and options for a tool, run that tool from the comma - How do I set the ROM @ref MBC type? - See @ref setting_mbc_and_rom_ram_banks + <!-- --> + +- 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)` + + You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by @ref ihxcheck during conversion of an .ihx file into a ROM file. + + See the section @ref docs_rombanking_mbcs for more details about how banks work and what their size is. You may want to use a tool such as @ref romusage to calculate the amount of free and used space. @anchor toolchain_changing_important_addresses diff --git a/gbdk-lib/examples/gb/banks_autobank/Makefile b/gbdk-lib/examples/gb/banks_autobank/Makefile @@ -5,8 +5,19 @@ CFLAGS = -DGBDK_2_COMPAT BINS = autobanks.gb CSOURCES := $(wildcard *.c) ASMSOURCES := $(wildcard *.s) + +# Compiling will produce .o files OBJS = $(CSOURCES:%.c=%.o) $(ASMSOURCES:%.c=%.o) +# Process: .c and .s files -> .o -> (bankpack) -> .rel -> (linker) ... -> .gb +# +# In this makefile autobanked .o files get saved as .rel files (-Wb-ext=.rel) +# which will be passed to the linker instead of .o files. +# +# This allows correct packing every time, even +# for source files that don't get re-compiled. +OBJS_AUTOBANKED = $(CSOURCES:%.c=%.rel) $(ASMSOURCES:%.c=%.rel) + all: $(BINS) make.bat: Makefile @@ -23,13 +34,14 @@ make.bat: Makefile $(CC) $(CFLAGS) -S -o $@ $< # Link the compiled object files into a autobanks.gb ROM file -# -autobank : turns on auto banking -# -Wb-v : prints out assigned bank info -# -Wl-yo4 : Use 4 ROM banks -# -Wl-ya4 : Use 4 RAM banks -# -Wl-yt19 : Use MBC5 cartridge type +# -autobank : turns on auto banking +# -Wb-v : prints out assigned bank info +# -Wb-ext=.rel : set output extension for autobanked files to .rel +# -Wl-yo4 : Use 4 ROM banks +# -Wl-ya4 : Use 4 RAM banks +# -Wl-yt19 : Use MBC5 cartridge type $(BINS): $(OBJS) - $(CC) $(CFLAGS) -autobank -Wb-v -Wl-yt19 -Wl-yo4 -Wl-ya4 -o $(BINS) $(OBJS) + $(CC) $(CFLAGS) -autobank -Wb-ext=.rel -Wb-v -Wl-yt19 -Wl-yo4 -Wl-ya4 -o $(BINS) $(OBJS_AUTOBANKED) # ./romusage autobanks.map -g clean: diff --git a/gbdk-lib/include/Makefile b/gbdk-lib/include/Makefile @@ -1,14 +0,0 @@ -VER = 2.94 - -doc: - mkdir -p ../doc - doxygen libc.dox - make -C ../doc/libc/latex pdf - -dist: - mkdir -p ../build/doc - cd ../doc/libc; tar czf ../../build/doc/gbdk-doc-html-$(VER).tar.gz html - cp ../doc/libc/latex/refman.pdf ../build/doc/gbdk-doc-$(VER).pdf - gzip ../build/doc/gbdk-doc-$(VER).pdf - (cd ../doc/libc; tar cf - html) | (cd ../build/doc; tar xf -) - diff --git a/gbdk-lib/include/libc.dox b/gbdk-lib/include/libc.dox @@ -1,5 +0,0 @@ -PROJECT_NAME = "gbdk-lib" -OUTPUT_DIRECTORY = "../doc/libc" -RECURSIVE = yes -INPUT = . -PREDEFINED = "NONBANKED= BANKED="
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.