[9front] bring sd(3) from 9atom

[9front] bring sd(3) from 9atom

[Stuart Morrow]

The allusion by bootrc to an 'led' file prompted looking into this.
Sd stuff was brought in from 9atom in 2011, but the documentation was not.
What follows is true and factual AFAICS.
The change from short-form AoE path to long-form seems to be personal
preference. I dunno.
References to 9load(8) are no more.

diff bd63aeb60d1c38cd04e2f64c809685814c5607d7 uncommitted
--- a/sys/man/3/sd
+++ b/sys/man/3/sd
@@ -21,16 +21,19 @@
 .IR C  ,
 and by its unit number
 .IR u .
-The controller naming convention for ATA(PI) units starts
-with the first controller being named
+The controller naming convention for legacy IDE units
+names the first controller
 .LR C ,
-the second
-.LR D ,
-etc. up to a maximum of 4 controllers
-.RB ([ C-F ]);
-legacy controllers are always 'C' and 'D'.
-There can be a maximum of 2 units per ATA(PI) controller
+and the second
+.LR D .
+There can be a maximum of 4 IDE controllers and a
+maximum of 2 units per IDE controller
 .RB ([ 01 ]).
+Other ATA controllers start with
+the first controller being named
+.LR E
+There can be a maximum of 16 units per non-legacy ATA controller
+.RB ([ 0-9a-f ]).
 The controller naming convention for SCSI units starts with
 the first controller being named
 .LR 0 ,
@@ -106,7 +109,7 @@
 A line prefixed by
 .B config
 will be returned for appropriate media,
-e.g. for ATA(PI) units the remainder of the line contains
+e.g. for IDE units the remainder of the line contains
 configuration information from the device's
 .I identify
 command (config and capabilities)
@@ -170,10 +173,19 @@
 .PP
 The
 .B raw
-file is used to execute an arbitrary command on the unit at
-a low level.
+file is used to execute an arbitrary SCSI or ATA
+commands on the unit at a low level.  SCSI commands
+are submitted as raw CDBs up to 16 bytes long.
+ATA commands are formatted as ATA8-AST FISes
+prefixed by two bytes \- an ata escape
+.B 0xff
+and a byte specifying the ATA protcol.  All devices
+respond to basic SCSI commands such as
+.B inquiry .
 This is used by programs such as
 .IR scuzz (8)
+and
+.IR atazz (8)
 to manipulate devices that do not fit the simple storage model
 or for maintenance purposes.
 The following steps may be taken to execute a command
@@ -187,7 +199,9 @@
 Read the
 .I raw
 file to retrieve the status of the command,
-returned as a text integer.
+returned as a text integer for SCSI commands.
+ATA commands return the one byte status and
+response FIS.
 .LP
 Reading
 .B /dev/sdctl
