Mercurial > hg > index.cgi

comparison docs/extension-virtualports.txt @ 0:bef2801ac83e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial checkin with reference implementation of core protocol Initial checkin. Has the initial version of the protocol documentation along with a reference implementation of the core protocol.
author William Astle <lost@l-w.ca>
date Sun, 08 May 2016 12:56:39 -0600
parents
children 3a4c972c92ec
comparison
equal deleted inserted replaced
-1:000000000000 0:bef2801ac83e
1 This document describes an extension to the LWWire protocol which provides
2 virtual serial ports. The protocol comes in two parts. The first is the low
3 level signalling protocol to transfer data on the ports and the second is
4 the higher level "modem" protocol.
5
6 A low level port is simply an eight bit clean channel that allows traffic to
7 pass over it bidirectionally. The low level signalling protocol does not
8 care what that data is.
9
10 A port must be opened before it can be used. Once it is opened, it is
11 connected with some sort of endpoint. That may be a modem simulation or some
12 other endpoint specification. When communication is finished, the port is
13 then closed. A port can be closed by either the client or the server.
14
15 LWWire Protocol Extension
16 =========================
17
18 This extension is called VPORT and is assigned extension number 00. It
19 defines the following operations in its extension space:
20
21 00 VPORT_OPEN
22
23 This request opens a virtual port. It takes the following parameters:
24
25 Octet Meaning
26 ----- -------
27 0-2 F3 00 00
28 3 endpoint type
29
30 The endpoint type is 0 for a basic virtual modem as defined by this
31 extension. Any other value is an extension number which may accept VPORT
32 connections. In particular, the CCHAN extension is of interest here.
33
34 Octet Meaning
35 ----- -------
36 0 status
37 1 port number assigned
38 F0-FF reserved for private endpoint types
39
40 If the status is 0, it means the open was successful and a port was
41 successfully allocated. Communication over the port can now begin.
42
43 Any other status is a failure and the port number value must be regarded as
44 invalid. The server MUST send 0 for this port number in this instance. The
45 status will be usually be one 1 if no ports are available to assign or 2 if
46 ports are available but the requested endpoint type is not available.
47
48
49 01 VPORT_CLOSE
50
51 This call informs the server that the client is finished with the specified
52 port. The call looks as follows:
53
54 Octet Meaning
55 ----- -------
56 0-2 F3 00 01
57 3 port number
58
59 The return from this call is exactly one octet, a status. If the status is
60 zero, the port has been closed successfully. If it is 1, it means the port
61 was not open in the first place.
62
63 When a port is closed, all data currently buffered on the server is cleared.
64 It may or may not be delivered to its intended destination.
65
66
67 02 VPORT_POLL
68
69 This call requests the server to provide information on the specified port.
70 The call looks as follows:
71
72 Octet Meaning
73 ----- -------
74 0-2 F3 00 02
75 03 the port to poll
76
77 The return looks as follows:
78
79 Octet Meaning
80 ----- -------
81 0 status
82 1 write max
83 2 read max
84
85 If the status is nonzero, then the port is not open and the write max and
86 read max items should be ignored.
87
88 Otherwise, write max will be set to the maximum number of octets the server
89 is willing to handle on a write operation and read max will be the number of
90 bytes the server can provide in response to a read operation. If either
91 number exceeds 255, then the server will set the respective value to 255. A
92 value of 0 for the read max means the server has no data to send. A value of
93 0 for the write max means the server's buffer is full and it is waiting for
94 the endpoint to do something with it.
95
96
97 03 VPORT_POLLMULTI
98
99 This operation is similar to VPORT_POLL except it allows polling multiple
100 ports simultaneously. It will return 3 bytes for each port polled, organized
101 as in the VPORT_POLL call. The ports are returned in the same order as
102 specified in the request.
103
104 The request looks as follows:
105
106 Octet Meaning
107 ----- -------
108 0-2 F3 00 03
109 3 number of ports to query
110 4-n port nubmers to query
111
112 This operation can easily have quite a large request size and quite a large
113 response size (maximum request size is 260 bytes and the maximum response is
114 768 bytes). This call should only be used for a small number of active
115 ports.
116
117 04 VPORT_READ
118
119 This request reads bytes from a virtual port. The request looks as follows:
120
121 Octet Meaning
122 ----- -------
123 0-2 F3 00 04
124 3 port number
125 4 maximum size to read in octets
126
127 The response is an LWWire variable length packet as follows:
128
129 Octet Meaning
130 ----- -------
131 0 status
132 1 number of bytes returned (n)
133 2-n returned data
134
135 If status is nonzero, then the read failed. This will usually be due to a
136 lack of data (1) OR the port not being open (2). In this case, any
137 subsequent octets in the packet can be ignored.
138
139 Otherwise, the packet will contain n bytes of data. The client must be
140 certain not to request more bytes than it can handle.
141
142
143 05 VPORT_WRITE
144
145 This request is used to send octets to a port. The request looks as follows:
146
147 Octet Meaning
148 ----- -------
149 0-2 F3 00 05
150 3 port number
151 4 number of bytes
152 5-n the data to write
153
154 The response is as follows:
155
156 Octet Meaning
157 ----- -------
158 0 status
159 1 bytes written
160
161 If status is zero, than the bytes written value will be valid. If all bytes
162 were written, then it will match the number in the request. If this value is
163 less than the requested number, it means some bytes were not written for
164 whatever reason and the client must deal with queueing or buffering as
165 appropriate.
166
167