sys/man/3/aoe

   1 .TH AOE 3
   2 .SH NAME
   3 aoe \- ATA-over-Ethernet (AoE) interface
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -a #æ /dev
   7 .sp 0.3v
   8 .B /dev/aoe/ctl
   9 .B /dev/aoe/log
  10 .BI /dev/aoe/ shelf . slot /config
  11 .BI /dev/aoe/ shelf . slot /ctl
  12 .BI /dev/aoe/ shelf . slot /devlink/0
  13 \&...
  14 .BI /dev/aoe/ shelf . slot /devlink/ i
  15 .BI /dev/aoe/ shelf . slot /ident
  16 \&...
  17 .fi
  18 .SH DESCRIPTION
  19 The AoE (ATA-over-Ethernet) interface serves a three-level
  20 directory providing control and access to AoE targets.
  21 The interface provided is primarily intended for low-level
  22 control of the AoE initiator.  See
  23 .IR sdaoe (3)
  24 for the standard interface.
  25 .SS Top-level files
  26 In order to access AoE targets, one or more Ethernet controllers
  27 need to be bound to the AoE initiator.  By default, the system
  28 starts with no interfaces bound.  For automatic binding of interfaces
  29 on boot, the
  30 .B aoeif
  31 configuration variable is set in
  32 .IR plan9.ini (8).
  33 Ethernet interfaces are specified as
  34 .BI ether n\fR,
  35 not as
  36 .BI #l n\fR.
  37 To bind the first and second Ethernet devices on boot, add
  38 .IP
  39 .EX
  40 aoeif=ether0 ether1
  41 .EE
  42 .PP
  43 To bind
  44 .B ether1
  45 to a running system:
  46 .IP
  47 .EX
  48 % echo bind '#l1/ether1' >/dev/aoe/ctl
  49 .EE
  50 .PP
  51 And to unbind it
  52 .IP
  53 .EX
  54 % echo unbind '#l1/ether1' >/dev/aoe/ctl
  55 .EE
  56 .PP
  57 When an interface is unbound, targets depending
  58 on that interface are removed.
  59 .PP
  60 Each local interface is called a
  61 .IR netlink .
  62 The mapping of
  63 AoE targets to netlinks is called a
  64 .IR devlink .
  65 Each devlink may
  66 see multiple interfaces per target.
  67 For example, if the local
  68 machine has one Ethernet address bound and the target has
  69 two interfaces on the same Ethernet segment, this will result
  70 in one netlink and one devlink with two Ethernet addresses.
  71 AoE frames are sent in round-robin fashion.
  72 Each successive
  73 frame is sent on the next address available on the next available
  74 devlink (local interface).
  75 .PP
  76 Normally the initiator automatically discovers and adds new
  77 device directories on startup.  New devices are not added
  78 except as new interfaces are bound to the initiator.
  79 Several messages can be written to
  80 .B /dev/aoe/ctl
  81 which alter this behavior:
  82 .TP
  83 .BI autodiscover\  toggle
  84 If toggle is absent,
  85 the state of
  86 .B autodiscover
  87 is toggled.  If it is the string
  88 .BR on ,
  89 it is turned on.  Any other string turns
  90 .B autodisover
  91 off.
  92 This option is not useful after Ethernet devices have been bound.
  93 .TP
  94 .BI discover\  shelf.slot
  95 Attempt to find the named target on all bound interfaces.
  96 .TP
  97 .BI remove\  shelf.slot
  98 The converse of
  99 .BR discover :
 100 remove the named target if it exists.
 101 .TP
 102 .BI rediscover\  toggle
 103 Allow or disallow rediscovery.
 104 This allows for automatic discovery of new targets.
 105 Unfortunately, it also allows automatic modification
 106 or loss of existing targets.  This option is considered dangerous.
 107 .br
 108 .ne 4
 109 .PP
 110 Reading
 111 .B /dev/aoe/ctl
 112 returns a list of colon-separated lines
 113 with keywords and their values:
 114 .TF rediscover
 115 .PD
 116 .TP
 117 .BI debug
 118 .PD 0
 119 .TP
 120 .BI autodiscover
 121 .TP
 122 .B rediscover
 123 Returns the current state of the variable named by the keyword.
 124 Writing the variable's
 125 name to the control file toggles the state of that variable.
 126 .PD
 127 .TP
 128 .BI if "n path"
 129 Path to
 130 .IR n th
 131 bound Ethernet device.
 132 .TP
 133 .BI if "n ea"
 134 Ethernet address of this device.
 135 .TP
 136 .BI if "n flag"
 137 A flag of ``Up'' indicates that this interface is available.
 138 .TP
 139 .BI if "n lostjumbo"
 140 Number of consecutive lost jumbograms.
 141 .TP
 142 .BI if "n datamtu"
 143 Incorrect and unused.
 144 .SS Shelf-and-slot subdirectories
 145 Once configured, each AoE target is accessed via files in the directory named
 146 for its shelf and slot.  For example, shelf 42, slot 0 would be
 147 accessed through the path
 148 .LR /dev/aoe/42.0 .
 149 The
 150 .B ident
 151 file contains the read-only, verbatim result of the identify unit ATA command.
 152 The
 153 .B config
 154 file contains the target's AoE configuration string.  Writing to this file
 155 sets the targets configuration string.
 156 .PP
 157 Reading a shelf and slot's
 158 .B ctl
 159 file returns a list of colon-separated lines
 160 with the following keywords and values:
 161 .TF firmware
 162 .PD
 163 .TP
 164 .B state
 165 ``Up'' or ``down''.
 166 .TP
 167 .B nopen
 168 Number of clients using this target.
 169 .TP
 170 .B nout
 171 Number of outstanding AoE frames.
 172 .TP
 173 .B nmaxout
 174 Maximum number of outstanding frames allowed.
 175 .TP
 176 .B nframes
 177 Maximum number of outstanding frames.
 178 .I Nframes
 179 is greater than
 180 .I nmaxout
 181 when the initiator is reducing the number of in-flight
 182 frames due to packet loss.  It is assumed that packet
 183 loss is due to an overwhelmed target and not poor
 184 network conditions.
 185 .TP
 186 .BI maxbcount
 187 Maximum number of data bytes per AoE frame.  Using
 188 standard frames,
 189 .B maxbcount
 190 is 1024 or two sectors.
 191 AoE ATA headers are 36 bytes.
 192 .TP
 193 .B model
 194 .PD 0
 195 .TP
 196 .B serial
 197 .TP
 198 .B firmware
 199 The respective fields from the ATA
 200 .B identify unit
 201 command.
 202 .PD
 203 .TP
 204 .B flag
 205 List of flags useful for debugging.  The flag
 206 .B jumbo
 207 indicates that jumbo frames are accepted, not that
 208 they are being used.
 209 .I Maxbcount
 210 should be consulted for this purpose.
 211 .PP
 212 The
 213 .B data
 214 file may be read or written like a normal file
 215 except that reads and writes to this file are converted to
 216 AoE commands to the target, so transfers should be 512 or 1024 bytes long
 217 (or a larger multiple of 512 iff jumbo packets are in use).
 218 The size of this file is the usable size of the target.
 219 .PP
 220 The
 221 .B devlink
 222 directory contains one file for each interface the target was
 223 discovered on.  The files are numbers from 0 to
 224 .I n
 225 and contain a list of colon-separated lines
 226 with keywords and their values:
 227 .TF mintimer
 228 .PD
 229 .TP
 230 .B addr
 231 A space-separated list of the target's Ethernet addresses visible from
 232 this interface.
 233 .TP
 234 .B npkt
 235 The number of frames sent on this interface.
 236 .TP
 237 .B resent
 238 The number of frames re-sent.  Frames are re-sent
 239 when they have been outstanding twice the RTT average.
 240 .TP
 241 .B flag
 242 ``Up'' when the netlink is up.
 243 .TP
 244 .B rttavg
 245 .PD 0
 246 .TP
 247 .B mintimer
 248 Minimum timer and RTT average as per
 249 .IR "Congestion Avoidance and Control" .
 250 .PD
 251 .TP
 252 .B nl path
 253 Path of the Ethernet device.
 254 .TP
 255 .B nl ea
 256 Ethernet address of the local Ethernet device.
 257 .TP
 258 .B nl flag
 259 ``Up'' if the local interface is up.
 260 .TP
 261 .B nl lostjumbo
 262 Number of consecutive jumbograms lost.
 263 .TP
 264 .B nl datamtu
 265 Unused.
 266 .PP
 267 .SH SOURCE
 268 .B /sys/src/9/port/devaoe.c
 269 .SH SEE ALSO
 270 .\" .IR cec (1),
 271 .\" .IR vblade (1),
 272 .IR sd (3),
 273 .IR sdaoe (3),
 274 .IR vblade (8),
 275 .IR snoopy (8)
 276 .br
 277 .BR http://www.coraid.com/documents/AoEr10.txt
 278 .br
 279 Van Jacobson and Michael J. Karels,
 280 .IR "``Congestion Avoidance and Control''" ,
 281 ACM Computer Communication Review;
 282 Proceedings of the Sigcomm '88 Symposium in Stanford, CA, August, 1988.
 283 .SH BUGS
 284 There is no
 285 .B raw
 286 file for executing arbitrary commands.
 287 .PP
 288 This is a fairly primitive interface;
 289 .IR sdaoe (3)
 290 is usually more suitable.