7 General Driver Protocol

7.1 Preliminaries

7.1.1 Purpose of this Document

This document is addressed to system programmers. It specifies the recommended L3 conventions for communicating with IO drivers as well as for writing and installing them.

Important concepts of L3 are flexibility and extendability. In the field of hardware drivers this means that privileged users may replace and add IO drivers. (The only exception is the backing store (hard disk) driver, which belongs to the kernel itself.) So the protocols specified in this document are not enforcible, but they are strongly recommended to all people implementing driver software.

It is recommended to obey the conventions specified here not only in hardware drivers but even when designing higher level software (if possible and senseful).

7.1.2 Related Documents

7.1.3 Method of Description

7.2 The General Driver Protocol

Usually hardware drivers in L3 are realized as a set of processes. Whether a driver consists of one, two or even more processes depends on the type of device. The General Driver Protocol (GDP) defines the communication between drivers and user or system processes. It is strongly recommended that all drivers use this protocol. If possible it should be used also by ,,high level drivers''.

7.2.1 Orders and Replies

The method to communicate with drivers is the usual L3 inter process communication. So orders are sent and results are received as messages. This chapter defines the various message types used by the GDP.

An order message always consists of an order code followed by additional parameters. In the same way a reply message starts with a reply code and may be followed by additional parameters. In general the additional parameters are objects of various types (e.g. blocks, strings, characters, bitmaps ...), coordinates (block numbers, screen positions ...) and mode specifiers (colour, font ...). The GDP has the protocol type number 1. So all GDP order codes have the form

The same convention holds for GDP specific reply codes.

7.2.2 Message Codes

In GDP the message code is always the first element of a message. This section defines the codes used for orders, interrogations and displays. The message code contains the addressed subchannel, the message type, the desired function and the type of the involved object:

01
GDP identification

subchannel
If a driver process distributes its orders to other processes or handles more than one physical or logical device, this field specifies the addressed subchannel. Its range is 0...255. The default subchannel is 0.

object type
This field specifies the type of object involved. Its range is 0...4095. The concrete semantics of the requested operation depends on the combination of the object type and the function specified by the IO-bits.

function

0
reply

1..3
reserved

4
alternate in requested

5
alternate out requested

6..7
reserved

8
exec in

9
exec out

10
exec early in

11
exec early out

12
interrogate in

13
interrogate out

14..15
reserved

reply
The execution of an order is answered by a ,,reply''. The same holds for an interrogation concerning an executable order. The reply code is followed by an object (specified in the type field) and an additional error status information referring to the acknowledged operation. The structure of the error status object is described in the object type table.

alternate in request, alternate out request
Whenever an order or an interrogation is not executable, the driver has to reply an alternate in/out request. In the reply message the subchannel, object type and further parameters have to be as close at the original order or interrogation as possible, but the alternate request must specify an executable order.

in order
An in order always requests the driver to send data (usually after performing an input operation) or the actual settings of control or status parameters. The specified object type determines the type of operation. The driver has to operate in synchrounous mode, i.e. has to reply after executing the order.

out order
An out order sends data for output or control information to the driver. The specified object type determines the type of operation. The driver has to operate in synchrounous mode, i.e. has to reply after executing the order.

early in order
Here one has to differentiate between driver controlled devices (e.g. disks, tapes) and devices controlled by external events (e.g. keyboards, RS232 and LAN receivers).

  1. early in at driver controlled devices

    The driver is free to handle the order in synchronuous way (like an 'in order') or in the early mode. In the second case the driver has to reply immmediately a time delay after which the data is supposed to be available. Following this reply the driver will initiate the data input operation. Some time later it will receive a new early in order concerning to the same object. If the data is available now, the driver has to send the data as reply, otherwise a new supposed time delay.

  2. early in at devices controlled by external events

    If the requested data is available within the driver, it has to send the data as reply, otherwise it must send a nil reply (without waiting for data).

early out order
The driver is free to handle the order in synchronuous way (like an 'out order') or in the early mode. In the second case the driver has to answer an immediate 'early ack'. In contrast to synchronuous mode the data output is initiated after the early ack. Thus a write error may occurr later. If this happens, the reply to the next order will signal an error in the error status field.

Attention: There is no strict relationship between the error ack and the preceding early out operations. All between the last synchronuous operation and the error reply must be regarded as faulty.

interrogate in order, interrogate out order
The driver is asked whether it could execute the specified order or not (and why not). An interrogation will never change the drivers state nor really read or write data.

