dtvmkfs
=======

Build a file system image for flashing into the C64 DTV (v2/v3). The hummer
racing game uses a different flash load routine, so the SYS-address needs
to be set in a special way for this to work, or a DTV-kernel must be used.


License
-------

dtvmkfs is Copyright (C) 2007-2008 by Mikkel Holm Olsen and may be 
distributed freely under the terms of the GNU GPL, which can be found in 
the file COPYING.

dtvmkfs uses zlib by Jean-loup Gailly and Mark Adler. The license of zlib
allows free distribution of both source and binary versions under the terms
listed in zlib-1.2.3/zlib.h.

Furthermore it uses the unzip library by Gilles Vollant, included in the
zlib source distribution under zlib/contrib/minizip/. The license terms for
the unzip library can be found in zlib-1.2.3/contrib/minizip/unzip.h.

The source distribution of dtvmkfs includes a copy of the zlib source tree
in the directory zlib-1.2.3. No changes have been made to any files in this
directory from the downloaded zlib source, and it is only included to allow 
the application to be built in the most easy way.

The code for compressing and uncompressing dtvpacked data is based on
Daniel Kahlin's dtvpack. The license for this can be found in the file
dtvpack.lic.


Obtaining dtvmkfs
-----------------

The latest version of dtvmkfs is available from:
http://symlink.dk/nostalgia/dtv/dtvmkfs/


Building dtvmkfs
----------------

In order to build dtvmkfs a C-compiler is needed. Development is primarily
done under Linux with a newer gcc (currently 4.1.1), and with GNU Make.
Since there are not many things that need to be configured (and since I
do not know much about these tools), I do not use autoconf and automake.
I doubt that portability will be much greater with these, but if you
can prove me wrong, please do so.

Currently, I do not even have a configure-script, so any tweaking of the
build options must be done by manually editing the Makefile. This may
change in the future, but currently I am mostly interested in easy
development, and to please the Microsoft Windows crowd, I release a binary
version for Win32 (compiled with MinGW/MSYS).

The build instructions are therefore very simple: Unpack the source,
go to the directory where you unpacked and type make. If this does not
work out for you, experiment with altering the Makefile. Any suggestions
for improvements are welcome.


Usage
-----

The program is called dtvmkfs (or dtvmkfs.exe on Windows, I guess), and
should be invoked in the following way:

  dtvmkfs [options] <files>

The options that can be specified are as follows:
  -h or --help
        Show help/usage information and exit.

  -V or --version
        Print version information and exit.

  -d or --debug
        Increase debugging level. May be specified multiple times. Max
        debugging level used is 5 (-ddddd).

  -i <file> or --import <file>
        Import filesystem dump. The file should be a full DTV flash fs dump
        (2097152 bytes), and currently only the kernel-area ($000000-$00FFFF)
        is used. Also use the -k option to dump this area to file.

  -e <num> or --entries <num>
        Reserve <num> entries in the directory. If not specified, the
        directory (at addr $010000) will be written without any additional
        space.

  -m or --maindir
        Print the main directory, including the flash-, load- and sys-
        addresses. Also shows the total memory usage.

  -l or --listing
        Print a simulated directory listing to stdout during processing. 
        This is the C64 directory listing generated, and only includes the
        files that are not hidden.

  -p or --prgfile <file>
        Dump the directory listing ($-file) to PRG-file <file> after 
        creating it. This allows it to be loaded into VICE or similar
        to test the apearance of it before flashing.

  -w <n> or --width <n>
        Specify directory width (8-24, default 16). <n> is the number 
        of characters used for the filename (and header). Default
        is 16 characters to match the apearance of a C64 directory listing,
        but since the DTV supports filename lengths of up to 24 characters,
        this option allows a wider directory listing to be generated.

  -H <txt> or --header <txt>
        Set the text of the directory header to txt. Defaults to DTV FLASH.

  -k or --kernel-area
        Include the kernel-area ($000000-$00FFFF) in the flash fs dump. A
        kernel can be imported with the -i option, and will be written to
        the flash dump. Particularly useful for testing on the DTV version
        of Vice.

  -1 or --onefile
        Write complete flash fs image to flashfs.bin. This is the default
        unless -2 or -c is specified.

  -2 or --twofiles
        Write image to two files (for dtvtrans). They will be named
        t010000.bin and t100000.bin, where the number is the address 
        (in hexadecimal) in the flash.

  -c or --chunked
        Write image to multiple files of 128kB. These can fit on 1541
        floppies (or D64-files) for using IEC-based devices for the
        transfer to the DTV. The files are named cXXXXXX.bin where XXXXXX
        is a (hexadecimal) address for the start of this block. Only the
        chunks that are actually used will be dumped to files, to save the
        work of transfering several 128kB files of just $FF.

Any command line arguments specified after the options are treated as 
files to be included in the filesystem (option processing can be 
terminated by specifying --, which can be handy if filenames start with
- or --). The files can be specified in 3 distinct ways:

