Mercurial > hg > index.cgi

annotate docs/extension-virtualports.txt @ 16:13be9d3a6927 default tip

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