Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-File<invalid destination page 1581>The IKBD ControllerThe Atari 16/32 bit computer line uses the Intelligent KeyBoarDController (IKBD) for keyboard, joystick (old-style CX-40), mouse, and
clock communication. The 6850 ACIA serial communications chip is used to
transfer data packets from the IKBD interface to the host computer.
The TOS calls Bconout( 4, ??? ), Ikbdws(), and Initmous() handle
communication to the controller. Return messages from the controller must
be processed by placing a specialized handler in the vector table returned
by the XBIOS call Kbdvbase(). Kbdvbase() returns the pointer to a vector
table as follows:
typedef struct
{
void (*midivec)( UBYTE data ); /* Passed in d0 */
void (*vkbderr)( UBYTE data ); /* Passed in d0 */
void (*vmiderr)( UBYTE data ); /* Passed in d0 */
void (*statvec)( char *packet ); /* Passed in a0 */
void (*mousevec)( char *packet ); /* Passed in a0 */
void (*clockvec)( char *packet ); /* Passed in a0 */
void (*joyvec)( char *packet ); /* Passed in a0 */
void (*midisys)( VOID );
void (*ikbdsys)( VOID );
char ikbdstate;
} KBDVECS;
When an IKBD message is pending, the interrupt handler for the ACIAs
calls either the midisys handler or the ikbdsys handler to retrieve the
data and handle any errors. The default action for the ikbdsys handler is
to decide whether the packet contains error, status, joystick, clock, or
mouse information and to route it appropriately to vkbderr, statvec,
joyvec, clockvec, or mousevec. Keyboard packets are handled internally by
ikbdsys.
When an interrupt occurs on either 6850 chip (IKBD or MIDI), the following
chain of events happen:
1. The system interrupt handler installed in MFP #4 is called. This routine
determines which 6850 caused the interrupt.
2. If the MIDI 6850 caused the interrupt, midisys() is called immediately.
midisys() checks the MIDI control register for either an error condition
or a data byte. If a data byte is available, it is placed in the low
byte of d0 and sent to midivec(). If an error occurred, vmiderr() is
called.
3. If the Keyboard 6850 generated the interrupt, ikbdsys() is called
immediately. The ikbdsys() handler checks for an error condition or the
availability of a data byte. If an error condition exists, vkbderr() is
called. Otherwise, the ikbdsys() handler reads data byte(s) as necessary
to form a complete 'packet' depending on what generated the interrupt
(joystick, mouse, or keyboard).
4. If the ikbdsys() handler receives a keyboard make or break code, it
handles the packet internally. Otherwise, the address of the packet is
passed to statvec(), mousevec(), clockvec(), or joyvec().
Handler vectors may be altered by modifying the structure whose address is
returned by Kbdvbase() or by using Mfpint() as appropriate.
Your handler should be patched into the appropriate vector and, if
appropriate, expect the packet buffer to be pointed to by register A0.
Unless your handler is designed to completely replace the functions of the
default handler you should jump through the original vector pointer upon
exit, otherwise simply use the 680x0 RTS instruction.
Each byte received through the keyboard ACIA falls into one of the
following categories as follows:
Category Value(s) Meaning
Keyboard 0x00- One of these values is generated each time a key is
Make Code 0x7F depressed. This value may be used with Keytbl() to
generate an ASCII code for the scan code.
Keyboard 0x80- This code is generated when a key previously
Break Code 0xFF depressed has been released. It represents the make
code logically OR'ed with 0x80.
Status 0xF6 This codes indicate the beginning of a multiple byte
Packet status packet.
Header
Absolute 0xF7 See Below
Mouse
Position
Relative 0xF8- See Below
Mouse 0xFB
Position
Time-of-Day 0xFC See Below
Joystick 0xFD See Below
Report
Joystick 0 0xFE See Below
Event
Joystick 1 0xFF See Below
Event
Status Any When the ikbdstate variable (found in the KBDVECSPacket structure) is non-zero, it represents the number of
Data remaining bytes to retrieve that are part of a status
packet and should thus not be treated as any of the
above codes.
The KeyboardKeyboard keys generate both a 'make' and 'break' code for each complete
press and release respectively. The 'make' code is equivalent to the high
byte of the IKBD scan code. 'make' codes are not related in any way to
ASCII codes. They represent the physical position of the key in the
keyboard matrix and may vary in keyboards designed for other countries.
The XBIOS function Keytbl() provides lookup values which make
internationalization possible. The key 'break' code is the 'make' code
logically ORed with 0x80.
It should be noted that 'key repeats' are not generated by the ACIA but
by a coordination of the ikbdsys and system timer handlers.
The MouseThe mouse may be programmed to return position reports in either
absolute, relative, or keycode mode (it is by default programmed to return
relative position reports).
In relative reporting mode, the IKBD generates a mouse packet each time
a mouse button is pressed or released, and every time the mouse is moved
over a preset threshold distance (which is configurable). A relative mouse
report packet is headed by a byte value between 0xF8 and 0xFB followed by
the X and Y movement of the mouse as signed bytes. If the movement is
greater than can be represented as signed bytes (-128 to 127), multiple
packets are sent.
The header byte determines the state of the mouse buttons as follows:
Header Mouse Button State
0xF8 No buttons depressed.
0xF9 Left button depressed.
0xFA Right button depressed.
0xFB Both buttons depressed.
In absolute reporting mode, the IKBD only generates a mouse packet when
interrogated. Mouse packets in absolute mode are headed by a 0xF7 byte
followed by the MSB and LSB of the X value and the MSB and LSB of the Y
value respectively. The minimum and maximum X and Y values are
user-definable.
Keycode reporting mode generates keyboard 'make' and 'break' codes for
mouse movements rather than sending standard mouse packets. Mouse movement
is translated into the arrow keys and the codes 0x74 and 0x75 represent
the left and right mouse button respectively. 'break' codes are sent
immediately after the corresponding 'make' code is delivered.
The JoystickThe basic CX-40 style joystick controls are still present on every Atari
computer. Atari recommends that these ports should not be supported when
STe/Falcon030 enhanced joysticks are present unless the option for
four-player play is desired. While no direct TOS support is available for
reading these ports, it is possible using the IKBD controller in one of
several joystick reporting modes.
Joystick event reporting mode (the default) sends a joystick packet each
time the status of one of the joysticks changes. The joystick packet
header is 0xFE if the state of joystick 0 has changed or 0xFF if the
status of joystick 1 has changed. This header byte is followed by a BYTE
containing the new state of the joystick as follows:
The four bits corresponding to joystick position can be interpreted as
follows:
Joysticks may be interrogated at any time by sending an interrogate
command (as described later in this chapter). The packet response to this
command is 0xFD followed by the BYTE report of joystick 0 and 1 (as shown
above).
The joysticks may be placed into joystick monitoring or fire button
monitoring mode. In these modes, all other IKBD communication is stopped
and all processor time is devoted to the processing of packets. Joystick
monitoring mode cause the IKBD to send a continuous stream of two-byte
packets as follows: The first byte contains the status of joystick buttons
0 and 1 in bits 1 and 0 respectively. The second byte contains the
position state of joystick 0 in the high nibble and joystick 1 in the
lower nibble (the position state can be interpreted as shown in the
diagram above).
Fire button monitoring mode constantly scans joystick button 1 and
returns the results in BYTEs packed with 8 reports each (one per bit).
These modes may be paused or halted using the appropriate commands.
Joystick keycode mode is similar to mouse keycode mode. This mode
translates all joystick position information into arrow keys. A 'make'
code of 0x74 is generated when joystick button 0 is depressed and a 'make'
code of 0x75 is generated when joystick button 1 is depressed. The rate at
which the IKBD controller generates these joystick events can be
controlled using commands discussed in the following section.
Time-of-DayThe IKBD controller maintains a separate time-of day clock that is kept
synchronized with GEMDOS time by OS calls. A time-of-day packet may be
requested using the method shown below under IKBD commands.
The response packet from the IKBD is seven bytes in length identified by
its header byte of 0xFC and followed by six UBYTES containing the year
(last two digits), month, day, hours (0-24), minutes, and seconds in BCD
format (ex: a month byte in December would be 0x12).
IKBD CommandsCommands may be sent to the IKBD using any of the TOS function calls
described above. Some commands may generate packets while other commands
change the operating state of the IKBD controller. Unrecognized command
codes are treated as NOPs. Here is a table of valid IKBD command codes.