Mercurial > hg > index.cgi

comparison docs/extension-packet.txt @ 7:2e382e1a173e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
children 7231f922b0f2
comparison
equal deleted inserted replaced
6:3a4c972c92ec 7:2e382e1a173e
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