aftool - tools for Alien Flash
------------------------------

(c) 2011 Hannu Nuotio <nojoopa@users.sf.net>


1. Intro
--------

aftool is a small utility for dealing with Alien Flash .crt images and
the actual cartridge via the USB connection.

aftool is GPL, see COPYING_tool. Some bits taken from VICE(minus).

For more info on Alien Flash, see:
http://t-winkler.net/dokuwiki/doku.php?id=en:af:start


2. Usage
--------

Below is the output of "aftool -h":

--< snip >--
Usage: aftool [OPTION]* COMMAND ARGS

Available COMMANDs:

    Alien Flash .crt - injecting/extracting

  icrt AFCRT INCART [OFFSET]
Inject a .crt file to an Alien Flash .crt file and save the results.

  id64 AFCRT IND64
Inject a .d64 image (adding the header) to an Alien Flash .crt and save the results.
Destination address is $040000.

  iprg AFCRT INPRG
Inject a .prg file (adding the header) to an Alien Flash .crt and save the results.
Destination address is $010000.

  ibin [INAFCRT] INBIN OFFSET
Inject a binary file to an Alien Flash .crt (if given)
and save the results to a new Alien Flash .crt file.

  ecrt INAFCRT OUTCART CRTTYPE [OFFSET]
Extract a .crt file from an Alien Flash .crt.

  ed64 INAFCRT OUTD64
Extract a .d64 image from an Alien Flash .crt.
Source address is $040100.

  eprg INAFCRT OUTPRG
Extract a .prg file from an Alien Flash .crt.
Source address is $010100.

  aftt2af INAFCRT [INAFTT]*
Apply AFTT file(s) on an Alien Flash .crt and save the results.


    Alien Flash .crt - misc. operations

  af2bin INAFCRT OUTBIN [OFFSET]
Converts an Alien Flash .crt file to a binary file.
OFFSET must be a range, default range is 'af' (all Flash).

  erasecrt INAFCRT OFFSET
Erase a range of an Alien Flash .crt file and save the results.
A single ADDR implies the whole sector, use the ADDR-ADDR
format with the same ADDR twice for erasing a single byte.

  progcrt INAFCRT OFFSET BYTE [BYTE]*
Program the BYTE(s) to an Alien Flash .crt file and save the results.
If a range is given, the BYTE(s) is/are repeated to fill it.

  emptycrt INAFCRT OFFSET
Check if the range OFFSET of the Alien Flash .crt is empty.
A single ADDR implies the whole sector, use the ADDR-ADDR
format with the same ADDR twice for checking a single byte.

  dumpcrt INAFCRT
Dump info on the Alien Flash .crt.


    Alien Flash USB - sending/receiving

  scrt INCART [OFFSET]
Flash a .crt file via Alien Flash USB.

  sd64 IND64
Flash a .d64 image (adding the header) via Alien Flash USB.
Destination address is $040000.

  sprg INPRG
Flash a .prg file (adding the header) via Alien Flash USB.
Destination address is $010000.

  rcrt OUTCART CRTTYPE [OFFSET]
Retrieve a .crt file via Alien Flash USB.

  rd64 OUTD64
Retrieve a .d64 image via Alien Flash USB.
Source address is $040100.

  rprg OUTPRG
Retrieve a .prg file via Alien Flash USB.
Source address is $010100.

  rbin OUTBIN OFFSET
Reads data via Alien Flash USB, saves to a binary file.


    Alien Flash USB - misc. operations

  erase OFFSET
Erase one or more sectors of Alien Flash via USB.

  prog OFFSET BYTE [BYTE]*
Program the BYTE(s) to Alien Flash via USB. No erasing is performed.
If a range is given, the BYTE(s) is/are repeated to fill it.

  nop DUMMY
Initialize USB, but don't do any actual operation.
The argument DUMMY is ignored, but must exist.


    AFTT file handling

  sendaftt INAFTT [OUTBIN]
Sends the AFTT file via Alien Flash USB, optionally
capturing the read bytes to a binary file.

  crt2aftt INCART OUTAFTT [OFFSET]
Converts a .crt file to an AFTT file.

  d642aftt IND64 OUTAFTT
Convert .d64 image to an AFTT file, adding the header.
Destination address is $040000.

  prg2aftt INPRG OUTAFTT
Convert .prg to an AFTT file, adding the header.
Destination address is $010000.

  aftt2bin [INAFTT]* OUTBIN
Apply AFTT file(s) to an empty cartridge and save the
programmed range to a raw binary file.

  dumpaftt INAFTT [VERBOSE]
