The Serial Interface

The Z88 has a single serial port which has to be shared by all applications, so it is important that applications use the system to access the port to avoid interfering with the correct operation of other applications running in the machine. The system runs the serial port using interrupts and buffering, so most of its operation is transparent, but there are certain operations, such as directly controlling the RTS line (required for auto-dialing by some modems), which the system calls do not support and in these cases the hardware is accessed more directly - see the "Hardware" section of these notes. The serial port specification is reproduced here for convenience:

Using the Serial Port

The serial port is accessed by opening the device :COM.0, using GN_Opf, and then using the standard file I/O routines: OS_Gb, OS_Gbt, OS_Pb, OS_Pbt and OS_Mv. The device should be closed after the operation is complete. For most application this level of access should be sufficient, however, it may be necessary to change the serial port parameters from within an application. This is done by writing new values to the Panel, using the OS_Sp call, and then issuing a soft reset command to the serial driver. Changing the Panel setting may affect other software in the machine, so should not be undertaken lightly. It would be appropriate to reset the Panel to its original setting after serial port operations are complete. This can be achieved by first reading the Panel settings with OS_Nq. The "EazyLink" and "PCLINK II" popdowns use this technique. OS_Sp and OS_Nq are covered in detail in the "Miscellaneous useful routines" section.

The serial soft reset operation is carried out by opening the OS_Si call. The OS_Si call provides a low level access to the serial port. The call can perform nine different operations depending on the reason code passed to it:

Reason code    Action
SI_HRD ($00)   Hard reset the serial port
SI_SFT ($03)   Soft reset the serial port
SI_INT ($06)   Interrupt entry point (System use only).
SI_GBT ($09)   Get byte from serial port
SI_PBT ($0C)   Put byte to serial port
SI_ENQ ($0F)   Status enquiry
SI_FTX ($12)   Flush Tx (transmit) buffer
SI_FRX ($15)   Flush Rx (receive) buffer
SI_TMO ($18)   Set timeout
SI_GX  ($1B)   Get multiple bytes from serial port, using default timeout (OZ 4.5)
SI_PX  ($1E)   Put multiple bytes to serial port, using default timeout (OZ 4.5)
SI_GXT ($21)   Get multiple bytes from serial port until terminator using default timeout (OZ 4.5)

SI_GBT and SI_PBT are low-level interface for OS_Gbt and OS_Pbt API's. SI_GBT and SI_PBT are unstable for application level in all OZ ROM releases until V4.4. With OZ V4.4 and later, they can be used by applications directly (no need to open a handle to the serial port). The built-in Imp/Export and EazyLink popdowns now uses this interface.

This operating system call used for low level serial port communication uses the following interface and is mainly used by the operating system:

RST 20H, DEFB $8D

IN:

   IX = handle returned from GN_Opf of ":COM.0"
   L = reason code
   Other register usage depends on L
 
OUT:

   Depends on reason code
   IX will always be unchanged

The various reason code parameters are described in detail in the System calls Reference for OS_SI section.  

Flow Control

Flow control can be controlled either be software or hardware. The hardware handshaking is always active, so if you want to use software exclusively you will need to wire a cable to set the handshaking lines high at all times - ie. pins 5, 8 and 9 together on the Z88 D-connector.

An external device can ask the Z88 to stop sending by either sending an XOFF character or by de-asserting (bringing low) the CTS line. With software flow control, transmission can only stop when the XOFF character has been processed, so there is potentially a slight delay in response, while previously sent characters are read. With hardware control, transmission stops on the next character boundary. Transmission is resumed on the receipt of an XON character, in the case of software control, or be re-asserting CTS, ie. bringing it high. The output buffer is around 95 bytes long.

If software control is used, the Z88 will send an XOFF to an external device once the receive buffer is more than half full. Characters will continue to be received until there are only 15 character spaces left in the buffer. At this point an XOFF will be sent for every character subsequently sent by the external device. If the receive buffer overflows then data is lost forever. The Z88 will send an XON when the receive buffer has been cleared to less than a quarter full. Under hardware control, the Z88 will de-assert (bring low) RTS when the receive buffer is more than half full and the re-assert (bring high) when it has become less than a quarter full. The input buffer is around 127 bytes long.

NOTE: When working with software handshaking the performance of the serial port is seriously reduced. When working at speeds of 9600 baud or above, the software handshaking will not work unless there is an intercharacter gap, ie. some time is left between the sending of each character. The gap allows the Z88 to catch up with serial operations, and without it the machine may loose characters. 

After OZ 4.0, the driver has been seriously optimized to avoid such bytes lost. In 4.5, all the input put are unbuffered if no handshaking is set. It allows fast transfer up to 38400 bauds. To optimize speed transfer, three reason calls perform block transfer.

Serial Port Lines

The following table describes the 9-pin D-connector of the Z88:

Pin    Signal type              direction
1 -    unswitched +5V at 10µA   output
2 TxD  transmit data            output
3 RxD  receive data             input
4 RTS  ready to send            output
5 CTS  clear to send            input
6 -    not used
7 GND  Ground
8 DCD  data carrier detect      input
9 DTR  switched +5V at 10mA     output

NOTE: DTR is high when the machine is awake. The machine is always awake when the the screen is active, but even if asleep, the machine will wake every minute or so to carry out various housekeeping tasks, such as checking for alarms, and at these times DTR will go high. Pin 1 will show a signal if there is power available to the machine.