Home XBIOSXBIOS PCI-BIOSPCI-BIOS Sound routinesSound routines

4.18 Interface programming

• Bconmap Selects a serial port.
• Dosound Programs sound generator.
• ExtRsConf Configures the RS-232/RS-485 port.
• Giaccess Reads from and writes to the GI sound chip.
• Ikbdws Programs the keyboard chip.
• Iorec Obtains address of the input/output buffer of RS-232, keyboard chip or MIDI port serial device.
• Kbdvbase Obtains buffer and interrupt vectors for mouse, MIDI and intelligent keyboard.
• Mfpint Initializes the multi-function peripheral chip interrupt.
• Midiws Writes string of characters to the MIDI port.
• Offgibit Clears a bit in port A register of the GI sound chip.
• Ongibit Sets a bit in port A register of the GI sound chip.
• Rsconf Configures the RS-232 port.

See also: Interrupt functions

4.18.1 Bconmap

Name: »Select serial port« - Select a default port.
 
Opcode: 44
 
Syntax: int32_t Bconmap( int16_t devno );
 
Description: The XBIOS routine Bconmap selects one of the serial ports for Bios output. In addition one can inquire for a pointer to the BCONMAP structure, with which one can query for the highest BIOS device number and also install new device drivers. devno can assume the following values:
 

devno Meaning
-402 Remove device / RSVF list (HSMODA)
-401 Append entry (HSMODA)
-400 Overwrite selected entry (HSMODA)
-2 Return pointer to BCONMAP structure
-1 Only inquire current channel
0 Test whether Bconmap is present
6 ST-compatible RS-232 port (U:\dev\modem1)
7 SCC Channel B (U:\dev\modem2)
8 TTMFP RS-232 port (U:\dev\serial1)
9 SCC Channel A (U:\dev\serial2)
>10 Own driver

The function affects both the BIOS vector table in the system variables, as well as the behaviour of the functions Rsconf and Iorec.
 
Note: In TOS 4.04, and when no TT-MFP is present, SCC Channel A will be device #8.
 
HSMODA
These functions are only present if the HSMODA package is installed.
 
int32_t Bconmap((int16_t)-400, (int16_t)dev_nr, (int32_t)ptr_to_6_longs)
The constant MAPT_OVE is defined as -400. This function serves for overwriting already existing MAPTAB entries. dev_nr is a device number from 6 upwards that already has to exist in MAPTAB, otherwise the error-code -15 EUNDEV will be returned. ptr_to_6_longs points to a structure that corresponds to a MAPTAB entry. This structure will be copied to the corresponding place in the MAPTAB. If the addressed device is the one currently set by Bconmap for AUX, then the newly hooked-in routines will also be copied to xco* and into the current Rsconf and Iorec cells. This function serves only for hooking in MagiC-friendly routines. If successful, the device number to which the entry refers will be returned, i.e. dev_nr.
 
To install devices on the BIOS numbers that are permanently assigned to a computer, one should always use MAPT_OVE. For the ST this pertains for instance to number 6, for a MegaSTE to numbers 6 to 8 and for a TT030 to numbers 6 to 9.
 
int32_t Bconmap((int16_t)-401, (int32_t)ptr_to_6_longs)
The constant MAPT_APP is defined as -401. This function serves for appending a channel to the MAPTAB or for writing to an empty channel. ptr_to_6_longs points to a structure that corresponds to a MAPTAB entry. The return is either the channel number selected by this function for the entry, or the error-code -12 EGENRL if there is no room for a MAPTAB augmentation. Here it cannot happen that the vectors are transferred immediately to xco*, as a previously absent channel, or one in use, can not have been set as AUX.
 
MAPT_APP searches for the first free channel after those BIOS numbers that are permanently assigned to a computer and can therefore only be used for installing additional devices.
 
int32_t Bconmap((int16_t)-402, (int16_t) dev_nr, (int32_t)ptr_to_listentry)
The constant MAPT_DEL is defined as -402. This function serves for deleting a device from the MAPTAB and for unhooking a RSVF list from the RSVF daisy chain.
 
dev_nr is either the BIOS channel number of the device to be removed from the MAPTAB, or -1 for doing nothing. The corresponding MAPTAB entry is cleared by entering special dummy-routine pointers that point to the assembler command RTS. The Iorec pointer entry is set to 0. If the deleted channel was also set as the BIOS AUX device, then BIOS AUX will be reset as number 6, even if number 6 has just been deleted.
 
ptr_to_listentry is either the pointer to the RSVF list to be unhooked, or 0 for doing nothing. The pointer must refer to the start of a list, which is then removed completely, even if it contains more than one interface object and end or daisy-chain object.
 
