Mercurial > hg > index.cgi

annotate docs/protocol.txt @ 6:3a4c972c92ec

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add non-variable packet READ option It is clear that variable packets are inconvenient on high speed bitbanger implementations of the lwwire protocol. This update provides an alternative to the variable length READ option that does not require the use of variable length packets.
author William Astle <lost@l-w.ca>
date Sat, 11 Jun 2016 11:13:49 -0600
parents 422f5e8fff85
children 2e382e1a173e
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
bef2801ac83e Initial checkin with reference implementation of core protocol
William Astle <lost@l-w.ca>
parents:
diff changeset
422 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
423 F0-FF reserved for private extensions and will never be assigned