.th LHDH VI 4/21/86
.sh NAME
LHDH \- kernel interface to LHDH
.sh DESCRIPTION
The LHDH device is the ARPANET interface used by KSOS.
.s3
The LHDH devices are identified to the kernel by their SEIDs.
The first two components of an LHDH seid are always the same:
the name space field is 'device_nsp' and the unique id 0 field
is 42.
The unique id 1 field corresponds to the unit number of the LHDH.
Thus, if there were two LHDHs on a system, they would have seids
(device_nsp, char(42), 0) and (device_nsp, char(42), 1).
.s3
The device driver for each LHDH device is always in one of three
states: RESET, READY or ERROR.
The LHDH devices start out in the RESET state when KSOS is first
booted.
State transitions can occur in the following cases.
.s3
.lp 25 20
(any) -> RESET	The device driver is put into the RESET state by
the Reset function.
.s3
.lp 25 20
RESET -> READY	If the internal Initialize function is successfully
performed, the driver is put into the READY state.
If the device driver is in the RESET state when a Read or Write
function is performed, Initialize is first called.
Also, Initialize is called as part of a Busback function.
The Initialize function enables both halves of the LHDH device,
sets the HOSTRELAY bit in the receive csr, and waits for
HOSTREADY and IMPREADY.
.s3
.lp 25 20
RESET -> ERROR	If the Initialize function fails, the driver is put
into the ERROR state.
.s3
.lp 25 20
READY -> ERROR	If at the end of a Read or Write operation the
ERROR or MASTERERROR bits are set in the appropriate csr, an
error value is returned and the driver is put into the ERROR state.
No other operations may be performed until the device is Reset.
.i0
.s3
There are seven basic functions of the LHDH driver.
They are implemented with the following system calls:
K_open, K_read_block, K_write_block, K_device_function and K_close.
.s3
.lp 20 15
Open	Before any data may be pass between the LHDH and a process,
that process must open the device.
The K_open system call is used to perform this function.
At the time of the open all relevant security levels are checked
to make sure that the specified access of the LHDH device would
not violate the security model in effect.
Note that opening the device is a higher level function of the
kernel I/O system and has no effect on the device itself or the
device driver.
.s3
.lp 20 15
Reset	The Reset function physically resets the LHDH device and
puts the driver in the internal RESET state.
This function affects both the transmit and receive halves of the
device.
The Reset function is performed by making a K_device_function
system call with the function set to SETTERMMODES2 and the
O_RESET bit set in the low order word of the block number.
The Reset and Busback functions can be performed in the same
system call.
.s3
.lp 20 15
Initialize	This function is not explicitly invoked by the user
process, but is called implicitly by other explicit functions.
Its purpose is to enable both transmit and receive halves of the
LHDH device, set the HOSTRELAY bit and wait for HOSTREADY and IMPREADY
(IMPREADY means IMPNOTREADY is false).
If HOSTREADY and IMPREADY are detected within 10 seconds of HOSTRELAY
being set, the driver is put in the READY state.
Otherwise, it is put in the ERROR state.
.s3
The Initialize function is called when a Read or Write function
is requested and the device driver is in the RESET state.
It is also called when the Busback option is selected.
.s3
.lp 20 15
Busback	This function puts the LHDH device in Busback mode
(i.e., sets the appropriate bit in the csr).
This function is only valid when the device driver is in the
RESET state.
Thus, it is necessary to first perform a Reset function.
Busback mode is selected by making a K_device_function system call
with the function set to SETTERMMODES2 and the O_BUSBACK bit set
in the low order word of the block number.
The normal way of selecting this option is to make a K_device_function
system call with both O_RESET and O_BUSBACK bits set in the block
number.
.s3
.lp 20 15
Read	The Read function is similar to a read from a normal terminal
device.
It is performed by making a K_device_function or K_read_block system
call.
The block number argument is not used.
Asynchronous I/O is supported.
If no data has been received within TIMEOUT seconds, the system call
will return Xtimeout.
The EOM, ERROR and MASTERERROR bits of the csr are set and returned
in the device dependent field of the status.
.s3
.lp 20 15
Write	The Write function is similar to a write to a normal terminal
device.
It is performed by making a K_device_function or K_write_block system
call.
If O_LASTBIT is set in the low order word of the block number
argument, LASTBIT will be set in the csr to indicate the end of
message.
Asynchronous I/O is supported.
If the block has not been transmitted after TIMEOUT seconds,
Xtimeout is returned.
The ERROR and MASTERERROR bits of the csr are set and returned in the device
dependent field of the status.
.s3
.lp 20 15
Close	The Close function is performed by the K_close system call.
It has no effect on the device driver, but prevents further access
by the process to the device.
.i0
.sh DEFINITIONS
Timeout interval in seconds:
.sp
.lp 20 15
TIMEOUT	= 10
.i0
.s3
Option bits which may be set for SETTERMMODES2 and WRITE:
.sp
.lp 20 15
O_RESET	= 0
.lp 20 15
O_BUSBACK	= 1
.lp 20 15
O_LASTBIT	= 2
.i0
.s3
Csr bit positions to be checked, they are returned in status.devDep:
.sp
.lp 20 15
ERROR	= 15
.lp 20 15
EOM	= 13
.lp 20 15
MASTERERROR	= 9
.i0
.sh "SEE ALSO"
K_device_function(II),
K_read(II),
K_write(II),
ioFunction(IIa),
ioStatus(IIa)
