SRVPRO.DOC
SRVPRO.DOC - Network Server Protocol Description
History
-------
This document's change history:
16/12/88 Skeleton created. Luc
17/12/88 Expanded up to S-DRIVE. Luc
31/12/88 Added null S-RESET. Luc
04/01/89 Added null H-RESET, some specs. Luc
05/01/89 Added more specs. Luc
08/01/89 Added roflag to S-DISK. Luc
15/09/89 Added zero length for S-DISK. Luc
29/09/89 Added error to S-DISK. Luc
07/10/89 Completed S-WRITE description. Luc
22/07/92 Little clarifications. Luc
General
-------
The Server Protocol is used between a Host and one or
more Servers. It enables the Servers to function as
remote peripherals of the Host. (At present, only as
disk drives). The protocol is not very symmetric:
the Server passively waits for requests to arrive,
and then sends responses. The Host does all the timing
and controlling work.
Communication takes place over channels, which are just
numbers. Within each channel sequence numbers are used.
The protocol is intended to be guarded against packet
loss and/or finite out-of-order arrival. (This means
that it can take out-of-order arrivel, but in that case
performance may suffer)
A channel is usually dedicated to a single peripheral,
such as a disk/drive, a serial line, and possibly others.
Channels are not pre-assigned, but assigned as needed by
the Server. The Server is the only one allowed to create
channels. If packets arrive on closed channels, either
sends a reset notification (H-RESET or S-RESET), which
causes everything to start over again.
These reset packets are also used to initiate the
communication. The Host periodically attempts to send
an H-RESET. When a Server receives one, it should reply
with an S-RESET, followed by channel on-line packets
(S-DRIVE only for now). These are then either acknowledged
by the Host, or refused with an S-CLOSE packet. At any
time the Host may send an S-CLOSE packet, thereby closing
the channel. If it does so without a reason specified,
the Server should retry to open the channel.
To allow loss of channel open packets, the Host periodically
transmits an H-POLL packet, indicating the state of all
channels. If the Server state of a channel hasn't changed,
and it doesn't match several H-POLL packets, the
Server should take action.
The packets are specified symbolically. All upper case
words indicate constants, which are specified at the end
of this document. Lower case indicates generic fields,
usually of one byte, unless noted otherwise.
All packets have the form
MAGIC check TYPE [chan seq] ...
MAGIC is a magic header byte to recognize this
protocol.
check is a check byte, chose such that the total sum
of the packet is CHECK.
TYPE is the packet type.
chan is the channel number.
seq is the sequence number for this packet.
Resets and polls
----------------
The H-RESET and S-RESET packets are intended to start
the protocol. The rules are chosen such that a Host
or Server restart should trigger one of them.
To initiate the protocol, a Host periodically sends null
H-RESET packets, until it receives a response, which must
be either a S-RESET or an S-DENY. If an S-RESET, it should
be a null one, but this is not checked. Anyway, the Host
should now send a non-null S-RESET, to indicate it's desire
to start a connection. The Server then responds with either
an S-DENY or a non-null S-RESET. If it's a non-null S-RESET,
the connection is established, and the Server is expected to
announce it's services shortly. An S-DENY at any point ends
any connection, and stops the polling. Both a null S-RESET
and a null H-RESET stop the connection. Thus, a connection
is established by a non-null H-RESET, answered by a non-null
S-RESET.
MAGIC check H-RESET host-id
host-id is a nul-terminated string, identifying the
Host.
If the host-id is the empty string, this packet
should reset the Server. It closes the connection.
The Server should respond with a null S-RESET, or
with an S-DENY. A Host will periodically send a null
H-RESET packet until it receives a response, to find
the Server.
If the host-id is not the empty string, this packet
resets the Server, and then attempts to re-establish
a connection. The Server should respond with a non-null
S-RESET or with an S-DENY.
MAGIC check S-DENY server-id-reason
server-id-reason is a nul-terminated string, identifying
the Server and giving the reason it is not available.
Tells the Host that the Server is not available. The
reason string should be in the form "server-id: reason".
A Host should stop trying if it receives this response.
MAGIC check S-RESET server-id
server-id is a nul-terminated string, identifying the
Server, or just a nul (the empty string).
Announces that the Server has been reset. This packet is
typically sent as response to a H-RESET packet, but may
also be sent to clean up the protocol. The latter case
may happen when packets arrive on closed channels, or
if H-POLL mismatches are persistent. It is also sent
as response to all other packets after Server startup.
The act of sending an S-RESET packet resets the Server
completely, with all channels closed. It should mark
all it's devices "open not yet tried", causing them
to send channel open packets one-by-one.
If server-id is the empty string, it means that this
Server is now idle (i.e. has no Host), and the Host
should attempt to reconnect by sending an H-RESET
packet. This is sent by the Server if packets arrive
on closed channels, for example.
MAGIC check H-POLL chan-states
chan-states is a list of (chan,state) pairs, each
stating that the indicated channel has the indicated
state. Channels not mentioned are implicitly understood
to be in the closed state.
The H-POLL packet tells the Server the states of all
channels as the Host sees them. If mismatches persist
long enough (several H-POLL packets after a state
change), the Server should take action, depending
on the channel state.
If an H-POLL packet can not be delivered due to network
errors, the Host will drop the connection.
XXX The exact coding for channel states is not yet
specified, and consequently the list of (chan,state)
pairs must currently always be empty. There is thus
no provision for lost channel status packets.
Channel open/close
------------------
This describes the protocol part that takes care of the
opening and closing of protocol channels. It is expected
that the opening and closing of channels are infrequent
events, typically happening only in the initialisation
phase of the protocol. Therefore, these packets carry no
sequence numbers.
MAGIC check s-open chan ...
s-open is one of several packet types below,
each corresponding to a device type. This describes
only the general channel open rules.
These packets are sent by the Server to open a
channel. It describes the device that is opened
on the channel. When this packet is sent, the channel
is considered half-open. The expected response is either
an h-open or an H-CLOSE packet.
MAGIC check h-open chan ...
h-open is one of several packet types below,
each corresponding to a device type. This describes
only the general channel close rules.
These packets are sent by the Host to acknowledge the
opening of a channel. If received, the half-open
channel enters the full-open mode.
MAGIC S-CLOSE chan reason
reason is a nul-terminated string, indicating the reason
why a channel was closed.
This packet is sent by the Server to indicate that it
has closed a channel. Normally the reason should be
specified. This packet merely exists to allow Servers
to withdraw devices at any time.
MAGIC H-CLOSE chan reason
reason is a nul-terminated string, indicating the reason
why a channel was closed.
This packet tells the Server that a channel has been
closed, and the reason this was done. It may arrive
if the channel is half-open (in response to a h-open
packet), or if the channel is full-open. If the reason
is the empty string, the Server should retry to open the
device, otherwise it should not. H-CLOSE packets with
an empty reason may be sent to recover from channel
errors.
s-open can presently only take on the value S-DRIVE.
h-open can presently only take on the value H-DRIVE.
Drives & disks
--------------
This part describes the protocol to share disk drives.
It consists of two parts. First, a channel is opened
as a drive with an S-DRIVE packet. Then a disk is "inserted"
in the drive with S-DISK packets. If a disk is inserted,
finally, then data transfer packets will flow.
Sequence numbers are used on drive channels to assure that
data will not associate with the wrong disk. These sequence
numbers are maintained solely by the Server. They should
be changed on every S-DISK packet sent by the Server.
Only packets with the current sequence number are accepted.
MAGIC check S-DRIVE chan drive-cap drive-name
drive-cap is a 4-byte drive capability description,
giving the address type, the allowed flags and the
maximum sector size of the drive (this could be the
only sector size supported). drive-name is a nul-
terminated string giving the drive name. Drive names
should be chosen with a Server-dependent prefix, because
they must be unique across the network.
This announces to the Host that the Server has a drive
available with the indicated properties. The Host should
respond with an H-DRIVE or an H-CLOSE. The act of
sending an S-DRIVE half-opens the drive.
MAGIC check H-DRIVE chan drive-cap drive-name
drive-cap and drive-name are as specified above for
S-DRIVE.
Acknowledge from the Host that a drive channel has been
opened. The drive-cap may have been adjusted downward
(allowing less features, or smaller sectors). The drive-
name should not have been changed. The Server should
check these things, and immediately respond S-CLOSE if
they fail. When received, the drive is full-open, and
S-DISK packets may follow over the channel.
MAGIC check S-DISK chan seq sector-spec part data error ro
sector-spec is a 7-byte physical sector specification,
describing a sector's address and it's length. If the
true sector length is not known, zero is used. part is
a sector part offset, and should be zero. data is a
multiple of 128 bytes of data. error is an error code,
zero for no error. ro is a flag that indicates wether
the disk is writable. If zero, a disk is read/write,
otherwise it is read only.
This announces to the Host that the indicated drive
channel now has a new disk, specifying this disk's
so-called T0S1 sector. The T0S1 sector of a disk
specifies it's name and kind, and should reside
on physical track 0, physical sector 1, physical side 0.
This packet resembles an S-READ packet, but it differs
because only this part of the data will be sent. A
Server should not lie about the T0S1 sector: a sub-
sequent H-READ of this sector should return the same
data. As a special case, if the sector-spec is all-zero,
thereby indicating "F=CP/M, T=0, S=0", it means that
this sector does not physically exist. However, this is
allowed only if the drive-cap of this drive specified a
zero address-type (meaning F=CP/M).
The Host could respond with an H-DISK or H-GONE
packet, bearing this sequence number. It need not
respond.
MAGIC check H-DISK chan seq disk-name comment
disk-name is a nul-terminated string, giving the
name of the disk just inserted by the preceding S-DISK.
comment is a nul-terminated comment string, which could
for example be a description of the disk. It may also
be the null string.
The H-DISK packet tells the Server the name of the
disk with the indicated sequence nummer, and it gives
a comment regarding the contents of this disk. This
packet is not needed for the protocol, it purely serves
as a means of notification. Multiple instances of it may
arrive, as long as they have the right sequence number.
Packets with a wrong sequence number are simply
discarded.
MAGIC check H-GONE chan seq reason
reason is a nul-terminated string.
This packet is used by the Host to refuse a disk. If
the reason is the null string, the Server should attempt
to re-insert it using another S-DISK packet. Otherwise,
it should not.
MAGIC check S-GONE chan seq reason
reason is a nul-terminated string.
This packet is used by the Server to tell the Host that
a disk is gone. The reason may be null, and if so, the
disk was simply taken out of the drive (physically).
No further communication regarding this disk is allowed.
MAGIC check H-READ chan seq sector-spec
sector-spec is a 7-byte physical sector specification,
describing a sector's address and it's length.
This packet requests the Server to read the specified
sector and send the results to the Host. When received,
the Server should discard any pending H-READ/H-WRITE
request and start a new one. The Host should start a
timer when sending this packet, and receive a response
before the timer goes off.
MAGIC check S-READ chan seq sector-spec part data error
sector-spec is a 7-byte physical sector specification,
describing a sector's address and it's length. part is
a sector part offset. data is a multiple of 128 bytes
of data. error is an error code, zero for no error.
This packet is sent by the Server in reply to an H-READ
packet. When received, the Host should restart it's
response timer, and see if it has all the data. If so,
another request may be sent. The sector of data may
be sent in parts to obey packet size limits.
MAGIC check H-WRITE chan seq sector-spec part data
sector-spec is a 7-byte physical sector specification,
describing a sector's address and it's length. part is
a sector part offset. data is a multiple of 128 bytes
of data.
This packet requests the Server to write the specified
data to the specified sector. When received, the Server
should discard any pending H-READ request, and check if
an H-WRITE request for the same sector is in progress.
If so, the data is added to the buffer, otherwise a new
H-WRITE request is started. If the data is now complete,
it should be written and an S-WRITE packet should be
returned to the Host. The Host should start a timer
when sending this packet, and receive a response before
the timer goes off.
MAGIC check S-WRITE chan seq sector-spec error
sector-spec is a 7-byte physical sector specification,
describing a sector's address and it's length. error is
an error code, zero for no error.
This packet is sent by the Server in reply to an H-WRITE
packet, to indicate that the write was performed and a
new request can be sent by the Host.
States
------
This section describes the protocol states. At present,
they are not specified here, but implied from the
description above.
Constants
---------
This section specifies the constants used above in
the protocol description.
MAGIC 'S'+80H Magic number heading all protocol
packets.
CHECK 123 Value to which all packets should
sum.
H-RESET 01H
S-DENY 02H
S-RESET 03H
H-POLL 04H
S-CLOSE 10H
H-CLOSE 11H
S-DRIVE 12H
H-DRIVE 13H
S-DISK 20H
H-DISK 21H
S-GONE 22H
H-GONE 23H
H-READ 24H
S-READ 25H
H-WRITE 26H
S-WRITE 27H
DJO LAN implementation
----------------------
On the DJO LAN network, a few additional rules apply.
The assigned substation for Servers is 08H, but Hosts
should not assume this. They should accept any (station,
substation) pair as a Server address.