Porting WonderWitch applications

WonderWitch applications compiled using the official Qute SDK require a copy of FreyaOS (and FreyaBIOS) to run. Unfortunately, nowadays a loose WonderWitch cartridge required to run such programs can go for as much as $100 on the second-hand market, with the full SDK fetching prices above $200 - much more than the console itself. This makes not just creating, but even running WonderWitch applications inaccessible to most hobbyists.

(If you're an employee of Qute Corporation reading this, I would be very happy to volunteer and help resolving this situation.)

However, there already exists a large base of tutorials and software, including open source software, written for the API provided by Freya. One way to facilitate interoperability between the Wonderful toolchain (and, by extension, alternate execution environments) and such WonderSwan software would be to reimplement the required parts of the Freya API. In the past, projects like WSSim and WWWLib have been created to achieve this, as well as dedicated emulators like MiracleMage.

The Wonderful toolchain provides the libwwcl (WWitch Compatibility Layer) library for this purpose - a clean room reimplementation of selected Freya APIs.

To create a libwwcl project template, use the -t wwcl argument when creating a new project:

  $ wf-wswantool project new -t wwcl new_project_name

• While a Freya application uses the Makefile to configure the default memory layout (ASCII1, ASCII2, JAPANESE1, JAPANESE2), libwwcl relies on WWCL_INIT_MODE macros and the wwcl_init() function for this.
  • These macros and functions are provided in <wwcl.h>, which is a new header that can be used instead of <sys/bios.h>.
  • The macros are entirely optional. If you want to declare the memory layout yourself using the Wonderful toolchain's memory management, that is supported - use wwcl_init_custom() in this situation.
• A Freya application uses on-cartridge SRAM as static data space. This is not currently available on Wonderful - however, WonderSwan Color
  • gcc-ia16 requires a __far modifier for all constant arrays to be stored in ROM. See Addressing RAM and ROM for more information.
• The Text API operates on Shift-JIS strings. To make gcc-ia16 use Shift-JIS strings instead of UTF-8 strings, pass -fexec-charset=shift-jis to the compiler.

The implementation is incomplete; you can help by expanding it.

• Bank (bank.h) is not implemented.
• Color (libwwc.h) is mostly implemented.
• Comm (comm.h) is mostly implemented (comm_xmodem missing).
• Display (disp.h) is fully implemented.
• Key (key.h) is partially implemented (key repeat support missing).
• Sound (sound.h) is mostly implemented.
• System (system.h) is partially implemented (a lot of its functionality is only useful inside a FreyaOS environment, however).
• Text (text.h) is partially implemented (cursor support missing).
• Timer (timer.h) is partially implemented (real time clock support missing).