Date: Wed, 23 Apr 2014 17:04:02 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44635 - head/en_US.ISO8859-1/books/handbook/disks Message-ID: <201404231704.s3NH42TB040728@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404231704.s3NH42TB040728>