MAPT_DEL returns 1 if successful, or -1 in case of error.
 
Return value: Bconmap returns the old setting. If devno equals -2, then the function returns a pointer to BCONMAP.
 
Availability: According to Atari one should test one's TOS version for the presence of Bconmap in the following manner:
  
WORD has_bconmap ( VOID )
{
   return (0L == Bconmap (0));
}
Group: Interface programming
 
See also: Binding   Bconout   Bconin   Bcostat   Bconstat   Iorec   Rsconf
 

4.18.1.1 Bindings for Bconmap

C: #include <tos.h>
 
int32_t Bconmap( int16_t devno );
 
Assembler:
  
move.w    devno,-(sp)  ; Offset 2
move.w    #44,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.18.2 Dosound

Name: »Dosound« - Program the sound generator (PSG).
 
Opcode: 32
 
Syntax: void *Dosound( const int8_t *buf );
 
Description: The XBIOS routine Dosound starts a process for control of the programmable sound generator. The buffer buf holds commands for the programming of the sound generator. The following commands are supported:
 
Command Meaning
   
0x0x byte Write byte into register x of the sound chip
0x80 byte Load bytes into temporary register for use by command 0x81
0x81 byte1 Number of the sound register into which the value of the temporary register is to be transferred.
     byte2 Signed value to be added to the temporary register until value in third byte is met.
     byte3 Value of the temporary register at which the loop is terminated.
0x82 byte The number of 50 Hz ticks (20 ms) to wait for the next command. If the byte holds the value 0 the processing is terminated.
...  
0xff byte  
Return value: The function returns the previous playing sound buffer, if any.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding
 

4.18.2.1 Bindings for Dosound

C: #include <tos.h>
 
void Dosound( const int8_t *buf );
 
Assembler:
  
pea       buf          ; Offset 2
move.w    #32,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack
move.l    d0,a0

4.18.3 ExtRsConf

Name: »RS-232/RS485 configuration« - Configure the RS-232/RS-485-port.
 
Opcode: 162
 
Syntax: int32_t Xbios( 162, int16_t command, int16_t device, int32_t param );
 
Description: The XBIOS routine ExtRsConf configures the serial port.
 

Parameter Meaning
command 0x0000 - Return 0 to check that ExtRsConf
           is present
  0x0001 - Set port driver mode:
           param = 0 -> RS232
           param = 1 -> RS422
           param = 2 -> RS485
   
device BIOS device (6 = MFP serial, ...)
   
param See above.

Note: The function is only for the hardware of the Milan 2.1. However, it only exists as a special version and is not freely available.
 
Return value: E_OK (0) - OK
EUNCMD (-3) - Unknown command
ERROR (-1) - General error
EUNDEV (-15) - Unknown device
 
Availability: The function is present as of the MilanTOS dated 2002-06-09.
 
Group: Interface programming
 
See also: Binding
 

4.18.3.1 Bindings for ExtRsConf

C: #include <tos.h>
 
int32_t Xbios( 162, int16_t command, int16_t device, int32_t param );
 
Assembler:
  
move.l    param,-(sp)     ; Offset  6
move.w    device,-(sp)    ; Offset  4
move.w    command,-(sp)   ; Offset  2
move.w    #162,-(sp)      ; Offset  0
trap      #14             ; Call XBIOS
lea       10(sp),sp       ; Correct stack

4.18.4 Giaccess

Name: »access GI sound chip« - Permit access to the registers of the GI sound chip.
 
Opcode: 28
 
Syntax: int8_t Giaccess( int16_t data, int16_t regno );
 
Description: The XBIOS routine Giaccess reads or sets the registers in the GI sound chip. The following apply:
 
Parameter Meaning
   
data Is written at a write access to the register specified in regno
regno Number of the desired register (0..15). At write accesses bit 7 is also set.
Return value: The function returns the contents of the specified register.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding
 

4.18.4.1 Bindings for Giaccess

C: #include <tos.h>
 
int8_t Giaccess( int16_t data, int16_t regno );
 
Assembler:
  
move.w    regno,-(sp)  ; Offset 4
move.w    data,-(sp)   ; Offset 2
move.w    #28,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack

4.18.5 Ikbdws

Name: »write string to keyboard« - Program the keyboard chip.
 
Opcode: 25
 
Syntax: void Ikbdws( int16_t count, const int8_t *ptr );
 
Description: The XBIOS routine Ikbdws passes a string to the intelligent keyboard controller. The following apply:
 

Parameter Meaning
count Number of bytes to be output - 1
ptr Pointer to the bytes in memory
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding
 

4.18.5.1 Bindings for Ikbdws

C: #include <tos.h>
 
void Ikbdws( int16_t count, const int8_t *ptr );
 
