Support 128K memory bank switching for bigger games

[jorgegv]

Support 128K memory bank switching for bigger games.

Development is done in branch banked_game_data

A (WIP) design document for this functionality can be found in that branch, in doc/BANKING-DESIGN.md

Main goal

• Allow games to use all 8 RAM banks in the ZX Spectrum 128: 3 banks are already used as the standard 48K (5,2,0), allow use of the remaining ones (1,3,4,6,7)
  • Design a memory manager (desired features: RO/RW pages, compressed pages) and memory map
  • Modify RAGE1 tools to locate game data elements in memory according to the memory map
  • Modify RAGE1 tools to generate memory manager configuration
  • Modify engine for multiple datasets/banks
• Allow compiling for 48K/128K using the same sources - Use case: you start your project compiling for 48 and when memory gets tight, you change to 128 mode with no source changes besides a config option
• Update documentation

Steps

• Design a standard memory map (interrupts, heap, code, bss, data)
• Design memory map and write design document
• Test new memory map with stubs for:
  • Heap memory management
  • Interrupt management
  • SP1 library
• Test memory manager:
  • Modify RAGE1 to generate game data in a new section
    • Refactor DATAGEN/FLOWGEN for better generation of mixed ASM/C/H files
    • Create generic sprite/bullet/hero initialization function + Make DATAGEN output sprite definition data + Remove DATAGEN generation of sprite/bullet/hero init functions ( -> this makes screens consist only of data, no code, which is needed to do banking with SDCC)
    • Make DATAGEN generate different C files for data that is always accesible (e.g. Hero/Bullet sprites, game map, which go into the home bank, the same as code), and data that is associated to map screens (assets, which go in the paged memory banks)
    • Integrate FLOWGEN data generation into DATAGEN
    • Generate FLOW data which refers to one single screen contiguous with the rest of screen data
    • Reorder DATAGEN data generation so that all data belonging to a single map screen is contiguous and can be located in the same memory bank
    • Move banked data into high memory banks:
      • Vectorize accesses to game assets via pointers at a known address - see data: access game assets via pointers in fixed memory address #48
      • Modify Makefile to build banked data binary file (see this link for ideas) - Datasets
      • Compress dataset binaries with ZX0
      • Create r1banktool.pl to manage the bank and TAP layout:
        • Gathers compiled+compressed datasets and packs them out efficiently in the memory banks (searches for dataset_*.zx0 files in datasets dir)
        • Creates the bank_N.bin files in banks directory (to be created). They will be later processed to get TAPs.
        • Generate a dataset_map.asm source file which will be included in the main program. This file maps dataset -> memory bank and start address so that whenever a dataset needs to be loaded, we know where to find it.
        • Generate a BASIC loader that loads the datasets in the memory banks in a fixed order
        • Generate also a bank_bins.cfg which contains the bank numbers in the same order that the BASIC loader is going to load them.
        • Integrate these changes into the general build
      • Modify Makefile to create the final TAP file with the generated BASIC loader, the main program and the TAPs for all the used banks. The bank TAPs are used according to the previously generated banks.cfg
      • Modify RAGE1 test program to initialize memory manager at start and load the original data at the LOWMEM page frame
• Design and document final heap location
  • Adjust heap start and size
  • Document heap configuration and maximum values for e.g. SP1 sprites, which is the main (only?) heap user
• Refactor and generalize: mutiple datasets, "resident" (always available) home_dataset.
  • Document the design of 48/128 compilation mode
  • Make DATAGEN generate game data in multiple datasets - see datagen: generate game data in multiple datasets #49
  • Conditional 48/128 compilation based on a game_config setting (e.g. zx_target directive, with 48/128 values). For 48mode, only home_dataset is compiled, all assets go there and the banking functions are not used. For 128 mode, all functionality from this issue is brought in.
• Update USAGE-OVERVIEW.md with instructions for 48/128 builds

This issue has originated the following non-trivial design changes:

• Complete memory map redesign
• Classification of assets into home and banked types
• Complex build system with multiple TAP blocks and custom BASIC loader
• Explicit heap dimensioning and initialization
• Split asset state and configuration for all asset types

[jorgegv]

Wonderfull and concise instructions for bank switching in 128k mode:

https://z88dk.org/forum/viewtopic.php?p=19215#p19215

[jorgegv]

merged in 95777c4