--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/extension-virtualports.txt	Sun May 08 12:56:39 2016 -0600
@@ -0,0 +1,167 @@
+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.
+
+