This document describes an extension to the LWWire protocol which provides
virtual serial ports. The protocol comes in two parts. The first is the low
level signalling protocol to transfer data on the ports and the second is
the higher level "modem" protocol.

A low level port is simply an eight bit clean channel that allows traffic to
pass over it bidirectionally. The low level signalling protocol does not
care what that data is.

A port must be opened before it can be used. Once it is opened, it is
connected with some sort of endpoint. That may be a modem simulation or some
other endpoint specification. When communication is finished, the port is
then closed. A port can be closed by either the client or the server.

LWWire Protocol Extension
=========================

This extension is called VPORT and is assigned extension number 00. It
defines the following operations in its extension space:

00 VPORT_OPEN

This request opens a virtual port. It takes the following parameters:

Octet	Meaning
-----	-------
 0-2	F3 00 00
 3	endpoint type

The endpoint type is 0 for a basic virtual modem as defined by this
extension. Any other value is an extension number which may accept VPORT
connections. In particular, the CCHAN extension is of interest here.

Octet	Meaning
-----	-------
0	status
1	port number assigned
F0-FF	reserved for private endpoint types

If the status is 0, it means the open was successful and a port was
successfully allocated. Communication over the port can now begin.

Any other status is a failure and the port number value must be regarded as
invalid. The server MUST send 0 for this port number in this instance. The
status will be usually be one 1 if no ports are available to assign or 2 if
ports are available but the requested endpoint type is not available.


01 VPORT_CLOSE

This call informs the server that the client is finished with the specified
port. The call looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 01
3	port number

The return from this call is exactly one octet, a status. If the status is
zero, the port has been closed successfully. If it is 1, it means the port
was not open in the first place.

When a port is closed, all data currently buffered on the server is cleared.
It may or may not be delivered to its intended destination.


02 VPORT_POLL

This call requests the server to provide information on the specified port.
The call looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 02
03	the port to poll

The return looks as follows:

Octet	Meaning
-----	-------
0	status
1	write max
2	read max

If the status is nonzero, then the port is not open and the write max and
read max items should be ignored.

Otherwise, write max will be set to the maximum number of octets the server
is willing to handle on a write operation and read max will be the number of
bytes the server can provide in response to a read operation. If either
number exceeds 255, then the server will set the respective value to 255. A
value of 0 for the read max means the server has no data to send. A value of
0 for the write max means the server's buffer is full and it is waiting for
the endpoint to do something with it.


03 VPORT_POLLMULTI

This operation is similar to VPORT_POLL except it allows polling multiple
ports simultaneously. It will return 3 bytes for each port polled, organized
as in the VPORT_POLL call. The ports are returned in the same order as
specified in the request.

The request looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 03
3	number of ports to query
4-n	port nubmers to query

This operation can easily have quite a large request size and quite a large
response size (maximum request size is 260 bytes and the maximum response is
768 bytes). This call should only be used for a small number of active
ports.

04 VPORT_READ

This request reads bytes from a virtual port. The request looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 04
3	port number
4	maximum size to read in octets

The response is an LWWire variable length packet as follows:

Octet	Meaning
-----	-------
0	status
1	number of bytes returned (n)
2-n	returned data

If status is nonzero, then the read failed. This will usually be due to a
lack of data (1) OR the port not being open (2). In this case, any
subsequent octets in the packet can be ignored.

Otherwise, the packet will contain n bytes of data. The client must be
certain not to request more bytes than it can handle.


05 VPORT_WRITE

This request is used to send octets to a port. The request looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 05
3	port number
4	number of bytes
5-n	the data to write

The response is as follows:

Octet	Meaning
-----	-------
0	status
1	bytes written

If status is zero, than the bytes written value will be valid. If all bytes
were written, then it will match the number in the request. If this value is
less than the requested number, it means some bytes were not written for
whatever reason and the client must deal with queueing or buffering as
appropriate.


06 VPORT_READFIXED

This request reads bytes from a virtual port. The request looks as follows:

Octet	Meaning
-----	-------
0-2	F3 00 04
3	port number
4	size to read in octets (N)

The response is looks as follows:

Octet	Meaning
-----	-------
0	status
1	number of bytes returned (n)
2-...	returned data

In all cases, there will be exactly N octets in the returned data. Any bytes
not filled by actual data are undefined but should be zero.

If status is nonzero, then the read failed. This will usually be due to a
lack of data (1) OR the port not being open (2). In this case, any
subsequent octets in the packet can be ignored.

If (n) is less than (N), then there will be extra octets in the returned
data section which must be ignored.

This option is provided as an alternative to the VPORT_READ call for systems
which cannot easily handle a variable length packet safely. In particular, a
115k "bitbanger" implementation on the Coco itself might choose to use this
option to adding another 500+ bytes to its lwwire client driver. Ohter
communication channels that do not have this limitation should prefer the
variable length packet option with larger request sizes to minimize
transaction count.