Mercurial > hg > index.cgi
annotate docs/extension-virtualports.txt @ 6:3a4c972c92ec
Add non-variable packet READ option
It is clear that variable packets are inconvenient on high speed bitbanger
implementations of the lwwire protocol. This update provides an alternative
to the variable length READ option that does not require the use of variable
length packets.
author | William Astle <lost@l-w.ca> |
---|---|
date | Sat, 11 Jun 2016 11:13:49 -0600 |
parents | bef2801ac83e |
children |
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 |