Subversion Repositories planix.SVN

.TH AOE 3

.SH NAME

aoe \- ATA-over-Ethernet (AoE) interface

.SH SYNOPSIS

.nf

.B bind -a #æ /dev

.sp 0.3v

.B /dev/aoe/ctl

.B /dev/aoe/log

.BI /dev/aoe/ shelf . slot /config

.BI /dev/aoe/ shelf . slot /ctl

.BI /dev/aoe/ shelf . slot /devlink/0

\&...

.BI /dev/aoe/ shelf . slot /devlink/ i

.BI /dev/aoe/ shelf . slot /ident

\&...

.fi

.SH 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

.IR sdaoe (3)

for the standard interface.

.SS 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

.B aoeif

configuration variable is set in

.IR plan9.ini (8).

Ethernet interfaces are specified as

.BI ether n\fR,

not as

.BI #l n\fR.

To bind the first and second Ethernet devices on boot, add

.IP

.EX

aoeif=ether0 ether1

.EE

.PP

To bind

.B 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 interface is unbound, targets depending

on that interface are removed.

.PP

Each local interface is called a

.IR netlink .

The mapping of

AoE targets to netlinks is called a

.IR 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.

Several messages can be written to

.B /dev/aoe/ctl

which alter this behavior:

.TP

.BI autodiscover\  toggle

If toggle is absent,

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 on 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.

.br

.ne 4

.PP

Reading

.B /dev/aoe/ctl

returns a list of colon-separated lines

with keywords and their values:

.TF rediscover

.PD

.TP

.BI debug

.PD 0

.TP

.BI autodiscover

.TP

.B 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.

.PD

.TP

.BI if "n path"

Path to

.IR n th

bound Ethernet device.

.TP

.BI if "n ea"

Ethernet address of this device.

.TP

.BI if "n flag"

A flag of ``Up'' indicates that this interface is available.

.TP

.BI if "n lostjumbo"

Number of consecutive lost jumbograms.

.TP

.BI if "n datamtu"

Incorrect and unused.

.SS "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

.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 a target's

.B ctl

file returns a list of colon-separated lines

with the following keywords and values:

.TF firmware

.PD

.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 outstanding frames.

.I Nframes

is greater than

.I 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

.PD 0

.TP

.B serial

.TP

.B firmware

The respective fields from the ATA

.B identify unit

command.

.PD

.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.

.I Maxbcount

should be consulted for this purpose.

.PP

Writing to the

.B ctl

file, the following commands may be issued:

.TF identify

.PD

.TP

.B failio

fail outstanding i/o.

.TP

.B identify

send an ata

.L "identify device"

command to the target.

.TP

.BI maxbno " n"

set the maximum number of block sent per

packet.

.TP

.BI mtu  " n"

set the maximum number of bytes (including

header) sent per packet.

.TP

.B nofail

never fail this target.  This is useful if your

root device is on this target.

.TP

.BI setsize " n"

with no arguments, reset the device size to

the size claimed.  Otherwise, assume the

device is the given size.

.PP

The

.B 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 target, so transfers should be 512 or 1024 bytes long

(or a larger multiple of 512 iff jumbo packets are in use).

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

with keywords and their values:

.TF mintimer

.PD

.TP

.B addr

A space-separated 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 re-sent.  Frames are re-sent

when they have been outstanding twice the RTT average.

.TP

.B flag

``Up'' when the netlink is up.

.TP

.B rttavg

.PD 0

.TP

.B mintimer

Minimum timer and RTT average as per

.IR "Congestion Avoidance and Control" .

.PD

.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 (8),

.\" .IR vblade (8),

.IR sd (3),

.IR sdaoe (3),

.IR aoesrv (8),

.IR snoopy (8)

.br

.BR http://support.coraid.com/documents/AoEr11.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.

.PP

This is a fairly primitive interface;

.IR sdaoe (3)

is usually more suitable.