annotate docs/protocol.txt @ 7:2e382e1a173e

Add PACKET extension Added a PACKET extension based on Brett Gordon's initial spec but with a couple of additions.
author William Astle <lost@l-w.ca>
date Sat, 11 Jun 2016 12:26:39 -0600
parents 422f5e8fff85
children cf915ece9e48
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
1 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 6 day of week (0-6, 0 = Sunday)
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
123
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
124 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
125 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
126 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
127 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
128 where a leap second is in effect. This is unlikely to ever be a problem in
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
129 real deployments since leap seconds can occur at most four times per year.
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
132 46 PRINTFLUSH
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
133
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
134 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
135 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
136 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
137
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 47 GETSTAT
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
140
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
141 Octet Meaning
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 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
144 1 drive number
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
145 2 GetStat or SetStat code
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 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
148 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
149 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
150
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 49 INIT
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 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
155 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
156 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
157 operations.
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
160 50 PRINT
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
161
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
162 Octet Meaning
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 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
165 1 print data octet
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 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
168 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
169 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
170 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
171 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
172 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
173
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
174
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
175 52 READ
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
176
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
177 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
178 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
179 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
180 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
181 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
182 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
183 with old Drivewire implementations.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
184
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
185 Octet Meaning
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
186 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
187 1 drive number
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
188 2-4 LSN requested
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 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
191 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
192 (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
193 response will look as follows:
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 Octet Meaning
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
196 0 00
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
197 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
198 3-258 sector data
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 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
201 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
202 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
203 as an error.
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
206 53 SETSTAT
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
207
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
208 Octet Meaning
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 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
211 1 drive number
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
212 2 GetStat or SetStat code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
213
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
214 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
215 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
216 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
217
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 54 TERM
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
220
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
221 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
222 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
223 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
224 should not use this operation.
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
227 57 WRITE
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
228
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
229 Octet Meaning
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 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
232 1 drive number
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
233 2-4 24 bit LSN
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
234 5-260 sector data
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
235 261-262 16 bit checksum
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
236
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
237 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
238 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
239 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
240 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
241 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
242 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
243
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
244 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
245 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
246 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
247 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
248
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
249 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
250 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
251 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
252 ever.
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
255 5A DWINIT
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
256
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
257 Octet Meaning
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 0 5A (opcode)
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
260 1 driver version
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 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
263 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
264
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
265 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
266 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
267 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
268
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
269 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
270
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
271 Octet Meaning
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
272 ----- -------
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
273 0 server identifier
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
274
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
275 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
276 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
277 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
278 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
279
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
280
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
281 72 REREAD
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
282
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
283 See 52 READ.
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 77 REWRITE
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 57 WRITE.
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 D2 READEX
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 Octet Meaning
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 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
296 1 drive number
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
297 2-4 24 bit LSN
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
298
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
299 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
300 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
301 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
302 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
303
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
304 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
305 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
306 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
307 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
308 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
309
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
310 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
311 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
312 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
313 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
314
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
315 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
316 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
317 recommended.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
318
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
319 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
320 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
321 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
322 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
323 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
324 this as an alias for READEX.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
325
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
326
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
327 F0 REQUESTEXTENSION
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
328
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
329 Octet Meaning
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
330 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
331 1 extension code (8 bits)
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
332
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
333 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
334 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
335 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
336 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
337 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
338
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
339 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
340 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
341
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
342 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
343 particular client.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
344
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
345 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
346
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
347
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
348 F1 DISABLEEXTENSION
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 Octet Meaning
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
351 0 operation code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
352 1 extension code
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
353
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
354 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
355 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
356 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
357 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
358 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
359 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
360 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
361 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
362
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
363 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
364 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
365 case, the ACK response is correct.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
366
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
367 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
368
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
369
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
370 F2 REREADEX
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 D2 READEX.
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 F3 EXTENSIONOP
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 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
378 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
379 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
380 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
381 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
382 currently active.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
383
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
384 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
385 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
386 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
387 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
388 extension without any coordination.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
389
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
390
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
391 F8 RESET3
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
392 FE RESET1
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
393 FF RESET2
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 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
396 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
397 operation.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
398
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 Error Codes
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
401 ===========
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
402
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
403 Code Meaning
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 00 No error, checksum OK
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
406 F3 checksum error
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
407 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
408 F5 write error
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
409 F6 not ready (invalid drive, etc)
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
410
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
411
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
412 Extension Codes
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
413 ===============
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
414
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
415 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
416 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
417 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
418 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
419 range listed below.
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
420
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
421 00 VPORT
7
2e382e1a173e Add PACKET extension
William Astle <lost@l-w.ca>
parents: 5
diff changeset
422 01 PACKET
0
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
423 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
424 F0-FF reserved for private extensions and will never be assigned