1
0
mirror of https://github.com/cc65/cc65.git synced 2024-12-28 06:30:16 +00:00

cbm_k_ functions documented

git-svn-id: svn://svn.cc65.org/cc65/trunk@5775 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
silverdr 2012-07-09 19:23:52 +00:00
parent 58530c142a
commit 1908158362

View File

@ -143,27 +143,26 @@ function.
<sect1><tt/cbm.h/<label id="cbm.h"><p>
<!-- <itemize> -->
<!-- <item><ref id="cbm_k_acptr" name="cbm_k_acptr"> -->
<!-- <item><ref id="cbm_k_basin" name="cbm_k_basin"> -->
<!-- <item><ref id="cbm_k_bsout" name="cbm_k_bsout"> -->
<!-- <item><ref id="cbm_k_chkin" name="cbm_k_chkin"> -->
<!-- <item><ref id="cbm_k_ciout" name="cbm_k_ciout"> -->
<!-- <item><ref id="cbm_k_ckout" name="cbm_k_ckout"> -->
<!-- <item><ref id="cbm_k_clall" name="cbm_k_clall"> -->
<!-- <item><ref id="cbm_k_close" name="cbm_k_close"> -->
<!-- <item><ref id="cbm_k_clrch" name="cbm_k_clrch"> -->
<!-- <item><ref id="cbm_k_getin" name="cbm_k_getin"> -->
<!-- <item><ref id="cbm_k_iobase" name="cbm_k_iobase"> -->
<!-- <item><ref id="cbm_k_listen" name="cbm_k_listen"> -->
<!-- <item><ref id="cbm_k_load" name="cbm_k_load"> -->
<!-- <item><ref id="cbm_k_open" name="cbm_k_open"> -->
<!-- <item><ref id="cbm_k_readst" name="cbm_k_readst"> -->
<!-- <item><ref id="cbm_k_save" name="cbm_k_save"> -->
<!-- <item><ref id="cbm_k_setlfs" name="cbm_k_setlfs"> -->
<!-- <item><ref id="cbm_k_setnam" name="cbm_k_setnam"> -->
<!-- <item><ref id="cbm_k_talk" name="cbm_k_talk"> -->
<!-- <item><ref id="cbm_k_unlsn" name="cbm_k_unlsn"> -->
<itemize>
<item><ref id="cbm_k_acptr" name="cbm_k_acptr">
<item><ref id="cbm_k_basin" name="cbm_k_basin">
<item><ref id="cbm_k_bsout" name="cbm_k_bsout">
<item><ref id="cbm_k_chkin" name="cbm_k_chkin">
<item><ref id="cbm_k_ciout" name="cbm_k_ciout">
<item><ref id="cbm_k_ckout" name="cbm_k_ckout">
<item><ref id="cbm_k_clall" name="cbm_k_clall">
<item><ref id="cbm_k_close" name="cbm_k_close">
<item><ref id="cbm_k_clrch" name="cbm_k_clrch">
<item><ref id="cbm_k_getin" name="cbm_k_getin">
<item><ref id="cbm_k_iobase" name="cbm_k_iobase">
<item><ref id="cbm_k_listen" name="cbm_k_listen">
<item><ref id="cbm_k_load" name="cbm_k_load">
<item><ref id="cbm_k_open" name="cbm_k_open">
<item><ref id="cbm_k_readst" name="cbm_k_readst">
<item><ref id="cbm_k_save" name="cbm_k_save">
<item><ref id="cbm_k_setlfs" name="cbm_k_setlfs">
<item><ref id="cbm_k_setnam" name="cbm_k_setnam">
<item><ref id="cbm_k_unlsn" name="cbm_k_unlsn">
<!-- <item><ref id="cbm_load" name="cbm_load"> -->
<!-- <item><ref id="cbm_open" name="cbm_open"> -->
<!-- <item><ref id="cbm_opendir" name="cbm_opendir"> -->
@ -171,7 +170,7 @@ function.
<!-- <item><ref id="cbm_readdir" name="cbm_readdir"> -->
<!-- <item><ref id="cbm_save" name="cbm_save"> -->
<!-- <item><ref id="cbm_write" name="cbm_write"> -->
<!-- </itemize> -->
</itemize>
(incomplete)
@ -1558,6 +1557,494 @@ be used in presence of a prototype.
</quote>
<sect1>cbm_k_acptr<label id="cbm_k_acptr"><p>
<quote>
<descrip>
<tag/Function/Input byte from serial bus
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char cbm_k_acptr (void);/
<tag/Description/The function returns a byte of data, which it
gets from the current TALKer on the serial bus.
In order to receive the data, the device must have previously been
sent a command to TALK and a secondary address if it needs one.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_talk" name="cbm_k_talk">,
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_basin<label id="cbm_k_basin"><p>
<quote>
<descrip>
<tag/Function/Input a Character from the Current Device
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char cbm_k_basin (void);/
<tag/Description/The function returns a character from the current input device.
Device must first have been OPENed and then designated as the input channel by the CHKIN routine.
When this function is called, the next byte of data available from the device is returned.
Exception is the routine for the keyboard device (which is the default input device).
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_chkin" name="cbm_k_chkin">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_bsout<label id="cbm_k_bsout"><p>
<quote>
<descrip>
<tag/Function/Output a byte
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_bsout (unsigned char C);/
<tag/Description/Function sends the character to the current output device.
Unless a device has been OPENed and designated as the
current output channel using the CHKOUT routine, the character is
printed to the screen, which is the default output device. If the
cassette is the current device, outputting a byte will only add it to
the buffer. No actual transmission of data will occur until the
192-byte buffer is full.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_chkin" name="cbm_k_chkout">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_chkin<label id="cbm_k_chkin"><p>
<quote>
<descrip>
<tag/Function/Designate a Logical File As the Current Input Channel
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_chkin (unsigned char FN);/
<tag/Description/If you wish to
get data from any device other than the keyboard, this function must be
called after OPENing the device, before you can get a data byte with
the cbm_k_basin or cbm_k_getin routine. When called, the routine will designate
the logical file whose file number was supplied as the
current file, its device as the current device, and its secondary
address as the current secondary address. If the device on the
channel is a serial device, which requires a TALK command and
sometimes a secondary address, function will send them over the
serial bus.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_basin" name="cbm_k_basin">,
<ref id="cbm_k_getin" name="cbm_k_getin">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_ciout<label id="cbm_k_ciout"><p>
<quote>
<descrip>
<tag/Function/Transmit a byte over the serial bus
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_ciout (unsigned char C);/
<tag/Description/Purpose of this function is to send a byte of data over
the serial bus. In order for the data to be received, the serial
device must have first been commanded to LISTEN and been given a
secondary address if necessary. This routine always buffers the
current character, and defers sending it until the next byte is
buffered. When the UNLISTEN command is sent, the last byte will be
sent with an End or Identify (EOI).
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_listen" name="cbm_k_listen">,
<ref id="cbm_k_unlsn" name="cbm_k_unlsn">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_ckout<label id="cbm_k_ckout"><p>
<quote>
<descrip>
<tag/Function/Designate a Logical File As the Current Output Channel
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_ckout (unsigned char FN);/
<tag/Description/If you wish to
output data to any device other than the screen, this routine must be
called after OPENing the device, and before you output a data byte
with the cbm_k_bsout() function. When called, the function will designate the
logical file whose file number was supplied as the current
file, its device as the current device, and its secondary address as
the current secondary address. If the device on the channel uses the
serial bus, and therefore requires a LISTEN command and possibly a
secondary address, this information will be sent on the bus.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_bsout" name="cbm_k_bsout">,
<ref id="cbm_k_listen" name="cbm_k_listen">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_clall<label id="cbm_k_clall"><p>
<quote>
<descrip>
<tag/Function/Close All Logical I/O Files
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void cbm_k_clall (void);/
<tag/Description/It closes all
open files, by resetting the index into open files to
zero and restores the default I/O devices.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_close" name="cbm_k_close">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_close<label id="cbm_k_close"><p>
<quote>
<descrip>
<tag/Function/Close a Logical I/O File
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_close (unsigned char FN);/
<tag/Description/It is used to
close a logical file after all I/O operations involving that file have
been completed.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_clall" name="cbm_k_clall">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_clrch<label id="cbm_k_clrch"><p>
<quote>
<descrip>
<tag/Function/Restore Current Input and Output Devices to the Default Devices
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void cbm_k_clrch (void);/
<tag/Description/It sets the
current input device to the keyboard, and the current output device to
the screen. Also, if the current input device was formerly a serial
device, the routine sends it an UNTALK command on the serial bus, and
if a serial device was formerly the current output device, the routine
sends it an UNLISTEN command.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_chkin" name="cbm_k_chkin">,
<ref id="cbm_k_ckout" name="cbm_k_ckout">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_getin<label id="cbm_k_getin"><p>
<quote>
<descrip>
<tag/Function/Get One Byte from the Input Device
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char cbm_k_getin (void);/
<tag/Description/Function gets a character from the current input device.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_basin" name="cbm_k_basin">,
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_iobase<label id="cbm_k_iobase"><p>
<quote>
<descrip>
<tag/Function/Return Base Address of Memory-Mapped I/O Devices
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned cbm_k_iobase (void);/
<tag/Description/This function returns the address of
the memory section where the memory mapped I/O devices are located. This
address can then be used with an offset to access the memory mapped I/O
devices in the Commodore 64. The offset is the number of locations from
the beginning of the page on which the I/O register you want is located.
This function exists to provide compatibility between the Commodore 64,
VIC-20, and future models of the Commodore 64. If the I/O locations for
a program are set by a call to this function, they should
still remain compatible with future versions of the Commodore 64, the
KERNAL and BASIC.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_listen<label id="cbm_k_listen"><p>
<quote>
<descrip>
<tag/Function/Command a device on the serial bus to LISTEN
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_listen (unsigned char dev);/
<tag/Description/This function will command a device on the serial bus to
receive data. The KERNAL routine will OR the supplied device number bit by bit
to convert it to a listen address, then transmits this data as a command on
the serial bus. The specified device will then go into listen mode, and
be ready to accept information.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_unlsn" name="cbm_k_unlsn">,
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_load<label id="cbm_k_load"><p>
<quote>
<descrip>
<tag/Function/Load RAM from a Device
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned int __fastcall__ cbm_k_load(unsigned char flag, unsigned addr);/
<tag/Description/This function LOADs data bytes from any input device directly into the memory.
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 flag 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 starting address for the load must be supplied.
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.
Function returns the address of the highest RAM location loaded.
Before this function can be called, the KERNAL SETLFS, and SETNAM
routines must be called.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_setlfs" name="cbm_k_setlfs">,
<ref id="cbm_k_setnam" name="cbm_k_setnam">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_open<label id="cbm_k_open"><p>
<quote>
<descrip>
<tag/Function/Open a Logical I/O File
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char cbm_k_open (void);/
<tag/Description/This function assigns a logical file to a device, so that it can be used for
Input/Output operations. In order to specify the logical file number,
the device number, and the secondary address if any, the cbm_k_setlfs() function must first be called.
Likewise, in order to designate the filename, the cbm_k_setnam() function must be used first. After these two
functions are called, cbm_k_open() is then called.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_setlfs" name="cbm_k_setlfs">,
<ref id="cbm_k_setnam" name="cbm_k_setnam">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_readst<label id="cbm_k_readst"><p>
<quote>
<descrip>
<tag/Function/Read status word
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char cbm_k_readst (void);/
<tag/Description/This function returns the current status of the I/O devices. It is usually called after new communication to an I/O device and gives information about device status, or errors that have occurred during the I/O operation.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_save<label id="cbm_k_save"><p>
<quote>
<descrip>
<tag/Function/Save RAM to a Device
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/unsigned char __fastcall__ cbm_k_save(unsigned int start, unsigned int end)/
<tag/Description/This function saves a section of memory. The cbm_k_setlfs() and cbm_k_setnam() functions must be
used before calling this function. However, a file name is not required to
SAVE to device 1 (the Datassette(TM) recorder). Any attempt to save to
other devices without using a file name results in an error. NOTE: Device 0 (the keyboard), device 2 (RS-232), and device 3 (the screen) cannot be SAVEd to. If the attempt is made, an error occurs, and the SAVE is stopped.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_setlfs" name="cbm_k_setlfs">,
<ref id="cbm_k_setnam" name="cbm_k_setnam">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_setlfs<label id="cbm_k_setlfs"><p>
<quote>
<descrip>
<tag/Function/Set up a logical file
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_setlfs (unsigned char LFN, unsigned char DEV, unsigned char SA);/
<tag/Description/This functions sets up the logical file by setting its number, device address,
and secondary address.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_setnam" name="cbm_k_setnam">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_setnam<label id="cbm_k_setnam"><p>
<quote>
<descrip>
<tag/Function/Set Filename Parameters
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_setnam (const char* Name);/
<tag/Description/This function is used to set up the file name for the OPEN,
SAVE, or LOAD operations.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_open" name="cbm_k_open">,
<ref id="cbm_k_load" name="cbm_k_load">,
<ref id="cbm_k_save" name="cbm_k_save">
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_talk<label id="cbm_k_talk"><p>
<quote>
<descrip>
<tag/Function/Commands device to TALK
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void __fastcall__ cbm_k_talk (unsigned char dev);/
<tag/Description/When called, it ORs the device number with the TALK code (64, $40) and sends it on the serial
bus. This commands the device to TALK.
<tag/Limits/<itemize>
<item>The function is only available as fastcall function, so it may
only be used in presence of a prototype.
</itemize>
<tag/Availability/cc65
<tag/See also/
<ref id="cbm_k_acptr" name="cbm_k_acptr">,
<tag/Example/None.
</descrip>
</quote>
<sect1>cbm_k_unlsn<label id="cbm_k_unlsn"><p>
<quote>
<descrip>
<tag/Function/Send an UNLISTEN command
<tag/Header/<tt/<ref id="cbm.h" name="cbm.h">/
<tag/Declaration/<tt/void cbm_k_unlsn (void);/
<tag/Description/This function commands all devices on the serial bus to
stop receiving data from the host computer (i.e., UNLISTEN). Calling this
function results in an UNLISTEN command being transmitted on the serial
bus. Only devices previously commanded to LISTEN are affected. This
function is normally used after the host computer is finished sending data
to external devices. Sending the UNLISTEN commands the listening devices
to get off the serial bus so it can be used for other purposes.
<tag/Limits/<itemize>
<item>
</itemize>
<tag/Availability/cc65
<tag/See also/
<tag/Example/None.
</descrip>
</quote>
<sect1>cclear<label id="cclear"><p>
<quote>