Added submodule filesHEADmaster

13 files changed, 2821 insertions, 0 deletions

diff --git a/gbdk/docs/pages/01_getting_started.md b/gbdk/docs/pages/01_getting_started.md
new file mode 100644
index 00000000..435f9824
--- /dev/null
+++ b/gbdk/docs/pages/01_getting_started.md
@@ -0,0 +1,146 @@
+@page docs_getting_started Getting Started
+
+
+Follow the steps in this section to start using GBDK-2020.
+
+# 1. Download a Release and unzip it
+You can get the latest releases from here: https://github.com/gbdk-2020/gbdk-2020/releases
+
+
+# 2. Compile Example projects
+Make sure your GBDK-2020 installation is working correctly by compiling some of the included @ref docs_example_programs "example projects".
+
+If everything works in the steps below and there are no errors reported then each project that was built should have its own .gb ROM file (or suitable extension for the other supported targets).
+
+## Windows (without Make installed):
+Navigate to a project within the example projects folder (`"examples\gb\"` under your GBDK-2020 install folder) and open a command line. Then type:
+
+    compile
+
+or
+
+    compile.bat
+
+This should build the example project. You can also navigate into other example project folders and build in the same way.
+
+
+## Linux / MacOS / Windows with Make installed:
+Navigate to the example projects folder (`"examples/gb/"` under your GBDK-2020 install folder) and open a command line. Then type:
+
+    make
+
+This should build all of the examples sequentially. You can also navigate into an individual example project's folder and build it by typing `make`.
+
+
+# 3. Use a Template
+__To create a new project use a template!__ 
+
+There are template projects included in the @ref docs_example_programs "GBDK example projects" to help you get up and running. Their folder names start with `template_`.
+
+1. Copy one of the template folders to a new folder name.
+
+2. If you moved the folder out of the GBDK examples then you __must__ update the `GBDK` path variable and/or the path to `LCC` in the `Makefile` or `compile.bat` so that it will still build correctly.
+
+3. Type `make` on the command line in that folder to verify it still builds.
+
+4. Open main.c to start making changes.
+
+
+# 4. If you use GBTD / GBMB, get the fixed version
+If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the `const` fix and other improvements. See @ref const_gbtd_gbmb.
+
+
+# 5. Review Coding Guidelines
+Take a look at the @ref docs_coding_guidelines "coding guidelines", even if you have experience writing software for other platforms. There is important information to help you get good results and performance on the Game Boy.
+
+If you haven't written programs in C before, check the @ref docs_c_tutorials "C tutorials section".
+
+
+# 6. Hardware and Resources
+If you have a specific project in mind, consider what hardware want to target. It isn't something that has to be decided up front, but it can influence design and implementation.
+
+What size will your game or program be?
+  - 32K Cart (no-MBC required)
+  - Larger than 32K (MBC required)
+  - See more details about @ref docs_rombanking_mbcs "ROM Banking and MBCs"
+
+What console platform(s) will it run on?
+  - Game Boy (GB/GBC)
+  - Analogue Pocket (AP)
+  - Sega Master System (SMS)
+  - Game Gear (GG)
+  - Mega Duck (DUCK)
+  - See @ref docs_supported_consoles
+
+If targeting the Game Boy, what hardware will it run on?
+  - Game Boy (& Game Boy Color)
+  - Game Boy Color only
+  - Game Boy & Super Game Boy
+  - See how to @ref faq_gb_type_header_setting "set the compatibility type in the cartridge header". Read more about hardware differences in the @ref Pandocs
+
+
+# 7. Set up C Source debugging
+Tracking down problems in code is easier with a debugger. Emulicious has a @ref Emulicious_debug "debug adapter" that provides C source debugging with GBDK-2020.
+
+
+# 8. Try a GBDK Tutorial
+You might want to start off with a guided GBDK tutorial from the @ref links_gbdk_tutorials "GBDK Tutorials section".
+
+  - __Note:__ Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principles are all the same, but the setup and parts of the @ref docs_toolchain "toolchain" (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools).
+
+
+# 9. Read up!
+- It is strongly encouraged to read more @ref docs_index "GBDK-2020 General Documentation".
+- Learn about the Game Boy hardware by reading through the @ref Pandocs technical reference.
+
+
+# 10. Need help?
+Check out the links for @ref links_help_and_community "online community and support" and read the @ref docs_faq "FAQ".
+
+
+
+# Migrating From Pre-GBDK-2020 Tutorials
+Several popular GBDK Tutorials, Videos and How-to's were made before GBDK-2020 was available, as a result some information they include is outdated or incompatible. The following summarizes changes that should be made for best results.
+
+## Also see: 
+- @ref docs_migrating_versions
+- @ref docs_coding_guidelines
+- @ref docs_getting_started (the section above this)
+
+## Use auto-banking
+GBDK-2020 now supports auto-banking (@ref rom_autobanking). In most cases using auto-banking will be easier and less error prone than manually assigning source and assets to banks.
+- There is a source example `banks_autobank` project.
+
+## Non-standard types (UINT8, etc)
+The old GBDK types `UINT8`, `INT8`, `UINT16`, `INT16` are non-standard and less portable.
+
+The following should be used instead: `uint8_t`, `int16_t`, `uint16_t`, `int32_t`, `uint32_t` and `bool`.
+
+These are standard types defined in `stdint.h` (`#include <stdint.h>`) and `stdbool.h` (`#include <stdbool.h>`).
+
+## If using GBTD / GBMB, get the fixed version
+If you plan to use GBTD / GBMB for making graphics, make sure to get the version with the `const` fix and other improvements. See @ref const_gbtd_gbmb.
+
+## LCC and SDCC flags that are not needed
+The following flag is no longer needed with @ref lcc and @ref sdcc, it can be removed without any loss of performance.
+- `-DUSE_SFR`
+   - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). Check here why: https://gbdev.gg8.se/forums/viewtopic.php?id=697
+
+## ROM Header Settings (such as Color, SGB, etc)
+Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. See @ref faq_gb_type_header_setting.
+
+## GBDK Header include changes
+The following header files which are now cross platform were moved from `gb/` to `gbdk/`: `bcd.h`, `console.h`, `far_ptr.h`, `font.h`, `gbdecompress.h`, `gbdk-lib.h`, `incbin.h`, `metasprites.h`, `platform.h`, `version.h`
+- When including them use `#include <gbdk/...>` instead of `#include <gb/>`
+
+## Include .h headers, not .c source files
+Do not `#include` `.c` source files into other `.c` source files. Instead create `.h` header files for them and include those.
+- https://www.tutorialspoint.com/cprogramming/c_header_files.htm
+
+## Use the Template Projects
+Modern project templates are included with GBDK-2020. Using them (and their Makefile or compile.bat) as a starting point for projects is recommended and can help ensure better default settings and project organization.
+
+## Use hUGEtracker instead of gbt_player
+hUGEtracker and its driver @ref hUGEdriver are smaller, more efficient and more versatile than gbt_player.
+    
+
diff --git a/gbdk/docs/pages/02_links_and_tools.md b/gbdk/docs/pages/02_links_and_tools.md
new file mode 100644
index 00000000..00efbc64
--- /dev/null
+++ b/gbdk/docs/pages/02_links_and_tools.md
@@ -0,0 +1,151 @@
+@page docs_links_and_tools Links and Third-Party Tools
+
+
+This is a brief list of useful tools and information. It is not meant to be complete or exhaustive, for a larger list see the @ref awesome_gb "Awesome Game Boy Development" list.
+
+@anchor links_sdcc_docs
+# SDCC Compiler Suite User Manual
+  - GBDK-2020 uses the SDCC compiler and related tools. The SDCC manual goes into much more detail about available features and how to use them.  
+  http://sdcc.sourceforge.net/doc/sdccman.pdf  
+  http://sdcc.sourceforge.net
+
+
+@anchor links_help_and_community
+# Getting Help
+  - GBDK Discord community:  
+  https://github.com/gbdk-2020/gbdk-2020/#discord-servers
+
+  - Game Boy discussion forum:  
+  https://gbdev.gg8.se/forums/
+
+
+@anchor links_gameboy_docs
+# Game Boy Documentation
+  - @anchor Pandocs
+    __Pandocs__  
+    Extensive and up-to-date technical documentation about the Game Boy and related hardware.  
+    https://gbdev.io/pandocs/
+
+  - @anchor awesome_gb
+    __Awesome Game Boy Development list__  
+    A list of Game Boy/Color development resources, tools, docs, related projects and homebrew.  
+    https://gbdev.io/list.html
+
+
+@anchor links_sms_gg_docs
+# Sega Master System / Game Gear Documentation
+  - @anchor smspower
+    __SMS Power!__  
+    Community site with technical documentation, reviews and other content related to the Sega 8-bit systems.  
+    https://www.smspower.org/
+
+
+@anchor links_gbdk_tutorials
+# Tutorials
+  - @anchor tutorials_larolds
+    __Larold's Jubilant Junkyard  Tutorials__      
+    Several walk throughs about the fundamentals of developing for the Game Boy with GBDK-2020. There are simple examples with source code.  
+    https://laroldsjubilantjunkyard.com/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 tutorials_typorter
+    __Pocket Leage Tutorial__  
+    https://blog.ty-porter.dev/development/2021/04/04/writing-a-gameboy-game-in-2021-pt-0.html
+
+
+@anchor link_examples
+# Example code
+  - @anchor examples_gbdk_playground
+    __Simplified GBDK examples__  
+    https://github.com/mrombout/gbdk_playground/commits/master
+
+
+@anchor links_graphic
+# Graphics Tools
+  - @anchor gbtd_gbmb
+    @anchor gbmb
+    @anchor gbtd     
+    @anchor toxa_gbtd_gbmb
+    __Game Boy Tile Designer and Map Builder (GBTD / GBMB)__  
+    Sprite / Tile editor and Map Builder that can export to C that works with GBDK.  
+    This is an updated version with const export fixed and other improvements.  
+    https://github.com/gbdk-2020/GBTD_GBMB
+ 
+      - A GIMP plugin to read/write GBR/GBM files and do map conversion:  
+        https://github.com/bbbbbr/gimp-tilemap-gb
+      - Command line version of the above tool that doesn't require GIMP (png2gbtiles):  
+        https://github.com/bbbbbr/gimp-tilemap-gb/tree/master/console
+
+  - @anchor Tilemap_Studio
+    __Tilemap Studio__  
+    A tilemap editor for Game Boy, GBC, GBA, or SNES projects.  
+    https://github.com/Rangi42/tilemap-studio/
+
+
+@anchor tools_music
+# Music drivers and tools
+  - @anchor gbt-player
+    __GBT Player__  
+    A .mod converter and music driver that works with GBDK and RGBDS.  
+    https://github.com/AntonioND/gbt-player  
+    Docs from GBStudio that should mostly apply: https://www.gbstudio.dev/docs/music/
+
+
+  - @anchor hUGEdriver
+    __hUGEtracker__ and __hUGEdriver__  
+    A tracker and music driver that work with GBDK and RGBDS.
+    It is smaller, more efficient and more versatile than gbt_player.  
+    https://github.com/untoxa/hUGEBuild  
+    https://github.com/SuperDisk/hUGEDriver  
+    https://github.com/SuperDisk/hUGETracker
+
+
+@anchor tools_emulators
+# Emulators
+  - @anchor bgb
+    __BGB__  
+    Accurate emulator, has useful debugging tools.  
+    http://bgb.bircd.org/
+
+  - @anchor emulicious
+    __Emulicious__  
+    An accurate emulator with extensive tools including source level debugging.  
+    https://emulicious.net/
+
+
+@anchor tools_debug
+# Debugging tools
+  - @anchor Emulicious_debug
+    __Emulicious debug adapter__  
+    Provides source-level debugging in VS Code that works with GBDK2020.  
+    https://marketplace.visualstudio.com/items?itemName=emulicious.emulicious-debugger
+
+  - @anchor romusage
+    __romusage__  
+    Calculate used and free space in banks (ROM/RAM) and warn about errors such as bank overflows.  
+    https://github.com/bbbbbr/romusage
+
+  - @anchor bgb_symbol_conversion
+    __noi file to sym conversion for bgb__  
+    Debug information in .noi files can be converted to a symbol format that @ref bgb "BGB" recognizes using:
+    - @ref lcc : `-Wm-yS` (with `--debug`, or `-Wl-j` to create the .noi)
+    - directly with @ref makebin : `-yS` (with `-j` passed to the linker)
+
+  - @anchor src2sym
+    __src2sym.pl__  
+    Add line-by-line C source code to the main symbol file in a BGB compatible format. This allows for C source-like debugging in BGB in a limited way.
+    https://gbdev.gg8.se/forums/viewtopic.php?id=710
+
+
+@anchor tools_build_ci_cd
+# Continuous Integration and Deployment
+  - @anchor GBDK_GitHub_Action_Builder
+    __GBDK GitHub Action Builder__  
+    A Github Action which provides basic CI/CD for building projects based on GBDK (not for building GBDK itself).  
+    https://github.com/wujood/gbdk-2020-github-builder
+    
diff --git a/gbdk/docs/pages/03_using_gbdk.md b/gbdk/docs/pages/03_using_gbdk.md
new file mode 100644
index 00000000..ec464ca5
--- /dev/null
+++ b/gbdk/docs/pages/03_using_gbdk.md
@@ -0,0 +1,173 @@
+@page docs_using_gbdk Using GBDK
+
+
+# Interrupts
+Interrupts allow execution to jump to a different part of your code as soon as an external event occurs - for example the LCD entering the vertical blank period, serial data arriving or the timer reaching its end count. For an example see the irq.c sample project.
+
+Interrupts in GBDK are handled using the functions @ref disable_interrupts(), @ref enable_interrupts(), @ref set_interrupts(uint8_t ier) and the interrupt service routine (ISR) linkers @ref add_VBL(), @ref add_TIM, @ref add_LCD, @ref add_SIO and @ref add_JOY which add interrupt handlers for the vertical blank, timer, LCD, serial link and joypad interrupts respectively.
+
+Since an interrupt can occur at any time an Interrupt Service Request (ISR) cannot take any arguments or return anything. Its only way of communicating with the greater program is through the global variables. When interacting with those shared ISR global variables from main code outside the interrupt, it is a good idea to wrap them in a `critical {}` section in case the interrupt occurs and modifies the variable while it is being used.
+
+Interrupts should be disabled before adding ISRs. To use multiple interrupts, _logical OR_ the relevant IFLAGs together.
+
+ISRs should be kept as small and short as possible, do not write an ISR so long that the Game Boy hardware spends all of its time servicing interrupts and has no time spare for the main code.
+
+For more detail on the Game Boy interrupts consider reading about them in the @ref Pandocs.
+
+## Available Interrupts
+The GameBoy hardware can generate 5 types of interrupts. Custom Interrupt Service Routines (ISRs) can be added in addition to the built-in ones available in GBDK.
+
+  - VBL : LCD Vertical Blanking period start
+    - The default VBL ISR is installed automatically.
+      - See @ref add_VBL() and @ref remove_VBL()
+
+  - LCD : LCDC status (such as the start of a horizontal line)
+    - See @ref add_LCD() and @ref remove_LCD()
+    - Example project: `lcd_isr_wobble`
+
+  - TIM : Timer overflow
+    - See @ref add_TIM() and @ref remove_TIM()
+    - Example project: `tim`
+
+  - SIO : Serial Link I/O transfer end
+    - The default SIO ISR gets installed automatically if any of the standard SIO calls are used. These calls include add_SIO(), remove_SIO(), send_byte(), receive_byte().
+    - The default SIO ISR cannot be removed once installed. Only secondary chained SIO ISRs (added with add_SIO() ) can be removed.
+    - See @ref add_SIO() and @ref remove_SIO()
+    - Example project: `comm`
+
+  - JOY : Transition from high to low of a joypad button
+      - See @ref add_JOY() and @ref remove_JOY()
+
+## Adding your own interrupt handler
+It is possible to install your own interrupt handlers (in C or in assembly) for any of these interrupts. Up to 4 chained handlers may be added, with the last added being called last. If the remove_VBL() function is to be called, only three may be added for VBL.
+
+Interrupt handlers are called in sequence. To install a new interrupt handler, do the following:
+
+  1. Write a function (say foo()) that takes no parameters, and that returns nothing. Remember that the code executed in an interrupt handler must be short.
+  2. Inside a `__critical { ... }` section, install your interrupt handling routines using the add_XXX() function, where XXX is the interrupt that you want to handle.
+  3. Enable interrupts for the IRQ you want to handle, using the set_interrupts() function. Note that the VBL interrupt is already enabled before the main() function is called. If you want to set the interrupts before main() is called, you must install an initialization routine.
+
+See the `irq` example project for additional details for a complete example.
+
+## Using your own Interrupt Dispatcher
+If you want to use your own Interrupt Dispatcher instead of the GBDK chained dispatcher (for improved performance), then don't call the `add_...()` function for the respective interrupt and its dispatcher won't be installed.
+  - Exception: the VBL dispatcher will always be linked in at compile time.
+  - For the SIO interrupt, also do not make any standard SIO calls to avoid having its dispatcher installed.
+
+Then, @ref ISR_VECTOR() or @ref ISR_NESTED_VECTOR() can be used to install a custom ISR handler.
+
+## Returning from Interrupts and STAT mode
+By default when an Interrupt handler completes and is ready to exit it will check STAT_REG and only return at the BEGINNING of either LCD Mode 0 or Mode 1. This helps prevent graphical glitches caused when an ISR interrupts a graphics operation in one mode but returns in a different mode for which that graphics operation is not allowed.
+
+You can change this behavior using nowait_int_handler() which does not check @ref STAT_REG before returning. Also see @ref wait_int_handler().
+
+
+# What GBDK does automatically and behind the scenes
+
+## OAM (VRAM Sprite Attribute Table)
+GBDK sets up a Shadow OAM which gets copied automatically to the hardware OAM by the default V-Blank ISR. The Shadow OAM allows updating sprites without worrying about whether it is safe to write to them or not based on the hardware LCD mode.
+
+## Font tiles when using stdio.h
+Including @ref stdio.h and using functions such as @ref printf() will use a large number of the background tiles for font characters. If stdio.h is not included then that space will be available for use with other tiles instead.
+
+## Default Interrupt Service Handlers (ISRs)
+  - V-Blank: A default V-Blank ISR is installed on startup which copies the Shadow OAM to the hardware OAM and increments the global @ref sys_time variable once per frame.
+  - Serial Link I/O: If any of the GBDK serial link functions are used such as @ref send_byte() and @ref receive_byte(), the default SIO serial link handler will be installed automatically at compile-time.
+
+
+# Copying Functions to RAM and HIRAM
+See the `ram_function` example project included with GBDK which demonstrates copying functions to RAM and HIRAM.
+
+`Warning!` Copying of functions is generally not safe since they may contain jumps to absolute addresses that will not be converted to match the new location.
+
+It is possible to copy functions to RAM and HIRAM (using the memcpy() and hiramcpy() functions), and execute them from C. Ensure you have enough free space in RAM or HIRAM for copying a function.
+
+There are basically two ways for calling a function located in RAM, HIRAM, or ROM:
+
+  - Declare a pointer-to-function variable, and set it to the address of the function to call.
+  - Declare the function as extern, and set its address at link time using the -Wl-gXXX=# flag (where XXX is the name of the function, and # is its address).
+
+The second approach is slightly more efficient. Both approaches are demonstrated in the `ram_function.c` example.
+
+
+# Mixing C and Assembly
+You can mix C and assembly (ASM) in two ways as described below. For additional detail see the @ref links_sdcc_docs.
+
+## Inline ASM within C source files
+
+Example:  
+
+       __asm__("nop");
+
+Another Example:  
+
+      void some_c_function() 
+      {
+        // Optionally do something
+        __asm
+            (ASM code goes here)
+        __endasm;
+      }
+
+
+## In Separate ASM files
+
+@todo This is from GBDK 2.x docs, verify it with GBDK-2020 and modern SDCC
+
+It is possible to assemble and link files written in ASM alongside files written in C.
+
+  - A C identifier `i` will be called `_i` in assembly.
+  - Results are always returned into the `DE` register.
+  - Parameters are passed on the stack (starting at `SP+2` because the return address is also saved on the stack).
+  - Assembly identifiers are exported using the `.globl` directive.
+  - You can access GameBoy hardware registers using `_reg_0xXX` where `XX` is the register number (see `sound.c` for an example).
+  - Registers must be preserved across function calls (you must store them at function begin, and restore them at the end), except `HL` (and `DE` when the function returns a result).
+
+Here is an example of how to mix assembly with C:
+
+`main.c`
+
+    main()
+    {
+      int16_t i;
+      int16_t add(int16_t, int16_t);
+
+      i = add(1, 3);
+    }
+
+`add.s`
+
+    .globl _add
+    _add:         ; int16_t add(int16_t a, int16_t b)
+                  ; There is no register to save:
+                  ;  BC is not used
+                  ;  DE is the return register
+                  ;  HL needs never to be saved
+    LDA  HL,2(SP)
+    LD   E,(HL)   ; Get a in DE
+    INC  HL
+    LD   D,(HL)
+    INC  HL
+    LD   A,(HL)   ; Get b in HL
+    INC  HL
+    LD   H,(HL)
+    LD   L,A
+    ADD  HL,DE    ; Add DE to HL
+    LD   D,H
+    LD   E,L
+                  ; There is no register to restore
+    RET           ; Return result in DE
+
+
+# Including binary files in C source with incbin
+Data from binary files can be included in C source files as a const array using the @ref INCBIN() macro.
+
+See the `incbin` example project for a demo of how to use it.
+
+
+# Known Issues and Limitations
+
+## SDCC
+  - Const arrays declared with `somevar[n] = {x}` will __NOT__ get initialized with value `x`. This may change when the SDCC RLE initializer is fixed. Use memset for now if you need it.
+
+  - SDCC banked calls and @ref far_pointers in GBDK only save one byte for the ROM bank, so for example they are limtied to __bank 15__ max for MBC1 and __bank 255__ max for MBC5. See @ref banked_calls for more details.
diff --git a/gbdk/docs/pages/04_coding_guidelines.md b/gbdk/docs/pages/04_coding_guidelines.md
new file mode 100644
index 00000000..9e3171e2
--- /dev/null
+++ b/gbdk/docs/pages/04_coding_guidelines.md
@@ -0,0 +1,227 @@
+@page docs_coding_guidelines Coding Guidelines
+
+# Learning C / C fundamentals
+Writing games and other programs with GBDK will be much easier with a basic understanding of the C language. In particular, understanding how to use C on "Embedded Platforms" (small computing systems, such as the Game Boy) can help you write better code (smaller, faster, less error prone) and avoid common pitfalls.
+
+
+@anchor docs_c_tutorials
+## General C tutorials
+  - https://www.learn-c.org/
+  -  https://www.tutorialspoint.com/cprogramming/index.htm
+
+## Embedded C introductions
+
+  - http://dsp-book.narod.ru/CPES.pdf
+  - https://www.phaedsys.com/principals/bytecraft/bytecraftdata/bcfirststeps.pdf
+
+## Game Boy games in C
+
+  - https://gbdev.io/list.html#c
+
+# Understanding the hardware
+In addition to understanding the C language it's important to learn how the Game Boy hardware works. What it is capable of doing, what it isn't able to do, and what resources are available to work with. A good way to do this is by reading the @ref Pandocs and checking out the @ref awesome_gb list.
+
+
+# Writing optimal C code for the Game Boy and SDCC
+The following guidelines can result in better code for the Game Boy, even though some of the guidance may be contrary to typical advice for general purpose computers that have more resources and speed.
+
+
+## Tools
+
+@anchor const_gbtd_gbmb
+### GBTD / GBMB, Arrays and the "const" keyword
+__Important__: The old @ref gbtd_gbmb "GBTD/GBMB" fails to include the `const` keyword when exporting to C source files for GBDK. That causes arrays to be created in RAM instead of ROM, which wastes RAM, uses a lot of ROM to initialize the RAM arrays and slows the compiler down a lot.
+
+__Use of @ref toxa_gbtd_gbmb "toxa's updated GBTD/GBMB" is highly recommended.__
+
+If you wish to use the original tools, you must add the `const` keyword every time the graphics are re-exported to C source files.
+
+
+## Variables
+  - 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, especially when comparing two values.
+
+  - Use explicit types so you always know the size of your variables. `int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t` and `bool`.
+  These are standard types defined in `stdint.h` (`#include <stdint.h>`) and `stdbool.h` (`#include <stdbool.h>`).
+
+  - Global and local static variables are generally more efficient than local non-static variables (which go on the stack and are slower and can result in slower code).
+
+  - @anchor const_array_data
+  `const` keyword: use const for arrays, structs and variables with read-only (constant) data. It will reduce ROM, RAM and CPU usage significantly. Non-`const` values are loaded from ROM into RAM inefficiently, and there is no benefit in loading them into the limited available RAM if they aren't going to be changed.
+
+  - Here is how to delcare `const` pointers and variables:
+    - non-const pointer to a const variable: `const uint8_t * some_pointer;`
+    - const pointer to a non-const variable: `uint8_t * const some_pointer;`
+    - const pointer to a const variable: `const uint8_t * const some_pointer;`
+    - https://codeforwin.org/2017/11/constant-pointer-and-pointer-to-constant-in-c.html
+    - https://stackoverflow.com/questions/21476869/constant-pointer-vs-pointer-to-constant
+
+  - For calculated values that don't change, pre-compute results once and store the result. Using lookup-tables and the like can improve speed and reduce code size. Macros can sometimes help. It may be beneficial to do the calculations with an outside tool and then include the result as C code in a const array.
+
+  - Use an advancing pointer (`someStruct->var = x; someStruct++`) to loop through arrays of structs instead of using indexing each time in the loop `someStruct[i].var = x`.
+
+  - When modifying variables that are also changed in an Interrupt Service Routine (ISR), wrap them the relevant code block in a `__critical { }` block. See http://sdcc.sourceforge.net/doc/sdccman.pdf#section.3.9
+
+  - When using constants and literals the `U`, `L` and `UL` postfixes can be used.
+    - `U` specifies that the constant is unsigned
+    - `L` specifies that the constant is long.
+
+    - NOTE: In SDCC 3.6.0, the default for char changed from signed to unsigned. The manual says to use `--fsigned-char` for the old behavior, this option flag is included by default when compiling through @ref lcc. 
+
+    @anchor fixed_point_type
+  - A fixed point type (`fixed`) is included with GBDK when precision greater than whole numbers is required for 8 bit range values (since floating point is not included in GBDK).
+
+  See the "Simple Physics" sub-pixel example project.
+
+  Code example:
+    
+        fixed player[2];
+        ...
+        // Modify player position using its 16 bit representation
+        player[0].w += player_speed_x;
+        player[1].w += player_speed_y;
+        ...
+        // Use only the upper 8 bits for setting the sprite position
+        move_sprite(0, player[0].h ,player[1].h);
+
+
+## Code structure
+
+  - Do not `#include` `.c` source files into other `.c` source files. Instead create `.h` header files for them and include those.
+    https://www.tutorialspoint.com/cprogramming/c_header_files.htm
+
+  - Instead of using a blocking @ref delay() for things such as sprite animations/etc (which can prevent the rest of the game from continuing) many times it's better to use a counter which performs an action once every N frames. @ref sys_time may be useful in these cases.
+
+  - When processing 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 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. Globals and local static vars can be used instead when applicable.
+
+  - Use inline functions if the function is short (with the `inline` keyword, such as `inline uint8_t 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.
+
+    It is even faster to check if a variable is 0 than if it is equal to some other value, so looping from _N down to zero_ is faster than looping _from zero up to N_.
+
+  For instance:
+
+        for(i = 0; i < 10; i++)
+
+  is less efficient than:
+
+        for(i = 0; i != 10; i++)
+
+  and if possible, even better:
+
+        for(i = 10; i != 0; i--)
+-->
+
+## GBDK API/Library
+
+  - stdio.h: If you have other ways of printing text, avoid including @ref stdio.h and using functions such as @ref printf(). Including it will use a large number of the background tiles for font characters. If stdio.h is not included then that space will be available for use with other tiles instead.
+
+  - drawing.h: The Game Boy graphics hardware is not well suited to frame-buffer style graphics such as the kind provided in @ref drawing.h. Due to that, most drawing functions (rectangles, circles, etc) will be slow . When possible it's much faster and more efficient to work with the tiles and tile maps that the Game Boy hardware is built around.
+
+  - @ref waitpad() and @ref waitpadup check for input in a loop that doesn't HALT at all, so the CPU will be maxed out until it returns. One alternative is to write a function with a loop that checks input with @ref joypad() and then waits a frame using @ref wait_vbl_done() (which idles the CPU while waiting) before checking input again.
+
+  - @ref joypad(): When testing for multiple different buttons, it's best to read the joypad state *once* into a variable and then test using that variable (instead of making multiple calls).
+
+
+## Toolchain
+
+  - See SDCC optimizations: http://sdcc.sourceforge.net/doc/sdccman.pdf#section.8.1
+
+  - Use profiling. Look at the ASM generated by the compiler, write several versions of a function, compare them and choose the faster one.
+
+  - Use the SDCC `--max-allocs-per-node` flag with large values, such as `50000`. `--opt-code-speed` has a much smaller effect.
+    - GBDK-2020 (after v4.0.1) compiles the library with `--max-allocs-per-node 50000`, but it must be turned on for your own code.  
+    (example: `lcc ... -Wf--max-allocs-per-node50000` or `sdcc ... --max-allocs-per-node 50000`).
+
+    - The other code/speed flags are `--opt-code-speed` or `--opt-code-size `.
+
+  - Use current SDCC builds from http://sdcc.sourceforge.net/snap.php  
+    The minimum required version of SDCC will depend on the GBDK-2020 release. See @ref docs_releases
+
+  - Learn some ASM and inspect the compiler output to understand what the compiler is doing and how your code gets translated. This can help with writing better C code and with debugging.
+
+
+@anchor docs_chars_varargs
+## chars and vararg functions
+
+In standard C when `chars` are passed to a function with variadic arguments (varargs, those declared with `...` as a parameter), such as @ref printf(), those `chars` get automatically promoted to `ints`. For an 8 bit CPU such as the Game Boy's, this is not as efficient or desirable in most cases. So the default SDCC behavior, which GBDK-2020 expects, is that chars will remain chars and _not_ get promoted to ints when **explicitly cast as chars while calling a varargs function**.
+
+  - They must be explicitly re-cast when passing them to a varargs function, even though they are already declared as chars.
+
+  - Discussion in SDCC manual:  
+    http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.5  
+    http://sdcc.sourceforge.net/doc/sdccman.pdf#subsection.3.5.10
+
+  - If SDCC is invoked with -std-cxx (--std-c89, --std-c99, --std-c11, etc) then it will conform to standard C behavior and calling functions such as @ref printf() with chars may not work as expected.
+
+For example:
+
+    unsigned char i = 0x5A;
+    
+    // NO:
+    // The char will get promoted to an int, producing incorrect printf output
+    // The output will be: 5A 00
+    printf("%hx %hx", i, i);
+    
+    // YES:
+    // The char will remain a char and printf output will be as expected
+    // The output will be: 5A 5A
+    printf("%hx %hx", (unsigned char)i, (unsigned char)i);
+
+Some functions that accept varargs:
+ - @ref EMU_printf, @ref gprintf(), @ref printf(), @ref sprintf()
+
+Also See:
+ - Other cases of char to int promotion: http://sdcc.sourceforge.net/doc/sdccman.pdf#chapter.6
+
+
+#  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. 
+
+
+## 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.
+
+The parameters to a function are pushed in right to left order with no aligning - so a byte takes up a byte on the stack instead of the more natural word. So for example the function int store_byte( uint16_t addr, uint8_t byte) would push 'byte' onto the stack first then addr using a total of three bytes. As the return address is also pushed, the stack would contain:
+
+      At SP+0 - the return address
+
+      At SP+2 - addr
+
+      At SP+4 - byte 
+
+Note that the arguments that are pushed first are highest in the stack due to how the Game Boy's stack grows downwards.
+
+The function returns in DE.
+
+
+## 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.
+
+Getting at C variables is slightly tricky due to how local variables are allocated on the stack. However you shouldn't be using the local variables of a calling function in any case. Global variables can be accessed by name by adding an underscore. 
+
+
+## Segments
+The use of segments for code, data and variables is more noticeable in assembler. GBDK and SDCC define a number of default segments - `_CODE`, `_DATA` and `_BSS`. Two extra segments `_HEADER` and `_HEAP` exist for the Game Boy header and malloc heap respectively.
+
+The order these segments are linked together is determined by crt0.s and is currently `_CODE` in ROM, then `_DATA`, `_BSS`, `_HEAP` in WRAM, with `STACK` at the top of WRAM. `_HEAP` is placed after `_BSS` so that all spare memory is available for the malloc routines. To place code in other than the first two banks, use the segments `_CODE_x` where x is the 16kB bank number.
+
+As the `_BSS` segment occurs outside the ROM area you can only use .ds to reserve space in it.
+
+While you don't have to use the `_CODE` and `_DATA` distinctions in assembler you may wish to do so to maintain consistency. 
+
diff --git a/gbdk/docs/pages/05_banking_mbcs.md b/gbdk/docs/pages/05_banking_mbcs.md
new file mode 100644
index 00000000..590a62c0
--- /dev/null
+++ b/gbdk/docs/pages/05_banking_mbcs.md
@@ -0,0 +1,256 @@
+@page docs_rombanking_mbcs ROM/RAM Banking and MBCs
+
+
+
+# ROM/RAM Banking and MBCs (Memory Bank Controllers)
+The standard Game Boy cartridge with no MBC has a fixed 32K bytes of ROM. In order to make cartridges with larger ROM sizes (to store more code and graphics) MBCs can be used. They allow switching between multiple ROM banks that use the same memory region. Only one of the banks can be selected as active at a given time, while all the other banks are inactive (and so, inaccessible).
+
+
+## Non-banked cartridges
+Cartridges with no MBC controller are non-banked, they have 32K bytes of fixed ROM space and no switchable banks. For these cartridges the ROM space between `0000h and 7FFFh` can be treated as a single large bank of 32K bytes, or as two contiguous banks of 16K bytes in Bank 0 at `0000h - 3FFFh` and Bank 1 at `4000h to 7FFFh`.
+
+
+## MBC Banked cartridges (Memory Bank Controllers)
+@anchor MBC
+@anchor MBCS
+Cartridges with MBCs allow the the Game Boy to work with ROMS up to 8MB in size and with RAM up to 128kB. Each bank is 16K Bytes.
+  - Bank 0 of the ROM is located in the region at `0000h - 3FFFh`. It is _usually_ fixed (non-banked) and cannot be switched out for another bank.
+  - The higher region at `4000h to 7FFFh` is used for switching between different ROM banks.
+
+See the @ref Pandocs for more details about the individual MBCs and their capabilities.
+
+
+# Working with Banks
+To assign code and constant data (such as graphics) to a ROM bank and use it:
+  - Place the code for your ROM bank in one or several source files.
+  - Specify the ROM bank to use, either in the source file or at compile/link time.
+  - Specify the number of banks and MBC type during link time.
+  - When the program is running and wants to use data or call a function that is in a given bank, manually or automatically set the desired bank to active.
+
+
+## Setting the ROM bank for a Source file
+The ROM and RAM bank for a source file can be set in a couple different ways. Multiple different banks cannot be assigned inside the same source file (unless the `__addressmod` method is used), but multiple source files can share the same bank.
+
+If no ROM and RAM bank are specified for a file then the default _CODE, _BSS and _DATA segments are used.
+
+Ways to set the ROM bank for a Source file:
+  - `#pragma bank <N>` at the start of a source file. Example (ROM bank 2): `#pragma bank 2`
+  - The lcc switch for ROM bank `-Wf-bo<N>`. Example (ROM bank 2): `-Wf-bo2`
+  - Using @ref rom_autobanking
+
+Note: You can use the `NONBANKED` keyword to define a function as non-banked if it resides in a source file which has been assigned a bank.
+
+
+## Setting the RAM bank for a Source file
+  - Using the lcc switch for RAM bank `-Wf-ba<N>`. Example (RAM bank 3): `-Wf-ba3`
+
+
+@anchor setting_mbc_and_rom_ram_banks
+## Setting the MBC and number of ROM & RAM banks available
+
+At the link stage this is done with @ref lcc using pass-through switches for @ref makebin.
+  - `-Wl-yo<N>` where `<N>` is the number of ROM banks. 2, 4, 8, 16, 32, 64, 128, 256, 512
+    - `-Wl-yoA` may be used for automatic bank size.
+  - `-Wl-ya<N>` where `<N>` is the number of RAM banks. 2, 4, 8, 16, 32
+  - `-Wl-yt<N>` where `<N>` is the type of MBC cartridge (see below).
+    - Example: `Wl-yt0x1A`
+
+The MBC settings below are available when using the makebin MBC switch.
+
+Additional details available at [Pandocs](https://gbdev.io/pandocs/The_Cartridge_Header.html#0147---cartridge-type "Pandocs")
+
+```
+# From Makebin source:
+#
+#-Wl-yt<NN> where <NN> is one of the numbers below
+#
+# 0147: Cartridge type:
+# 0-ROM ONLY            12-ROM+MBC3+RAM
+# 1-ROM+MBC1            13-ROM+MBC3+RAM+BATT
+# 2-ROM+MBC1+RAM        19-ROM+MBC5
+# 3-ROM+MBC1+RAM+BATT   1A-ROM+MBC5+RAM
+# 5-ROM+MBC2            1B-ROM+MBC5+RAM+BATT
+# 6-ROM+MBC2+BATTERY    1C-ROM+MBC5+RUMBLE
+# 8-ROM+RAM             1D-ROM+MBC5+RUMBLE+SRAM
+# 9-ROM+RAM+BATTERY     1E-ROM+MBC5+RUMBLE+SRAM+BATT
+# B-ROM+MMM01           1F-Pocket Camera
+# C-ROM+MMM01+SRAM      FD-Bandai TAMA5
+# D-ROM+MMM01+SRAM+BATT FE - Hudson HuC-3
+# F-ROM+MBC3+TIMER+BATT FF - Hudson HuC-1
+# 10-ROM+MBC3+TIMER+RAM+BATT
+# 11-ROM+MBC3
+```
+
+
+## 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
+  - @ref BANK(): retrieve a bank number using a reference created with @ref BANKREF()
+  - @ref BANKREF_EXTERN(): Make a @ref BANKREF() reference residing in another source file accessible in the current file for use with @ref BANK().
+
+
+## Banking and Functions
+
+@anchor banked_keywords
+### BANKED/NONBANKED keywords
+- `BANKED`:
+  - The function will use banked sdcc calls.
+  - Placed in the bank selected by its source file (or compiler switches).
+- `NONBANKED`:
+  - Placed in the non-banked lower 16K region (bank 0), regardless of the bank selected by its source file.
+- `<not-specified>`:
+  - The function does not use sdcc banked calls (`near` instead of `far`).
+  - Placed in the bank selected by its source file (or compiler switches).
+
+@anchor banked_calls
+### Banked Function Calls
+Banked functions 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).
+  - Using @ref SWITCH_ROM() (and related functions for other MBCs) to manually switch in the required bank and then call the function.
+
+Non-banked functions (either in fixed Bank 0, or in an non-banked ROM with no MBC):
+  - May call functions in any bank: __YES__
+  - May use data in any bank: __YES__
+
+@todo Fill in this info for Banked Functions
+Banked functions (located in a switchable ROM bank)
+  - May call functions in any bank: ?
+  - May use data in any bank: __NO__ (may only use data from currently active 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).
+
+
+## Const Data (Variables in ROM)
+@todo Const Data (Variables in ROM)
+
+
+## Variables in RAM
+@todo Variables in RAM
+
+
+## Far Pointers
+@anchor far_pointers
+Far pointers include a segment (bank) selector so they are able to point to addresses (functions or data) outside of the current bank (unlike normal pointers which are not bank-aware). A set of macros is provided by GBDK 2020 for working with far pointers.
+
+__Warning:__ Do not call the far pointer function macros from inside interrupt routines (ISRs). The far pointer function macros use a global variable that would not get restored properly if a function called that way was interrupted by another one called the same way. However, they may be called recursively.
+
+See @ref FAR_CALL, @ref TO_FAR_PTR and the `banks_farptr` example project.
+
+
+## Bank switching
+You can manually switch banks using the @ref SWITCH_ROM(), @ref SWITCH_RAM(), and other related macros. See `banks.c` project for an example.
+
+Note: You can only do a switch_rom_bank call from non-banked `_CODE` since otherwise you would switch out the code that was executing. Global routines that will be called without an expectation of bank switching should fit within the limited 16k of non-banked `_CODE`.
+
+
+## Restoring the current bank (after calling functions which change it without restoring)
+@anchor banking_current_bank
+If a function call is made (for example 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)
+{
+    // A function which changes the bank and
+    // *doesn't* restore it after changing.
+    some_function();
+}
+```
+It should be:
+```
+void vbl_music_isr(void)
+{
+    // Save the current bank
+    uint8_t _saved_bank = _current_bank;
+
+    // A function which changes the bank and
+    // *doesn't* restore it after changing.
+    some_function();
+
+    // Now restore the current bank
+    SWITCH_ROM(_saved_bank);
+}
+```
+
+## Currently active bank: _current_bank
+The global variable @ref _current_bank is updated automatically when calling @ref SWITCH_ROM(), @ref SWITCH_ROM_MBC1() and @ref SWITCH_ROM_MBC5, or when a `BANKED` function is called.
+
+
+
+@anchor rom_autobanking
+# Auto-Banking
+A ROM bank auto-assignment feature was added in GBDK 2020 4.0.2.
+
+Instead of having to manually specify which bank a source file will reside in, the banks can be assigned automatically to make the best use of space. The bank assignment operates on object files, after compiling/assembling and before linking.
+
+To turn on auto-banking, use the `-autobank` argument with lcc.
+
+For a source example see the `banks_autobank` project.
+
+In the source files you want auto-banked, do the following:
+  - Set the source file to be autobanked `#pragma bank 255` (this sets the temporary bank to `255`, which @ref bankpack then updates when repacking).
+  - Create a reference to store the bank number for that source file: `BANKREF(<some-bank-reference-name>)`.
+    - More than one `BANKREF()` may be created per file, but they should always have unique names.
+
+In the other source files you want to access the banked data from, do the following:
+  - Create an extern so the bank reference in another file is accessible: `BANKREF_EXTERN(<some-bank-reference-name>)`.
+  - Obtain the bank number using  `BANK(<some-bank-reference-name>)`.
+
+Example: level_1_map.c
+
+        #pragma bank 255
+        BANKREF(level_1_map)
+        ...
+        const uint8_t level_1_map[] = {... some map data here ...};
+
+Accessing that data: main.c
+
+      BANKREF_EXTERN(level_1_map)
+      ...
+      SWITCH_ROM( BANK(level_1_map) );
+      // Do something with level_1_map[]
+
+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.
+
+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 its previously assigned bank until a source change causes the compiler to rebuild it to an object file again which resets its 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.
+
+
+
+# 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.
+
+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
+In order to see how much space is used or remains available in a bank, you can use the third-party @ref romusage tool.
+
+
+## Other important notes
+  - The @ref SWITCH_ROM_MBC5 macro is not interrupt-safe. If using less than 256 banks you may always use SWITCH_ROM - that is faster. Even if you use mbc5 hardware chip in the cart.
+
+
+# Banking example projects
+There are several projects in the GBDK 2020 examples folder which demonstrate different ways to use banking.
+  - `Banks`: a basic banking example
+  - `Banks_new`: examples of using new bank assignment and calling conventions available in GBDK 2020 and its updated SDCC version.
+  - `Banks_farptr`: using far pointers which have the bank number built into the pointer.
+  - `Banks_autobank`: shows how to use the bank auto-assignment feature in GBDK 2020 4.0.2 or later, instead of having to manually specify which bank a source file will reside it.
+
diff --git a/gbdk/docs/pages/06_toolchain.md b/gbdk/docs/pages/06_toolchain.md
new file mode 100644
index 00000000..7ec791a1
--- /dev/null
+++ b/gbdk/docs/pages/06_toolchain.md
@@ -0,0 +1,276 @@
+@page docs_toolchain GBDK Toolchain
+
+
+@anchor toolchain_overview
+# Overview
+GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy ROMs.
+- All tools are located under `bin/`
+- The typical order of tools called is as follows (when using lcc these steps are usually performed automatically).
+  1. Compile and assemble source files (.c, .s, .asm) with @ref sdcc and @ref sdasgb
+  2. Optional: perform auto banking with @ref bankpack on the object files
+  3. Link the object files into .ihx file with @ref sdldgb
+  4. Validate the .ihx file with @ref ihxcheck
+  5. Convert the .ihx file to a ROM file (.gb, .gbc) with @ref makebin
+
+To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with `-h`.
+
+
+# Data Types
+For data types and special C keywords, see @ref file_asm_gbz80_types_h "asm/gbz80/types.h" and @ref file_asm_types_h "asm/types.h".
+
+Also see the SDCC manual (scroll down a little on the linked page): http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1
+
+
+@anchor toolchain_changing_important_addresses 
+# Changing Important Addresses
+It is possible to change some of the important addresses used by the toolchain at link time using the -Wl-g XXX=YYY and =Wl-b XXX=YYY flags (where XXX is the name of the data, and YYY is the new address). 
+
+@ref lcc will include the following linker defaults for @ref sdldgb if they are not defined by the user.
+
+  - `_shadow_OAM`
+    - Location of sprite ram (requires 0xA0 bytes).
+    - Default `-Wl-g _shadow_OAM=0xC000`
+
+  - `.STACK`
+    - Initial stack address
+    - Default `-Wl-g .STACK=0xE000`
+
+  - `.refresh_OAM`
+    - Address to which the routine for refreshing OAM will be copied (must be in HIRAM). Default
+    - Default `-Wl-g .refresh_OAM=0xFF80`
+
+  - `_DATA`
+    - Start of RAM section (starts after Shadow OAM)
+    - Default `-Wl-b _DATA=0xc0A0`
+
+  - `_CODE`
+    - Start of ROM section
+    - Default `-Wl-b _CODE=0x0200`
+
+
+@anchor toolchain_compiling_programs
+# Compiling programs
+
+The @ref lcc program is the front end compiler driver for the actual compiler, assembler and linker. It works out what you want to do based on command line options and the extensions of the files you give it, computes the order in which the various programs must be called and then executes them in order. Some examples are:
+
+  - Compile the C source 'source.c', assemble and link it producing the Gameboy image 'image.gb'
+
+        lcc -o image.gb source.c
+
+  - Assemble the file 'source.s' and link it producing the Gameboy image 'image.gb'
+
+        lcc -o image.gb source.s
+
+  - Compile the C program 'source1.c' and assemble it producing the object file 'object1.o' for later linking.
+
+        lcc -c -o object1.o source1.c
+
+  - Assemble the file 'source2.s' producing the object file 'object2.o' for later linking
+
+        lcc -c -o object2.o source2.s
+
+  - Link the two object files 'object1.o' and 'object2.o' and produce the Gameboy image 'image.gb'
+
+        lcc -o image.gb object1.o object2.o
+
+  - Do all sorts of clever stuff by compiling then assembling source1.c, assembling source2.s and then linking them together to produce image.gb. 
+
+        lcc -o image.gb source1.c source2.s
+
+Arguments to the assembler, linker, etc can be passed via lcc using -Wp..., -Wf..., -Wa... and -Wl... to pass options to the pre-processor, compiler, assembler and linker respectively. Some common options are:
+
+  - To generate an assembler listing file.
+
+        -Wa-l
+
+  - To generate a linker map file.
+
+        -Wl-m
+
+  - To bind var to address 'addr' at link time.
+
+        -Wl-gvar=addr
+
+For example, to compile the example in the memory section and to generate a listing and map file you would use the following. Note the leading underscore that C adds to symbol names.
+
+    lcc -Wa-l -Wl-m -Wl-g_snd_stat=0xff26 -o image.gb hardware.c
+
+
+@subsection Makefiles
+## Using Makefiles
+
+Please see the sample projects included with GBDK-2020 for a couple different examples of how to use Makefiles.
+
+You may also want to read a tutorial on Makefiles. For example:  
+https://makefiletutorial.com/  
+https://www.tutorialspoint.com/makefile/index.htm
+
+@anchor build_tools
+# Build Tools
+
+@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
+- lcc can compile, link and generate a binary in a single pass: `lcc -o somerom.gb somesource.c`
+- @anchor lcc_debug
+  lcc now has a `-debug` flag that will turn on the following recommended flags for debugging
+    - `--debug` for sdcc (lcc equiv: `-Wf-debug`)
+    - `-y` enables .cdb output for @ref sdldgb (lcc equiv: `-Wl-y`)
+    - `-j` enables .noi output for @ref sdldgb (lcc equiv: `-Wl-j`)
+
+
+@anchor sdcc
+## sdcc
+SDCC C Source compiler.
+
+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 Game Boy.
+
+For detailed settings see @ref sdasgb-settings
+
+- Arguments can be passed to it through @ref lcc using `-Wa-<argument>`
+
+
+@anchor bankpack
+## 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.
+- Must be called after compiling/assembling and before linking.
+- Arguments can be passed to it through @ref lcc using `-Wb-<argument>`
+
+
+@anchor sdldgb
+## 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>`
+
+
+@anchor ihxcheck
+## 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>`
+
+
+@anchor makebin
+## makebin
+IHX to ROM converter.
+
+- For detailed settings see @ref makebin-settings
+- For makebin `-yt` MBC values see @ref setting_mbc_and_rom_ram_banks
+
+Converts .ihx files produced by @ref sdldgb into ROM files (.gb, .gbc). Also used for setting some ROM header data.
+- Arguments can be passed to it through @ref lcc using `-Wm-<argument>`
+
+
+@anchor gbdk_utilities
+# GBDK Utilities
+
+
+@anchor utility_gbcompress
+## 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().
+
+Can also compress (and decompress) using block style RLE encoding with the `--alg=rle` flag. Decompression support is available in GBDK, see @ref rle_decompress().
+
+
+@anchor utility_png2asset
+## png2asset
+Tool for converting PNGs into GBDK format MetaSprites and Tile Maps.
+
+- Convert single or multiple frames of graphics into metasprite structured data for use with the ...metasprite...() functions.
+- When `-map` is used, converts images into Tile Maps and matching Tile Sets
+- Supports Game Boy 2bpp, GBC 4bpp, SGB 4bpp, and SMS/GG 4bpp
+
+For detailed settings see @ref png2asset-settings  
+For working with sprite properties (including cgb palettes), see @ref metasprite_and_sprite_properties  
+For API support see @ref move_metasprite() and related functions in @ref metasprites.h  
+
+### Working with png2asset
+  - The origin (pivot) for the metasprite is not required to be in the upper left-hand corner as with regular hardware sprites. See `-px` and `-py`.
+
+  - The conversion process supports using both SPRITES_8x8 (`-spr8x8`) and SPRITES_8x16 mode (`-spr8x16`). If 8x16 mode is used then the height of the metasprite must be a multiple of 16.
+
+#### Terminology
+The following abbreviations are used in this section:
+* Original Game Boy and Game Boy Pocket style hardware: `DMG`
+* Game Boy Color: `CGB`
+
+#### Conversion Process
+png2asset accepts any png as input, although that does not mean any image will be valid. The program will follow the next steps:
+  - The image will be subdivided into tiles of 8x8 or 8x16.
+  - For each tile a palette will be generated.
+  - If there are more than 4 colors in the palette it will throw an error.
+  - The palette will be sorted from darkest to lightest. If there is a transparent color that will be the first one (this will create a palette that will also work with `DMG` devices).
+  - If there are more than 8 palettes the program will throw an error.
+
+With all this, the program will generate a new indexed image (with palette), where each 4 colors define a palette and all colors within a tile can only have colors from one of these palettes
+
+It is also posible to pass a indexed 8-bit png with the palette properly sorted out, using `-keep_palette_order`
+  - Palettes will be extracted from the image palette in groups of 4 colors.
+  - Each tile can only have colors from one of these palettes per tile.
+  - The maximum number of colors is 32.
+
+Using this image a tileset will be created
+  - Duplicated tiles will be removed.
+  - Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use `-noflip` to turn off matching mirrored tiles).
+  - The palette won't be taken into account for matching, only the pixel color order, meaning there will be a match between tiles using different palettes but looking identical on grayscale.
+
+
+#### Maps
+Passing `-map` the png can be converted to a map that can be used in both the background and the window. In this case, png2asset will generate:
+  - The palettes
+  - The tileset
+  - The map
+  - The color info
+    - By default, an array of palette index for each tile. This is not the way the hardware works but it takes less space and will create maps compatibles with both `DMG` and `CGB` devices.
+    - Passing `-use_map_attributes` will create an array of map attributes. It will also add mirroring info for each tile and because of that maps created with this won't be compatible with `DMG`.
+      - Use `-noflip` to make background maps which are compatible with `DMG` devices.
+
+#### Meta sprites
+By default the png will be converted to metasprites. The image will be subdivided into meta sprites of `-sw` x `-sh`. In this case png2asset will generate:
+  - The metasprites, containing an array of:
+    - tile index
+    - y offset
+    - x offset
+    - flags, containing the mirror info, the palettes for both DMG and GBC and the sprite priority
+  - The metasprites array
+
+
+#### Super Game Boy Borders (SGB)
+Screen border assets for the Super Game Boy can be generated using png2asset.
+
+The following flags should be used to perform the conversion:
+  - `<input_border_file.png> -map -bpp 4 -max_palettes 4 -pack_mode sgb -use_map_attributes -c <output_border_data.c>`
+  - Where `<input_border_file.png>` is the image of the SGB border (256x224) and `<output_border_data.c>` is the name of the source file to write the assets out to.
+
+
+See the `sgb_border` example project for more details.
diff --git a/gbdk/docs/pages/06b_supported_consoles.md b/gbdk/docs/pages/06b_supported_consoles.md
new file mode 100644
index 00000000..8f614387
--- /dev/null
+++ b/gbdk/docs/pages/06b_supported_consoles.md
@@ -0,0 +1,244 @@
+@page docs_supported_consoles Supported Consoles & Cross Compiling
+  
+@anchor docs_consoles_supported_list
+# Consoles Supported by GBDK
+As of version `4.0.5` GBDK includes support for other consoles in addition to the Game Boy.
+
+  - Game Boy and related clones
+    - Nintendo Game Boy / Game Boy Color (GB/GBC)
+    - Analogue Pocket (AP)
+    - Mega Duck / Cougar Boy (DUCK)
+
+  - Sega Consoles
+    - Sega Master System (SMS)
+    - Sega Game Gear (GG)
+
+  - MSX DOS (MSXDOS)
+
+While the GBDK API has many convenience functions that work the same or similar across different consoles, it's important to keep their different capabilities in mind when writing code intended to run on more than one. Some (but not all) of the differences are screen sizes, color capabilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed.
+
+ 
+@anchor docs_consoles_compiling
+# Cross Compiling for Different Consoles
+
+## lcc
+When compiling and building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via its port and platform combination.
+
+
+## sdcc
+When building directly with the sdcc toolchain, the following must be specified manually
+(when using @ref lcc it will populate these automatically based on `-m<port>:<plat>`).
+
+When compiling with @ref sdcc-settings "sdcc":
+  - `-m<port>`, `-D__PORT_<port>` and `-D__TARGET_<plat> `
+
+When assembling with @ref sdasgb-settings "sdasgb" (for GB/AP) and @ref sdasz80-settings "sdasz80" (for SMS/GG):
+  - Select the appropriate include path: `-I<gbdk-path>lib/small/asxxxx/<plat>`
+
+When linking with @ref sdldgb-settings "sdldgb" (for GB/AP) and @ref sdldz80-settings "sdldz80" (for SMS/GG or MSXDOS):
+  - Select the appropriate include paths: `-k <gbdk-path>lib/small/asxxxx/<port>`, `-k <gbdk-path>lib/small/asxxxx/<plat>`
+  - Include the appropriate library files `-l <port>.lib`, `-l <plat>.lib`
+  - The crt will be under `  <gbdk-path>lib/small/asxxxx/<plat>/crt0.o`
+
+MSXDOS requires an additional build step after makebin to create the final binary:
+  - `makecom <image.bin> [<image.noi>] <output.com>`
+
+
+## Console Port and Platform Settings
+  - Nintendo Game Boy / Game Boy Color
+    - @ref lcc : `-mgbz80:gb`
+    - port:`gbz80`, plat:`gb`
+  - Analogue Pocket
+    - @ref lcc : `-mgbz80:ap`
+    - port:`gbz80`, plat:`ap`
+  - Mega Duck / Cougar Boy
+    - @ref lcc : `-mgbz80:duck`
+    - port:`gbz80`, plat:`duck`
+
+  - Sega Master System
+    - @ref lcc : `-mz80:sms`
+    - port:`z80`, plat:`sms`
+  - Sega Game Gear
+    - @ref lcc : `-mz80:gg`
+    - port:`z80`, plat:`gg`
+
+  - MSX DOS
+    - @ref lcc : `-mz80:msxdos`
+    - port:`z80`, plat:`msxdos`
+
+
+# Cross-Platform Constants
+There are several constant \#defines that can be used to help select console specific code during compile time (with `#ifdef`, `#ifndef`) .
+
+## Console Identifiers
+  - When `<gb/gb.h>` is included (either directly or through `<gbdk/platform.h>`)
+    - When building for Game Boy:
+      - `NINTENDO` will be \#defined
+      - `GAMEBOY` will be \#defined
+    - When building for Analogue Pocket
+      - `NINTENDO` will be \#defined
+      - `ANALOGUEPOCKET` will be \#defined
+    - When building for Mega Duck / Cougar Boy
+      - `NINTENDO` will be \#defined
+      - `MEGADUCK` will be \#defined
+
+
+  - When `<sms/sms.h>` is included (either directly or through `<gbdk/platform.h>`)
+    - When building for Master System
+      - `SEGA` will be \#defined
+      - `MASTERSYSTEM` will be \#defined
+    - When building for Game Gear
+      - `SEGA` will be \#defined
+      - `GAMEGEAR` will be \#defined
+
+  - When `<msx/msx.h>` is included (either directly or through `<gbdk/platform.h>`)
+    - `MSXDOS` will be \#defined
+
+## Console Hardware Properties
+Constants that describe properties of the console hardware are listed below. Their values will change to reflect the current console target that is being built.
+
+  - @ref DEVICE_SCREEN_X_OFFSET, @ref DEVICE_SCREEN_Y_OFFSET
+  - @ref DEVICE_SCREEN_WIDTH, @ref DEVICE_SCREEN_HEIGHT
+  - @ref DEVICE_SCREEN_BUFFER_WIDTH, @ref DEVICE_SCREEN_BUFFER_HEIGHT
+  - @ref DEVICE_SCREEN_MAP_ENTRY_SIZE
+  - @ref DEVICE_SPRITE_PX_OFFSET_X, @ref DEVICE_SPRITE_PX_OFFSET_Y
+  - @ref DEVICE_SCREEN_PX_WIDTH, @ref DEVICE_SCREEN_PX_HEIGHT
+
+
+# Using <gbdk/...> headers
+Some include files under `<gbdk/..>` are cross platform and others allow the build process to auto-select the correct include file for the current target port and platform (console).
+
+For example, the following can be used
+    
+    #include <gbdk/platform.h>
+    #include <gbdk/metasprites.h>
+
+Instead of
+
+    #include <gb/gb.h>
+    #include <gb/metasprites.h>
+
+and
+
+    #include <sms/sms.h>
+    #include <sms/metasprites.h>
+
+
+@anchor docs_consoles_cross_platform_examples
+# Cross Platform Example Projects
+GBDK includes an number of cross platform example projects. These projects show how to write code that can be compiled and run on multiple different consoles (for example Game Boy and Game Gear) with, in some cases, minimal differences. 
+
+They also show how to build for multiple target consoles with a single build command and `Makefile`. The `Makefile.targets` allows selecting different `port` and `plat` settings when calling the build stages.
+
+## Cross Platform Asset Example
+The cross-platform `Logo` example project shows how assets can be managed for multiple different console targets together.
+
+In the example @ref utility_png2asset is used to generate assets in the native format for each console at compile-time from separate source PNG images. The Makefile is set to use the source PNG folder which matches the current console being compiled, and the source code uses @ref set_native_tile_data() to load the assets tiles in native format.
+
+
+# Porting From Game Boy to Analogue Pocket
+The Analogue Pocket is (for practical purposes) functionally identical to the Game Boy / Color, but has a couple altered register flag and address definitions and a different boot logo. In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices.
+
+## Registers and Flags
+Use API defined registers and register flags instead of hardwired ones.
+   - LCDC register: @ref LCDC_REG or @ref rLCDC
+   - STAT register: @ref STAT_REG or @ref rSTAT
+   - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON)
+   - STAT flags: -> STATF_... (example: @ref STATF_LYC)
+
+## Boot logo
+As long as the target console is @ref docs_consoles_compiling "set during build time" then the correct boot logo will be automatically selected.
+
+
+# Porting From Game Boy to Mega Duck / Cougar Boy
+The Mega Duck is fairly similar to the classic Game Boy. It has a couple altered register flag and address definitions, no boot logo and a different startup/entry-point address. In order for software to be easily ported to the Mega Duck, or to run on both, use the following practices.
+
+## Registers and Flags
+Use API defined registers and register flags instead of hardwired ones
+   - LCDC register: @ref LCDC_REG or @ref rLCDC
+   - STAT register: @ref STAT_REG or @ref rSTAT
+   - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON)
+   - STAT flags: -> STATF_... (example: @ref STATF_LYC)
+
+
+# Porting From Game Boy to SMS/GG
+
+## Tile Data and Tile Map loading
+
+### Tile and Map Data in 2bpp Game Boy Format
+- @ref set_bkg_data() and @ref set_sprite_data() will load 2bpp tile data in "game boy" format on both GB and SMS/GG.
+- On the SMS/GG @ref set_2bpp_palette() sets 4 colors that will be used when loading 2bpp assets with set_bkg_data(). This allows GB assets to be easily colorized without changing the asset format. There is some performance penalty for using the conversion.
+- @ref set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG.
+
+### Tile and Map Data in Native Format
+Use the following api calls when assets are avaialble in the native format for each platform.
+
+@ref set_native_tile_data()
+  - GB/AP: loads 2bpp tiles data
+  - SMS/GG: loads 4bpp tile data
+
+@ref set_tile_map()
+  - GB/AP: loads 1-byte-per-tile tilemaps
+  - SMS/GG: loads 2-byte-per-tile tilemaps
+
+There are also bit-depth specific API calls:
+- 1bpp: @ref set_1bpp_colors, @ref set_bkg_1bpp_data, @ref set_sprite_1bpp_data
+- 2bpp: @ref set_2bpp_palette, @ref set_bkg_2bpp_data, @ref set_sprite_2bpp_data, @ref set_tile_2bpp_data (sms/gg only)
+- 2bpp: @ref set_bkg_4bpp_data (sms/gg only), @ref set_sprite_4bpp_data (sms/gg only)
+
+### Emulated Game Boy Color map attributes on the SMS/Game Gear
+On the Game Boy Color, @ref VBK_REG is used to select between the regular background tile map and the background attribute tile map (for setting tile color palette and other properties).
+
+This behavior is emulated for the SMS/GG when using @ref set_bkg_tiles() and @ref VBK_REG. It allows writing a 1-byte tile map separately from a 1-byte attributes map.
+
+@note Tile map attributes on SMS/Game Gear use different control bits than the Game Boy Color, so a modified attribute map must be used.
+
+# Hardware Comparison
+The specs below reflect the typical configuration of hardware when used with GBDK and is not meant as a complete list of their capabilities.
+
+GB/AP
+- Sprites:
+  - 256 tiles (upper 128 are shared with background) (amount is doubled in CGB mode)
+  - tile flipping/mirroring: yes
+  - 40 total, max 10 per line
+  - 2 x 4 color palette (color 0 transparent). 8 x 4 color palettes in CGB mode
+- Background: 256 tiles (typical setup: upper 128 are shared with sprites) (amount is doubled in CGB mode)
+  - tile flipping/mirroring: no (yes in CGB mode)
+  - 1 x 4 color palette. 8 x 4 color palettes in CGB mode
+- Window "layer": available
+- Screen: 160 x 144
+- Hardware Map: 256 x 256
+
+
+SMS/GG
+- Sprites:
+  - 256 tiles (a bit less in the default setup)
+  - tile flipping/mirroring: no
+  - 64 total, max 8 per line
+  - 1 x 16 color palette (color 0 transparent)
+- Background: 512 tiles (upper 256 are shared with sprites)
+  - tile flipping/mirroring: yes
+  - 2 x 16 color palettes
+- Window "layer": not available
+- SMS
+  - Screen: 256 x 192
+  - Hardware Map: 256 x 224
+- GG
+  - Screen: 160 x 144
+  - Hardware Map: 256 x 224
+
+
+@anchor docs_consoles_safe_display_controller_access
+## Safe VRAM / Display Controller Access
+
+GB/AP
+- VRAM / Display Controller (PPU)
+  - VRAM and some other display data / registers should only be written to when the @ref STATF_B_BUSY bit of @ref STAT_REG is off. Most GBDK API calls manage this automatically.
+
+SMS/GG
+- Display Controller (VDP)
+  - Writing to the VDP should not be interrupted while an operation is already in progress (since that will interfere with the internal data pointer causing data to be written to the wrong location).
+  - Recommended approach: Avoid writing to the VDP (tiles, map, scrolling, colors, etc) during an interrupt routine (ISR).
+  - Alternative (requires careful implementation): Make sure writes to the VDP during an ISR are only performed when the @ref _shadow_OAM_OFF flag indicates it is safe to do so.
+
+
diff --git a/gbdk/docs/pages/07_sample_programs.md b/gbdk/docs/pages/07_sample_programs.md
new file mode 100644
index 00000000..c437a335
--- /dev/null
+++ b/gbdk/docs/pages/07_sample_programs.md
@@ -0,0 +1,131 @@
+@page docs_example_programs Example Programs
+
+
+GBDK includes several example programs both in C and in assembly. They are located in the examples directory, and in its subdirectories. They can be built by typing `make` in the correnponding directory.
+
+
+# banks (various projects)
+There are several different projects showing how to use ROM banking with GBDK.
+
+
+# comm
+Illustrates how to use communication routines.
+
+
+# crash
+Demonstrates how to use the optional GBDK crash handler which dumps debug info to the Game Boy screen in the event of a program crash.
+
+
+# colorbar
+The colorbar program, written by Mr. N.U. of TeamKNOx, illustrates the use of colors on a Color GameBoy.
+
+
+# dscan
+Deep Scan is a game written by Mr. N.U. of TeamKNOx that supports the Color GameBoy. Your aim is to destroy the submarines from your boat, and to avoid the projectiles that they send to you. The game should be self-explanatory. The following keys are used:
+
+    RIGHT/LEFT   : Move your boat
+    A/B          : Send a bomb from one side of your boat
+    START        : Start game or pause game
+
+    When game is paused:
+
+    SELECT       : Invert A and B buttons
+    RIGHT/LEFT   : Change speed
+    UP/DOWN      : Change level
+
+
+# filltest
+Demonstrates various graphics routines.
+
+
+# fonts
+Examples of how to work with the built in font and printing features.
+
+
+# galaxy
+A C translation of the space.s assembly program.
+
+
+# gb-dtmf
+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) 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
+An example of how to use the LCD ISR for visual special effects.
+
+
+# paint
+The paint example is a painting program. It supports different painting tools, drawing modes, and colors. At the moment, it only paints individual pixels. This program illustrates the use of the full-screen drawing library. It also illustrates the use of generic structures and big sprites.
+
+    Arrow keys : Move the cursor
+    SELECT     : Display/hide the tools palette
+    A          : Select tool
+
+
+# rand
+The rand program, written by Luc Van den Borre, illustrates the use of the GBDK random generator.
+
+
+# ram_fn
+The ram_fn example illustrates how to copy functions to RAM or HIRAM, and how to call them from C.
+
+
+# rpn
+A basic RPN calculator. Try entering expressions like 12 134* and then 1789+.
+
+
+# samptest
+Demonstration of playing a sound sample.
+
+
+# sgb (various)
+A collection of examples showing how to use the Super Game Boy API features.
+
+
+@anchor examples_sound_sample
+# sound
+The sound example is meant for experimenting with the sound generator of the GameBoy (to use on a real GameBoy). The four different sound modes of the GameBoy are available. It also demonstrates the use of bit fields in C (it's a quick hack, so don't expect too much from the code). The following keys are used:
+
+    UP/DOWN      : Move the cursor
+    RIGHT/LEFT   : Increment/decrement the value
+    RIGHT/LEFT+A : Increment/decrement the value by 10
+    RIGHT/LEFT+B : Set the value to maximum/minimum
+    START        : Play the current mode's sound (or all modes if in control screen)
+    START+A      : Play a little music with the current mode's sound
+    SELECT       : Change the sound mode (1, 2, 3, 4 and control)
+    SELECT+A     : Dump the sound registers to the screen
+
+
+# space
+The space example is an assembly program that demonstrates the use of sprites, window, background, fixed-point values and more. The following keys are used:
+
+    Arrow keys     : Change the speed (and direction) of the sprite
+    Arrow keys + A : Change the speed (and direction) of the window
+    Arrow keys + B : Change the speed (and direction) of the background
+    START          : Open/close the door
+    SELECT         : Basic fading effect
+
+
+# templates
+Two basic template examples are provided as a starting place for writing your GBDK programs.
+
diff --git a/gbdk/docs/pages/08_faq.md b/gbdk/docs/pages/08_faq.md
new file mode 100644
index 00000000..73423162
--- /dev/null
+++ b/gbdk/docs/pages/08_faq.md
@@ -0,0 +1,98 @@
+@page docs_faq Frequently Asked Questions (FAQ)
+
+@anchor toolchain_faq 
+
+# General
+  - How can sound effects be made?
+    - The simplest way is to use the Game Boy sound hardware directly. See the @ref examples_sound_sample "Sound Example" for a way to test out sounds on the hardware.
+    - Further discussion on using the Sound Example rom can be found in the ZGB wiki. Note that some example code there is ZGB specific and not part of the base GBDK API: https://github.com/Zal0/ZGB/wiki/Sounds <!-- -->
+
+# Graphics and Resources
+  - How do I use a tile map when its tiles don't start at index zero?
+    - The two main options are:
+      - Use @ref set_bkg_based_tiles(), @ref set_bkg_based_submap(), @ref set_win_based_tiles(), @ref set_win_based_submap() and provide a tile origin offset.
+      - Use @ref utility_png2asset with `-tile_origin` to create a map with the tile index offsets built in.
+      <!-- -->  
+
+# ROM Header Settings
+  - How do I set the ROM's title?
+    - Use the @ref makebin `-yn` flag. For example with @ref lcc `-Wm-yn"MYTITLE"` or with @ref makebin directly `-yn "MYTITLE"`. The maximum length is up to 15 characters, but may be shorter.
+    - See "0134-0143 - Title" in @ref Pandocs for more details. <!-- -->  
+
+  @anchor faq_gb_type_header_setting
+  - How do I set SGB, Color only and Color compatibility in the ROM header?
+    - Use the following @ref makebin flags. Prefix them with `-Wm` if using @ref lcc.
+      - `-yc` : GameBoy Color compatible
+      - `-yC` : GameBoy Color only
+      - `-ys` : Super GameBoy compatible <!-- -->  
+
+  - How do I set the ROM @ref MBC type, and what MBC values are available to use with the `-yt` @ref makebin flag?
+    - See @ref setting_mbc_and_rom_ram_banks <!-- -->  
+
+# Errors / Compiling / Toolchain
+  @anchor faq_sdcc_peephole_instruction_error
+  - What does `z80instructionSize() failed to parse line node, assuming 999 bytes` mean?
+    - This is a known issue with SDCC Peephole Optimizer parsing and can be ignored. A bug report has been filed for it. <!-- -->  
+
+  @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)`
+    - 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 faq_error_mbc_size
+  - What does `error: size of the buffer is too small` mean?
+    - Your program is using more banks than you have configured in the toolchain.
+      Either the MBC type was not set, or the number of banks or MBC type should be changed to provide more banks. 
+
+      See the section @ref setting_mbc_and_rom_ram_banks for more details. <!-- -->  
+
+  - What do the following kinds of warnings / errors mean?
+    `info 218: z80instructionSize() failed to parse line node, assuming 999 bytes`
+    - This is a known issue with SDCC, it should not cause actual problems and you can ignore the warning. <!-- -->  
+
+  - Why is the compiler so slow, or why did it suddenly get much slower?
+    - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data <!-- -->  
+
+  - What flags should be enabled for debugging?
+    - You can use the @ref lcc_debug "lcc debug flag" <!-- -->  
+
+  - Is it possible to generate a debug symbol file (`.sym`) compatible with the @ref bgb emulator?
+    - Yes, turn on `.noi` output (LCC argument: `-Wl-j` or `-debug` and then use `-Wm-yS` with LCC (or `-yS` with makebin directly). <!-- -->  
+
+  - How do I move the start of the `DATA` section and the `Shadow OAM` location?
+    - The default locations are: `_shadow_OAM=0xC000` and 240 bytes after it `_DATA=0xC0A0`
+    - So, for example, if you wanted to move them both to start 256(0x100) bytes later, use these command line arguments for LCC:
+      - To change the Shadow OAM address: `-Wl-g_shadow_OAM=0xC100`
+      - To change the DATA address (again, 240 bytes after the Shadow OAM): `-Wl-b_DATA=0xc1a0`
+     <!-- -->  
+
+
+# API / Utilities
+  - Is there a list of all functions in the API?
+    - [Functions](globals_func.html)
+    - [Variables](globals_vars.html) <!-- -->  
+
+  - Can I use the `float` type to do floating point math?
+    - There is no support for 'float' in GBDK-2020.
+    - Instead consider some form of `fixed point` math (including the @ref fixed_point_type "fixed" type included in GBDK). <!-- -->  
+
+  - Why are 8 bit numbers not printing correctly with printf()?
+    - To correctly pass chars/uint8s for printing, they must be explicitly re-cast as such when calling the function. See @ref docs_chars_varargs for more details.  <!-- -->  
+
+  - How can maps larger than 32x32 tiles be scrolled? & Why is the map wrapping around to the left side when setting a map wider than 32 tiles with set_bkg_data()?
+    - The hardware Background map is 32 x 32 tiles. The screen viewport that can be scrolled around that map is 20 x 18 tiles. In order to scroll around within a much larger map, new tiles must be loaded at the edges of the screen viewport in the direction that it is being scrolled. @ref set_bkg_submap can be used to load those rows and columns of tiles from the desired sub-region of the large map.
+    - See the "Large Map" example program and @ref set_bkg_submap().
+    - Writes that exceed coordinate 31 of the Background tile map on the x or y axis will wrap around to the Left and Top edges. <!-- -->  
+
+  - When using gbt_player with music in banks, how can the current bank be restored after calling gbt_update()? (since it changes the currently active bank without restoring it).
+    - See @ref banking_current_bank "restoring the current bank" <!-- -->  
+
+  - How can CGB palettes and other sprite properties be used with metasprites?
+    - See @ref metasprite_and_sprite_properties "Metasprites and sprite properties" <!-- -->  
+
+  - Weird things are happening to my sprite colors when I use png2asset and metasprites. What's going on and how does it work?
+    - See @ref utility_png2asset for details of how the conversion process works.
+
diff --git a/gbdk/docs/pages/09_migrating_new_versions.md b/gbdk/docs/pages/09_migrating_new_versions.md
new file mode 100644
index 00000000..854203d7
--- /dev/null
+++ b/gbdk/docs/pages/09_migrating_new_versions.md
@@ -0,0 +1,86 @@
+@page docs_migrating_versions Migrating to new GBDK Versions
+
+This section contains information that may be useful to know or important when upgrading to a newer GBDK release.
+
+# GBDK 2020 versions
+
+## Porting to GBDK 2020 4.0.6
+  - Renamed `bgb_emu.h` to `emu_debug.h` and BGB_* functions to EMU_*
+    - Aliases for the BGB_* ones and a `bgb_emu.h` shim are present for backward compatibility, but updating to the new naming is recommended
+
+
+## Porting to GBDK 2020 4.0.5
+  - GBDK now requires SDCC 12259 or higher with GBDK-2020 patches
+  - @ref utility_png2asset "png2asset" is the new name for the `png2mtspr` utility
+  - @ref lcc : Changed default output format when not specified from `.ihx` to `.gb` (or other active rom extension)
+  - The `_BSS` area is deprecated (use `_DATA` instead)
+  - The `_BASE` area is renamed to `_HOME`
+  - Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared)
+  - @ref itoa(), @ref uitoa(), @ref ltoa(), @ref ultoa() all now require a radix value (base) argument to be passed. On the Game Boy and Analogue Pocket the parameter is required but not utilized.
+  - set_bkg_1bit_data has been renamed to @ref set_bkg_1bpp_data
+  - The following header files which are now cross platform were moved from `gb/` to `gbdk/`: `bcd.h`, `console.h`, `far_ptr.h`, `font.h`, `gbdecompress.h`, `gbdk-lib.h`, `incbin.h`, `metasprites.h`, `platform.h`, `version.h`
+    - When including them use `#include <gbdk/...>` instead of `#include <gb/>`
+  
+## Porting to GBDK 2020 4.0.4
+  - GBDK now requires SDCC 12238 or higher
+  - Made sample.h, cgb.h and sgb.h independent from gb.h
+
+
+## Porting to GBDK 2020 4.0.3
+  - No significant changes required
+
+
+## Porting to GBDK 2020 4.0.2
+ - The default font has been reduced from 256 to 96 characters.
+   - Code using special characters may need to be updated.
+   - The off-by-1 character index offset was removed for fonts. Old fonts with the offset need to be re-adjusted.
+
+
+## Porting to GBDK 2020 4.0.1
+ - __Important!__ : The `WRAM` memory region is no longer automatically initialized to zeros during startup.
+   - Any variables which are declared without being initialized may have __indeterminate values instead of 0__ on startup. This might reveal previously hidden bugs in your code.
+   - Check your code for variables that are not initialized before use.
+   - In BGB you can turn on triggering exceptions (options panel) reading from unitialized RAM. This allows for some additional runtime detection of uninitialized vars.
+ - In .ihx files, multiple writes to the same ROM address are now warned about using @ref ihxcheck.
+ - `set_*_tiles()` now wrap maps around horizontal and vertical boundaries correctly. Code relying on it not wrapping correctly may be affected.
+
+
+## Porting to GBDK 2020 4.0
+ - GBDK now requires SDCC 4.0.3 or higher
+ - The old linker `link-gbz80` has been REMOVED, the linker @ref sdldgb from SDCC is used.
+   - Due to the linker change, there are no longer warnings about multiple writes to the same ROM address.
+ - GBDK now generates .ihx files, those are converted to a ROM using @ref makebin (lcc can do this automatically in some use cases)
+ - Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. See @ref faq_gb_type_header_setting.
+ - OAM symbol has been renamed to `_shadow_OAM`, that allows accessing shadow OAM directly from C code
+
+
+## Porting to GBDK 2020 3.2
+  - No significant changes required
+
+## Porting to GBDK 2020 3.1.1
+  - No significant changes required
+
+## Porting to GBDK 2020 3.1
+  - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). check here why:
+    https://gbdev.gg8.se/forums/viewtopic.php?id=697
+
+## Porting to GBDK 2020 3.0.1
+ - LCC was upgraded to use SDCC v4.0. Makefile changes may be required
+   - The symbol format changed. To get bgb compatible symbols turn on `.noi` output (LCC argument: `-Wl-j` or `-debug`) and use `-Wm-yS`
+   - ?? Suggested: With LCC argument: `-Wa-l` (sdasgb:`-a   All user symbols made global`)
+   - In SDCC 3.6.0, the default for char changed from signed to unsigned.
+     - If you want the old behavior use `--fsigned-char`.
+     - lcc includes `--fsigned-char` by default
+     - Explicit declaration of unsigned vars is encouraged (for example, '15U' instead of '15')
+   - `.init` address has been removed
+
+--------------------------------------------------
+
+# Historical GBDK versions
+
+## GBDK 1.1 to GBDK 2.0
+ - Change your int variables to long if they have to be bigger than 255. If they should only contain values between 0 and 255, use an unsigned int.
+ - If your application uses the delay function, you'll have to adapt your delay values.
+ - Several functions have new names. In particular some of them have been changed to macros (e.g. show_bkg() is now SHOW_BKG).
+ - You will probably have to change the name of the header files that you include.
+
diff --git a/gbdk/docs/pages/10_release_notes.md b/gbdk/docs/pages/10_release_notes.md
new file mode 100644
index 00000000..d6125e42
--- /dev/null
+++ b/gbdk/docs/pages/10_release_notes.md
@@ -0,0 +1,504 @@
+@page docs_releases GBDK Releases
+
+The GBDK 2020 releases can be found on Github:
+https://github.com/gbdk-2020/gbdk-2020/releases
+
+
+# GBDK 2020 Release Notes
+## GBDK 2020 4.0.6
+  2022/02
+  - Building GBDK
+    - Changed to target older version of macOS (10.10) when building for better compatibility
+  - Platforms
+    - Added support for Mega Duck / Cougar Boy (`duck`). See @ref docs_supported_consoles
+  - Library
+    - Added @ref memcmp()
+    - Added @ref add_low_priority_TIM() function for timer interrupts which allow nesting for GB/CGB
+    - Added @ref set_bkg_based_tiles(), @ref set_bkg_based_submap(), @ref set_win_based_tiles(), @ref set_win_based_submap() for when a map's tiles don't start at VRAM index zero
+    - Added @ref clock() for SMS/GG
+    - Added macro definitions for SDCC features:
+      - `#define SFR     __sfr`
+      - `#define AT(A)   __at(A)`
+    - Added check for OAM overflow to metasprite calls for GB/CGB
+    - Added constant definitions @ref PSG_LATCH, @ref PSG_CH0, @ref PSG_CH1, @ref PSG_CH2, @ref PSG_CH3, @ref PSG_VOLUME for SMS/GG
+    - Renamed `bgb_emu.h` to `emu_debug.h` and BGB_* functions to EMU_*.
+      - Aliases for the BGB_* ones and a `bgb_emu.h` shim are present for backward compatibility
+    - Changed headers to wrap SDCC specific features (such as `NONBANKED`) with `#ifdef __SDCC`
+    - Changed @ref rand() and @ref arand() to return `uint8_t` instead of `int8_t` (closer to the standard)
+    - Fixed declaration for @ref PCM_SAMPLE and definition for @ref AUD3WAVE
+    - Fixed definition of `size_t` to be `unsigned int` instead of  `int`
+    - Fixed @ref vmemcpy() and @ref memmove() for SMS/GG
+    - Fixed random number generation for SMS/GG
+    - Fixed letter `U` appearing as `K` for min font
+    - Fixed define name in crash_handler.h
+    - Exposed @ref __rand_seed
+  - Toolchain / Utilities
+    - @ref utility_png2asset "png2asset"
+      - Added SMS/GG graphics format support
+      - Added 4bpp and SGB borders
+      - Added warning when image size is not an even multiple of tile size
+      - Added `-tile_origin` offset option for when map tiles do not start at tile 0 in VRAM
+      - Added `*_TILE_COUNT` definition to output
+      - Fixed CGB `...s_map_attributes` type definition in output
+      - Fixed values for `num_palettes` in output
+      - Fixed incorrect `TILE_COUNT` value when not `-using_structs`
+    - @ref lcc
+      - Changed @ref makebin flags to turn off Nintendo logo copy for GB/CGB (use version in crt instead)
+      - Fixed lcc handling of makebin `-x*` arguments
+  - Examples
+    - Added logo example (cross-platform)
+    - Added @ref ISR_VECTOR example of a raw ISR vector with no dispatcher for GB/CGB
+    - Changed sgb_border example to use png2asset for graphics
+    - Changed use of set_interrupts() in examples so it's outside critical sections (since it disables/enables interrupts)
+    - Changed cross-platform auto-banks example to use .h header files
+    - Changed SGB border example to also work with SGB on PAL SNES
+  - Docs
+    - Added new section: Migrating From Pre-GBDK-2020 Tutorials
+
+
+## GBDK 2020 4.0.5
+  2021/09
+  - Includes SDCC version 12539 with GBDK-2020 patches for Z80
+  - Known Issues
+    - SDCC: `z80instructionSize() failed to parse line node, assuming 999 bytes`
+      - This is a known issue with the SDCC Peephole Optimizer parsing and can be ignored.
+    - `-bo<n>` and `-ba<n>` are not supported by the Windows build of @ref sdcc
+    - On macOS the cross platform `banks` example has problems parsing the filename based ROM and RAM bank assignments into `-bo<n>` and `-ba<n>`
+  - Added support for new consoles. See @ref docs_supported_consoles
+    - Analogue Pocket (`ap`)
+    - Sega Master System (`sms`) and Game Gear (`gg`)
+  - Library
+    - Fixed error when calling get_bkg_tile_xy: `?ASlink-Warning-Undefined Global '.set_tile_xy' referenced by module `
+?ASlink-Warning-Byte PCR relocation error for symbol  .set_tile_xy
+    - Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared)
+    - Added many new register flag constants and names. For example:
+      - @ref rLCDC is a new alias for @ref LCDC_REG
+      - @ref LCDCF_WINON, @ref LCDCF_WINOFF, @ref LCDCF_B_WINON
+    - Added @ref BANK(), @ref BANKREF(), @ref BANKREF_EXTERN()
+    - Added @ref INCBIN(), @ref BANK(), @ref INCBIN_SIZE(), @ref INCBIN_EXTERN()
+    - Added generic @ref SWITCH_ROM() and @ref SWITCH_RAM()
+    - Added @ref BGB_printf() and updated emulator debug output.
+    - Added @ref set_native_tile_data(), @ref set_tile_map(), @ref set_1bpp_colors, @ref set_bkg_1bpp_data, @ref set_sprite_1bpp_data, @ref set_2bpp_palette, @ref set_bkg_2bpp_data, @ref set_sprite_2bpp_data, @ref set_tile_2bpp_data (sms/gg only), @ref set_bkg_4bpp_data (sms/gg only), @ref set_sprite_4bpp_data (sms/gg only)
+    - Added RLE decompression support: @ref rle_init(), @ref  rle_decompress(),
+    - Changed @ref itoa(), @ref uitoa(), @ref ltoa(), @ref ultoa() to now require a radix value (base) argument to be passed. On the Game Boy and Analogue Pocket the parameter is required but not utilized.
+  - Examples
+    - Added cross-platform examples (build for multiple consoles: gb, ap, sms, gg)
+    - Added sms, gg, pocket(ap) examples
+    - Added incbin example
+    - Added simple physics sub-pixel / fixed point math example
+    - Added rle decompression example
+    - Changed windows make.bat files to compile.bat
+    - Bug fixes and updates for existing examples    
+  - Toolchain / Utilities
+    - @ref utility_png2asset "png2asset"
+      - @ref utility_png2asset "png2asset" is the new name for the `png2mtspr` utility
+      - Added collision rectangle width and height (`-pw`, `-ph`)
+      - Added option to use the palette from the source png (`-keep_palette_order`)
+      - Added option to disable tile flip (`-noflip`)
+      - Added export as map: tileset + bg (`-map`)
+      - Added option to use CGB BG Map attributes (`-use_map_attributes`)
+      - Added option to group the exported info into structs (`-use_structs`)
+    - @ref lcc
+      - Use `-m` to select target port and platform: "-m[port]:[plat]" ports:`gbz80,z80` plats:`ap,gb,sms,gg`
+      - Changed default output format when not specified from `.ihx` to `.gb` (or other active rom extension)
+      - Changed lcc to always use the linkerfile `-lkout=` option when calling bankpack
+      - Fixed name generation crash when outfile lacks extension
+    - @ref bankpack
+      - Added linkerfile input and output: `-lkin=<file>`, `-lkout=<file>`
+      - Added selector for platform specific behavior `plat=<plat>` (Default:gb, Avaialble:`gb,sms`). sms/gg targets prohibits packing `LIT_N` areas in the same banks as `CODE_N` areas
+      - Added randomization for auto-banks (`-random`) for debugging and testing
+    - @ref utility_gbcompress
+      - Added C source array format output (--cout) (optional variable name argument --varname=)
+      - Added C source array format input (--cin) (experimental)
+      - Added block style rle compression and decompression mode: `--alg=rle`
+      - Fixed comrpession errors when input size was larger than 64k
+  - Docs
+    - Added @ref docs_supported_consoles section
+    - Various doc updates and improvements
+  
+
+## GBDK 2020 4.0.4
+  2021/06
+  - Library
+    - Support SDCC INITIALIZER area (SDCC ~12207+)
+    - Added @ref get_vram_byte() / @ref get_win_tile_xy() / @ref get_bkg_tile_xy()
+    - Added @ref set_tile_data()
+    - Fixed SGB detection
+    - Fixed broken @ref get_tiles() / @ref set_tiles()
+    - Fixed broken token handling in @ref gb_decompress_sprite_data() / @ref gb_decompress_bkg_data() / @ref gb_decompress_win_data()
+    - Changed all headers to use standard `stdint.h` types (ex: `uint8_t` instead of `UINT8`/`UBYTE`)
+    - Made sample.h, cgb.h and sgb.h independent from gb.h
+  - Examples
+    - Added project using a .lk linkerfile
+    - Changed all examples to use standard stdint.h types
+    - Moved banks_farptr and banks_new examples to "broken" due to SDCC changes
+  - Toolchain / Utilities
+    - png2mtspr
+      - Added option to change default value for sprite property/attributes in (allows CGB palette, BG/WIN priority, etc).
+      - Improved: Turn off suppression of "blank" metasprite frames (composed of entirely transparent sprites)
+      - Fixed endless loop for png files taller than 255 pixels
+    - bankpack
+      - Fixed -yt mbc specifier to also accept Decimal
+      - Improved: bank ID can be used in same file it is declared. Requires SDCC 12238+ with `-n` option to defer symbol resolution to link time.
+    - gbcompress
+      - Added C source input (expirimental) and output
+      - Added size `#defines`
+    - lcc
+      - Added `-no-libs` and `-no-crt` options
+      - Added support for .lk linker files (useful when number of files on lcc command line exceeds max size on windows)
+      - Added support for converting .ihx to .gb
+      - Added rewrite .o files -> .rel for linking when called with `-autobank` and `-Wb-ext=.rel`
+      - Workaround @ref makebin `-Wl-yp` formatting segfault
+  - Docs
+    - Improved utility_png2mtspr documentation
+    - Various doc updates and improvements
+
+
+## GBDK 2020 4.0.3
+  2021/03
+  - Library
+    - 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 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
+    - Improved @ref printf(): ignore %0 padding and %1-9 width specifier instead of not printing, support upper case %X
+    - Fixed @ref line(): handle drawing when x1 is less than x2
+  - Examples
+    - Added large_map: showing how to use @ref set_bkg_submap()
+    - Added scroller: showing use of @ref get_bkg_xy_addr(), @ref set_bkg_tile_xy() and @ref set_vram_byte
+    - Added gbdecompress: de-compressing tile data into vram
+    - Added metasprites: show creating a large sprite with the new metasprite api
+    - Added template projects
+    - Fixed build issue with banks_autobank example
+    - Improved sgb_border
+  - Toolchain / Utilities
+    - Added @ref utility_gbcompress utility
+    - Added 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
+ 
+
+## GBDK 2020 4.0.2
+  2021/01/17
+  - Includes SDCC snapshot build version 12016 (has a fix for duplicate debug symbols generated from inlined header functions which GBDK 4.0+ uses)
+  - Updated documentation
+  - Library was improved
+      - Linking with stdio.h does not require that much ROM now
+      - Default font is changed to the smaller one (102 characters), that leaves space for user tiles
+      - Fixed broken support for multiplying longs
+      - memset/memcpy minor enhancements
+      - safer copy-to-VRAM functions
+      - loading of 1bit data fixed, also now it is possible to specify pixel color
+      - Improved code generation for the GBDK Library with SDCC switch on by default: `--max-allocs-per-node 50000`
+      - fixed wrong parameter offsets in hiramcpy() (broken ram_function example)
+      - Multiple minor improvements
+  - 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
+    - Fixed option to specify alternate base addresses for shadow_OAM, etc
+  - Examples: Added bgb debug example
+
+
+## GBDK 2020 4.0.1
+  2020/11/14
+  - Updated API 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
+    - set_*_tiles() now wrap maps around horizontal and vertical boundaries correctly
+    - new fill_*_rect() functions to clear rectangle areas
+    - runtime initialization code now does not initialize whole WRAM with zeros anymore, that allows BGB to raise exceptions when code tries to read WRAM that was not written before.
+    - enhanced SGB support
+     - joypad_init() / joypad_ex() support for multiple joypads
+     - SGB border example
+    - _current_bank variable is updated when using bank switching macros
+    - Reorganized examples: each example is in separate folder now, that simplifies understanding.
+    - Lcc improvements
+      - Fix -S flag
+      - Fix default stack location from 0xDEFF to 0xE000 (end of WRAM1)
+      - Fix cleanup of .adb files with -Wf--debug flag
+      - Fix output not working if target is -o some_filename.ihx
+
+
+## GBDK 2020 4.0
+  2020/10/01
+  - 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!
+    - SDCC 4.0.4 has fixed RGBDS support; library is not updated to support that in full yet, but it is possible to assemble and link code emitted by SDCC with RGDBS
+    - New banked trampolines are used, they are faster and smaller
+    - New (old) initialization for non-constant arrays do NOT require 5 times larger rom space than initialized array itself, SDCC even tries to compress the data
+  - Library was improved
+    - itoa/ltoa functions were rewritten, div/mod is not required now which is about 10 times faster
+    - sprite functions are inline now, which is faster up to 12 times and produces the same or smaller code; .OAM symbol is renamed into _shadow_OAM that allows accessing shadow OAM directly from C code
+    - interrupt handling was revised, it is now possible to make dedicated ISR's, that is important for time-sensitive handlers such as HBlank.
+    - printf/sprintf were rewritten and splitted, print functions are twice faster now and also requre less rom space if you use sprintf() only, say, in bgb_emu.h
+    - crash_handler.h - crash handler that allows to detect problems with ROMs after they are being released (adapted handler, originally written by ISSOtm)
+    - improved and fixed string.h
+    - many other improvements and fixes - thanks to all contributors!
+  - Revised examples
+  - Improved linux support
+  - Lcc has been updated
+    - it works with the latest version of sdcc
+    - quoted paths with spaces are working now
+
+
+## GBDK 2020 3.2
+  2020/06/05
+  - Fixed OAM initialization that was causing a bad access to VRAM
+  - Interrupt handlers now wait for lcd controller mode 0 or 1 by default to prevent access to inaccessible VRAM in several functions (like set_bkg_tiles)
+  - Several optimizations here and there
+
+
+## GBDK 2020 3.1.1
+  2020/05/17
+  - Fixed issues with libgcc_s_dw2-1.dll
+
+
+## GBDK 2020 3.1
+  2020/05/16
+  - Banked functions are working! The patcher is fully integrated in link-gbz80, no extra tools are needed. It is based on Toxa's work
+    - Check this post for more info
+    - Check the examples/gb/banked code for basic usage
+  - Behavior formerly enabled by USE_SFR_FOR_REG is on by default now (no need to specify it, it isn't a tested `#ifdef` anymore). check here why:
+    https://gbdev.gg8.se/forums/viewtopic.php?id=697
+  - Fixed examples that were not compiling in the previous version and some improvements in a few of them. Removed all warnings caused by changing to the new SDCC
+  - Fixed bug in lcc that was causing some files in the temp folder not being deleted
+  - Removed as-gbz80 (the lib is now compiled with sdasgb thanks to this workaround)
+    https://github.com/gbdk-2020/gbdk-2020/commit/d2caafa4a66eb08998a14b258cb66af041a0e5c8
+  - Profile support with bgb emulator
+    - 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 and this post
+      https://github.com/untoxa/bgb_profiling_toolkit/blob/master/readme.md
+      https://gbdev.gg8.se/forums/viewtopic.php?id=710
+
+
+## GBDK 2020 3.0.1
+  2020/04/12
+  - Updated SDCC to v.4.0
+  - Updated LCC to work with the new compiler
+
+
+## GBDK 2020 3.0
+  2020/04/12
+  - Initial GBDK 2020 release  
+  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 
+  line 32 after ".org .MODE_TABLE+4*.G_MODE" it's writing more
+  than 4 bytes invading some addresses required by input.s:41)
+  Because of this, all .s files in libc have been assembled 
+  with the old as-gbz80 and that's why it is still included
+
+
+# Historical GBDK Release Notes
+
+## GBDK 2.96
+  17 April, 2000  
+  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.
+
+## GBDK 2.95-3
+  19th August, 2000  
+
+  * Stopped lcc with sdcc from leaking .cdb files all across
+    /tmp.
+  * Optimised < and > for 16 bit varibles.
+  * Added a new lexer to sdcc.  Compiling files with large
+    initalised arrays takes 31% of the time (well, at least
+    samptest.c does :)  
+
+  This is an experimental release for those who feel keen. The main change is a new lexer (the first part in the compilation process which recognises words and symbols like '!=' and 'char' and turns them into a token number) which speeds up compilation of large initialised arrays like tile data by a factor of three. Please report any bugs that show up - this is a big change.
+
+  I have also included a 'minimal' release for win32 users which omits the documentation, library sources, and examples. If this is useful I will keep doing it.
+
+## GBDK 2.95-2
+  5th August, 2000  
+  Just a small update. From the README:
+
+  * Added model switching support
+     --model-medium uses near (16 bit) pointers for data, and
+     banked calls for anything not declared as 'nonbanked'
+     --model-small uses near (16 bit) pointers for data and
+     calls.  Nothing uses banked calls.  'nonbanked' functions
+     are still placed in HOME.  Libraries are under lib/medium
+     and lib/small.
+  * Added the gbdk version to 'sdcc --version'
+  * Changed the ways globals are exported, reducing the amount
+    of extra junk linked in.
+  * Turned on the optimisations in flex.  Large constant arrays
+    like tile data should compile a bit faster.
+
+## GBDK 2.95
+  22nd July, 2000 
+  * Fixed 'a << c' for c = [9..15]
+  * no$gmb doesn't support labels of > 32 chars.  The linker now
+  trims all labels to 31 chars long.
+  * Fixed wait_vbl for the case where you miss a vbl
+  * Fixed + and - for any type where sizeof == 2 and one of the
+  terms was on the stack.  This includes pointers and ints. Fixes
+  the text output bug in the examples.  Should be faster now as
+  well.  Note that + and - for longs is still broken.
+  * Fixed the missing */ in gb.h
+  * Added basic far function support.  Currently only works for isas
+  and rgbasm.  See examples/gb/far/*
+  * bc is now only pushed if the function uses it.  i.e. something
+  like:
+      int silly(int i) 
+      {
+      return i;
+      }   
+  will not have the push bc; pop bc around it.
+  * Better rgbasm 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..."
+  
+  to link everything together.  The .lib files are generated using
+  astorgb.pl and sdcc to turn the gbdk libraries into something
+  rgbds compatible.
+  The libraries are _not_ fully tested.  Trust nothing.  But give it
+  a go :)
+  * Ran a spell checker across the README and ChangeLog  
+
+  This is a recommended upgrade. Some of the big features are:
+
+  Decent rgbds support. All the libraries and most of the examples can now compile with rgbds as the assembler.
+  Banked function support. It is now easier to break the 32k barrier from within C. Functions can live in and be called transparently from any bank. Only works with rgbds
+  Fixed some decent bugs with RSH, LSH, and a nasty bug with + and - for int's and pointers.
+  Various optimisations in the code generator.
+
+  7th July, 2000  
+  Information on float and long support. Someone asked about the state of float/long support recently. Heres my reply:
+
+  long support is partly there, as is float support. The compiler will correctly recognise the long and float keywords, and will generate the code for most basic ops (+, -, &, | etc) for longs correctly and will generate the function calls for floats and hard long operations (*, /, %) correctly. However it wont generate float constants in the correct format, nor will it 'return' a long or float - gbdk doesn't yet support returning types of 4 bytes. Unfortunately its not going to make it into 2.95 as there's too much else to do, but I should be able to complete long support for 2.96
+
+## GBDK 2.94
+  7th May, 2000  
+  Many fixes - see the README for more.
+
+  7th May - Library documentation up. A good size part of the libraries that go with gbdk have been documented - follow the HTML link above to have a look. Thanks to quang for a good chunk of the gb.h documentation. Please report any errors :)
+   * Fixed 
+        \#define BLAH  7  // Unterminated ' error
+      in sdcpp
+    * Fixed
+        SCY_REG += 2, SCY_REG -= 5
+      (add and subtract in indirect space) as they were both quite broken.
+    * externs and static's now work as expected.
+    * You can now specify which bank code should be put into using a
+      \#pragma e.g:
+        \#pragma bank=HOME
+    Under rgbds and asxxxx putting code in the HOME bank will force
+    the code into bank 0 - useful for library functions.  The most
+    recent \#pragma bank= will be the one used for the whole file.
+    * Fixed an interesting bug in the caching of lit addresses
+    * Added support for accessing high registers directly using the
+    'sfr' directive.  See libc/gb/sfr.s and gb/hardware.h for an
+    example.  It should be possible with a bit of work to make high
+    ram directly usable by the compiler; at the moment it is
+    experimental.  You can test sfr's by enabling USE_SFR_FOR_REG=1
+    * Added remove_VBL etc functions.
+    * Documented the libs - see the gbdk-doc tarball distributed
+    seperatly.
+    * Two dimensional arrays seem to be broken.
+
+## GBDK 2.93
+  6th April, 2000  
+  From the README
+
+  * 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
+  assembler.  Try -W--asm=rgbds or -W--asm=isas.  The ISAS code is
+  untested as I dont have access to the real assembler.
+  * RSH is fixed
+  * AND is fixed
+  * The missing parts of 2.1.0's libs are there.  Note: They are
+  untested.
+  * The dscan demo now fully works (with a hack :)
+  * There is a bug with cached computed values which are later used
+  as pointers.  When the value is first used as a BYTE arg, then
+  later as a pointer the pointer fails as the high byte was never
+  computed and is now missing.  A temporary fix is to declare
+  something appropriate as 'volatile' to stop the value being
+  cached.  See dscan.c/bombs() for an example.
+
+## GBDK 2.92-2 for win32
+  26th March, 2000  
+  This is a maintenance release for win32 which fixes some of the niggly install problems, especially:
+  * 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=...
+     - Problems with the installer (now uses WinZip)
+     - Problems with the temp directory
+      Now scans TMP, TEMP, TMPDIR and finally c: tmp
+     - cygwin1.dll and 'make' are no longer required
+      gbdk is now built using mingw32 which is win32 native
+      make.bat is automagically generated from the Makefile
+     - I've reverted to using WORD for signed 16 bit etc.
+      GBDK_2_COMPAT is no longer required.
+
+  WORDS are now back to signed. GBDK_2_COMPAT is no longer needed.
+  Temporary files are created in TMP, TEMP, or TMPDIR instead of c: tmp
+  The installer is no more as it's not needed. There is a WinZip wrapped version for those with the extra bandwidth :).
+  gbdk autodetects where it is installed - no more environment variables.
+  cygwin1.dll and make are no longer required - gbdk is now compiled with mingw32.
+
+  See the ChangeLog section in the README for more information.
+
+  21st March, 2000  
+  Problems with the installer. It seems that the demo of InstallVISE has an unreasonably short time limit. I had planed to use the demo until the license key came through, but there's no sign of the key yet and the 3 day evaluation is up. If anyone knows of a free Windows installer with the ability to modify environment variables, please contact me. I hear that temporarily setting you clock back to the 15th works...
+
+  18th March, 2000  
+  libc5 version available / "Error creating temp file" Thanks to Rodrigo Couto there is now a Linux/libc5 version of gbdk3-2.92 available - follow the download link above. At least it will be there when the main sourceforge site comes back up... Also some people have reported a bug where the compiler reports '*** Error creating temp file'. Try typing "mkdir c: tmp" from a DOS prompt and see if that helps.
+
+## GBDK 2.92
+  8th March, 2000  
+  Better than 2.91 :). Can now be installed anywhere. All the demos work. See the README for more.
+  * All the examples now work (with a little bit of patching :)
+    * Fixed problem with registers being cached instead of being
+    marked volatile.
+    * More register packing - should be a bit faster.
+    * You can now install somewhere except c: gbdk | /usr/lib/gbdk
+    * Arrays initialised with constant addresses a'la galaxy.c now
+    work.
+    * Fixed minor bug with 104$: labels in as.
+    * Up to 167d/s...  
+
+## GBDK 2.91
+  27th Feb, 2000  
+ Better than 2.90 and includes Linux, win32 and a source tar ball. Some notes:
+
+  Read the README first
+  Linux users need libgc-4 or above. Debian users try apt-get install libgc5.
+  All the types have changed. Again, please read the README first.
+  I prefer release early, release often. The idea is to get the bugs out there so that they can be squashed quickly.
+  I've split up the libs so that they can be used on other platforms and so that the libs can be updated without updating the compiler. One side effect is that gb specific files have been shifted into their own directory i.e. gb.h is now gb/gb.h.
+
+  23rd Feb, 2000  
+  First release of gbdk/sdcc.
+  This is an early release - the only binary is for Linux and the source is only available through cvs. If your interested in the source, have a look at the cvs repository gbdk-support first, which will download all the rest of the code. Alternatively, look at gbdk-support and gbdk-lib at cvs.gbdk.sourceforge.net and sdcc at cvs.sdcc.sourceforge.net. I will be working on binaries for Win32 and a source tar ball soon. Please report any bugs through the bugs link above.
+
+  31st Jan, 2000  
+  Added Dermot's far pointer spec. It's mainly here for comment. If sdcc is ported to the Gameboy then I will be looking for some way to do far calls.
+
+  8th Jan, 2000  
+  Moved over to sourceforge.net. Thanks must go to David Pfeffer for gbdk's previous resting place, www.gbdev.org. The transition is not complete, but cvs and web have been shifted. Note that the cvs download instructions are stale - you should now look to cvs.gbdk.sourceforge.net.
+  I am currently working on porting sdcc over to the Z80. David Nathan is looking at porting it to the GB.
+
+  6th Jan, 2000  
+  Icehawk wrote "I did write some rumble pack routines. Just make sure to remind people to add -Wl-yt0x1C or -Wl-yt0x1D or -Wl-yt0x1E depending on sram and battery usage. Find the routines on my site (as usual). =)"
+
+  18th Oct, 1999  
+  Bug tracking / FAQ up. Try the link on the left to report any bugs with GBDK. It's also the first place to look if your having problems.
+
+## GBDK 2.1.5
+  17th Oct, 1999  
+
+  The compiler is the same, but some of the libraries have been improved. memset() and memcpy() are much faster, malloc() is fixed, and a high speed fixed block alternative malloc() was added.
diff --git a/gbdk/docs/pages/20_toolchain_settings.md b/gbdk/docs/pages/20_toolchain_settings.md
new file mode 100644
index 00000000..6ab9f5ec
--- /dev/null
+++ b/gbdk/docs/pages/20_toolchain_settings.md
@@ -0,0 +1,465 @@
+@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	Turns 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'
+-m	select port and platform: "-m[port]:[plat]" ports:gbz80,z80 plats:ap,duck,gb,sms,gg
+-N	do not search the standard directories for #include files
+-n	emit code to check for dereferencing zero pointers
+-no-crt do not auto-include the gbdk crt0.o runtime in linker list
+-no-libs do not auto-include the gbdk libs in linker list
+-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 : z80/gbz80 4.1.6 #12539 (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 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 (deprecated)
+      --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>
+      --asm=                Define assembler name (rgbds/asxxxx/isas/z80asm/gas)
+      --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
+```
+@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
+  -n   Don't resolve global assigned value symbols
+  -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 sdasz80-settings
+# sdasz80 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
+  -n   Don't resolve global assigned value symbols
+  -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
+-lkin=<file> : Load object files specified in linker file <file>
+-lkout=<file>: Write list of object files out to linker file <file>
+-yt<mbctype> : Set MBC type per ROM byte 149 in Decimal or Hex (0xNN) (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>"
+-plat=<plat> : Select platform specific behavior (default:gb) (gb,sms)
+-random      : Distribute banks randomly for testing (honors -min/-max)
+-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
+  -a   (platform) Select platform specific virtual address translation
+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 sdldz80-settings
+# sdldz80 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
+  -a   (platform) Select platform specific virtual address translation
+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
+Also see @ref setting_mbc_and_rom_ram_banks
+```
+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             generate GameBoy format binary file
+  -S             generate Sega Master System format binary file
+SMS format options (applicable only with -S option):
+  -xo n          rom size (0xa-0x2)
+  -xj n          set region code (3-7)
+  -xv n          version number (0-15)
+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
+  -yN            do not copy big N validation logo into ROM header
+  -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: compress a binary file and write it out.
+
+Options
+-h    : Show this help screen
+-d    : Decompress (default is compress)
+-v    : Verbose output
+--cin  : Read input as .c source format (8 bit char ONLY, uses first array found)
+--cout : Write output in .c / .h source format (8 bit char ONLY) 
+--varname=<NAME> : specify variable name for c source output
+--alg=<type>     : specify compression type: 'rle', 'gb' (default)
+Example: "gbcompress binaryfile.bin compressed.bin"
+Example: "gbcompress -d compressedfile.bin decompressed.bin"
+Example: "gbcompress --alg=rle binaryfile.bin compressed.bin"
+
+The default compression (gb) is the type used by gbtd/gbmb
+The rle compression is Amiga IFF style
+```
+@anchor png2asset-settings
+# png2asset settings
+```
+usage: png2asset    <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)
+-sp <props>         change default for sprite OAM property bytes (in hex) (default: 0x00)
+-px <x coord>       metasprites pivot x coordinate (default: metasprites width / 2)
+-py <y coord>       metasprites pivot y coordinate (default: metasprites height / 2)
+-pw <width>         metasprites collision rect widht (default: metasprites width)
+-ph <height>        metasprites collision rect height (default: metasprites height)
+-spr8x8             use SPRITES_8x8 (default: SPRITES_8x16)
+-spr8x16            use SPRITES_8x16 (default: SPRITES_8x16)
+-b <bank>           bank (default 0)
+-keep_palette_order use png palette
+-noflip             disable tile flip
+-map                Export as map (tileset + bg)
+-use_map_attributes Use CGB BG Map attributes (default: palettes are stored for each tile in a separate array)
+-use_structs        Group the exported info into structs (default: false) (used by ZGB Game Engine)
+-bpp                bits per pixel: 2, 4 (default: 2)
+-max_palettes       maximum number of palettes allowed (default: 2)
+-pack_mode          gb, sgb or sms (default:GB)
+-tile_origin        tile index offset for maps (instead of zero)
+```
diff --git a/gbdk/docs/pages/docs_index.md b/gbdk/docs/pages/docs_index.md
new file mode 100644
index 00000000..19b8386b
--- /dev/null
+++ b/gbdk/docs/pages/docs_index.md
@@ -0,0 +1,64 @@
+@mainpage General Documentation
+
+@anchor docs_index
+- @subpage docs_getting_started
+- @subpage docs_links_and_tools
+- @subpage docs_using_gbdk
+- @subpage docs_coding_guidelines
+- @subpage docs_rombanking_mbcs
+- @subpage docs_supported_consoles
+- @subpage docs_toolchain
+- @subpage docs_example_programs
+- @subpage docs_faq
+- @subpage docs_migrating_versions
+- @subpage docs_releases
+- @subpage docs_toolchain_settings
+
+
+
+# Introduction
+Welcome to GBDK-2020! The best thing to do is head over to the @ref docs_getting_started "Getting Started" section to get up and running.
+
+
+# About the Documentation
+This documentation is partially based on material written by the original GBDK authors in 1999 and updated for GBDK-2020. The API docs are automatically generated from the C header files using Doxygen.
+
+GBDK-2020 is an updated version of the original GBDK with a modernized SDCC toolchain and many API improvements and fixes. It can be found at: https://github.com/gbdk-2020/gbdk-2020/.
+
+The original GBDK sources, documentation and website are at: http://gbdk.sourceforge.net/
+
+
+# About GBDK
+The GameBoy Developer's Kit (GBDK, GBDK-2020) is used to develop games and programs for the Nintendo Game Boy (and some other consoles) in C and assembly. GBDK includes a set of libraries for the most common requirements and generates image files for use with a real GameBoy or emulators.
+
+GBDK features:
+ - C and ASM toolchain based on SDCC with some support utilities
+ - A set of libraries with source code
+ - Example programs in ASM and in C
+ - Support for multiple ROM bank images and auto-banking
+ - Support for multiple consoles: Game Boy, Analogue Pocket, Mega Duck, Master System and Game Gear
+
+GBDK is freeware. Most of the tooling code is under the GPL. The runtime libraries should be under the LGPL. Please consider mentioning GBDK in the credits of projects made with it.
+
+- - - - - -
+
+# Historical Info and Links
+
+Work on the original GBDK (pre-2020) was by:
+
+Pascal Felber, Lars Malmborg, Michael Hope, David Galloway (djmips), and others.
+
+
+The following is from the original GBDK documentation:
+
+Thanks to quang for many of the comments to the gb functions.  Some
+of the comments are ripped directly from the Linux Programmers
+manual, and some directly from the pan/k00Pa document.
+
+<a href="http://quangdx.com/">quangDX.com</a>
+
+<a href="http://gbdk.sourceforge.net/">The (original) gbdk homepage</a>
+
+<a href="http://www.devrs.com/gb/">Jeff Frohwein's GB development page.</a>
+A extensive source of Game Boy related information, including GeeBee's GB faq and the pan/k00Pa document.
+