Developing for WonderWitch

The WonderWitch is an official homebrew development environment provided by Qute Corporation.

As the official toolchain is proprietary, Wonderful provides its own toolchain for the platform, allowing use of both BIOS system calls and direct hardware access.

• The target uses the small memory model. As such, far functions are not allowed, and code can only be up to 64 kilobytes in total.
• The target's data segment points to SRAM (segment 0x1000), while the stack segment points to console RAM (segment 0x0000). This causes differences in how memory is managed:
  • Data does not co-exist with console RAM; the full 64 kilobytes is available to the program.
  • Local variables are in the stack, which is a different address space than static data. As such, pointers to it require a stack (__seg_ss) or far (__far) address space tag!
  • Using the ws_iram address space tag for pointers to IRAM (such as tile or screen data) is required.
• The target's code segment is dynamic and relocation is not supported. This means far pointers to code cannot be created at compile time, and manual relocations based on the code segment will not work.

• The “data segment =/= stack segment” memory layout is less common in 16-bit 8086 C development and, as such, has received fewer tests. Code may be less reliable than on the native wswan target.
• Some FreyaOS functionality (file system, process management) is not fully implemented.

The traditional way to distribute a WonderWitch program is through a set of one or more Freya-headered executable files, or .fx files. These are created by applying the wf-wwitchtool mkfent tool to an ELF file; however, this tool can be used to add a Freya file header to any file.

As the WonderWitch hardware is expensive and usage of emulators and flash cartridges is more common, particularly on the Western side of the WonderSwan fan community, programs are additionally built as .ws ROM images. These are built based on an open source, clean room reimplementation of the BIOS and OS, therefore they do not constitute copyright infringement.

The wf-wwitchtool mkrom tool can be used to turn any set of files into a ROM image. The default Makefile will include any files in the rom0 subdirectory in addition to the program executable.