From owner-svn-doc-all@FreeBSD.ORG Wed Apr 23 17:04:03 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 317A96C6; Wed, 23 Apr 2014 17:04:03 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 1BFCA1E16; Wed, 23 Apr 2014 17:04:03 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3NH42s2040729; Wed, 23 Apr 2014 17:04:02 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3NH42TB040728; Wed, 23 Apr 2014 17:04:02 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404231704.s3NH42TB040728@svn.freebsd.org> From: Dru Lavigne Date: Wed, 23 Apr 2014 17:04:02 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 23 Apr 2014 17:04:03 -0000 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: Many external storage solutions, such as hard drives, - USB thumbdrives, and CD/DVD burners, use the + USB thumbdrives, and CD + and DVD burners, use the Universal Serial Bus (USB). &os; provides - support for these devices. + support for USB 1.x, 2.0, and 3.0 devices. - - Configuration - - The USB mass storage devices driver, - &man.umass.4;, is built into the GENERIC - kernel and provides support for USB storage - devices. For a custom kernel, be sure that the following + + USB 3.0 support is not compatible with + some hardware, including Haswell (Lynx point) chipsets. If + &os; boots with a failed with error 19 + message, disable xHCI/USB3 in the system + BIOS. + + + Support for USB storage devices + is built into the GENERIC + kernel. For a custom kernel, be sure that the following lines are present in the kernel configuration file: - device scbus -device da -device pass -device uhci -device ohci -device ehci -device usb -device umass - - Since the &man.umass.4; driver uses the - SCSI subsystem to access the - USB storage devices, any + 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 + + &os; uses the &man.umass.4; driver which uses the + SCSI subsystem to access + USB storage devices. Since any USB device will be seen as a - SCSI device by the system. Depending on - the USB chipset on the motherboard, - device uhci or - device ohci is used to provide - USB 1.X support. Support for - USB 2.0 controllers is provided by - device ehci. - - - If the USB device is a - CD or DVD burner, - &man.cd.4;, must be added to the kernel via the line: - - device cd - - Since the burner is seen as a SCSI - drive, the driver &man.atapicam.4; should not be used in the - kernel configuration. - - + SCSI device by the system, + if the USB device is a + CD or DVD burner, do + not include + in a custom kernel configuration file. + + The rest of this section demonstrates how to verify that a + USB storage device is recognized by &os; and + how to configure the device so that it can be used. - Testing the Configuration + Device Configuration To test the USB configuration, plug in - the USB device. In the system message - buffer, &man.dmesg.8;, the drive should appear as something - like: - - 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) + the USB device. Use + dmesg to confirm that the drive appears in + the system message buffer. It should look something + like this: + + 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> - The brand, device node (da0), and - other details will differ according to the device. + The brand, device node (da0), speed, + and size will differ according to the device. Since the USB device is seen as a SCSI one, camcontrol can @@ -502,26 +502,36 @@ da0: 126MB (258048 512 byte sectors: 64H attached to the system: &prompt.root; camcontrol devlist -<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0) +<STECH Simple Drive 1.04> at scbus4 target 0 lun 0 (pass3,da0) + + Alternately, usbconfig can be used to + list the device. Refer to &man.usbconfig.8; for more + information about this command. - If the drive comes with a file system, it can be mounted. - Refer to for instructions on + &prompt.root; usbconfig +ugen0.3: <Simple Drive STECH> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA) + + If the device has not been formatted, + refer to for instructions on how to format and create partitions on the - USB drive. + USB drive. If the drive comes with a file + system, it can be mounted by root using the + instructions in . Allowing untrusted users to mount arbitrary media, by enabling vfs.usermount 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. To make the device mountable as a normal user, one solution is to make all users of the device a member of the operator group - using &man.pw.8;. Next, ensure that the operator group is able to + using &man.pw.8;. Next, ensure that operator is able to read and write the device by adding these lines to /etc/devfs.rules: @@ -529,31 +539,37 @@ da0: 126MB (258048 512 byte sectors: 64H add path 'da*' mode 0660 group operator - If SCSI disks are installed in the + If internal SCSI disks are also installed in the system, change the second line as follows: - add path 'da[3-9]*' mode 0660 group operator + add path 'da[3-9]*' mode 0660 group operator This will exclude the first three SCSI disks (da0 to da2)from belonging to the operator group. + class="groupname">operator group. Replace + 3 with the number of internal + SCSI disks. Refer to &man.devfs.rules.5; + for more information about this file. - Next, enable the &man.devfs.rules.5; ruleset in + Next, enable the ruleset in /etc/rc.conf: devfs_system_ruleset="localrules" - Next, instruct the running kernel to allow regular users - to mount file systems. The easiest way is to add the + Then, instruct the system to allow regular users + to mount file systems by adding the following line to /etc/sysctl.conf: vfs.usermount=1 - Since this only takes effect after the next reboot use - &man.sysctl.8; to set this variable now. + Since this only takes effect after the next reboot, use + sysctl to set this variable now: + + &prompt.root; sysctl vfs.usermount=1 +vfs.usermount: 0 -> 1 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< Suppose a USB thumbdrive is plugged in, and a device /dev/da0s1 appears. If the - device is preformatted with a FAT file system, it can be - mounted using: + device is formatted with a FAT file system, the user can + mount it using: &prompt.user; mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/username Before the device can be unplugged, it - must be unmounted first. After device + must be unmounted first: + + &prompt.user; umount /mnt/username + + After device removal, the system message buffer will show messages similar to the following: - 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 - - - - Further Reading - - Beside the Adding - Disks and Mounting and - Unmounting File Systems 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;. + 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