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