term% cat index.txt AOE(3) Library Functions Manual AOE(3)
NAME
aoe - ATA-over-Ethernet (AoE) interface
SYNOPSIS
bind -a #æ /dev
/dev/aoe/ctl
/dev/aoe/log
/dev/aoe/shelf.slot/config
/dev/aoe/shelf.slot/ctl
/dev/aoe/shelf.slot/devlink/0
...
/dev/aoe/shelf.slot/devlink/i
/dev/aoe/shelf.slot/ident
...
DESCRIPTION
The AoE (ATA-over-Ethernet) interface serves a three-level directory
providing control and access to AoE targets. The interface provided is
primarily intended for low-level control of the AoE initiator. See
sdaoe(3) for the standard interface.
Top-level files
In order to access AoE targets, one or more Ethernet controllers need
to be bound to the AoE initiator. By default, the system starts with
no interfaces bound. For automatic binding of interfaces on boot, the
aoeif configuration variable is set in plan9.ini(8). Ethernet inter‐
faces are specified as ethern, not as #ln. To bind the first and sec‐
ond Ethernet devices on boot, add
aoeif=ether0 ether1
To bind ether1 to a running system:
% echo bind '#l1/ether1' >/dev/aoe/ctl
And to unbind it
% echo unbind '#l1/ether1' >/dev/aoe/ctl
When an interface is unbound, targets depending on that interface are
removed.
Each local interface is called a netlink. The mapping of AoE targets
to netlinks is called a devlink. Each devlink may see multiple inter‐
faces per target. For example, if the local machine has one Ethernet
address bound and the target has two interfaces on the same Ethernet
segment, this will result in one netlink and one devlink with two Eth‐
ernet addresses. AoE frames are sent in round-robin fashion. Each
successive frame is sent on the next address available on the next
available devlink (local interface).
Normally the initiator automatically discovers and adds new device di‐
rectories on startup. New devices are not added except as new inter‐
faces are bound to the initiator. Several messages can be written to
/dev/aoe/ctl which alter this behavior:
autodiscover toggle
If toggle is absent, the state of autodiscover is toggled. If
it is the string on, it is turned on. Any other string turns
autodisover off. This option is not useful after Ethernet de‐
vices have been bound.
discover shelf.slot
Attempt to find the named target on all bound interfaces.
remove shelf.slot
The converse of discover: remove the named target if it exists.
rediscover toggle
Allow or disallow rediscovery. This allows for automatic dis‐
covery of new targets. Unfortunately, it also allows automatic
modification or loss of existing targets. This option is con‐
sidered dangerous.
Reading /dev/aoe/ctl returns a list of colon-separated lines with key‐
words and their values:
debug
autodiscover
rediscover
Returns the current state of the variable named by the keyword.
Writing the variable's name to the control file toggles the
state of that variable.
ifn path
Path to nth bound Ethernet device.
ifn ea Ethernet address of this device.
ifn flag
A flag of ``Up'' indicates that this interface is available.
ifn lostjumbo
Number of consecutive lost jumbograms.
ifn datamtu
Incorrect and unused.
Target subdirectories
Once configured, each AoE target is accessed via files in the directory
named for its shelf and slot. For example, shelf 42, slot 0 would be
accessed through the path The ident file contains the read-only, verba‐
tim result of the identify unit ATA command. The config file contains
the target's AoE configuration string. Writing to this file sets the
targets configuration string.
Reading a target's ctl file returns a list of colon-separated lines
with the following keywords and values:
state ``Up'' or ``down''.
nopen Number of clients using this target.
nout Number of outstanding AoE frames.
nmaxout
Maximum number of outstanding frames allowed.
nframes
Maximum number of outstanding frames. Nframes is greater than
nmaxout when the initiator is reducing the number of in-flight
frames due to packet loss. It is assumed that packet loss is
due to an overwhelmed target and not poor network conditions.
maxbcount
Maximum number of data bytes per AoE frame. Using standard
frames, maxbcount is 1024 or two sectors. AoE ATA headers are
36 bytes.
model
serial
firmware
The respective fields from the ATA identify unit command.
flag List of flags useful for debugging. The flag jumbo indicates
that jumbo frames are accepted, not that they are being used.
Maxbcount should be consulted for this purpose.
Writing to the ctl file, the following commands may be issued:
failio fail outstanding i/o.
identify
send an ata command to the target.
maxbno n
set the maximum number of block sent per packet.
mtu n set the maximum number of bytes (including header) sent per
packet.
nofail never fail this target. This is useful if your root device is
on this target.
setsize n
with no arguments, reset the device size to the size claimed.
Otherwise, assume the device is the given size.
The data file may be read or written like a normal file except that
reads and writes to this file are converted to AoE commands to the tar‐
get, so transfers should be 512 or 1024 bytes long (or a larger multi‐
ple of 512 iff jumbo packets are in use). The size of this file is the
usable size of the target.
The devlink directory contains one file for each interface the target
was discovered on. The files are numbers from 0 to n and contain a
list of colon-separated lines with keywords and their values:
addr A space-separated list of the target's Ethernet addresses visi‐
ble from this interface.
npkt The number of frames sent on this interface.
resent The number of frames re-sent. Frames are re-sent when they have
been outstanding twice the RTT average.
flag ``Up'' when the netlink is up.
rttavg
mintimer
Minimum timer and RTT average as per Congestion Avoidance and
Control.
nl path
Path of the Ethernet device.
nl ea Ethernet address of the local Ethernet device.
nl flag
``Up'' if the local interface is up.
nl lostjumbo
Number of consecutive jumbograms lost.
nl datamtu
Unused.
SOURCE
/sys/src/9/port/devaoe.c
SEE ALSO
sd(3), sdaoe(3), aoesrv(8), snoopy(8)
http://support.coraid.com/documents/AoEr11.txt
Van Jacobson and Michael J. Karels, ``Congestion Avoidance and Con‐
trol'', ACM Computer Communication Review; Proceedings of the Sigcomm
'88 Symposium in Stanford, CA, August, 1988.
BUGS
There is no raw file for executing arbitrary commands.
This is a fairly primitive interface; sdaoe(3) is usually more suit‐
able.
AOE(3)