7.3 Objects

7.3.1 Object Types

Object types are grouped in a hierarchical fashion. The 12-bit object type specifier is structured as follows:

Currently four device classes are known in this list:

7.3.2 Object Type Table

This table shows the tree of all actually defined object types with its codings. Codings not contained within this table are reserved for further extensions.

7.3.3 Object Description

The format (representation) of an object may depend on the message type. So in the detailed object description the format is marked by I, O, R or any combination of them:

I
the representation within an 'in order', 'interrogate in order' or 'alternate in order request'

O
the representation within an 'out order', 'interrogate out order' or 'alternate out order request'

R
the representation within a reply.

If any object format is not given for one of these cases, this object type cannot be used in this context.

0x000 Nil Object

Format:

This object type specifies ,,no object''. It is used e.g in simple ack or nak replies, which do not include any object.

When used in conjunction with orders or alternate order requests it has a special meaning (see [here]).

0x001 Time Delay

Format:

This specifies a supposed time period (in milliseconds) after which the operation should be retried. This reply may come only as a result to an early in order.

0x010 Error status

Format:

The error status always describes the result of the last operation. It is only valid after executing an order. The error status consists of 8 error bits and an error probability descriptor k:

Error bits:

Error probability:

Remark: GDP requires that each reply message contains the current error status as an additional object, not specified in the object type field of the GDP code. So the error status type 0x010 will never be used within GDP messages. It is listed in this section for sstematic reasons only.

0x011 Error Report

Format:

0x012 Substitution Report

Format:

0x020 Broadcast Object

Format:

The 'exec in' function of this object signals the start of a broadcast sequence and 'exec out' function signals the end. Remark: This object is only used for internal communication between the terminal process and its manager.

0x030 System Restart

Format:

Signals a system restart.

Remark: This object is only used for internal communication between the terminal process and its manager.

0x100 Byte String

Format:

The bytes are part of a sequential stream but do not form a closed object. So a byte string may be broken into smaller pieces or concatenated with other strings by the driver without changing the semantics. If a byte string should be read by an 'exec in', the driver has to wait until at least one byte is received. When using an 'exec early in' it has to respond immediately.

0x101 Datagram

Format:

A datagram is a string of bytes, which forms a closed semantical object. In contrast to byte strings, datagrams must always be handled as undivisible objects. If a datagram should be read by an 'exec in', the driver has to wait until a datagram is received. When using an 'exec early in' it has to respond immediately.

0x110 RS232 Transfer Mode Specifier

Format:

The baud rate is specified in bit per seconds. Parity is coded as

0
no parity

1
odd parity

3
even parity

5
high parity

7
low parity

0x111 RS232 Control Line Specifier

Format:

The line numbering refers to RS232. All 1-bits in line mask bits AND line value bits specify lines with 1-polarity, all 1-bits in line mask bits AND NOT line value bits specify lines with 0-polarity. All bits not set in line mask bits are undefined (reading) or not affected (writing).

0x112 Break Event

Format:

No data representation of break event is needed.

0x113 RS232 Output Flow Control Specifier

Format:

The first two parameters may be used to implement output flow control based on signal lines (CTS, DCD,...). They specify the state of the incoming control lines required for output. The line numbering refers to RS232. All 1-bits in line mask bits AND line value bits specify lines with 1-polarity required, all 1-bits in line mask bits AND NOT line value bits specify lines with 0-polarity required. Otherwise the output will be blocked.

Xon code and xoff code may be used to implement XON/XOFF or similar output flow protocols. An incoming xoff will block the output channel, while the next incoming xon will unblock it. Initially after sending a flow control specifier the channel will be in the xon state. The value 0 is reserved.

xon code = xoff = 0 specifies ,,no xon/xoff protocol''. If an xon/xoff protocol is switched on, these codes will not be transfered by the corresponding input channel but only to control the output.

0x114 RS232 Input Flow Control Specifier

Format:

The first two parameters specify the state of the incoming control lines required for input. The line numbering refers to RS232. All 1-bits in line mask bits AND line value bits specify lines with 1-polarity required, all 1-bits in line mask bits AND NOT line value bits specify lines with 0-polarity required. Otherwise incoming data will be ignored. The third parameter specifies the size of the driver's input buffer for incoming bytes. 'buffer limit' specifies a limit for collecting input, i. e., if input received, the driver waits 10 ms, until no more input received or buffer limit is reached. Generally the initial value for buffer limit is buffer half. The last 3 parameters are reserved and must be 0 !