Assembler:
  
pea       ptr          ; Offset 4
move.w    count,-(sp)  ; Offset 2
move.w    #25,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #8,sp        ; Correct stack

4.18.6 Iorec

Name: »input output record« - Obtain address of the input/ output buffer of a serial device.
 
Opcode: 14
 
Syntax: IOREC *Iorec( int16_t dev );
 
Description: The XBIOS routine Iorec returns the address of the input/output buffer of a serial device (RS-232, keyboard chip or MIDI port). The parameter dev can take the following values:
 

dev Meaning
0 RS-232
1 Keyboard
2 MIDI
Return value: The function returns a pointer to the IOREC array.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding   Bconmap
 

4.18.6.1 Bindings for Iorec

C: #include <tos.h>
 
IOREC *Iorec( int16_t dev );
 
Assembler:
  
move.w    dev,-(sp)    ; Offset 2
move.w    #14,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.18.7 Kbdvbase

Name: »keyboard vectors« - Return a pointer to the IKBD (intelligent keyboard), and MIDI interrupt vectors.
 
Opcode: 34
 
Syntax: KBDVBASE *Kbdvbase( void );
 
Description: The XBIOS routine Kbdvbase returns a pointer to a KBDVBASE structure contaning a 'jump' table to system vector handlers.
 
Note: Before one of the vectors specified in the structure is altered, one must ensure that a packet is not currently being sent (element drvstat = 0). Subsequently all interrupts should be blocked and a test performed to check that there really is no packet on the way.
 
Return value: The function returns a pointer to a KBDVBASE structure.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding
 

4.18.7.1 Bindings for Kbdvbase

C: #include <tos.h>
 
KBDVBASE *Kbdvbase( void );
 
Assembler:
  
move.w    #34,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.18.8 Mfpint

Name: »init MFP interrupt« - Initialize the multi-function peripheral chip interrupt.
 
Opcode: 13
 
Syntax: void Mfpint( int16_t number, int16_t (*vector)() );
 
Description: The XBIOS routine Mfpint initializes the multi-function chip interrupt for the connected peripheral devices. This permits hardware interrupts being intercepted. The argument vector specifies the interrupt service routine. The parameter number gives the number of the interrupt from 0 to 15:
 

number Description
0 I/O port bit 0 busy parallel port
1 RS-232 DCD
2 RS-232 CTS
3 Blitter
4 Timer D, RS-232 Baud rate generator
5 Timer C, 200-Hz system clock
6 Keyboard and MIDI
7 FDC and DMA
8 Timer B horizontal blank
9 RS-232 transmit error
10 RS-232 transmit buffer empty
11 RS-232 receive buffer full
12 RS-232 buffer full
13 Timer A (DMA sound)
14 RS-232 RI
15 Mono monitor detect / DMA sound complete
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding   Jdisint   Jenabint
 

4.18.8.1 Bindings for Mfpint

C: #include <tos.h>
 
void Mfpint( int16_t number, int16_t (*vector)() );
 
Assembler:
  
pea       vector       ; Offset 4
move.w    number,-(sp) ; Offset 2
move.w    #13,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #8,sp        ; Correct stack

4.18.9 Midiws

Name: »Midi write string« - Write string of characters to the MIDI port.
 
Opcode: 12
 
Syntax: void Midiws( int16_t cnt, void *ptr );
 
Description: The XBIOS routine Midiws outputs a string from a data buffer via the MIDI port. The following apply:
 
Parameter Meaning
   
cnt Number of bytes to be output - 1
ptr Pointer to byte string
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding
 

4.18.9.1 Bindings for Midiws

C: #include <tos.h>
 
void Midiws( int16_t cnt, void *ptr );
 
Assembler:
  
pea       ptr          ; Offset 4
move.w    cnt,-(sp)    ; Offset 2
move.w    #12,-(sp)    ; Offset 0
trap      #14          ; XBIOS aufrufen
addq.l    #8,sp        ; Stack korrigieren

4.18.10 Offgibit

Name: »GI bit off« - Clear individual bits in the port A register of the GI sound chip.
 
Opcode: 29
 
Syntax: void Offgibit( int16_t bitno );
 
Description: The XBIOS routine Offgibit clears a bit in register A of the GI sound chip. bitno specifies the value with which the register should be ANDed. The bits in this register have the following meaning:
 
Bit Description
   
 0 Floppy disk side select
 1 Select drive A:
 2 Select drive B:
 3 RS-232 RTS
 4 RS-232 DTR
 5 Centronics Strobe
 6 PIN 3 Monitor port
 7 Unused
As of TOS030 of the TT, however Modem 4 (1) or LAN (0)
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Gruppe: Interface programming
 
