Commander X16

Introduction

Here is a little demo of how to dynamically load files in RAM bank in assembly.

It's very simple to do but I think that it can be helpful for someone who don't know how to do this right away. In fact I personally would love to see more of this kind of programs in the download section ?

How this loader works ?

First thing to do is to tell the Kernal that we want to use a logical file. For this we need to use the SETLFS subroutine.

From the "C64 Programmer Reference Guide" :

Quote

This routine sets the logical file number, device address, and secondary address (command number) for other KERNAL routines.



The logical file number is used by the system as a key to the file table created by the OPEN file routine. Device addresses can range from 0 to 31. The following codes are used by the Commodore 64 to stand for the CBM devices listed below:

ADDRESS	DEVICE
0	Keyboard
1	Datassette™
2	RS-232C device
3	CRT display
4	Serial bus printer
8	CBM serial bus disk drive

Device numbers 4 or greater automatically refer to devices on the serial bus.



A command to the device is sent as a secondary address on the serial bus after the device number is sent during the serial attention handshaking sequence. If no secondary address is to be sent, the Y index register should be set to 255.



How to Use :

1. 
   Load the accumulator with the logical file number.
   


2. 
   Load the X index register with the device number.
   


3. 
   Load the Y index register with the command.
   

Since we want to load from the disk (or filesystem) we'll need to use the device number 8. The logical file is not important so we use the file 0.

Also, as we want to relocate the program into a bank at $A000, we'll set the Y register to #0 to activate secondary address mode.

Next step is telling the Kernal which file we want to load. For this we'll use the SETNAME subroutine.

From the "C64 Programmer Reference Guide" :

Quote

This routine is used to set up the file name for the OPEN, SAVE, or LOAD routines. The accumulator must be loaded with the length of the file name. The X and Y registers must be loaded with the address of the file name, in standard 6502 low-byte/high-byte format. The address can be any valid memory address in the system where a string of characters for the file name is stored. If no file name is desired, the accumulator must be set to 0, representing a zero file length. The X and Y registers can be set to any memory address in that case.



How to use :

1. 
   Load the accumulator with the length of the file name.
   


2. 
   Load the X index register with the low order address of the file name.
   


3. 
   Load the Y index register with the high order address.
   

For this we'll need to store our file names somewhere in our program so we write at the bottom of our file the names as a string of petscii characters. We then prepare our registers with the size of the filename to load, and then the address.

Our final step to load a file is obviously the LOAD subroutine.

From the "C64 Programmer Reference Guide" :

Quote

This routine LOADs data bytes from any input device directly into the memory of the Commodore 64. It can also be used for a verify operation, comparing data from a device with the data already in memory, while leaving the data stored in RAM unchanged.



The accumulator (.A) must be set to 0 for a LOAD operation, or 1 for a verify, If the input device is OPENed with a secondary address (SA) of 0 the header information from the device is ignored. In this case, the X and Y registers must contain the starting address for the load. If the device is addressed with a secondary address of 1, then the data is loaded into memory starting at the location specified by the header. This routine returns the address of the highest RAM location loaded.



Before this routine can be called, the KERNAL SETLFS, and SETNAM routines must be called.

NOTE: You can NOT LOAD from the keyboard (0), RS-232 (2), or the screen (3).
How to use :

0. 
   Call the SETLFS, and SETNAM routines. If a relocated load is desired, use the SETLFS routine to send a secondary address of 0.
   


1. 
   Set the A register to 0 for load, 1 for verify.
   


2. 
   If a relocated load is desired, the X and Y registers must be set to the start address for the load.
   

As the Reference guide said, we want to load a file so we set our A register to 0 and since we want to load to banked RAM ($A000) we enter the address in our X and Y registers.

One last thing that we need to do just after each of our LOAD calls, is to verify that our file has been successfully loaded. For this, we'll need to use the READST subroutine.

From the "C64 Programmer Reference Guide" :

Quote

This routine returns the current status of the I/O devices in the accumulator. The routine is usually called after new communication to an I/O device. The routine gives you information about device status, or errors that have occurred during the I/O operation.



The bits returned in the accumulator contain the following information: (see table below)

ST Bit Position	ST Numeric Value	Cassette Read	Serial Bus R/W	Tape Verify + Load
0	1		time out write
1	2		time out read
2	4	short block		short block
3	8	long block		long block
4	16	unrecoverable read error		any mismatch
5	32	checksum error		checksum error
6	64	end of file	EOI line
7	-128	end of tape	device not present	end of tape

How to use :

1. 
   Call this routine.
   


2. 
   Decode the information in the A register as it refers to your pro- gram.
   

As usual, following the Reference guide, all we need to do is call this subroutine just after our LOAD call, and check the content of the Accumulator. If zero, the load was successful.

And that's all ! You can chain file loading as much as you need, and even you just need to call SETLFS once at the start of the chain.

Note that you'll need to switch the bank between file loads to prevent overwriting previously added program. And since Bank 0 is also reserved you'll need to first switch to bank 1 and start from here.

At the end you can also load a file in place of the loader, just avoid overwriting memory where the code is currently being executed. You can for example leave this kind of code in your first bank and at last run it to load a program from $0800 to $9EFF.

Kernal Subroutines full documentation : https://www.pagetable.com/c64ref/kernal/

Post Scriptum

If you have any suggestions for the code or even want to change things in this description, don't hesitate to tell me !