cbmtools is a collection of tools operating on cbm-style prg-files:

  chd  - 'hd' like hex dump for cbm files
  cld  - cbm binary linker (opt executable output)
  cgen - cbm self-checking test file generator
  cpch - cbm binary patcher


+----------------------------------------+
| chd - 'hd' like hex dump for cbm files |
+----------------------------------------+

USAGE
-----
chd (cbmtools) 0.6: cbm binary hexdump

usage: chd [-n][-l<addr>][-L][-O[d|t|<addr>][-v][-d][-h][-V] <file>...

Valid options:
    -n              file has no load address
    -l              override load address
    -L              24-bit addressing (default: 16-bit)
    -O              consider pointer overloading
    -v              be verbose
    -d              debugging output
    -h              displays this help text
    -V              output program version

EXAMPLES
--------

*normal*
metal-rox-mk3$ chd digdug.prg 
00AC  78 A2 AB 9A 8D AB 01 8D  AC 01 AC 25 AB D0 09 AD |x.....a..a.%..i.|
00BC  AD AD AC 53 AB 4C 5B AB  4C CC AE 02 78 A2 01 9A |...S.L[.L..bx.a.|
00CC  A9 E7 95 00 8E 18 03 A9  03 8D 19 03 4E 11 D0 A9 |.....xc.c.ycNq..|
00DC  05 48 A9 F0 A8 AA E8 5D  13 02 9D 82 FF D0 F7 48 |eH.....]sb.....H|
00EC  B5 02 25 00 AA B9 E8 01  99 0E 7F 59 0E 7F D0 03 |.b%....a.n.Yn..c|
00FC  C8 D0 F2 A9 72 48 98 D0  25 20 12 03 DE D7 01 DE |....rH..% rc..a.|
010C  D7 01 91 BB D0 18 84 9D  20 D5 FF B0 11 40 B0 02 |.a...x.. ...q@.b|
011C  7D 72 30 09 B2 A4 29 3F  B3 A5 25 05 0A 9A 60 F2 |}r0i..)?..%ej.`.|
dumped $00AC-$012C (130 bytes, 1 block)
metal-rox-mk3$ 

*override load address*
metal-rox-mk3$ chd -l 0x0801 digdug.prg 
0801  78 A2 AB 9A 8D AB 01 8D  AC 01 AC 25 AB D0 09 AD |x.....a..a.%..i.|
0811  AD AD AC 53 AB 4C 5B AB  4C CC AE 02 78 A2 01 9A |...S.L[.L..bx.a.|
0821  A9 E7 95 00 8E 18 03 A9  03 8D 19 03 4E 11 D0 A9 |.....xc.c.ycNq..|
0831  05 48 A9 F0 A8 AA E8 5D  13 02 9D 82 FF D0 F7 48 |eH.....]sb.....H|
0841  B5 02 25 00 AA B9 E8 01  99 0E 7F 59 0E 7F D0 03 |.b%....a.n.Yn..c|
0851  C8 D0 F2 A9 72 48 98 D0  25 20 12 03 DE D7 01 DE |....rH..% rc..a.|
0861  D7 01 91 BB D0 18 84 9D  20 D5 FF B0 11 40 B0 02 |.a...x.. ...q@.b|
0871  7D 72 30 09 B2 A4 29 3F  B3 A5 25 05 0A 9A 60 F2 |}r0i..)?..%ej.`.|
dumped $0801-$0881 (130 bytes, 1 block)
metal-rox-mk3$ 

*long address*
metal-rox-mk3$ chd -L digdug.prg 
0000AC  78 A2 AB 9A 8D AB 01 8D  AC 01 AC 25 AB D0 09 AD |x.....a..a.%..i.|
0000BC  AD AD AC 53 AB 4C 5B AB  4C CC AE 02 78 A2 01 9A |...S.L[.L..bx.a.|
0000CC  A9 E7 95 00 8E 18 03 A9  03 8D 19 03 4E 11 D0 A9 |.....xc.c.ycNq..|
0000DC  05 48 A9 F0 A8 AA E8 5D  13 02 9D 82 FF D0 F7 48 |eH.....]sb.....H|
0000EC  B5 02 25 00 AA B9 E8 01  99 0E 7F 59 0E 7F D0 03 |.b%....a.n.Yn..c|
0000FC  C8 D0 F2 A9 72 48 98 D0  25 20 12 03 DE D7 01 DE |....rH..% rc..a.|
00010C  D7 01 91 BB D0 18 84 9D  20 D5 FF B0 11 40 B0 02 |.a...x.. ...q@.b|
00011C  7D 72 30 09 B2 A4 29 3F  B3 A5 25 05 0A 9A 60 F2 |}r0i..)?..%ej.`.|
dumped $0000AC-$00012C (130 bytes, 1 block)
metal-rox-mk3$ 

*pointer overloading*
metal-rox-mk3$ chd -Od digdug.prg 
00AC  78 A2 AB                                         |x..|
00AC  9A 8D AB                                         |...|
00AC  01 8D AC                                         |a..|
00AD  01 AC                                            |a.|
00AD  25 AB                                            |%.|
00AC  D0 09 AD                                         |.i.|
00AE  AD                                               |.|
00AE  AD                                               |.|
00AE  AC                                               |.|
00AD  53 AB                                            |S.|
00AC  4C 5B AB                                         |L[.|
00AC  4C CC AE 02                                      |L..b|
02B0  78 A2 01 9A A9 E7 95 00  8E 18 03 A9 03 8D 19 03 |x.a......xc.c.yc|
02C0  4E 11 D0 A9 05 48 A9 F0  A8 AA E8 5D 13 02 9D 82 |Nq..eH.....]sb..|
02D0  FF D0 F7 48 B5 02 25 00  AA B9 E8 01 99 0E 7F 59 |...H.b%....a.n.Y|
02E0  0E 7F D0 03 C8 D0 F2 A9  72 48 98 D0 25 20 12 03 |n..c....rH..% rc|
02F0  DE D7 01 DE D7 01 91 BB  D0 18 84 9D 20 D5 FF B0 |..a..a...x.. ...|
0300  11 40 B0 02 7D 72 30 09  B2 A4 29 3F B3 A5 25 05 |q@.b}r0i..)?..%e|
0310  0A 9A 60 F2                                      |j.`.|
dumped $00AC-$0314 (130 bytes, 1 block)
metal-rox-mk3$ 


