Disk image generation
=====================

A loadable disk image for the Q1 emulator is a python list

.. code-block:: text

  data = [
  # track 0
  [
    [0x9e, 0x00, 0x00],
    [0x9b, 0x00, 0x00, ... ],
    ...
    [0x9e, 0x00, 0x57],
    [0x9b, 0x00, 0x00, ... ]
  # track 1
  [
    [0x9e, 0x01, 0x00],
    [0x9b, 0x0c, 0x00, ... ],
    ...
    [0x9e, 0x01, 0x12],
    [0x9b, 0x0c, 0x41, ... ]
  ],
  ...
  # track 73
  [
    [0x9e, 0x01, 0x00],
    [0x9b, 0x0c, 0x00, ... ],
    ...
    [0x9e, 0x01, 0x12],
    [0x9b, 0x0c, 0x41, ... ]
  ],
  ]

And can be converted into a **filesys** object

.. code-block:: text

  fs = filesys.FileSys()
  fs.loadtracks(disk.data)


which can then be provided to the emulator in the constructor (hardcoded so
far)

.. code-block:: text

  self.io = z80io.IO(self.cpu.m, fs)


Disk images are currently created from two sources using two different methods:
a modified **q1decode** program from Mattis Lind and a homemade utility **binread.py**.


q1decode
^^^^^^^^

The disk 'images' found here were generated by a modified
code gotten from https://github.com/MattisLind/q1decode

The modified code generates an **output.py** file with a
nearly useful python list in it.

The procedure is as follows

.. code-block:: text

    > gcc q1decode.c && cat Q1DISKS/PL1/C_S0T01.000 | ./a.out 255
    > rm -f output.py
    > cat Q1DISKS/PL1/C_S0T01.000 | ./a.out 255

The argument to a.out, in this case 255, must match the record size for that
track. This might not always be known but in theory can be found on the file
index on track 0.

The generated python code needs to be modified to

* ensure that records start at 0
* remove trailing ','s
* wrap the lists elements in a named outer list

So far I have chosen name the list 'data' and put each track in its own
python file (see disks/debugdisk).


binread.py
^^^^^^^^^^

For images produced by datamuseum.dk we use the tool in **utils/binread.py**
to convert from .BIN files to python data structures that can be loaded
by the emulator. The utility is compatible with the geometry specifications
found from datamuseum's FloppyTools:

.. code-block:: text

  binread.py -f Q1_FLOPPY.BIN -g '1c 1h 88s 40b, 29c 1h 19s 255b, 43c 1h 126s 20b, 1c 1h 19s 255b'