Mercurial > hg > index.cgi

comparison docs/protocol.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 422f5e8fff85
comparison
equal deleted inserted replaced
-1:000000000000 0:bef2801ac83e
1 DRAFT 2014-12-24
2
3 Introduction
4 ============
5
6 The LWWire protocol is based on the Drivewire protocol originally created by
7 Boisy Pitre and later expanded by others including Aaron Wolfe. The
8 original Drivewire protocol was very simple. It has since acquired quite a
9 few bits and bobs that have unfortunate semantics. Further, Over the years,
10 Drivewire has accumulated quite a few features which it is not possible for
11 the client to reliably detect support for. In addition, the protocol seems
12 to be ever expanding and accumulating features of limited utility.
13
14 The goal of LWWire is to provide a stable core protocol that returns to the
15 roots of Drivewire 3. The core protocol will support extension negotiation
16 which allows the client to request specific additional features. This
17 negotiation must occur before the features can be used.
18
19 A secondary goal is for a basic Drivewire client to be able to perform block
20 I/O on virtual drives even if it does not support the advanced negotiation.
21
22 The Protocol
23 ============
24
25 Throughout the protocol discussion, the term client will refer to the device
26 being served, usually a Coco an emulator of some sort. The term server will
27 refer to the software running on a PC or other similar device that answers
28 requests from the client.
29
30 The LWWire protocol is a master-slave protocol with the client serving the
31 role of the master. This seems like a reversal but it is necessary because
32 the client will usually be the device with limited resources which cannot
33 reliably respond to a byte appearing on the communication channel. Thus, all
34 transactions are initiated by the client.
35
36 All values greater than a single octet are represented in network byte
37 order, which is otherwise known as big endian. The protocol is octet based.
38
39 The first octet of any request is an operation code. This operation code
40 completely defines the request. Further data may follow the operation code,
41 depending on the specifc operation. Some operations may require further
42 round trips as well.
43
44 There are two possible types of response from the server. The first is a
45 standard fixed length response which is defined by the particular operation.
46 However, an operation may further define that it returns a variable length
47 packet. Such a packet is prefixed by a 16 bit length followed by the actual
48 data. Where such a packet is described, the header is not included in the
49 description. The variable length return values should be avoided except
50 when there is a true benefit to using them. Such a use might be passing
51 along an IP packet, for instance.
52
53 When a client comes online, it must send a "DWINIT" operation. The
54 driver version/identifier value is not specified by the protocol and must
55 not change the behaviour of the server. The server will then respond with
56 its version number. If that number is anything other 0x80, the client must
57 assume the server is NOT LWWire. If it receives no response, it may continue
58 with the notion that it might be a Drivewire 3 server.
59
60 If the client does receive an indicator that it is talking to LWWire, and it
61 wishes to use anything other than requests in the Base protocol (anyting in
62 the "Base Protocol" section below), it MUST initiate a feature negotiation
63 request and it MUST NOT initiate any usage of the requested feature unless
64 it receives an ACK response from the server.
65
66 If the delay between subsequent bytes in a request is greater 10
67 milliseconds, the server MUST assume the transaction has failed and treat
68 it as an unknown transaction. The client MUST implement a similar timeout
69 to prevent entering into an infinite loop waiting for octets that may never
70 come. The timeout on the client must be no longer than 1000 milliseconds and
71 should be no shorter than 10 milliseconds. These timeouts MUST be applied to
72 ALL octets that are part of the communication stream.
73
74 Notwithstanding the above, some operations may specify a longer timeout
75 which must be respected by that operation.
76
77 If the server receives an unknown request OR it detects a timeout receiving
78 a request, it MUST abort any ongoing request. It MUST then remain silent for
79 at least 1100 milliseconds to force a timeout on the client. The server MAY
80 choose to change it's port speed parameters if it detects that the request
81 may be valid but there is a transmission speed mismatch. This behaviour MUST
82 NOT be relied upon by the client.
83
84
85 Protocol Operations
86 ===================
87
88 Each operation is formatted with a header indicating the operation code in
89 hexadecimal following by it's name. Below that is the specification of the
90 actual request in a table organized by offset within the request. The table
91 may be absent if the request consists of nothing but the operation code.
92 Below that is prose describing the operation.
93
94
95 Base Protocol
96 -------------
97
98 The base protocol is always active. It is basically the old Drivewire 3
99 protocol with no support for wirebug, which turns out to be useful mostly on
100 paper rather than in real circumstances. Operations are listed in numerical
101 order.
102
103 00 NOOP
104
105 This request is a "no-op". The server MUST ignore it and not treat it as an
106 error.
107
108
109 23 TIME
110
111 This request instructs the server to respond with its current date and time.
112 The response looks as follows:
113
114 Octet Meaning
115 ----- -------
116 0 years since 1900
117 1 month (1-12)
118 2 day (1-31)
119 3 hour (0-23)
120 4 minute (0-59)
121 5 second (0-60)
122 6 day of week (0-6, 0 = Sunday)
123
124 This packet roughly corresponds to the return structure for the localtime()
125 function in C. Note that this request is part of the original Drivewire 3
126 specification. However, Drivewire 3 specifies only 0-59 for the seconds
127 value. LWWire allows the value 60 for the seconds value for the rare case
128 where a leap second is in effect. This is unlikely to ever be a problem in
129 real deployments since leap seconds can occur at most four times per year.
130
131
132 46 PRINTFLUSH
133
134 This operation tells the server to flush its print buffer to its defined
135 printer or analogue. If it does not support a printer or analogue, or there
136 is no data to flush, this operation does nothing.
137
138
139 47 GETSTAT
140
141 Octet Meaning
142 ----- -------
143 0 operation code
144 1 drive number
145 2 GetStat or SetStat code
146
147 This operations are specified for compatibility with Drivewire. There is no
148 response defined. It SHOULD be treated the same as NOOP. The server MAY
149 choose to log this request but is not required to.
150
151
152 49 INIT
153
154 This indicates the server MUST switch to Drivewire 3 mode (if it has one)
155 or, if it doesn't, switch to Base Protocol mode by disabling all extensions.
156 It must also clear any statistics counters and state set by any previous
157 operations.
158
159
160 50 PRINT
161
162 Octet Meaning
163 ----- -------
164 0 operation code
165 1 print data octet
166
167 This request tells the server to queue the specified print data octet for
168 output to a printer or some analogue supported by the server. If the server
169 does not support printing, it will simply ignore this request. The server
170 MAY choose to flush the print buffer to its printer or analogue at any time,
171 say because it has not received additional data for some time. The precise
172 mechanism to do this is not specifically defined.
173
174
175 52 READ
176
177 NOTE: this operation should not be used unless a buffered I/O channel of
178 some kind is in use. Because the client must read the first response byte
179 and then decide whether to read 258 further bytes, it is a good idea for the
180 server to introduce a short delay after the result code, say the length of a
181 single octet transmission. It is strongly recommended that the READEX
182 operation be used instead. This operation is supported for compatibility
183 with old Drivewire implementations.
184
185 Octet Meaning
186 0 operation code
187 1 drive number
188 2-4 LSN requested
189
190 This operation requests the server to read a sector from a specified drive.
191 In the event of an error, this operation will return a nonzero error code
192 (see the "Error Codes" section below). In the event of success, the
193 response will look as follows:
194
195 Octet Meaning
196 0 00
197 1-2 16 bit checksum (simple sum)
198 3-258 sector data
199
200 If the checksum of the received data does not match, the client may choose
201 to retry with the REREAD operation. The server may choose to treat REREAD as
202 an alias of READ or it may treat a REREAD without a previous matching READ
203 as an error.
204
205
206 53 SETSTAT
207
208 Octet Meaning
209 ----- -------
210 0 operation code
211 1 drive number
212 2 GetStat or SetStat code
213
214 This operation is specified for compatibility with Drivewire. There is no
215 response defined. It SHOULD be treated the same as NOOP. The server MAY
216 choose to log this request but is not required to.
217
218
219 54 TERM
220
221 This request indicates the client is finished with the protocol. It should
222 be treated the same as INIT (49). It is only specified here for
223 compatibility with the old Drivewire 3 protocol. New client implementations
224 should not use this operation.
225
226
227 57 WRITE
228
229 Octet Meaning
230 ----- -------
231 0 operation code
232 1 drive number
233 2-4 24 bit LSN
234 5-260 sector data
235 261-262 16 bit checksum
236
237 This operation tells the server to write the specified sector data to the
238 specified LSN on the specified drive. Before doing the write, however, the
239 server will verify the checksum (simple sum of sector octets) and if it
240 fails, it will not write the sector and return the appropriate error code.
241 Otherwise, it will attempt the write and return an error code if
242 appropriate. The error codes are listed in the "Error Codes" section below.
243
244 The response to this transaction is a single octet indicating success (00)
245 or failure (error code). On a checksum error, the client may choose to retry
246 with the REWRITE operation. On other errors, retrying does not make sense as
247 the error condition is unlikely to go away.
248
249 The server may choose to treat REWRITE as an alias of WRITE. It may also
250 choose to treat a REWRITE in the absence of a matching WRITE immediately
251 prior as an error. The client is not obligated to use the REWRITE operation
252 ever.
253
254
255 5A DWINIT
256
257 Octet Meaning
258 ----- -------
259 0 5A (opcode)
260 1 driver version
261
262 The driver version above may be a value assigned by the Drivewire
263 maintainer. However, LWWire does not treat any values specially.
264
265 Upon receiving this operation, the server must disable any extensions and
266 enter into Base Protocol mode. It must also clear any statistics counters
267 and state set by any previous operations.
268
269 The server will respond with the following packet:
270
271 Octet Meaning
272 ----- -------
273 0 server identifier
274
275 The server identifier received will be 0x80 if the server supports the
276 LWWire protocol. If it is anything other than 0x80, the client MUST assume
277 that the server is NOT LWWire and take whatever action it deems appropriate,
278 which may include falling back to Drivewire mode.
279
280
281 72 REREAD
282
283 See 52 READ.
284
285
286 77 REWRITE
287
288 See 57 WRITE.
289
290
291 D2 READEX
292
293 Octet Meaning
294 ----- -------
295 0 operation code
296 1 drive number
297 2-4 24 bit LSN
298
299 The READEX operation requests the server to read the logical sector
300 specified by the LSN from the specified drive. The server will respond with
301 256 bytes of data. In the event that an error occured, it will respond with
302 256 NUL bytes. Otherwise, it will respond with the actual sector data.
303
304 The client will calculate a 16 bit checksum which is a simple sum of all
305 bytes received. It will then send that checksum to the server. The server
306 must permit a longer timeout waiting for the checksum than is otherwise
307 expected to give the remote side long enough to actually calculate the
308 checksum. It is recommended that the timeout here be at least 50ms.
309
310 Upon receipt of the checksum, the server will verify that it is correct. If
311 there was an error reading the sector OR the checksum does not match, the
312 server will return one of the error codes in the "Error Codes" section
313 below. Otherwise it will return a NUL byte.
314
315 In the event of a checksum error, the client may retry the read. Other
316 errors are unlikely to go away on a retry so retrying in those cases is not
317 recommended.
318
319 The REREADEX request follows an identical flow. The server MAY choose to
320 treat a REREADEX operation without an immediately preceding READEX operation
321 as an error. It may choose to avoid re-reading the sector data from the
322 backing store on the server if it has already read the same LSN for a
323 previous READEX operation. However, it is also acceptable to simply treat
324 this as an alias for READEX.
325
326
327 F0 REQUESTEXTENSION
328
329 Octet Meaning
330 0 operation code
331 1 extension code (8 bits)
332
333 This request is used to request a specific extension, as specified by the
334 extension code. The server will respond with an ACK response (0x42) or a NAK
335 response (0x55). Any other response must be considered an error and the
336 client MUST re-initialize its driver and perform the DWINIT handshake again.
337 That includes in the case of a timeout.
338
339 A NAK means the server does not support the requested extension OR it is
340 unwilling to make it available for whatever reason.
341
342 An ACK means the server has enabled the requested extension for this
343 particular client.
344
345 See the section "Extension Codes" for a list of extension codes.
346
347
348 F1 DISABLEEXTENSION
349
350 Octet Meaning
351 0 operation code
352 1 extension code
353
354 This request is used to request that the server discontinue usage of a
355 specific extension. The server will respond with an ACK (0x42) if it is
356 able to discontinue the extension. This is the normal response. Some
357 extensions may not be disablable (which will be specified in the extension
358 specification). In this case, the server will respond with a NAK (0x55). In
359 the event of a NAK, the client may choose to continue with the extension
360 enabled. It may also choose to treat that as an error condition and
361 re-initiate the DWINIT handshake which will forcibly disable all extensions.
362
363 Requesting to disable an extension that is not enabled is not considered
364 an error since it doesn't require changing the state of anything. In that
365 case, the ACK response is correct.
366
367 See the section "Extension Codes" for a list of extension codes.
368
369
370 F2 REREADEX
371
372 See D2 READEX.
373
374
375 F3 EXTENSIONOP
376
377 This request indicates that the request is associated with a specific
378 extension. The second octet is the extension number. Everything after that
379 is defined entirely by the specified extension. If the specified extension
380 is not enabled, this request MUST be treated as an unknown request. The
381 server MUST NOT send a response to any request for any extension that is not
382 currently active.
383
384 This mechanism is provided so that extensions can provide their own
385 operations without having to select operation codes from the global pool.
386 Codes can only be assigned in the global pool by the LWWire maintainer.
387 Codes used inside this request structure can be arbitrarily defined by the
388 extension without any coordination.
389
390
391 F8 RESET3
392 FE RESET1
393 FF RESET2
394
395 Either one of these operations should be treated as though the client has
396 gone away or restarted. These MUST be treated exactly like the INIT (49)
397 operation.
398
399
400 Error Codes
401 ===========
402
403 Code Meaning
404 ---- -------
405 00 No error, checksum OK
406 F3 checksum error
407 F4 read error (out of bounds, underlying I/O error)
408 F5 write error
409 F6 not ready (invalid drive, etc)
410
411
412 Extension Codes
413 ===============
414
415 Any code not otherwise listed below is reserved. If you wish to have an
416 official extension code assigned, contact the maintainer of LWWire to
417 request one. If you are working on something that does not need general
418 distribution, or which is only experimental, consider using the private
419 range listed below.
420
421 00 VPORT
422 E0-EF reserved for future extension code expansion
423 F0-FF reserved for private extensions and will never be assigned