See also: Binding   Ongibit
 

4.18.10.1 Bindings for Offgibit

C: #include <tos.h>
 
void Offgibit( int16_t bitno );
 
Assembler:
  
move.w    bitno,-(sp)  ; Offset 2
move.w    #29,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.18.11 Ongibit

Name: »GI bit on« - Set individual bits in the port A register of the GI sound chip.
 
Opcode: 30
 
Syntax: void Ongibit( int16_t bitno );
 
Description: The XBIOS routine Ongibit sets a bit in register A of the GI sound chip. bitno specifies the value with which the register should be ORed. The bits in this register have the following meaning:
 
Bit Description
   
 0 Floppy disk side select
 1 Select drive A:
 2 Select drive B:
 3 RS-232 RTS
 4 RS-232 DTR
 5 Centronics strobe
 6 PIN 3 monitor port
 7 Unused
As of TOS030 of the TT, however Modem 4 (1) or LAN (0)
Return value: The function does not return a result.
 
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding   Offgibit
 

4.18.11.1 Bindings for Ongibit

C: #include <tos.h>
 
void Ongibit( int16_t bitno );
 
Assembler:
  
move.w    bitno,-(sp)  ; Offset 2
move.w    #30,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.18.12 Rsconf

Name: »RS-232 configuration« - Configure the RS-232 port.
 
Opcode: 15
 
Syntax: int32_t Rsconf( int16_t baud, int16_t ctr, int16_t ucr, int16_t rsr, int16_t tsr, int16_t scr );
 
Description: The XBIOS routine Rsconf configures the serial port. Since different hardware components may be in use with various computers, the function has to be used with care, i.e.:
 
  • Current settings should be established with Rsconf (-1,-1,-1,-1,-1,-1)
  • Only manipulate the necessary bits
  • Then set the new values.

Due to the possibility that various components may be in use, the usable values have been restricted in the following way:
 

Parameter Restriction
ucr Bit 1: Type of parity
         0 = Odd
         1 = Even
   
      2: Parity
         0 = No
         1 = Yes
   
    3+4: Number of stop bits
         0 = Invalid
         1 = 1 stop bit
         2 = 1.5 stop bits
         3 = 2 stop bits
   
    5+6: Word length
         0 = 8 bits
         1 = 7 bits
         2 = 6 bits
         3 = 5 bits
   
rsr Not usable
tsr Bit 3: (1 = Break)
scr Not usable

Technically impossible values must therefore be ignored. Otherwise the following assignments apply:
 

Parameter Meaning
baud Baud rate
  -1: Don't change
   0: 19200 Baud
   1: 9600 Baud
   2: 4800 Baud
   3: 3600 Baud
   4: 2400 Baud
   5: 2000 Baud
   6: 1800 Baud
   7: 1200 Baud
   8: 600 Baud
   9: 300 Baud
  10: 200 Baud
  11: 150 Baud
  12: 134 Baud
  13: 110 Baud
  14: 75 Baud
  15: 50 Baud
   
ctr Type of flow control
  -1: Don't change
   0: No flow control [powerup default]
   1: XON/XOFF (Control-S, Control-Q)
   2: RTS/CTS
   3: RTS/CTS and XON/XOFF
   
ucr New value for register, or -1
tsr New value for register, or -1
rsr New value for register, or -1
scr New value for register, or -1

Note: As of TOS 1.04 the last Baud rate set can be established with Rsconf (-2,-1,-1,-1,-1). One should never rely on the fact that all the settings could actually be made as desired, and hence pay close attention to the return value of the function.
 
Return value: The function returns in packed form the values of the registers ucr, rsr, scr and tsr as follows:
 

Bits 0..7: scr register
Bits 8..15: tsr register
Bits 16..23: rsr register
Bits 24..31: ucr register
Availability: All TOS versions.
 
Group: Interface programming
 
See also: Binding   Bconmap
 

4.18.12.1 Bindings for Rsconf

C: #include <tos.h>
 
int32_t Rsconf( int16_t baud, int16_t ctr, int16_t ucr, int16_t rsr, int16_t tsr, int16_t scr );
 
Assembler:
  
move.w    scr,-(sp)    ; Offset 12
move.w    tsr,-(sp)    ; Offset 10
move.w    rsr,-(sp)    ; Offset  8
move.w    ucr,-(sp)    ; Offset  6
move.w    ctr,-(sp)    ; Offset  4
move.w    baud,-(sp)   ; Offset  2
move.w    #15,-(sp)    ; Offset  0
trap      #14          ; Call XBIOS
lea       $E(sp),sp    ; Correct stack
Home XBIOSXBIOS PCI-BIOSPCI-BIOS Sound routinesSound routines