# HG changeset patch # User William Astle # Date 1465669599 21600 # Node ID 2e382e1a173e84176679c8cfd934483a999f376b # Parent 3a4c972c92ec556d048f98e2b33562bd235fa874 Add PACKET extension Added a PACKET extension based on Brett Gordon's initial spec but with a couple of additions. diff -r 3a4c972c92ec -r 2e382e1a173e docs/extension-packet.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/extension-packet.txt Sat Jun 11 12:26:39 2016 -0600 @@ -0,0 +1,202 @@ +This document describes an extension to the LWWire protocol which provides +raw packet data transfer. This extension leaves it up to the protocol server +to decide how it obtains packets from and sends packets to the wider +network. It is expected that this will likely be a virtual network interface +of some kind but that is not strictly required. This extension only +describes the mechanism for passing packets between the server and the +client. Essentially, it is a link layer protocol. + +LWWire Server Operations +======================== + +The server side will maintain a transmit queue. This queue will have some +defined maximum length after which any subsequent packets will be dropped +until space opens in the queue. The length of the queue will be settable by +the client up to some server defined maximum size. The maximum size +supported by the server is left up to the server but it must necessarily be +at least 1 and probably higher to support any significant data transfer. + +The server must drop any packets unless this extension is enabled. If the +extension is disabled after being enabled, any packets in the queue must be +immediately dropped. The queue must also be cleared upon a protocol reset. + + +LWWire Protocol Extension +========================= + +This extension is called PACKET and is assigned extension number 01. It +defines the following operations in its extension space. + +00 PACKET_POLL + +This requests information about the next packet in the server's queue. + +Request: + +Octet Meaning +----- ------- +0-2 F3 01 00 + +Response: + +Octet Meaning +----- ------- +0-1 16 bit length + +If the returned length is zero, then there is no packet queued on the +server. Subsequent PACKET_POLL calls will return the same result until the +packet in the queue is either retrieved or dropped. + + +01 PACKET_RECEIVE + +This receives the first packet in the queue. + +Request: + +Octet Meaning +----- ------- +0-2 F3 01 01 + +Response: + +Octet Meaning +----- ------- +0-n packet data + +This request MUST NOT be issued without first calling PACKET_POLL to +determine the length of the packet. If it is issued when no packet is +waiting, the server MUST trigger an unknown operation error state. + +The client sends no indication that it has received the packet. As soon as +the server has delivered the packet on the wire, it must remove it from the +queue. If it detects an error condition during transmission, it MAY choose +to retain the packet at the head of the queue. + +The client must issue another PACKET_POLL to learn the length of the next +packet in the queue, if there is one. + +02 PACKET_SEND + +This request allows the client to deliver a packet to the server. + +Request: + +Octet Meaning +----- ------- +0-2 F3 01 02 +3-4 16 bit length +5- packet data + +There is no response from the server. The server is free to drop the packet +if it cannot handle it, just as any other packet receiver may do. The client +will receive no indication that this has happened. This is indistinguishable +from any other cause of packets to be dropped. + + +03 PACKET_DROP + +This is a complement to PACKET_RECEIVE. It causes the server to discard the +packet at the head of its transmit queue. + +Request: + +Octet Meaning +----- ------- +0-2 F3 01 03 + +There is no response from the server. If the server has no packets in its +queue, nothing happens. + +A sequence of PACKET_POLL/PACKET_DROP until PACKET_POLL returns an empty +queue indication can be used to clear the server queue. + +This operation allows the client to refuse delivery of a packet that it will +not be able to handle in a timely manner or which it cannot handle at all +due to size. + + +04 PACKET_SETRXMTU +05 PACKET_SETQUEUELEN +06 PACKET_SETTXMTU + +These requests allow for setting parameters for the server queue. + +Request: + +Octet Meaning +----- ------- +0-2 F3 01 +3-+x + +Response: + +Octet Meaning +----- ------- +0-x actual value set + + +"x" is the size of the value. MTU is a 16 bit value. Queue length is an 8 +bit value. + +See the Link Parameters section for more detail on the various parameters +that can be set. + + +Link Parameters +=============== + +Queue length (QUEUELEN) +----------------------- + +This is the maximum length of queue of packets waiting to be delivered to +the client. Setting this too high can lead to overwhelming the client with +packets it cannot handle. A faster client may choose to increase this value +while a slower client may choose to decrease it. The client may choose to +adjust this value based on the work load it currently has, as well. + +The server must respect any request to set the queue length for any value +less than it's maximum capable queue length. The minimum limit for the queue +length is 2, but servers should support a higher queue length if possible. + + +Receive MTU (RXMTU) +------------------- + +This is the maximum packet size the client is willing to accept. While the +client need not set this, it is beneficial to do so. That way, the server +side can drop packets that are too big rather than queuing them. In fact, in +IP (and similar) settings, the sending side can then send a "packet too big" +indicator which may cause remote transmitters to reduce their packet sizes. +In particular, TCP benefits from this. + +By default, the server will send any packets it receives of any size. That +is, the MTU will be assumed to be compatible with any packets it might +receive the network. The client can discover what the server's notion of the +maximum packet size is by querying the RXMTU. It is recommended that the +default RXMTU on the server be no greater than 1500 (ethernet MTU) and no +lower than 576, but these values should be chosen based on the protocols +being transported by the server and client. + + +Transmit MTU (TXMTU) +-------------------- + +This is the maximum packet size the server is willing to relay. This will +default to the same size as the RXMTU setting. However, changing the RXMTU +will not change the TXMTU setting. The client should query this at startup +to find out what packets it shouldn't bother sending so it can pass along +"too big" notifications to its own transmitters. + +If the server receives from the client a packet larger than the TXMTU +setting, it should just drop it. Normally, the client will not set this +value. It can simply use its own notion of MTU to avoid sending packets +larger than it wants to handle and the server can blithely go on with a +larger notion. However, if the client does set the value lower, it can be +useful for the server to discard rogue packet transmissions from the client. + +The restrictions on this value are the same as for the RXMTU value. The +server must not reject any reasonable value smaller than its actual limit +from the client should the client choose to set one. The server need not +accept a value larger than its actual capability, of course. + diff -r 3a4c972c92ec -r 2e382e1a173e docs/protocol.txt --- a/docs/protocol.txt Sat Jun 11 11:13:49 2016 -0600 +++ b/docs/protocol.txt Sat Jun 11 12:26:39 2016 -0600 @@ -419,5 +419,6 @@ range listed below. 00 VPORT +01 PACKET E0-EF reserved for future extension code expansion F0-FF reserved for private extensions and will never be assigned