- C64 KERNAL API (Craig Taylor)

-

- Craig Taylor: Kernal 64 / 128

- C= Hacking, Volume 1, Issue 3; July 15, 1992

-

- Corrections (typos as well as content), translations etc.

- welcome at: https://github.com/mist64/c64ref

-

----------------------------------------------

-

# This plain text file is formatted so that it can be automatically

# parsed in order to create cross-references etc.

# * Lines starting with "-" is top-level information. The first line

# is the title. Lines starting with "--" are separators.

# * Lines starting with "#" are internal comments.

# * Hex addresses start at column 0.

# * Symbols start at column 7.

# * The description starts at column 15.

# * All lines of the description until the first blank line are

# combined into the heading.

# * The remaining text is in MarkDown format.

# The encoding is UTF-8.

$FF81 CINT Setup VIC, screen values, (128: 8563)...

Registers In : None.

Registers Out : None.

Memory Changed: Screen Editor Locations.

$FF84 IOINIT Initializes pertinant display and i/o devices

Registers In : C64: None. | C128: $0A04/bit 7

| 0 - Full Setup.

| 1 - Partial Setup. (no 8563 char)

Registers Out : .A, .X, .Y destroyed.

Memory Changed: CIA's, VIC, 8502 port, (C128: also optionally 8563).

Note : This routine automatically distinguishes a PAL system from a

NTSC system and sets PALCNT accordingly for use in the

time routines.

$FF87 RAMTAS Clears Z-Page, Sets RS-232 buffers, top/bot Ram.

Registers In : None.

Registers Out : .A, .X, .Y destroyed.

Memory Changed: Z-Page, Rs-232 buffers, top/bot Ram ptrs

$FF8D VECTOR Copies / Stores KERNAL indirect RAM vectors.

Registers In : .C = 0 (Set KERNAL Vectors) | .C = 1 (Duplicate KERNAL vectors)

.XY = address of vectors | .XY = address of user vectors

Registers Out : .A, .Y destroyed | .A, .Y destroyed.

Memory Changed: KERNAL Vectors changed | Vectors written to .XY

Note : This routine is rarely used, usually the vectors are directly

changed themselves. The vectors, in order, are :

C128: IRQ,BRK,NMI,OPEN,CLOSE,CHKIN,CHKOUT,CLRCH,BASIN,BSOUT

STOP,GETIN,CLALL,EXMON (monitor),LOAD,SAVE

C64 : IRQ,BRK,NMI,OPEN,CLOSE,CHKIN,CHKOUT,CLRCH,BASIN,BSOUT

STOP,GETIN,CLALL,USRCMD (not used),LOAD,SAVE

$FF90 SETMSG Set control of KERNAL control and error messages.

Registers In : .A bit 7 = KERNAL Control Messages (1 = on)

bit 6 = KERNAL Error Messages (1 = on)

Registers Out : None.

Note : KERNAL Control messages are those defined as Loading, Found etc

... KERNAL Error messages are I/O ERROR # messages which are

listed as follows:

$FF93 SECND Sends secondary address to device after a LISTN

Registers In : .A = secondary address

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FF96 TKSA Sends secondary address to device after TALK

Registers In : .A = secondary address.

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FF99 MEMTOP Read or Set top of System Ram

Registers In : .C = 1 (Read MemTop) | .C = 0 (Set MemTop)

| .XY = top of memory

Registers Out : .XY = top of memory | None.

Memory Changed: None. | Top of memory changed.

Note : On the C=128, this routine refers to the top of BANK 0 RAM, not

BANK 1 RAM.

$FF9C MEMBOT Read or Set bottom of System Ram

Registers In : .C = 1 (Read MemBot) | .C = 0 (Set MemBot)

| .XY = bottom of memory.

Registers Out : .XY = bottom of memory | None.

Memory Changed: None. | Bottom of Memory changed.

Note : On the C=128, this routine refers to the bottom of BANK 0 RAM,

not, BANK 1 RAM.

$FF9F KEY Scans Keyboard

Registers In : None.

Registers Out : None.

Memory Changed: Relevant System Keyboard Values

$FFA2 SETMO

This is a routine who's code never made it into any versions

of the KERNAL on the C64, Vic-20 and C128. Thus it is of no

pratical use.

$FFA5 ACPTR Get byte from current talker.

Registers In : None.

Registers Out : .A = data byte.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFA8 CIOUT Output byte to current listener.

Registers In : .A = byte.

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFAB UNTLK Commands current TALK device to stop TALKING.

Registers In : None.

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFAE UNLSN Commands current listening device to stop listening.

Registers In : None.

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFB1 LISTN Commands device to begin listening.

Registers In : .A = device #.

Registers Out : .A used.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFB4 TALK Commands device to begin talking.

Registers In : .A = device #.

Registers Out : .A used.

Memory Changed: None.

Note : Low level serial I/O - recommended use OPEN,CLOSE,CHROUT etc..

