1
0

aoe 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321
  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 "Target 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 target'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. Writing to the
  213. .B ctl
  214. file, the following commands may be issued:
  215. .TF identify
  216. .PD
  217. .TP
  218. .B failio
  219. fail outstanding i/o.
  220. .TP
  221. .B identify
  222. send an ata
  223. .L "identify device"
  224. command to the target.
  225. .TP
  226. .BI maxbno " n"
  227. set the maximum number of block sent per
  228. packet.
  229. .TP
  230. .BI mtu " n"
  231. set the maximum number of bytes (including
  232. header) sent per packet.
  233. .TP
  234. .B nofail
  235. never fail this target. This is useful if your
  236. root device is on this target.
  237. .TP
  238. .BI setsize " n"
  239. with no arguments, reset the device size to
  240. the size claimed. Otherwise, assume the
  241. device is the given size.
  242. .PP
  243. The
  244. .B data
  245. file may be read or written like a normal file
  246. except that reads and writes to this file are converted to
  247. AoE commands to the target, so transfers should be 512 or 1024 bytes long
  248. (or a larger multiple of 512 iff jumbo packets are in use).
  249. The size of this file is the usable size of the target.
  250. .PP
  251. The
  252. .B devlink
  253. directory contains one file for each interface the target was
  254. discovered on. The files are numbers from 0 to
  255. .I n
  256. and contain a list of colon-separated lines
  257. with keywords and their values:
  258. .TF mintimer
  259. .PD
  260. .TP
  261. .B addr
  262. A space-separated list of the target's Ethernet addresses visible from
  263. this interface.
  264. .TP
  265. .B npkt
  266. The number of frames sent on this interface.
  267. .TP
  268. .B resent
  269. The number of frames re-sent. Frames are re-sent
  270. when they have been outstanding twice the RTT average.
  271. .TP
  272. .B flag
  273. ``Up'' when the netlink is up.
  274. .TP
  275. .B rttavg
  276. .PD 0
  277. .TP
  278. .B mintimer
  279. Minimum timer and RTT average as per
  280. .IR "Congestion Avoidance and Control" .
  281. .PD
  282. .TP
  283. .B nl path
  284. Path of the Ethernet device.
  285. .TP
  286. .B nl ea
  287. Ethernet address of the local Ethernet device.
  288. .TP
  289. .B nl flag
  290. ``Up'' if the local interface is up.
  291. .TP
  292. .B nl lostjumbo
  293. Number of consecutive jumbograms lost.
  294. .TP
  295. .B nl datamtu
  296. Unused.
  297. .PP
  298. .SH SOURCE
  299. .B /sys/src/9/port/devaoe.c
  300. .SH SEE ALSO
  301. .\" .IR cec (8),
  302. .\" .IR vblade (8),
  303. .IR sd (3),
  304. .IR sdaoe (3),
  305. .IR aoesrv (8),
  306. .IR snoopy (8)
  307. .br
  308. .BR http://support.coraid.com/documents/AoEr11.txt
  309. .br
  310. Van Jacobson and Michael J. Karels,
  311. .IR "``Congestion Avoidance and Control''" ,
  312. ACM Computer Communication Review;
  313. Proceedings of the Sigcomm '88 Symposium in Stanford, CA, August, 1988.
  314. .SH BUGS
  315. There is no
  316. .B raw
  317. file for executing arbitrary commands.
  318. .PP
  319. This is a fairly primitive interface;
  320. .IR sdaoe (3)
  321. is usually more suitable.