#2257 Magic Desk Plus (CRT id 87): cartconv and the emulator disagree about what the subtype byte means

[Enver Haase-Beer]

Disclosure: this investigation and write-up were done with the help of Claude Code
(Anthropic). Every factual claim below is backed by a reproducible command line, a
file:line citation, or an SVN revision, given inline.

Version: git mirror VICE-Team/svn-mirror @ cbc2f46, self-reporting VICE Version 3.10
(trunk at or shortly after r46225)
Platform: Linux x86_64 (Ubuntu, kernel 6.8), configured --enable-headlessui

Note on the build: stock cbc2f46 segfaults before the emulator starts in the headless
UI, so I applied a one-line NULL guard in log_archdep() to run at all. That is filed
separately. It touches only src/log.c and no cartridge code; everything below was
measured with it applied.

A companion report covers a second, independent problem: the EEPROM size of the
selected revision is never applied, so every EEPROM revision behaves as 32KiB. This
ticket is only about what the subtype byte is supposed to mean.

I hit this while adding Magic Desk Plus support to the 1541 Ultimate firmware
(GideonZ/1541ultimate#844), where I need to know what the subtype byte means in order
to read a CRT the same way VICE does. At the moment I cannot determine that from VICE.

---

1. -s 1 is written as "SRAM only" and read back as "SRAM + 8KiB EEPROM"

   cartconv -t mdp -s 1 -i rom256k.bin -o s1.crt
   x64sc -cartcrt s1.crt

In the monitor, select the EEPROM and write through the $DF00 window:

> de03 00      # bit 5 = 0 selects EEPROM
> de01 05      # page $05
> df00 aa
m df00 df00    # reads back AA -- an EEPROM is present and writable

cartconv.c:1668 documents -s 1 as "SRAM only" and refuses anything above 2 with that
wording. magicdeskplus.h:41 defines MAGICDESKPLUS_REV_SRAM_EEPROM_8K = 1. A file
written for one meaning is emulated as the other. For comparison, subtype 4 (which
does mean SRAM only to the emulator) reads back 00 here, as expected.

1. cartconv cannot write subtypes 3 and 4, which the emulator and the documentation
   both define

   $ cartconv -t mdp -s 3 -i rom256k.bin -o s3.crt
   Error: Magic Desk Plus revision must be 0 (SRAM + EEPROM), 1 (SRAM only), or 2 (EEPROM only)

magicdeskplus.h:43-44 defines revisions 3 (8KiB EEPROM) and 4 (SRAM only), and
vice.texi section "87 - Magic Desk Plus" lists all five. They cannot be produced with
VICE's own tool. To test them I patched header byte $1A of a cartconv-produced file
directly.

1. vice.texi contradicts itself

2. section "87 - Magic Desk Plus": revisions 0-4, with 8K/32K distinctions
   (matches magicdeskplus.h)

3. CRT id summary table, id 87: "Subtype 0: SRAM and EEPROM, 1: SRAM only,
   2: EEPROM only"
4. cartconv documentation, mdp: "-s 0 for SRAM and EEPROM, -s 1 for SRAM only,
   or -s 2 for EEPROM only"

The question I need answered: which numbering is intended? Right now an implementer
outside VICE has three documented answers and a fourth in the emulator's behaviour,
and no way to choose correctly.

Provenance. All three statements arrived together in r46225 (2026-09-08, gpz, "add
support for 'Magic Desk Plus', reworked patch from ClausS"), which added
magicdeskplus.c/.h, the cartconv support, and the vice.texi sections in one commit.
So this is not a case of one side having fallen behind -- the reader's 0-4 numbering
and the writer's 0-2 numbering were introduced simultaneously. I mention it only to
narrow where the intended meaning was lost.

One further note, since it may bear on the intended design: section 87 states "SRAM
and EEPROM data are stored in separate optional image files, not as CHIP packets in
the CRT image." I confirmed the emulator enforces that -- a CRT carrying store data in
$DF00 CHIP packets attaches and banks correctly, but the packets are ignored (a byte
planted in one reads back as $FF). That part is consistent; I mention it only because
it is the other half of what an implementer has to get right.

[gpz]

You missed some more places in the manual :) I missed them, we forgot about the fact there are two different EEPROM options, and it was quickly hacked in (by me, not Claus) before i merged.

Oh well. check r46239 (The Emulator was right, ie subtypes 0-4 exist)

One further note, since it may bear on the intended design: section 87 states "SRAM
and EEPROM data are stored in separate optional image files, not as CHIP packets in
the CRT image." I confirmed the emulator enforces that -- a CRT carrying store data in
$DF00 CHIP packets attaches and banks correctly, but the packets are ignored (a byte
planted in one reads back as $FF). That part is consistent; I mention it only because
it is the other half of what an implementer has to get right.

Mind you, we are working on the next revision of the CRT format right now, which will finally allow to include extra data like that cleanly. I strongly recommend not to use your own extensions for this, because it will result in CRT files that will no more work in VICE (and perhaps other emulators that use the specs), see https://pastebin.com/hzaT1GPk