Dump the actions of the AFTT file performs, using
verbosity level VERBOSE (0..3).


Notes on ARGS:

  AFCRT
Alien Flash .crt file.

  CART
A cartridge .crt file.
The following cart types are supported:
 * Action Replay (CRT ID 1, default OFFSET ar)
 * EasyFlash (CRT ID 32, default OFFSET rs1)
 * Alien Flash (CRT ID 57, default OFFSET af)

  CRTTYPE
Specifies a type of cart.
The following types are supported:
 * ar      Action Replay (CRT ID 1)
 * ef      EasyFlash (CRT ID 32)
 * af      Alien Flash (CRT ID 57)

  OFFSET
An address (or range) to the Flash space.
The following formats are supported:  (all values in hex)
 * ADDR        A single address (0 .. ffffff)
 * ADDR-ADDR   Address range (smaller ADDR first)
 * rsN         ROM SLOT N (N: 0 .. f)
 * csIJ        Flash chip I sector J (I: 0 .. 3, J: 0 .. 3f)
 * ar          Action Replay location (870000 .. 877fff)
 * at          Alien Flash Tools (0 .. ffff on ROML & ROMH)
 * af          All (or Alien?) Flash (0 .. ffffff)

  BIN
Raw binary file.

  PRG
Normal .prg file.

  D64
.d64 disk image file.

  AFTT
Alien Flash Terminal Tools file. Meant to be sent to an Alien Flash
cartridge via USB using a terminal program, hopefully obsoleted as a
format by this tool.

  USBDRV
Name of the USB driver: (default is first)
"linux"
"win32"
"ftd2xx"
"ftdi"
"dummy"

  USBPAR
Depends on the selected USB driver.
For "linux":
  The name of the USB device. (default = /dev/ttyUSB0)
For "win32":
  The number or the virtual COM port. (default = 37)
For "ftdi":
  A hex value in the range 1 .. ff to set the USB latency;
  "setvcpmode" to set VCP mode;
  "setd2xxmode" to set D2XX mode.
For "dummy":
  Dump sent bytes to given filename.


Available OPTIONs:
  -h           Show more help.
  -o OUTAFCRT  Save Alien Flash .crt to file OUTAFCRT. (default = use INAFCRT)
  -d USBDRV    Select Alien Flash USB driver.
  -u USBPAR    Set Alien Flash USB parameter.
  -b VAL       Set USB read block size. (default = $40)
  -x VAL       Set USB write block size. (default = $800)
  -r VAL       Use VAL (in hex) reads after chip erase. (default = $4000)
  -w VAL       Use VAL (in hex) reads after byte program. (default = $1)
  -e           Do erases in created AFTT files. (default = don't erase)
  -t TEXT      Use TEXT (max 16 chars) as description for .prg/.d64.
  -n TEXT      Use TEXT (max 32 chars) as cart name for created .crt.
  -q           Be quieter.
--< snip >--

Playing with the -r and -w options may be dangerous if you plan to
send the resulting AFTT files with real hardware.


3. Examples
-----------

Create an empty Alien Flash image: (read range $0-$0 as type "af" via dummy USB)
    aftool -d dummy rcrt empty_af.crt af 0-0

Inject an EasyFlash .crt to ROM SLOT 14 ($e) of an Alien Flash .crt:
    aftool icrt some_af.crt ef_too.crt rse

Extract ROM SLOT 7 of an Alien Flash .crt to an EasyFlash .crt:
    aftool ecrt af.crt ef_from_seven.crt rs7

Convert a .prg to an AFTT file (for sending), adding the needed sector erases:
    aftool prg2aftt blah.prg erase_prg_area_and_write_blah_conv.bin

Check if the created AFTT file is valid:
    aftool dumpaftt erase_prg_area_and_write_blah_conv.bin

Inject a .prg to an Alien Flash .crt, save results to a different file:
    aftool -o af_with_blah.crt iprg af.crt blah.prg

Do a dummy .crt file send:
    aftool -d dummy scrt somecart.crt

Check if the USB connection initializes:
    aftool nop foo

Check if the USB connection initializes, using driver "win32" and COM port 23:
    aftool -d win32 -u 23 nop foo

Read the whole Alien Flash cartridge via USB to a .crt image:
    aftool rcrt my_af.crt af

Send a .d64 to the Alien Flash cartridge via USB:
    aftool sd64 some.d64

Send an AFTT file to the Alien Flash cartridge via USB:
    aftool sendaftt erase_prg_area_and_write_blah_conv.bin



4. Future
---------

...
