ROM header

The file extensions used to mark WS cartridge files are typically:

• .ws - "mono" WonderSwan,
• .wsc - WonderSwan Color,
• .pc2 - Pocket Challenge V2.

ROM header

Every WonderSwan cartridge ROM contains a header.

The header is stored at the end (the final sixteen bytes) of the ROM image. For this reason, it is also sometimes called a "footer".

A notable consequence of this is that, unlike most other platforms, non-power-of-two ROM images are expected to be padded to the last bank downwards, rather than the first bank upwards; for example, a 768 KiB ROM image will be padded to 1 MiB by appending 256 KiB of padding data to the beginning, rather than the end of the ROM.

Parts of this header are validated or otherwise used by the console's boot ROM - they are marked in bold.

Header contents

Offset	Length	Contents
$0	5	Far jump instruction: 0xEA, offset, segment.
$5	1	Maintenance
$6	1	Developer/Publisher ID
$7	1	Color
$8	1	Game ID (binary-coded decimal)
$9	1	Game version? / Safe mode
$A	1	ROM size
$B	1	Save type/size
$C	1	Flags
$D	1	Mapper
$E	2	Checksum (sum of all ROM bytes excluding the checksum)

Maintenance ($5)

---

7  bit  0
---- ----
s... 0000
|    ||||
|    ++++- Must be zero; otherwise the console will prohibit execution.
|          Purpose unknown.
+--------- (Color) Splash bypass: 0 = Disable, 1 = Enable.
           Bypasses the custom boot splash stored in the console's
           internal EEPROM; presumably used for bricked console recovery.

Developer/Publisher ID ($6)

---

Known official developer/publisher IDs

ID	Publisher code	Publisher
$01	BAN	Bandai
$02	TAT	Taito
$03	TMY	Tomy
$04	KEX	Koei
$05	DTE	Data East
$06	AAE	Asmik Ace
$07	MDE	Media Entertainment
$08	NHB	Nichibutsu
$0A	CCJ	Coconuts Japan
$0B	SUM	Sammy
$0C	SUN	Sunsoft
$0D	PAW	Mebius
$0E	BPR	Banpresto
$10	JLC	Jaleco
$11	MGA	Imagineer
$12	KNM	Konami
$16	KBS	Kobunsha
$17	BTM	Bottom Up
$18	KGT	Kaga Tech
$19	SRV	Sunrise
$1A	CFT	Cyber Front
$1B	MGH	Megahouse
$1D	BEC	Interbec
$1E	NAP	Nihon Application
$1F	BVL	Bandai Visual
$20	ATN	Athena
$21	KDX	KID
$22	HAL	HAL Corporation
$23	YKE	Yuki Enterprise
$24	OMN	Omega Micott
$25	LAY	Layup
$26	KDK	Kadokawa Shoten
$27	SHL	Shall Luck
$28	SQR	Squaresoft
$2A	SCC	? (SUNCORPORATION?)
$2B	TMC	Tom Create
$2D	NMC	Namco
$2E	SES	Soeishinsha
$2F	HTR	Hearty Robin
$31	VGD	Vanguard
$32	MGT	Megatron
$33	WIZ	Wiz
$35	TAN	Tanita
$36	CPC	Capcom

Note that IDs $00 and $01 are used across a variety of commercial games. Homebrew is known to use arbitrary values in this field.

Color ($7)

---

7  bit  0
---- ----
???? ???c
        |
        +- 0 = Monochrome only, 1 = Supports Color mode.

Game version? / Safe mode ($9)

---

7  bit  0
---- ----
pvvv vvvv
|||| ||||
|+++ ++++- Game version?
+--------- Internal EEPROM write protect: 0 = Enable, 1 = Disable.
           This prohibits writing to the internal EEPROM for addresses
           0x60 and above (user settings, custom splash screen).
           Games are expected to enable write protection; however, the
           WonderWitch is factory configured with it disabled.

ROM size ($A)

---

Unofficial/inferred ROM size values are marked in italic.

ROM size values

ID	Size
$00	1 Mbit (128 KiB)
$01	2 Mbit (256 KiB)
$02	4 Mbit (512 KiB)
$03	8 Mbit (1 MiB)
$04	16 Mbit (2 MiB)
$05	24 Mbit (3 MiB)
$06	32 Mbit (4 MiB)
$07	48 Mbit (6 MiB)
$08	64 Mbit (8 MiB)
$09	128 Mbit (16 MiB)
$0A	256 Mbit (32 MiB)
$0B	512 Mbit (64 MiB)

Note that ROM sizes over 16 MiB are not supported by the Bandai 2001 mapper. The Bandai 2003 mapper is limited to 64 MiB.

Save type/size ($B)

---

Save type values

ID	Type	Size
$00	None
$01	SRAM	256 Kbit (32 KiB)
$02
$03		1 Mbit (128 KiB)
$04		2 Mbit (256 KiB)
$05		4 Mbit (512 KiB)
$10	EEPROM	1 Kbit (128 B)
$20		16 Kbit (2 KiB)
$50		8 Kbit (1 KiB)

Note that while ID $01 is commonly documented as 64 Kbit, all known cartridges using that value come with 256 Kbit SRAM chips. This requires further investigation.

Flags ($C)

---

7  bit  0
---- ----
???? SB?v
     || |
     || +- Starting orientation: 0 = horizontal, 1 = vertical
     |+--- Cartridge ROM width: 0 = 8-bit, 1 = 16-bit
     +---- Cartridge ROM wait state: 0 = +0 cycles, 1 = +1

Flag bits 2 and 3 correspond to System Control bits 2 and 3.

Bit 0 controls the splash screen's orientation, as well as the LCD segment (horizontal or vertical orientation) displayed during the first 128 ticks of the splash screen.

Mapper ($D)

---

Known mapper types

ID	Mapper
$00	Bandai 2001 or KARNAK
$01	Bandai 2003