@@ -237,18 +251,21 @@
 .B /sys/src/9/port/devsd.c
 .br
 .B /sys/src/9/*/sd*.[hc]
-.SH SEE ALSO
+.SH "SEE ALSO"
+.IR atazz (8),
+.IR sdahci (3),
+.IR sdaoe (3),
 .IR scuzz (8)
 .SH BUGS
 LUNs (logical unit numbers) are not implemented.
-For (S)ATA drives,
+For ATA drives,
 LUNs are not merely ignored but are actively
 prevented from working except for INQUIRY commands.
 .PP
-The 4 controller limit for ATA(PI) is not enforced.
+The 4 controller limit for IDE is not enforced.
 .PP
-No account is taken of some buggy ATA PCI controllers
+No account is taken of some buggy IDE PCI controllers
 such as the CMD640.
 .PP
-ATA(PI) units come up with DMA and multi-sector read/write
+IDE units come up with DMA and multi-sector read/write
 capability disabled.
--- a/sys/man/3/sdahci
+++ b/sys/man/3/sdahci
@@ -5,7 +5,7 @@
 .nf
 .B bind -a #S /dev
 .sp 0.3v
-.BI /dev/sdctl
+.B /dev/sdctl
 .sp 0.3v
 .BI /dev/sd En /ctl
 .BI /dev/sd En /raw
@@ -17,7 +17,7 @@
 .I sdahci
 driver provides access to AHCI devices via the
 .IR sd (3)
-interface.
+interface.  AHCI devices use the ATA command set.
 The AHCI programming interface supports up to 32
 hot-swappable ATAPI or hard disk-like devices per controller.
 The legacy IDE interface provided by
@@ -28,15 +28,14 @@
 onward.
 .PP
 AHCI controllers are detected automatically.
-Currently Intel and AMD controllers are detected.
+Currently ALi, AMD, Intel, JMicron, Marvell, SiS, VIA, and nVidia
controllers are detected.
 Intel controllers need to have AHCI enabled in the BIOS.
-For
-.L ich
+For ICH (I/O Controller Hub)
 parts this typically means enabling
 enhanced mode and AHCI.
 For ESB (Enterprise South Bridge) -based
 parts, only enhanced mode needs to be enabled.
-Intel
+Due to hardware errata, Intel
 .BR ich9 -based
 AHCI does not support hot swapping and
 drives must be connected to the lowest-numbered free port.
@@ -45,16 +44,16 @@
 .BR /dev/sdctl ,
 supports the following control messages for
 .IR sdahci :
-.TF "\fLahci idprint"
+.TF "\fLiahci idprint"
 .TP
-.B ahci debug
+.B iahci debug
 Toggle debug messages.  Default is off.
 .TP
-.B ahci idprint
+.B iahci idprint
 Toggle printing of drive identification messages.  Default is on.
 Prints short messages when a drive is identified or removed.
 .TP
-.B ahci aprint
+.B iahci aprint
 Print verbose ATAPI debugging messages.  Default is off.
 .PD
 .PP
@@ -61,57 +60,18 @@
 The device-level
 .B ctl
 file supports:
-.TF \fLsmartdisable
+.TF \fLmode
 .TP
-.B flushcache
-Send the ATA/ATAPI
-.B FLUSH CACHE
-command
-.RB ( 0xe7
-or
-.BR 0xea ).
-This command may take up to 60 seconds to complete.
-.TP
-.B identify
-Send the ATA/ATAPI
-.B IDENTIFY DEVICE
-command
-.RB ( 0xec ).
-If device information has changed, the new size,
-features and serial will be noted.
-If changed, I/O on existing file
-descriptors will result in the error string
-.LR "media or partition has changed" .
-.TP
 .BI "mode " speed
 Change the connection
 .I speed
 to one of
 .BR auto ,
-.BR satai
+.BR satai ,
+.BR sataii ,
 or
-.BR sataii .
+.BR sataiii .
 .TP
-.B nop
-Send the ATA
-.B NOP
-command
-.RB ( 0 )
-if the device supports it. Per standard, the result is always an error.
-.TP
-.B smart
-Send the ATA/ATAPI
-.B SMART RETURN STATUS
-command
-.RB ( 0xda ).
-This will fail unless SMART is enabled on the drive.
-.TP
-.B smartdisable
-Disable SMART on the drive.  SMART is a persistent property of the drive.
-.TP
-.B smartenable
-Enable SMART on the drive.
-.TP
 .BI "state " state
 Force a transition to the named
 .IR state .
@@ -151,10 +111,11 @@
 .SH SOURCE
 .B /sys/src/9/pc/sdiahci.c
 .SH SEE ALSO
+.IR atazz (8),
 .IR sd (3)
 .br
-.BR http://download.intel.com/technology/serialata/pdf/rev1_2.pdf .
+.BR http://download.intel.com/technology/serialata/pdf/rev1_3.pdf .
 .SH BUGS
-None of enclosure management, LED control and port multipliers are supported.
+Enclosure management, LED control and port multipliers are supported.
 .PP
 ATAPI devices may not be reset when they have outstanding commands.
--- a/sys/man/3/sdaoe
+++ b/sys/man/3/sdaoe
@@ -1,6 +1,6 @@
 .TH SDAOE 3
 .SH NAME
-sdaoe \- ATA-over-Ethernet (AoE) storage device interface
+sdaoe, addaoe \- ATA-over-Ethernet (AoE) storage device interface
 .SH SYNOPSIS
 .nf
 .B bind -a #S /dev
@@ -59,7 +59,13 @@
 echo config switch off spec e >/dev/sdctl
 .EE
 .PP
-To boot using target
+To boot from an AoE root, the
+.B sd
+device must be configured on boot.  To accomplish this,
+one must either PXE boot or boot from direct-attached
+storage and add two configuration lines to
+.IR plan9.ini (8).
+For example, to boot using target
 .B 42.0
 as
 .B #S/sde0
@@ -68,16 +74,15 @@
 .IP
 .EX
 aoeif=ether0 ether1
-aoedev=e!42.0
+aoedev=e!#æ/aoe/42.0
 .EE
 .SH SOURCE
 .B /sys/src/9/port/sdaoe.c
 .SH SEE ALSO
-.\" .IR vblade (1),
 .IR aoe (3),
 .IR sd (3),
-.\" .IR cec (8),
-.IR snoopy (8)
+.IR snoopy (8),
+.IR vblade (8)
 .SH BUGS
 It is not currently possible to boot from an AoE target without an
 external bootstrap like PXE.
--- a/sys/man/3/sdloop
+++ b/sys/man/3/sdloop
@@ -4,7 +4,7 @@
 .SH SYNOPSIS
 .nf
 .B bind -a #S /dev
-.BI "echo config switch on spec " l " type
loop/\fIpath\fP[!\fIsectsize\fP] >/dev/sdctl"
+.BI "echo config switch on spec " l " type
loop/\fIpath\fP[[!\fIsectors\fP]!\fIsectsize\fP] >/dev/sdctl"

 .BI /dev/sd l 0/ctl
 .BI /dev/sd l 0/raw
@@ -13,7 +13,8 @@
 .fi
 .SH DESCRIPTION
 .I Sdloop
-allows a file to be used as a sd device.
+allows a file to be used as a sd device.  By specifying a number
+of sectors, the device may be be a different size than the file.
 To configure
 .B /tmp/data
 as
@@ -45,7 +46,6 @@
 .B /sys/src/9/port/sdloop.c
 .SH SEE ALSO
 .IR sd (3),
-.IR sdaoe (3),
-.IR partfs (8)
+.IR sdaoe (3)
 .SH BUGS
 Maybe.