view docs/extension-packet.txt @ 9:a11b330771e0

Fix buffer pointer handling when logging received bytes Actually save the read buffer pointer so we can log the actual protocol bytes read in all cases correctly instead of displaying out of bounds memory in the case where the packet arrives in multiple pieces.
author William Astle <>
date Sat, 30 Jul 2016 10:35:14 -0600
parents 2e382e1a173e
children 7231f922b0f2
line wrap: on
line source
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.


This requests information about the next packet in the server's queue.


Octet	Meaning
-----	-------
0-2	F3 01 00


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.


This receives the first packet in the queue.


Octet	Meaning
-----	-------
0-2	F3 01 01


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.


This request allows the client to deliver a packet to the server.


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.


This is a complement to PACKET_RECEIVE. It causes the server to discard the
packet at the head of its transmit queue.


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.


These requests allow for setting parameters for the server queue.


Octet	Meaning
-----	-------
0-2	F3 01 <op>
3-+x	<value>


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.