If the filename starts with a @, the rest of the filename is treated as
a text-file consisting of a list of archives to be included. This allows
a group of games/archives to be stored in a single file.

If the filename is a single -, a list of archives is read from the
standard input stream. This is another way to automate the generation
of files to be included (on Linux and Unix), by a command such as:
  ls -1 --color=no data/* | ./dtvmkfs -- -
(producing the same result as the first example).

The lists of archives may contain comments, starting with a # and 
extending to the end of the line. This is true both for lines read from
the standard input and for lists specified with the @-prefix.

Other files are treated as the lines in the index.txt (as described in
a later section), except that the file type ZIP is also supported, in 
which case the file is treated as an archive, and the index.txt is 
processed.

Archive file format
-------------------

The ZIP archives should conform to the following specifications:

* It should contain a file called index.txt which lists the files
  to be included in the filesystem. The format of this file is described
  in the next section.

* Files to be included in the DTV flash filesystem can be in one of the
  following formats:
    DTV - A DTV-packed program file.
    PRG - A PRG-file, which will be dtv-packed during import. The load
          address is read from the file.
    BIN - A binary file, which will be dtv-packed during import.
    RAW - A binary file, which will NOT be DTV-packed during import.
  
* The zip archive can optionally contain a readme.txt, giving details 
  on what game/program the archive contains, who patched it for use on
  the DTV, etc. The readme.txt is not used by dtvmkfs.


Structure of the index.txt file
-------------------------------

The index.txt file in each archive consists of lines with the following
format. This is also the format of the arguments that can be specified
on the command line:
filename[,c64name[,loadaddr[,sysaddr[,ARGS]]]]

The filename is the name of the file (in the archive, or on the command
line). If the filename has a $ prepended, it will be hidden in the 
directory listing ($-file).

The c64name is the name of the file as it should appear in the directory
listing. If the c64name is not specified, the filename will be used, with
known extensions stripped off. If the first character of the c64name
specified is $, this file will not be included in the BASIC directory
listing (the $-file), but will still be included in the filesystem (i.e.
the $010000-directory) - with the $ stripped off. This is normally used
for multipart games to avoid cluttering up the BASIC directory listing.

The loadaddr is the address where a file should be loaded. Since the 
dtvpacked files do not include this information, it must be specified in
the index.txt file. The address is a decimal number (e.g. 2049 for normal
BASIC load address of $801), or a hexadecimal number prefixed with $ or 
0x (e.g. $0801 or 0x0801). If this is not specified, 2049 ($0801) will be 
the default.

The sysaddr is used by some menus (e.g. the INTRO made by Roland, and 
LSMENU made by me and LarsP). If the value is 0 (or not specified), the 
game/program will not be listed in the menu. Any other value will cause
the program to be listed, and is also used for the address to call when
the game is started. Note that some games are not loadable from BASIC, 
either because they are too large, because of a kernel loader bug, or 
simple because they do not have a BASIC stub with the appropriate SYS-line.
For the ones that are loadable from BASIC, one can determine the SYS 
address by doing a LIST instead of RUN after LOAD'ing the game. Normally
this would be something like SYS 2061, so simply enter 2061 as the sysaddr. 
Alternatively, open the PRG-file in a hex editor and look for the sys 
address in the first 20 bytes of the file (it will be plain ASCII).

ARGS are additional arguments. Currently the supported arguments are
  DTV - Treat this file as a DTV-packed program. Included verbatim, but
        run through the decompressor to find the size.
  PRG - Treat this file as a PRG-file. Load addres is fetched from the
        file, unless specified.
  BIN - Treat this file as binary. It will be dtvpacked and included.
  RAW - Treat this file as RAW. It will NOT be packed, but included
        verbatim.
  ZIP - The file is an archive (should contain index.txt). Archives 
        cannot be nested, so this only makes sense on the command line.

The index.txt file may contain comments, starting with a # and continuing
to the end of the line.


Limitations
-----------

dtvmkfs has a few limitations, which will most likely be some of the 
things that will be changed in future versions:

* Still not able to import the file system and "add" stuff to it. The 
  difficult part is parsing the $-file.
  
* No possibility to delete files in the imported flash image.

* No support for including a file at a fixed position. This will require
  some more handling of the address space to avoid overwriting vital parts.


Greetings
---------

Thanks to TLR and Roland for helping me out with important details about
how stuff is implemented on the DTV. Without their research/documentation
I would not have been able to undertake this task.

Hideki provided a working program (dtvbuild), and many of the options and
functions of dtvmkfs were inspired by his work.

Thanks to all the people who have used dtvmkfs, and especially those that
keep patching games for the DTV and putting them in the repository:
  http://symlink.dk/nostalgia/dtv/fixed/

Greetings to all at the DTV Hacking Forum.



Mikkel Holm Olsen
AKA Spaceman Spiff
dtv@symlink.dk

$Id: README,v 1.9 2008-10-13 21:42:00 spiff Exp $
