XBIOS call Bconmap() on Atari Falcon 030
This document describes the new XBIOS call, Bconmap(), which makes the new serial ports on a TT030 accessible to programs which were written when there was just one serial port.
There are new Bconin/out/stat/ostat device numbers on a TT:
devno meaning
0 PRN
1 currently-mapped serial port (see below)
2 CON
3 MIDI
4 IKBD
5 RAW
6 ST-compatible serial port (called Modem 1; default).
7 SCC Channel B (Modem 2 on the back of a TT).
8 TTMFP serial port (3-wire, Serial 1 or Modem 3).
9 SCC Channel A (full handshake, Serial 2 or Modem 4). Bcon calls on device 1 (normally AUX) might actually refer to any of these devices, or to a user-installed device (with an even higher devno). You use Bconmap to change the mapping of device 1. Bconmap also changes the mapping of Rsconf() calls, and of Iorec calls with Iorec device number 0.
The port assignments above are for TT only; other machines with "extra" serial ports will have other assignments. Port 6 is always going to be the ST-compatible one, though. Other devices may be installed by drivers at boot time (or even later).
***************************
XBIOS call 44 (0x2c)
LONG Bconmap(devno)
WORD devno; This call maps "devno" in as Bcon* device number 1. It returns the old mapping. If devno is -1, there's no change; the current mapping is simply returned. If devno is -2, a pointer is returned (see below). Legal values are -1 (for no change), -2 (to return the pointer), and values 6 and up.
You can tell you're on a system which doesn't support Bconmap by making the call and checking the return: if the return value is 44 (0x2c, the same as the XBIOS call number) then Bconmap is not available.
In addition to the above, if devno is -2, a pointer to the device mapping structure is returned. This is used by programs which need to install new mappable handlers. It also contains the number of mappable devices; the highest legal devno value for Bcon calls (including Bconmap itself) is that number plus 5.
Illegal values (0-5, or higher than the highest legal value, or negative but not -1 or -2) don't change anything, and return 0.
The mapping is accomplished by writing into the (published) vector table in low memory. In addition, new pointers are used to make Iorec and Rsconf indirect. Therefore, programs which use the vector table in low RAM and/or Iorec and Rsconf will see the "currently-mapped" device when they make Bcon calls with devno=1, and when they make Iorec and Rsconf calls.
Bconmap-aware programs can use the higher devno values to get at a specific port, no matter what the current mapping is. They still need to use Bconmap to "map in" the desired port before making Iorec and Rsconf calls.
***************************
INSTALLING NEW BCONMAP DEVICE DRIVERS
Bconmap(-2) returns a pointer to a structure. The structure looks like
this:
struct bconmap {
LONG *maptab; /* ptr to map table (see below) */
WORD maptabsize; /* number of lines in the table */
};
The map table contains a line for each device. Each line contains pointers to the Bconstat, Bconin, Bcostat, and Bconout routines, plus a pointer to the Rsconf routine, plus a pointer to the Iorec for that device. The table's size (the number of devices) is in maptabsize. Maptabsize is used by all Bcon calls to range-check the device number.
The highest legal value for Bcon calls (including Bconmap) is this number plus 5.
A Bconmappable driver must have Bconstat, Bconin, Bcostat, and Bconout entry points, plus an iorec, plus an Rsconf function pointer. You install it by copying the table pointed to by maptab into a larger area and adding your driver's entry (five procedure pointers and an iorec pointer), then changing maptab and maptabsize.
In the unlikely event that your program finds itself installing the 38th device, that is, the one which would have Bconmap number 44 (decimal), you should actually allocate TWO new rows for maptab, install your device in the SECOND one, and increment maptabsize by two. Otherwise, a current mapping of device 44 would be indistinguishable from the case where Bconmap was not available at all. No programs should be told to use device number 44.
*******************************
BCONMAP AND RSCONF
Rsconf has been mis-documented for some time. It actually returns a longword value. That longword is four bytes stuck together. Those four bytes are the UCR, RSR, and TSR registers of the MFP, plus a useless byte. The UCR register is in the high byte of the returned longword, followed by the RSR, then the TSR, and the useless byte in the low-order byte. These bytes are the values of those registers BEFORE the changes dictated by the arguments to Rsconf.
In addition, ever since TOS 1.4, Rsconf(-2,-1,-1,-1,-1,-1) returns the last baud-rate value set with Rsconf. If the first argument is -2, all the other arguments are ignored.
In the world of Bconmap, the Rsconf arguments have to be interpreted slightly differently. Not every device is a 68901 MFP any more. For the new devices, the bits which make sense are used, the others discarded.
Programmers should use Rsconf(-1,-1,-1,-1,-1,-1) to read the current values, then change the bits they want to change and call Rsconf again with the new values; changing bits in registers not listed below is now considered illegal. (Consider a REAL MFP: TSR contains, among other things, the transmitter enable bit; if you write 0x08 to cause a break, you will be disabling the transmitter!)
The bits in the Rsconf args and return value which Bconmappable devices must emulate are as follows:
UCR:
bits 6-5: word-length (00=8, 01=7, 10=6, 11=5)
bits 4-3: stop bits: (01=1, 10=1.5, 11=2; 00 is invalid)
bit 2: parity (0=no, 1=yes)
bit 1: parity (0=odd, 1=even, meaningful only if bit 2 is 1)
RSR:
none
TSR:
bit 3: break (sends break while 1)
SCR:
none
Programs which use synchronous modes probably talk directly to their hardware, so it doesn't make much sense to "emulate" that here. If a legal value is inconvenient (such as 1.5 stop bits with hardware which doesn't support it, or a baud rate you can't support) you can ignore it: users will get used to the restrictions imposed by your device and driver.
******************************
SCC channel A is shared between the DB9 on the back of the TT030 (labelled Serial 2 or Modem 4) and the round LAN connector on the left side. Initially, it is programmed to use the DB9 connector. The selection can be made as follows:
Select LAN connector: Offgibit(0x7f); /* clear bit 7 (only) */
Select DB9 connector: Ongibit(0x80); /* set bit 7 (only) */