0x200 Block Sequence

Format:

This is the basic data object for all magnetic devices. The length of a block sequence must always be the actual block size (specified in the transfer mode) or a multiple of this value.

0x200 Block Sequence Ptr

Format:

This type of object is used for paging within the kernel and the backing store drivers only.

0x210 Floppy Disk Transfer Mode Specifier

Format:

The sector size is given in bytes.

0x211 Floppy Disk Media Type Specifier

Format:

0
undefined media

1
3.5,, or 5.25'' diskette, double sided, single track

2
3.5,, or 5.25'' diskette, double sided, double track

3
5.25,, diskette, double sided, high density ''

4
3.5,, diskette, double sided, high density ''

,,Undefined media'' in an out operation means: Try to determine the media actually in the floppy disk drive and take it as new media type. If this succeeds, the answer has to be an ,,ack nil'' and the new media type can be requested by an in operation. Else (no readable diskette in the drive) the answer has to be an alternate out request.

0x300 Scan Ascii

Format:

The reply has the following Structure STRUCT (BYTE ascii, scan, reseved1, reserved2) [scan ascii]

0x301 Key

Format:

The reply has the following Structure STRUCT (BYTE ascii, scan, shift state, extended shift state) [key]

0x302 Shift State

Format:

The reply has the following Structure STRUCT (BYTE shift state, extended shift state, reseved1, reserved2) [state]

0x303 Make Break

Format:

The reply has the following Structure STRUCT (BYTE make break code, reseved1, reserved2, reserved3) [make break] STRUCT (BYTE ascii, scan, shift state, extended shift state) [key] Every make break code is sent, if it is detected. If no valid scan ascii could be derived from this make break code, the scan byte and the asci byte are set to 0xff.

0x304 Hot Key

Format:

Signals, that a hot key occured. Remark: This object is only used for internal communication between the terminal process and its manager.

0x305 Diacritical Flag

Format:

Sets a flag in the keyboard manager, which controls the consideration of diacritical chars.

0x400 Alpha8 (Attr, Char String)

Format:

0x401 Alpha8 (Attr, Char String, glue)

Format:

0x402 Alpha8 ((Char,Attr) String)

Format:

0x403 Alpha8 ((Char,Attr) String, Glue)

Format:

0x404 Alpha8 Char Filler

Format:

The specified rectangle is filled by the fill char without changing the attributes.

0x405 Alpha8 (Char,Attr) Scroller

Format:

A positive scroll line value means ,,scroll up'', a negative one ,,scroll down'', zero has no effect. A scroller can be used to fill a rectangular region by specifying 'scroll lines' large enough.

0x406 Alpha8 Update String

Format:

This is a special object which can only be used in the context of the GDP/CSC. It is described in the CSC chapter.

0x407 Attribute Mode

Format:

Sets the background colour for the attributes with bit 7. If mode = 0, then background of the attributes with bit 7 is intensiv, and if mode = 1, it is blinking.

0x450 Beep

Format:

Sounds a beep.

0x451 Click

Format:

Sounds a mouse click.

0x452 Tone

Format:

Turns on the loudspeaker in the given frequency.

0x480 Screen Descriptor

Format:

Video mode and active page are defined. The alphanumeric modes are characterized by 'char width = char height = 1'. The 'mode' can be

0
even bytes: char, odd bytes: attribute

1
1 bit pixel

2
2 bit pixel

3
2 plane pixel

4
4 plane pixel

0x481 Screen Memory

Format:

Outputting a screen memory includes a complete refresh of the hardware screen from the screen space. From now on all screen modifications are also made within the screen space (usually an alias space).

0x482 Screen Page

Format:

0x483 Screen Write Access

Format:

By this a process can signal to the driver that it wants to write to the (aliased) screen space. Usually the driver will protect the displayed part of the screen space from writing. In such a case the user process may request direct write access, if its software wants to modify the screen memory by its own. If the driver acknowledges this request, it has removed the write protection from the addressed 4K page for some milliseconds. Afterwards the driver will analyze the changes by itself and update the hardware screen. (This is a nil action, if the screen space is directly mapped to hardware.)

0x484 Screen Palette Descriptor

Format:

This is used to defines colour palettes. Available palettes as well as palette registers are numbered from 0. The overscan register (if available) has the reg no -1.

0x485 Screen Palette Selector

Format:

Selecting the active palette.

0x486 Screen Hardware

Format:

display type:

available modes:

