.TH AOE 3
.SH NAME
aoe \- AoE interface
.SH SYNOPSIS
.nf
.B bind -a #æ /dev

.B /dev/aoe/ctl
.B /dev/aoe/log
.BI /dev/aoe/ n.m /config
.BI /dev/aoe/ n.m /ctl
.BI /dev/aoe/ n.m /devlink/ \fI0\fR
\&...
.BI /dev/aoe/ n.m /devlink/ \fIi\fR
.BI /dev/aoe/ n.m /ident
\&...
.fi
.SH DESCRIPTION
.PP
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
.IR sdaoe (3)
for the standard interface.
.PP
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
.B aoeif
configuration variable is used in
.IR plan9.ini (8).
Ethernet interfaces are specified as
.BI ether n
not as
.BI #l n \fR.\fI
To bind the first and second Ethernet devices on boot, add
.IP
.EX
aoeif=ether0 ether1
.EE
.PP
To bind ether1 to a running system:
.IP
.EX
% echo bind '#l1/ether1' > /dev/aoe/ctl
.EE
.PP
And to unbind it
.IP
.EX
% echo unbind '#l1/ether1' > /dev/aoe/ctl
.EE
.PP
When an interfaces are unbound, targets depending
on that interface are removed.
.PP
Each local interface is called a netlink.  The mapping of
AoE targets to netlinks is called a devlink.  Each devlink may
see multiple interfaces 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 Ethernet 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).
.PP
Normally the initiator automatically discovers and adds new
device directories on startup.  New devices are not added
except as new interfaces are bound to the initiator.  There
are several messages that can be sent to the
.B ctl
file which alter this behavior:
.TP
.BI autodiscover\  toggle
If toggle is
.IR nil ,
the state of
.B autodiscover
is toggled.  If it is the string
.BR on ,
it is turned on.  Any other string turns
.B autodisover
off.  This option is not useful after Ethernet devices have been bound.
.TP
.BI discover\  shelf.slot
Attempt to find the named target all bound interfaces.
.TP
.BI remove\  shelf.slot
The converse of
.BR discover.
Remove the named target if it exists.
.TP
.BI rediscover\  toggle
Allow or disallow rediscovery.  This allows for automatic discovery
of new targets.  Unfortunately, it also allows automatic modification
or loss of existing targets.  This option is considered dangerous.
.PP
Reading the ctl file returns a list of colon-separated lines
.TP
.B debug
.TP
.B autodiscover
.TP
.B rediscover
Returns the current state of the named variable.  Writing the variable's
name to the control file toggles the state of that variable.
.TP
.BI if n\ \fLpath
Path to \fInth\fR bound Ethernet device.
.TP
.BI if n\ \fLea
Ethernet address of this device.
.TP
.BI if n\ \fLflag
``Up'' indicates this interface is available.
.TP
.BI if n\ \fLlostjumbo
Number of consecutive lost jumbograms.
.TP
.BI if n\ \fLdatamtu
Incorrect and unused.
.PP
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
.LR /dev/aoe/42.0 .
The 
.B ident
file contains the read-only, verbatim result of the identify unit ATA command.
The
.B config
file contains the target's AoE configuration string.  Writing to this file
sets the targets configuration string.
.PP
Reading the
.B ctl
file returns a list of colon-separated lines:
.TP
.B state
``Up'' or ``down''.
.TP
.B nopen
Number of clients using this target.
.TP
.B nout
Number of outstanding AoE frames.
.TP
.B nmaxout
Maximum number of outstanding frames allowed.
.TP
.B nframes
Maximum number of outstand frames.
.B Nframes
is greater than
.B 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.
.TP
.BI maxbcount
Maximum number of data bytes per AoE frame.  Using
standard frames,
.B maxbcount
is 1024 or two sectors.  AoE ATA headers are 36 bytes.
.TP
.B model
.TP
.B serial
.TP
.B firmware
The respective fields from the ATA
.B identify unit
command.
.TP
.B flag
List of flags useful for debugging.  The flag
.B jumbo
indicates that jumbo frames are accepted, not that
they are being used.
.B Maxbcount
should be consulted for this purpose.
.PP
The
.B data
file may be read or written like a normal file.  Reads and
writes to this file are sent as AoE commands to the target.
The size of this file is the usable size of the target.
.PP
The
.B devlink
directory contains one file for each interface the target was
discovered on.  The files are numbers from 0 to
.I n
and contain a list of colon-separated lines:
.TP
.B addr
A space-seperated list of the target's Ethernet addresses visible from
this interface.
.TP
.B npkt
The number of frames sent on this interface.
.TP
.B resent
The number of frames resent.  Frames are resent
when they have been outstanding twice the
RTT average.
.TP
.B flag
``Up'' when the netlink is up.
.TP
.B rttavg
.B mintimer
Minimum timer and RTT average as per
.IR "Congestion Avoidance and Control" .
.TP
.B nl path
Path of the Ethernet device.
.TP
.B nl ea
Ethernet address of the local Ethernet device.
.TP
.B nl flag
``Up'' if the local interface is up.
.TP
.B nl lostjumbo
Number of consecutive jumbograms lost.
.TP
.B nl datamtu
Unused.
.PP
.SH SOURCE
.B /sys/src/9/port/devaoe.c
.SH SEE ALSO
.IR cec (1),
.IR snoopy (8),
.IR sd (3),
.IR sdaoe (3),
.IR vblade (1),
.br
.BR http://www.coraid.com/documents/AoEr10.txt ,
.br
Van Jacobson and Michael J. Karels,
.IR "``Congestion Avoidance and Control''" ,
ACM Computer Communication Review;
Proceedings of the Sigcomm '88 Symposium in Stanford, CA, August, 1988.
.SH BUGS
There is no
.B raw
file for executing arbitrary commands.