svn commit: r44635 - head/en_US.ISO8859-1/books/handbook/disks
Dru Lavigne
dru at FreeBSD.org
Wed Apr 23 17:04:03 UTC 2014
Author: dru
Date: Wed Apr 23 17:04:02 2014
New Revision: 44635
URL: http://svnweb.freebsd.org/changeset/doc/44635
Log:
Editorial review of USB Storage Devices chapter.
Update examples.
Add note for xhci.
Incorporate resources into context.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Wed Apr 23 15:28:20 2014 (r44634)
+++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Wed Apr 23 17:04:02 2014 (r44635)
@@ -431,70 +431,70 @@ super-block backups (for fsck -b #) at:
</indexterm>
<para>Many external storage solutions, such as hard drives,
- <acronym>USB</acronym> thumbdrives, and CD/DVD burners, use the
+ <acronym>USB</acronym> thumbdrives, and <acronym>CD</acronym>
+ and <acronym>DVD</acronym> burners, use the
Universal Serial Bus (<acronym>USB</acronym>). &os; provides
- support for these devices.</para>
+ support for <acronym>USB</acronym> 1.x, 2.0, and 3.0 devices.</para>
- <sect2>
- <title>Configuration</title>
-
- <para>The <acronym>USB</acronym> mass storage devices driver,
- &man.umass.4;, is built into the <filename>GENERIC</filename>
- kernel and provides support for <acronym>USB</acronym> storage
- devices. For a custom kernel, be sure that the following
+ <note>
+ <para><acronym>USB</acronym> 3.0 support is not compatible with
+ some hardware, including Haswell (Lynx point) chipsets. If
+ &os; boots with a <errorname>failed with error 19</errorname>
+ message, disable xHCI/USB3 in the system
+ <acronym>BIOS</acronym>.</para>
+ </note>
+
+ <para>Support for <acronym>USB</acronym> storage devices
+ is built into the <filename>GENERIC</filename>
+ kernel. For a custom kernel, be sure that the following
lines are present in the kernel configuration file:</para>
- <programlisting>device scbus
-device da
-device pass
-device uhci
-device ohci
-device ehci
-device usb
-device umass</programlisting>
-
- <para>Since the &man.umass.4; driver uses the
- <acronym>SCSI</acronym> subsystem to access the
- <acronym>USB</acronym> storage devices, any
+ <programlisting>device scbus # SCSI bus (required for ATA/SCSI)
+device da # Direct Access (disks)
+device pass # Passthrough device (direct ATA/SCSI access)
+device uhci # provides USB 1.x support
+device ohci # provides USB 1.x support
+device ehci # provides USB 2.0 support
+device xhci # provides USB 3.0 support
+device usb # USB Bus (required)
+device umass # Disks/Mass storage - Requires scbus and da
+device cd # needed for CD and DVD burners</programlisting>
+
+ <para>&os; uses the &man.umass.4; driver which uses the
+ <acronym>SCSI</acronym> subsystem to access
+ <acronym>USB</acronym> storage devices. Since any
<acronym>USB</acronym> device will be seen as a
- <acronym>SCSI</acronym> device by the system. Depending on
- the <acronym>USB</acronym> chipset on the motherboard,
- <literal>device uhci</literal> or
- <literal>device ohci</literal> is used to provide
- <acronym>USB</acronym> 1.X support. Support for
- <acronym>USB</acronym> 2.0 controllers is provided by
- <literal>device ehci</literal>.</para>
-
- <note>
- <para>If the <acronym>USB</acronym> device is a
- <acronym>CD</acronym> or <acronym>DVD</acronym> burner,
- &man.cd.4;, must be added to the kernel via the line:</para>
-
- <programlisting>device cd</programlisting>
-
- <para>Since the burner is seen as a <acronym>SCSI</acronym>
- drive, the driver &man.atapicam.4; should not be used in the
- kernel configuration.</para>
- </note>
- </sect2>
+ <acronym>SCSI</acronym> device by the system,
+ if the <acronym>USB</acronym> device is a
+ <acronym>CD</acronym> or <acronym>DVD</acronym> burner, do
+ <emphasis>not</emphasis> include <option>device atapicam</option>
+ in a custom kernel configuration file.</para>
+
+ <para>The rest of this section demonstrates how to verify that a
+ <acronym>USB</acronym> storage device is recognized by &os; and
+ how to configure the device so that it can be used.</para>
<sect2>
- <title>Testing the Configuration</title>
+ <title>Device Configuration</title>
<para>To test the <acronym>USB</acronym> configuration, plug in
- the <acronym>USB</acronym> device. In the system message
- buffer, &man.dmesg.8;, the drive should appear as something
- like:</para>
-
- <screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2
-GEOM: create disk da0 dp=0xc2d74850
-da0 at umass-sim0 bus 0 target 0 lun 0
-da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device
-da0: 1.000MB/s transfers
-da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>
+ the <acronym>USB</acronym> device. Use
+ <command>dmesg</command> to confirm that the drive appears in
+ the system message buffer. It should look something
+ like this:</para>
+
+ <screen>umass0: <STECH Simple Drive, class 0/0, rev 2.00/1.04, addr 3> on usbus0
+umass0: SCSI over Bulk-Only; quirks = 0x0100
+umass0:4:0:-1: Attached to scbus4
+da0 at umass-sim0 bus 0 scbus4 target 0 lun 0
+da0: <STECH Simple Drive 1.04> Fixed Direct Access SCSI-4 device
+da0: Serial Number WD-WXE508CAN263
+da0: 40.000MB/s transfers
+da0: 152627MB (312581808 512 byte sectors: 255H 63S/T 19457C)
+da0: quirks=0x2<NO_6_BYTE></screen>
- <para>The brand, device node (<filename>da0</filename>), and
- other details will differ according to the device.</para>
+ <para>The brand, device node (<filename>da0</filename>), speed,
+ and size will differ according to the device.</para>
<para>Since the <acronym>USB</acronym> device is seen as a
<acronym>SCSI</acronym> one, <command>camcontrol</command> can
@@ -502,26 +502,36 @@ da0: 126MB (258048 512 byte sectors: 64H
attached to the system:</para>
<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
-<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0)</screen>
+<STECH Simple Drive 1.04> at scbus4 target 0 lun 0 (pass3,da0)</screen>
+
+ <para>Alternately, <command>usbconfig</command> can be used to
+ list the device. Refer to &man.usbconfig.8; for more
+ information about this command.</para>
- <para>If the drive comes with a file system, it can be mounted.
- Refer to <xref linkend="disks-adding"/> for instructions on
+ <screen>&prompt.root; <userinput>usbconfig</userinput>
+ugen0.3: <Simple Drive STECH> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)</screen>
+
+ <para>If the device has not been formatted,
+ refer to <xref linkend="disks-adding"/> for instructions on
how to format and create partitions on the
- <acronym>USB</acronym> drive.</para>
+ <acronym>USB</acronym> drive. If the drive comes with a file
+ system, it can be mounted by <systemitem
+ class="username">root</systemitem> using the
+ instructions in <xref linkend="mount-unmount"/>.</para>
<warning>
<para>Allowing untrusted users to mount arbitrary media, by
enabling <varname>vfs.usermount</varname> as
described below, should not be considered safe from a
- security point of view. Most file systems in &os; were not
+ security point of view. Most file systems were not
built to safeguard against malicious devices.</para>
</warning>
<para>To make the device mountable as a normal user, one
solution is to make all users of the device a member of the
<systemitem class="groupname">operator</systemitem> group
- using &man.pw.8;. Next, ensure that the <systemitem
- class="groupname">operator</systemitem> group is able to
+ using &man.pw.8;. Next, ensure that <systemitem
+ class="groupname">operator</systemitem> is able to
read and write the device by adding these lines to
<filename>/etc/devfs.rules</filename>:</para>
@@ -529,31 +539,37 @@ da0: 126MB (258048 512 byte sectors: 64H
add path 'da*' mode 0660 group operator</programlisting>
<note>
- <para>If <acronym>SCSI</acronym> disks are installed in the
+ <para>If internal <acronym>SCSI</acronym> disks are also installed in the
system, change the second line as follows:</para>
- <programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting>
+ <programlisting>add path 'da[<replaceable>3</replaceable>-9]*' mode 0660 group operator</programlisting>
<para>This will exclude the first three
<acronym>SCSI</acronym> disks (<filename>da0</filename> to
<filename>da2</filename>)from belonging to the <systemitem
- class="groupname">operator</systemitem> group.</para>
+ class="groupname">operator</systemitem> group. Replace
+ <replaceable>3</replaceable> with the number of internal
+ <acronym>SCSI</acronym> disks. Refer to &man.devfs.rules.5;
+ for more information about this file.</para>
</note>
- <para>Next, enable the &man.devfs.rules.5; ruleset in
+ <para>Next, enable the ruleset in
<filename>/etc/rc.conf</filename>:</para>
<programlisting>devfs_system_ruleset="localrules"</programlisting>
- <para>Next, instruct the running kernel to allow regular users
- to mount file systems. The easiest way is to add the
+ <para>Then, instruct the system to allow regular users
+ to mount file systems by adding the
following line to
<filename>/etc/sysctl.conf</filename>:</para>
<programlisting>vfs.usermount=1</programlisting>
- <para>Since this only takes effect after the next reboot use
- &man.sysctl.8; to set this variable now.</para>
+ <para>Since this only takes effect after the next reboot, use
+ <command>sysctl</command> to set this variable now:</para>
+
+ <screen>&prompt.root; <userinput>sysctl vfs.usermount=1</userinput>
+vfs.usermount: 0 -> 1</screen>
<para>The final step is to create a directory where the file
system is to be mounted. This directory needs to be owned by
@@ -571,32 +587,24 @@ add path 'da*' mode 0660 group operator<
<para>Suppose a <acronym>USB</acronym> thumbdrive is plugged in,
and a device <filename>/dev/da0s1</filename> appears. If the
- device is preformatted with a FAT file system, it can be
- mounted using:</para>
+ device is formatted with a <acronym>FAT</acronym> file system, the user can
+ mount it using:</para>
<screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/<replaceable>username</replaceable></userinput></screen>
<para>Before the device can be unplugged, it
- <emphasis>must</emphasis> be unmounted first. After device
+ <emphasis>must</emphasis> be unmounted first:</para>
+
+ <screen>&prompt.user; <userinput>umount /mnt/<replaceable>username</replaceable></userinput></screen>
+
+ <para>After device
removal, the system message buffer will show messages similar
to the following:</para>
- <screen>umass0: at uhub0 port 1 (addr 2) disconnected
-(da0:umass-sim0:0:0:0): lost device
-(da0:umass-sim0:0:0:0): removing device entry
-GEOM: destroy disk da0 dp=0xc2d74850
-umass0: detached</screen>
- </sect2>
-
- <sect2>
- <title>Further Reading</title>
-
- <para>Beside the <link linkend="disks-adding">Adding
- Disks</link> and <link linkend="mount-unmount">Mounting and
- Unmounting File Systems</link> sections, reading various
- manual pages may also be useful: &man.umass.4;,
- &man.camcontrol.8;, and &man.usbconfig.8; under &os; 8.X
- or &man.usbdevs.8; under earlier versions of &os;.</para>
+ <screen>umass0: at uhub3, port 2, addr 3 (disconnected)
+da0 at umass-sim0 bus 0 scbus4 target 0 lun 0
+da0: <STECH Simple Drive 1.04> s/n WD-WXE508CAN263 detached
+(da0:umass-sim0:0:0:0): Periph destroyed</screen>
</sect2>
</sect1>
More information about the svn-doc-all
mailing list