0x487 Screen Plane Selector

Format:

    planes (bit 15..8):  select plane for read (0..3) 
    planes (bit 7..0) :  select planes for write (0..15) 
                         IF bit (selected planes for write, n) 
                            THEN select plane 'n' 
                         FI

Remark: This object is only used for internal communication between the display manager of the CONSOLE and its driver.

0x488 Screen EGA Palette Selector

Format:

    palette selector: 
          (bit 31..16):     don't care 
          (bit 15..8 ):     register to set 
                            0..15  <=>   palette register no 
                            0x 11  <=>   overscan register 
          (bit 7..0 ):      value to set

0x489 Screen VGA Color Register

Format:

 
    color to set:           0..255 
    color descriptor : 
          (bit 31..24):     don't care 
          (bit 23..16):     blue value     (0..63) 
          (bit 15..8 ):     green value    (0..63) 
          (bit 7..0 ):      red value      (0..63)

0x48a Screen VGA Register

Format:

 
    mode:  0..3:  read/write  dac-register 
              0:    0.. 63    (n = 192) 
              1:   64..127    (n = 192) 
              2:  128..191    (n = 192) 
              3:  192..255    (n = 192) 
 
             4:   read/write  attribut controller registers, 
                              graphik controller registers, 
                              sequencer registers; 
                              (n  =  37)

Remark: This object is only used for internal communication between the display manager of the CONSOLE and its driver.

0x48b Screen Activate

Format:

0x490 Window Size

Format:

0x4A0 Cursor Descriptor

Format:

Cursor number 0 is the alphanumeric cursor, 1 identifies the mouse. The following cursor shapes are defined:

          0            no visible cursor 
          n            defined by bitmap n (0 < n < 65536) 
          0x1ttbb      line cursor (bottom line = bb, top line = tt)

The following cursor modes are defined:

 
          0            overwriting 
          1            overwriting, blinking 
          2            reversing 
          3            reversing, blinking

0x500 Via Port Byte, 0x501 Via Port Word, 0x502 Via Port Dword

Format:

0x504 Via Port Byte String, 0x505 Via Port Word String, 0x506 Via Port Dword String

Format:

7.4 Open And Close

In or out orders containing the nil object have a special meaning. ,,In nil'' is defined as open, ,,out nil'' as close. ,,Out nil'' is also used as interrogation reply to denote a nonexistent operation.

Open Order (In Nil) 0x0008
The open order signals the driver that the ordering task will start from scratch.

Close Order (Out Nil) 0x0009
The driver is enforced to do the necessary close operations. After closing all orders except open have to be rejected by the driver.

Open Requested (Alternate In Requested Nil) 0x0004
By this reply the driver signals to the ordering process that the device is closed and a new open is necessary. Closing can be done by the ordering task (close order) as well by the driver itself. The latter should happen, if the environment changes, e.g. system switched off, terminal switched off, terminal changed, diskette changed... After closing all orders except open have to be rejected by the driver.

Close Requested (Alternate Out Requested Nil) 0x0005
This operation has to be proposed by the driver, if an order or interrogation is not executable and there is no real executable alternative at all.

7.5 Drivers and Process Linking

Most drivers will obey the Link Protocol (see ???) to prevent against unautorized access. The drivers reactions in this context are defined by the following rules:

  1. The driver starts without a linked partner.

  2. When receiving a link message from the supervisor, usually the driver accepts the process specified by this message as its new 'linked partner'. If the driver wants to reject this partner, it will immediately send an unlink message to the supervisor.

  3. When receiving an unlink message from the supervisor, the driver sets its 'linked partner' to nil process.

  4. If an unlink message or a new link message comes from the supervisor (and will be accepted by the driver) while a reply to a GDP order of the old partner is yet pending, this operation has to be aborted and an 'invalid partner' message has to be sent to the old partner.

  5. Whenever a GDP message comes from a different process than the driver's 'linked partner', the drived will skip the received order and response with an 'invalid partner' message.

Remark: In most cases a new partner will require a new open operation.

On the other side the processes calling the driver (e.g. as sysin or sysout partner) should use the following algorithm: 

    call (partner, gdp order, result, reply) ; 
    WHILE result = prc not existing COR reply = invalid partner REP 
          partner := partner (link no) ; 
          call (partner, gdp order, result, reply) 
    PER

Of course 'partner' should be initialized to 'nilprc'.

Marion Schalm, Jean Wolter, Michael Hohmuth
26.12.1995 (unfinished)