+-------------------------------------------------+
| cld - cbm binary linker (opt executable output) |
+-------------------------------------------------+

cld is a tool that can link multiple binary files together into a single
file, optionally producing an RLE packed executable binary.

Producing an executable can be useful for at least two purposes:

 - Quickly generating testable code from a large binary.
   (fast pack, fast depack)

 - Packing a very large binary to a more reasonable size to allow
   crunching with a LZ77-based cruncher afterwards.
   (full 64kB, $0000-$FFFF allowed)


USAGE
-----
cld (cbmtools) 0.6: cbm binary linker

usage: cld [-r<range>][-x][-X<opts>][-o<name>][-v][-d][-h][-V] <source>...

Valid options:
    -r              specify save range
    -x              produce executable output
    -X <opts>       options for executable
    -o              output file
    -v              be verbose
    -d              debugging output
    -h              displays this help text
    -V              output program version

EXAMPLES
--------
$ cld -otest.prg file1.prg file2.prg,0x1000
$ cld -otest.prg file1.prg,,0x20 file2.prg
$ cld file.prg -x -Xjmp=0x0801,sei

Loading:
  normal:   <file>[,,[<offs>][,<len>]]
  override: <file>,<addr>[,[<offs>][,<len>]]
  raw:      <file>@<addr>[,[<offs>][,<len>]]

Saving:
  normal:   <file>
  override: <file>,<addr>
  raw:      <file>@<addr>

Executable:
  The produced executable will call the binary with SP=$ff, sei or cli,
mem=$35/$36/$37.   It will typically clobber the low zp range + copy the
file up to the top of memory.  The full mem decruncher will clobber only
the start of sprite registers $d000-$d009 approximately.


+----------------------------------------------+
| cgen - cbm self-checking test file generator |
+----------------------------------------------+

cgen is a self checking test file generator.  It can generate binaries that
self check the entire 64kB memory range.  The integrity is checked using
the Fletcher-16 checksum algorithm.

USAGE
-----
cgen (cbmtools) 0.6: cbm test file generator

usage: cgen [-s<addr>][-e<addr>][-j<addr>][-S<seed>][-o<name>][-v][-d][-h][-V] srcnames...

Valid options:
    -s              start address
    -e              end address
    -j              jump address
    -S              set fixed seed
    -o              output file
    -v              be verbose
    -d              debugging output
    -h              displays this help text
    -V              output program version

EXAMPLES
--------

Generate a runnable self checking image $0801-$CFFF (202 blocks)
$ cgen -otest.prg

Generate a self checking image $0200-$3FFF (started by jumping to $0300)
$ cgen -s 0x0200 -e 0x4000 -j 0x300 -otest.prg

Generate a self checking image $0000-$FFFF (started by jumping to $0400) 
$ cgen -s 0x0000 -e 0x10000 -j 0x0400 -otest.prg


+---------------------------+
| cpch - cbm binary patcher |
+---------------------------+


USAGE
-----
cpch (cbmtools) 0.6: cbm binary patcher

usage: cpch [-r<range>][-p<patch>][-o<name>][-m][-v][-d][-h][-V] <source>...

Valid options:
    -r              specify save range
    -p              patch file
    -o              output file
    -m              merge patch files
    -v              be verbose
    -d              debugging output
    -h              displays this help text
    -V              output program version

EXAMPLES
--------

$ cpch -o patched.prg -p file.pch orig.prg
$ cpch -m -o merged.pch -p patch1.pch -p patch2.pch

Format:

The patch file has the format:
    0000: header
    xxxx: patch chunk #0
    xxxx: patch chunk #1
       ...
    xxxx: patch chunk #x
    xxxx: footer (or EOF)

(all words are little endian, lsb/msb)
 Header format:
    0x00: xx xx
    0x02: 04 00       ; length of header
    0x04: 50 54 53 48 ; "PTCH"

 Each patch chunk has the format:
    0x00: <startaddr> ; startaddress of this patch
    0x02: <length>    ; length of patch data
    0x04...0x04+length-1 ; actual data to patch with.

 Footer format
    0x00: xx xx
    0x02: 00 00

eof