$FFB7 READSS Return I/O status byte.

Registers In : None.

Registers Out : .A = status byte. (see section on ERROR messages).

Memory Changed: None.

$FFBA SETLFS Set logical file #, device #, secondary # for I/O.

Registers In : .A = logical file #, .X = device #, .Y = secondary #

Registers Out : None.

Memory Changed: None.

$FFBD SETNAM Sets pointer to filename in preperation for OPEN.

Registers In : .A = string length, .XY = string address.

Registers Out : None.

Memory Changed: None.

Note : To specify _no_ filename specify a length of 0.

$FFC0 OPEN Open up file that has been setup by SETNAM,SETLFS

Registers In : None.

Registers Out : .A = error code, .X,.Y destroyed.

.C = 1 if error.

Memory Changed: None.

$FFC3 CLOSE Close a logical file.

Registers In : .A = logical file #.

Registers Out : .A = error code, .X,.Y destroyed.

.C = 1 if error

Memory Changed: None.

$FFC6 CHKIN Sets input channel.

Registers In : .X = logical file #.

Registers Out : .A = error code, .X,.Y destroyed.

.C = 1 if error

Memory Changed: None.

$FFC9 CHKOUT Sets output channel.

Registers In : .X = logical file #.

Registers Out : .A = error code, .X,.Y destroyed.

.C = 1 if error

Memory Changed: None.

$FFCC CLRCH Restore default input and output channels.

Registers In : None.

Registers Out : .A, .X used.

Memory Changed: None.

$FFCF BASIN Read character from current input channel.

Cassette - Returned one character a time from cassette buffer.

Rs-232 - Return one character at a time, waiting until

character is ready.

Serial - Returned one character at time, waiting if nessc.

Screen - Read from current cursor position.

Keyboard - Read characters as a string, then return them

individually upon each call until all characters

have been passed ($0d is the EOL).

Registers In : None.

Registers Out : .A = character or error code, .C = 1 if error.

Memory Changed: None.

$FFD2 BSOUT Output byte to current channel

Registers In : .A = Byte

Registers Out : .C = 1 if ERROR (examine READST)

Memory Changed: Dependent upon current device.

$FFD5 LOAD Loads file into memory (setup via SETLFS,SETNAM)..

Registers In : .A = 0 - Load, Non-0 = Verify

.XY = load address (if secondary address = 0)

Registers Out : .A = error code .C = 1 if error.

.XY = ending address

Memory Changed: As per registers / data file.

$FFD8 SAVE Save section of memory to a file.

Registers In : .A = Z-page ptr to start adress

.XY = end address

Registers Out : .A = error code, .C = 1 if error.

.XY = used.

Memory Changed: None.

$FFDB SETTIM Set internal clock (TI$).

Registers In : .AXY - Clock value in jiffies (1/60 secs).

Registers Out : None.

Memory Changed: Relevant system time locations set.

$FFDE RDTIM Reads internal clock (TI$)

Registers In : None.

Registers Out : .AXY - Clock value in jiffies (1/60 secs).

Memory Changed: None.

$FFE1 STOP Scans STOP key.

Registers In : None.

Registers Out : .A = last keyboard row, .X = destroyed (if stop key)

Memory Changed: None.

Note : The last keyboard row is as follows:

.A -> | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0

KEY: |STOP |Q |C= |SPACE|2 |CTRL |<- |1

$FFE4 GETIN Read buffered data from file.

Keyboard - Read from keyboard buffer, else return null ($00).

Rs-232 - Read from Rs-232 buffer, else null is returned.

Serial - See BASIN

Cassette - See BASIN

Screen - See BASIN

Registers In : None.

Registers Out : .A = character, .C = 1 if error.

.XY = used.

Memory Changed: None.

$FFE7 CLALL Close all open files and channels.

Registers In : None.

Registers Out : .AX used.

Memory Changed: None.

Note : This routine does not _actually_ close the files, rather it

removes their prescense from the file tables held in memory.

It's recommended to use close to close files instead of using

this routine.

$FFEA UDTIME Update internal (TI$) clock by 1 jiffie (1/60 sec).

Registers In : None.

Registers Out : .A,.X destroyed.

Memory Changed: Relevant system time locations changed.

$FFED SCRORG Returns current window/screen size

Registers In : None.

Registers Out : .X - Window Row Max

.Y - Window Col Max

.A - Screen Col Max (128 only, 64 unchanged)

Memory Changed: None

$FFF0 PLOT Read or set cursor position.

Registers In : .C = 1 (Read) | .C = 0 (Set)

None. | .X = Col

| .Y = Row

Registers Out : .C = 1 (Read) | .C = 0 (Set)

.X = Current Col | None.

.Y = Current Row |

Memory Changed: None | Screen Editor Locations.

$FFF3 IOBASE Returns base of I/O Block

Registers In : None.

Registers Out : .XY = address of I/O block ($D000)

Memory Changed: Screen Editor Locations.