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 <op>
3-+x	<value>

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.