This is the CUTILS v1.0 user's manual


You should have the CUTILS ready on each platform. If not, read the INSTALL
file to install them. You also should have the cable connected between the
host and the VIC 20.


CLOAD - DOWNLOADING A PROGRAM TO THE VIC (Linux & Amiga)
  o Options
  o How to transfer a user program from a Linux PC or an Amiga to the VIC 20?
  o Example
  o How does it work?
  o Notes

CSAVE - UPLOADING A PROGRAM FROM THE VIC (Linux only)
  o Options
  o How to transfer a user program from the VIC 20 to a Linux PC?
  o Example
  o How does it work?
  o Notes



CLOAD - DOWNLOADING A PROGRAM TO THE VIC (Linux & Amiga)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

o Options

  .Linux

   usage: cload [-v] [-p IO_PORT] file

   file        The CBM binary file to be uploaded to the VIC (mandatory)
   -v          Print verbose informations about program addresses and size
   -p IO_PORT  specify the parallel port to use, with IO_PORT (in hex)
                instead of the default port at address 0x378. Valid addresses
                are 278, 378 and 3bc

  .Amiga

   usage: cload file

   file        The CBM binary file to be uploaded to the VIC (mandatory)

   Notes: The Amiga cload utility only works with files < 4KB.
          Use the <Ctrl> key to exit if stucks.


o How to transfer a user program from a Linux PC or an Amiga to the VIC 20?

  . Step 1 - VIC 20
    Load the CLOAD Basic program and run it.

    Note: You can omit this step if the program has already been loaded
    and you have not powered the VIC off, even after reset.
 
  . Step 2 - VIC 20
    Start the CLOAD utility with the command:
    SYS 267
    The VIC is now waiting for incoming data.

  . Step 3 - Linux or Amiga
    Start the cload utility by typing the command:
    cload <vic_file>
                                         
  If your cable is connected correctly, the program is transfered, and the
  VIC should display READY. On the Amiga version, you should see the Amiga
  LED blink during transfer (If you're very fast!) .
  You can now RUN the downloaded program ;)

  
o Example

  . Step 1 (VIC 20) - Loading and running of the CLOAD utility

	**** CBM BASIC V2 ****

	3583 BYTES FREE

	READY.
	LOAD

	PRESS PLAY ON TAPE
	OK

	SEARCHING
	FOUND CLOAD  

	LOADING
	READY.
	RUN

	READY.

  . Step 2 (VIC 20) - Launch the CLOAD assembly routine

	SYS 267
                                         
  . Step 3 (Linux or Amiga) - Launch the downloading

	cload vic_blitz
	3579 bytes transfered in 147.370 ms (23.717 KB/s)

  . Step 4 (VIC 20) - Run the program ;)

	READY.
	RUN


o How does it work?

  First, the start address and size are retrieved from the binary 
  file. 
  The BASIC pointers value are then computed and sent to the VIC.
  The body of the program is then downloaded. 

  For more information, take a look at the cload.c source code.


o Notes

  1. The VIC CLOAD routine (SYS 267) should always be started before 
     running the cload utility on Linux or Amiga. Otherwise you will
     get an error message. 

  2. To get out of the CLOAD waiting state on the VIC's side, use 
     <RUN STOP><RESTORE> or the reset switch on the cable. The program
     is still in memory, and you can re-run it with SYS 267.

  3. To get out of the CLOAD waiting state on the Amiga, simply press
     <Ctrl>

  4. See the FAQ for how to download to a memory location other than
     the Basic User Area

  5. You should always power off the VIC before switching between 
     CLOAD and CSAVE in VIC's memory



CSAVE - UPLOADING A PROGRAM FROM THE VIC
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

o Options

  .Linux

   usage: csave [-v] [-p IO_PORT] file

   file        The CBM binary file to be downloaded from the VIC (mandatory)
               Note: any existing file will be erased.
   -v          Print verbose informations about program addresses and size
   -p IO_PORT  specify the parallel port to use, with IO_PORT (in hex) instead
               of the default port at address 0x378. Valid addresses are
               278, 378 and 3bc


o How to transfer a user program from the VIC 20 to a Linux PC?

  . Step 1 - VIC 20
    Load the CSAVE Basic program and run it.

    Note: You can omit this step if the program has already been loaded
    and you have not powered the VIC off, even after reset.

  . Step 2 - VIC 20
    Load the program you want to transfer.

  . Step 3 - VIC 20
    Start the CSAVE utility with the command:
    SYS 267
    The VIC is now waiting for the PC to read the data.

  . Step 4 - Linux
    Start the csave utility by typing the command:
    csave <vic_file>

  If your cable is connected correctly, the program is transfered, and the
  VIC should display READY. The program is saved in the CBM binary format.


o Example

  . Step 1 (VIC 20) - Loading and running of the CSAVE utility

	**** CBM BASIC V2 ****

	3583 BYTES FREE

	READY.
	LOAD

	PRESS PLAY ON TAPE
	OK

	SEARCHING
	FOUND CSAVE

	LOADING
	READY.
	RUN

	READY.

  . Step 2 (VIC 20) - Loading of the program to upload

	LOAD

	PRESS PLAY ON TAPE
	OK

	SEARCHING
	FOUND ARTILLERY

	LOADING
        READY.

  . Step 3 (VIC 20) - Launch the CSAVE assembly routine

	SYS 267

  . Step 4 (Linux) - Launch the uploading

	csave artillery
	2577 bytes transfered in 130.069 ms (19.348 KB/s)


o How does it work?

  First, the start address and the end address+1 of program are
  sent to the Linux PC.
  The start address is then written in Little Endian mode at the
  beginning of the file.
  The program body is uploaded and written afterwards.

  For more information, read the csave.c source code.


o Notes

  1. The VIC CSAVE routine (SYS 267) should always be started before
     running the csave utility on Linux. Otherwise you will get an
     error message.

  2. To get out of the CSAVE waiting state on the VIC's side, use
     <RUN STOP><RESTORE> or the reset switch on the cable. The program
     is still in memory, and you can re-run it with SYS 267.

  3. See the FAQ for how to upload from a memory location other than
     the Basic User Area.

  4. You should always power off the VIC before switching between CLOAD
     or CSAVE in VIC's memory

