|
7
|
1 This document describes an extension to the LWWire protocol which provides
|
|
|
2 raw packet data transfer. This extension leaves it up to the protocol server
|
|
|
3 to decide how it obtains packets from and sends packets to the wider
|
|
|
4 network. It is expected that this will likely be a virtual network interface
|
|
|
5 of some kind but that is not strictly required. This extension only
|
|
|
6 describes the mechanism for passing packets between the server and the
|
|
|
7 client. Essentially, it is a link layer protocol.
|
|
|
8
|
|
|
9 LWWire Server Operations
|
|
|
10 ========================
|
|
|
11
|
|
|
12 The server side will maintain a transmit queue. This queue will have some
|
|
|
13 defined maximum length after which any subsequent packets will be dropped
|
|
|
14 until space opens in the queue. The length of the queue will be settable by
|
|
|
15 the client up to some server defined maximum size. The maximum size
|
|
|
16 supported by the server is left up to the server but it must necessarily be
|
|
|
17 at least 1 and probably higher to support any significant data transfer.
|
|
|
18
|
|
|
19 The server must drop any packets unless this extension is enabled. If the
|
|
|
20 extension is disabled after being enabled, any packets in the queue must be
|
|
|
21 immediately dropped. The queue must also be cleared upon a protocol reset.
|
|
|
22
|
|
|
23
|
|
|
24 LWWire Protocol Extension
|
|
|
25 =========================
|
|
|
26
|
|
|
27 This extension is called PACKET and is assigned extension number 01. It
|
|
|
28 defines the following operations in its extension space.
|
|
|
29
|
|
|
30 00 PACKET_POLL
|
|
|
31
|
|
|
32 This requests information about the next packet in the server's queue.
|
|
|
33
|
|
|
34 Request:
|
|
|
35
|
|
|
36 Octet Meaning
|
|
|
37 ----- -------
|
|
|
38 0-2 F3 01 00
|
|
|
39
|
|
|
40 Response:
|
|
|
41
|
|
|
42 Octet Meaning
|
|
|
43 ----- -------
|
|
|
44 0-1 16 bit length
|
|
|
45
|
|
|
46 If the returned length is zero, then there is no packet queued on the
|
|
|
47 server. Subsequent PACKET_POLL calls will return the same result until the
|
|
|
48 packet in the queue is either retrieved or dropped.
|
|
|
49
|
|
|
50
|
|
|
51 01 PACKET_RECEIVE
|
|
|
52
|
|
|
53 This receives the first packet in the queue.
|
|
|
54
|
|
|
55 Request:
|
|
|
56
|
|
|
57 Octet Meaning
|
|
|
58 ----- -------
|
|
|
59 0-2 F3 01 01
|
|
|
60
|
|
|
61 Response:
|
|
|
62
|
|
|
63 Octet Meaning
|
|
|
64 ----- -------
|
|
|
65 0-n packet data
|
|
|
66
|
|
|
67 This request MUST NOT be issued without first calling PACKET_POLL to
|
|
|
68 determine the length of the packet. If it is issued when no packet is
|
|
|
69 waiting, the server MUST trigger an unknown operation error state.
|
|
|
70
|
|
|
71 The client sends no indication that it has received the packet. As soon as
|
|
|
72 the server has delivered the packet on the wire, it must remove it from the
|
|
|
73 queue. If it detects an error condition during transmission, it MAY choose
|
|
|
74 to retain the packet at the head of the queue.
|
|
|
75
|
|
|
76 The client must issue another PACKET_POLL to learn the length of the next
|
|
|
77 packet in the queue, if there is one.
|
|
|
78
|
|
|
79 02 PACKET_SEND
|
|
|
80
|
|
|
81 This request allows the client to deliver a packet to the server.
|
|
|
82
|
|
|
83 Request:
|
|
|
84
|
|
|
85 Octet Meaning
|
|
|
86 ----- -------
|
|
|
87 0-2 F3 01 02
|
|
|
88 3-4 16 bit length
|
|
|
89 5- packet data
|
|
|
90
|
|
|
91 There is no response from the server. The server is free to drop the packet
|
|
|
92 if it cannot handle it, just as any other packet receiver may do. The client
|
|
|
93 will receive no indication that this has happened. This is indistinguishable
|
|
|
94 from any other cause of packets to be dropped.
|
|
|
95
|
|
|
96
|
|
|
97 03 PACKET_DROP
|
|
|
98
|
|
|
99 This is a complement to PACKET_RECEIVE. It causes the server to discard the
|
|
|
100 packet at the head of its transmit queue.
|
|
|
101
|
|
|
102 Request:
|
|
|
103
|
|
|
104 Octet Meaning
|
|
|
105 ----- -------
|
|
|
106 0-2 F3 01 03
|
|
|
107
|
|
|
108 There is no response from the server. If the server has no packets in its
|
|
|
109 queue, nothing happens.
|
|
|
110
|
|
|
111 A sequence of PACKET_POLL/PACKET_DROP until PACKET_POLL returns an empty
|
|
|
112 queue indication can be used to clear the server queue.
|
|
|
113
|
|
|
114 This operation allows the client to refuse delivery of a packet that it will
|
|
|
115 not be able to handle in a timely manner or which it cannot handle at all
|
|
|
116 due to size.
|
|
|
117
|
|
|
118
|
|
|
119 04 PACKET_SETRXMTU
|
|
|
120 05 PACKET_SETQUEUELEN
|
|
|
121 06 PACKET_SETTXMTU
|
|
|
122
|
|
|
123 These requests allow for setting parameters for the server queue.
|
|
|
124
|
|
|
125 Request:
|
|
|
126
|
|
|
127 Octet Meaning
|
|
|
128 ----- -------
|
|
|
129 0-2 F3 01 <op>
|
|
|
130 3-+x <value>
|
|
|
131
|
|
|
132 Response:
|
|
|
133
|
|
|
134 Octet Meaning
|
|
|
135 ----- -------
|
|
|
136 0-x actual value set
|
|
|
137
|
|
|
138
|
|
|
139 "x" is the size of the value. MTU is a 16 bit value. Queue length is an 8
|
|
|
140 bit value.
|
|
|
141
|
|
|
142 See the Link Parameters section for more detail on the various parameters
|
|
|
143 that can be set.
|
|
|
144
|
|
|
145
|
|
|
146 Link Parameters
|
|
|
147 ===============
|
|
|
148
|
|
|
149 Queue length (QUEUELEN)
|
|
|
150 -----------------------
|
|
|
151
|
|
|
152 This is the maximum length of queue of packets waiting to be delivered to
|
|
|
153 the client. Setting this too high can lead to overwhelming the client with
|
|
|
154 packets it cannot handle. A faster client may choose to increase this value
|
|
|
155 while a slower client may choose to decrease it. The client may choose to
|
|
|
156 adjust this value based on the work load it currently has, as well.
|
|
|
157
|
|
|
158 The server must respect any request to set the queue length for any value
|
|
|
159 less than it's maximum capable queue length. The minimum limit for the queue
|
|
|
160 length is 2, but servers should support a higher queue length if possible.
|
|
|
161
|
|
|
162
|
|
|
163 Receive MTU (RXMTU)
|
|
|
164 -------------------
|
|
|
165
|
|
|
166 This is the maximum packet size the client is willing to accept. While the
|
|
|
167 client need not set this, it is beneficial to do so. That way, the server
|
|
|
168 side can drop packets that are too big rather than queuing them. In fact, in
|
|
|
169 IP (and similar) settings, the sending side can then send a "packet too big"
|
|
|
170 indicator which may cause remote transmitters to reduce their packet sizes.
|
|
|
171 In particular, TCP benefits from this.
|
|
|
172
|
|
|
173 By default, the server will send any packets it receives of any size. That
|
|
|
174 is, the MTU will be assumed to be compatible with any packets it might
|
|
|
175 receive the network. The client can discover what the server's notion of the
|
|
|
176 maximum packet size is by querying the RXMTU. It is recommended that the
|
|
|
177 default RXMTU on the server be no greater than 1500 (ethernet MTU) and no
|
|
|
178 lower than 576, but these values should be chosen based on the protocols
|
|
|
179 being transported by the server and client.
|
|
|
180
|
|
|
181
|
|
|
182 Transmit MTU (TXMTU)
|
|
|
183 --------------------
|
|
|
184
|
|
|
185 This is the maximum packet size the server is willing to relay. This will
|
|
|
186 default to the same size as the RXMTU setting. However, changing the RXMTU
|
|
|
187 will not change the TXMTU setting. The client should query this at startup
|
|
|
188 to find out what packets it shouldn't bother sending so it can pass along
|
|
|
189 "too big" notifications to its own transmitters.
|
|
|
190
|
|
|
191 If the server receives from the client a packet larger than the TXMTU
|
|
|
192 setting, it should just drop it. Normally, the client will not set this
|
|
|
193 value. It can simply use its own notion of MTU to avoid sending packets
|
|
|
194 larger than it wants to handle and the server can blithely go on with a
|
|
|
195 larger notion. However, if the client does set the value lower, it can be
|
|
|
196 useful for the server to discard rogue packet transmissions from the client.
|
|
|
197
|
|
|
198 The restrictions on this value are the same as for the RXMTU value. The
|
|
|
199 server must not reject any reasonable value smaller than its actual limit
|
|
|
200 from the client should the client choose to set one. The server need not
|
|
|
201 accept a value larger than its actual capability, of course.
|
|
|
202
|
