Date: Tue, 29 May 2018 17:07:50 +0000 (UTC) From: Edward Tomasz Napierala <trasz@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r51744 - in head/en_US.ISO8859-1/books/handbook: . disks usb-device-mode Message-ID: <201805291707.w4TH7oLR043174@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: trasz (src,ports committer) Date: Tue May 29 17:07:50 2018 New Revision: 51744 URL: https://svnweb.freebsd.org/changeset/doc/51744 Log: Introduce a new chapter on USB Device Mode / USB OTG. Reviewed by: bcr@ Approved by: bcr@ MFC after: 2 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D15513 Added: head/en_US.ISO8859-1/books/handbook/usb-device-mode/ head/en_US.ISO8859-1/books/handbook/usb-device-mode/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/handbook/Makefile head/en_US.ISO8859-1/books/handbook/book.xml head/en_US.ISO8859-1/books/handbook/chapters.ent head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/handbook/Makefile Tue May 29 12:03:28 2018 (r51743) +++ head/en_US.ISO8859-1/books/handbook/Makefile Tue May 29 17:07:50 2018 (r51744) @@ -200,6 +200,7 @@ SRCS+= preface/preface.xml SRCS+= printing/chapter.xml SRCS+= security/chapter.xml SRCS+= serialcomms/chapter.xml +SRCS+= usb-device-mode/chapter.xml SRCS+= virtualization/chapter.xml SRCS+= x11/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/book.xml Tue May 29 12:03:28 2018 (r51743) +++ head/en_US.ISO8859-1/books/handbook/book.xml Tue May 29 17:07:50 2018 (r51744) @@ -253,6 +253,7 @@ &chap.l10n; &chap.cutting-edge; &chap.dtrace; + &chap.usb-device-mode; </part> <part xml:id="network-communication"> Modified: head/en_US.ISO8859-1/books/handbook/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/handbook/chapters.ent Tue May 29 12:03:28 2018 (r51743) +++ head/en_US.ISO8859-1/books/handbook/chapters.ent Tue May 29 17:07:50 2018 (r51744) @@ -42,6 +42,7 @@ <!ENTITY chap.l10n SYSTEM "l10n/chapter.xml"> <!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.xml"> <!ENTITY chap.dtrace SYSTEM "dtrace/chapter.xml"> + <!ENTITY chap.usb-device-mode SYSTEM "usb-device-mode/chapter.xml"> <!-- Part Four --> <!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.xml"> Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue May 29 12:03:28 2018 (r51743) +++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue May 29 17:07:50 2018 (r51744) @@ -588,133 +588,6 @@ da0: <STECH Simple Drive 1.04> s/n WD-WXE508CAN2 any block device, including optical drives or <acronym>iSCSI</acronym> <acronym>LUN</acronym>s.</para> </sect2> - - <sect2> - <title><acronym>USB</acronym> Mass Storage Target</title> - - <note> - <para>The &man.cfumass.4; driver is a <acronym>USB</acronym> - device mode driver first available in &os; 12.0.</para> - </note> - - <para>When running on <acronym>USB</acronym> - <acronym>OTG</acronym>-compliant hardware like that built into - many embedded boards, the &os; <acronym>USB</acronym> stack - can run in <emphasis>device mode</emphasis>. Device mode - makes it possible for the computer to present itself as - different kinds of <acronym>USB</acronym> device classes, - including serial ports, network adapters, and mass storage. A - <acronym>USB</acronym> host like a laptop or desktop computer - is able to access them just like physical - <acronym>USB</acronym> devices.</para> - - <para>The &man.usb.template.4; kernel module allows the - <acronym>USB</acronym> stack to switch between host-side and - device-side automatically, depending on what is connected to - the <acronym>USB</acronym> port. Connecting a - <acronym>USB</acronym> device like a memory stick to the - <acronym>USB</acronym> <acronym>OTG</acronym> port causes &os; - to switch to host mode. Connecting a <acronym>USB</acronym> - host like a computer causes &os; to switch to device - mode.</para> - - <para>What &os; presents to the <acronym>USB</acronym> host - depends on the <varname>hw.usb.template</varname> sysctl. See - &man.usb.template.4; for the list of available values. Note - that for the host to notice the configuration change, it must - be either physically disconnected and reconnected, or forced - to rescan the <acronym>USB</acronym> bus in a system-specific - way. When &os; is running on the host, &man.usbconfig.8; - <command>reset</command> can be used. This also must be done - after loading <filename>usb_template.ko</filename> if the - <acronym>USB</acronym> host was already connected to the - <acronym>USB</acronym> <acronym>OTG</acronym> socket.</para> - - <para>The <varname>hw.usb.template</varname> sysctl - is set to 0 by default, making &os; work as a - <acronym>USB</acronym> Mass Storage target. Both - &man.usb.template.4; and &man.cfumass.4; kernel modules must - be loaded. &man.cfumass.4; interfaces to the CTL subsystem, - the same one that is used for <acronym>iSCSI</acronym> or - Fibre Channel targets. On the host side, - <acronym>USB</acronym> Mass Storage initiators can only access - a single <acronym>LUN</acronym>, - <acronym>LUN</acronym> 0.</para> - - <para><acronym>USB</acronym> Mass Storage does not require the - &man.ctld.8; daemon to be running, although it can be used if - desired. This is different from <acronym>iSCSI</acronym>. - Thus, there are two ways to configure the target: - &man.ctladm.8;, or &man.ctld.8;. Both require the - <filename>cfumass.ko</filename> kernel module to be loaded. - The module can be loaded manually:</para> - - <screen>&prompt.root; <userinput>kldload cfumass</userinput></screen> - - <para>If <filename>cfumass.ko</filename> has not been built into - the kernel, <filename>/boot/loader.conf</filename> can be set - to load the module at boot:</para> - - <programlisting>cfumass_load="YES"</programlisting> - - <para>A <acronym>LUN</acronym> can be created without the - &man.ctld.8; daemon:</para> - - <screen>&prompt.root; <userinput>ctladm create -b block -o file=/data/target0</userinput></screen> - - <para>This presents the contents of the image file - <filename>/data/target0</filename> as a <acronym>LUN</acronym> - to the <acronym>USB</acronym> host. The file must exist - before executing the command. To configure the - <acronym>LUN</acronym> at system startup, add the command to - <filename>/etc/rc.local</filename>.</para> - - <para>&man.ctld.8; can also be used to manage - <acronym>LUN</acronym>s. Create - <filename>/etc/ctl.conf</filename>, add a line to - <filename>/etc/rc.conf</filename> to make sure &man.ctld.8; is - automatically started at boot, and then start the - daemon.</para> - - <para>This is an example of a simple - <filename>/etc/ctl.conf</filename> configuration file. Refer - to &man.ctl.conf.5; for a more complete description of the - options.</para> - - <programlisting>target naa.50015178f369f092 { - lun 0 { - path /data/target0 - size 4G - } -}</programlisting> - - <para>The example creates a single target with a single - <acronym>LUN</acronym>. The - <literal>naa.50015178f369f092</literal> is a device identifier - composed of 32 random hexadecimal digits. The - <literal>path</literal> line defines the full path to a file - or zvol backing the <acronym>LUN</acronym>. That file must - exist before starting &man.ctld.8;. The second line is - optional and specifies the size of the - <acronym>LUN</acronym>.</para> - - <para>To make sure the &man.ctld.8; daemon is started at - boot, add this line to - <filename>/etc/rc.conf</filename>:</para> - - <programlisting>ctld_enable="YES"</programlisting> - - <para>To start &man.ctld.8; now, run this command:</para> - - <screen>&prompt.root; <userinput>service ctld start</userinput></screen> - - <para>As the &man.ctld.8; daemon is started, it reads - <filename>/etc/ctl.conf</filename>. If this file is edited - after the daemon starts, reload the changes so they take - effect immediately:</para> - - <screen>&prompt.root; <userinput>service ctld reload</userinput></screen> - </sect2> </sect1> <sect1 xml:id="creating-cds"> Added: head/en_US.ISO8859-1/books/handbook/usb-device-mode/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/handbook/usb-device-mode/chapter.xml Tue May 29 17:07:50 2018 (r51744) @@ -0,0 +1,374 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="usb-device-mode"> + + <title>USB Device Mode</title> + + <sect1 xml:id="usb-device-mode-synopsis"> + <title>Synopsis</title> + + <info> + <authorgroup> + <author> + <personname> + <firstname>Edward Tomasz</firstname> + <surname>Napierala</surname> + </personname> + <affiliation> + <address> + <email>trasz@FreeBSD.org</email> + </address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </info> + + <para>This chapter covers the use of USB Device Mode and USB On + The Go (<acronym>USB OTG</acronym>) in &os;. This includes + virtual serial consoles, virtual network interfaces, and + virtual USB drives.</para> + + <para>When running on hardware that supports USB device mode + or <acronym>USB OTG</acronym>, like that built into + many embedded boards, the &os; <acronym>USB</acronym> stack + can run in <emphasis>device mode</emphasis>. Device mode + makes it possible for the computer to present itself as + different kinds of <acronym>USB</acronym> device classes, + including serial ports, network adapters, and mass storage, + or a combination thereof. A <acronym>USB</acronym> host like + a laptop or desktop computer is able to access them just like + physical <acronym>USB</acronym> devices.</para> + + <para>There are two basic ways the hardware can provide the + device mode functionality: with a separate "client port", which + only supports the device mode, and with a USB OTG port, which + can provide both device and host mode. For + <acronym>USB OTG</acronym> ports, the <acronym>USB</acronym> + stack switches between host-side and device-side automatically, + depending on what is connected to the port. Connecting a + <acronym>USB</acronym> device like a memory stick to the + port causes &os; to switch to host mode. Connecting a + <acronym>USB</acronym> host like a computer causes &os; to + switch to device mode. Single purpose "client ports" always + work in device mode.</para> + + <para>What &os; presents to the <acronym>USB</acronym> host + depends on the <varname>hw.usb.template</varname> sysctl. Some + templates provide a single device, such as a serial terminal; + others provide multiple ones, which can all be used at the same + time. An example is the template 10, which provides a mass + storage device, a serial console, and a network interface. + See &man.usb.template.4; for the list of available + values.</para> + + <para>Note that in some cases, depending on the hardware and the + hosts operating system, for the host to notice the configuration + change, it must be either physically disconnected and + reconnected, or forced to rescan the <acronym>USB</acronym> + bus in a system-specific way. When &os; is running on the host, + &man.usbconfig.8; <command>reset</command> can be used. + This also must be done after loading + <filename>usb_template.ko</filename> if the + <acronym>USB</acronym> host was already connected to the + <acronym>USB</acronym> <acronym>OTG</acronym> socket.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to set up USB Device Mode functionality on + &os;.</para> + </listitem> + + <listitem> + <para>How to configure the virtual serial port on + &os;.</para> + </listitem> + + <listitem> + <para>How to connect to the virtual serial port + from various operating systems.</para> + </listitem> + + <listitem> + <para>How to configure &os; to provide a virtual + <acronym>USB</acronym> network interface.</para> + </listitem> + + <listitem> + <para>How to configure &os; to provide a virtual + <acronym>USB</acronym> storage device.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="usb-device-mode-terminals"> + <title><acronym>USB</acronym> Virtual Serial Ports</title> + + <sect2> + <title>Configuring USB Device Mode Serial Ports</title> + + <para>Virtual serial port support is provided by templates + number 3, 8, and 10. Note that template 3 works with + Microsoft Windows 10 without the need for special drivers + and INF files. Other host operating systems work with all + three templates. Both &man.usb.template.4; and &man.umodem.4; + kernel modules must be loaded.</para> + + <para>To enable USB device mode serial ports, add those lines + to <filename>/etc/ttys</filename>:</para> + + <screen>ttyU0 "/usr/libexec/getty 3wire" vt100 onifconsole secure +ttyU1 "/usr/libexec/getty 3wire" vt100 onifconsole secure</screen> + + <para>Then add these lines to + <filename>/etc/devd.conf</filename>:</para> + + <screen>notify 100 { + match "system" "DEVFS"; + match "subsystem" "CDEV"; + match "type" "CREATE"; + match "cdev" "ttyU[0-9]+"; + action "/sbin/init q"; +};</screen> + + <para>Reload the configuration if + &man.devd.8; is already running:</para> + + <screen>&prompt.root; <userinput>service devd restart</userinput></screen> + + <para>Make sure the necessary modules are loaded and the + correct template is set at boot by adding + those lines to <filename>/boot/loader.conf</filename>, + creating it if it does not already exist:</para> + + <screen>umodem_load="YES" +hw.usb.template=3</screen> + + <para>To load the module and set the template without rebooting + use:</para> + + <screen>&prompt.root; <userinput>kldload umodem</userinput> +&prompt.root; <userinput>sysctl hw.usb.template=3</userinput></screen> + + </sect2> + + <sect2> + <title>Connecting to USB Device Mode Serial Ports from + &os;</title> + + <para>To connect to a board configured to provide USB device + mode serial ports, connect the USB host, such as a laptop, to + the boards USB OTG or USB client port. Use + <command>pstat -t</command> on the host to list the terminal + lines. Near the end of the list you should see a USB serial + port, eg "ttyU0". To open the connection, use:</para> + + <screen>&prompt.root; <userinput>cu -l /dev/ttyU0</userinput></screen> + + <para>After pressing the Enter key a few times you will see + a login prompt.</para> + </sect2> + + <sect2> + <title>Connecting to USB Device Mode Serial Ports from + macOS</title> + + <para>To connect to a board configured to provide USB device + mode serial ports, connect the USB host, such as a laptop, + to the boards USB OTG or USB client port. To open the + connection, use:</para> + + <screen>&prompt.root; <userinput>cu -l /dev/cu.usbmodemFreeBSD1</userinput></screen> + </sect2> + + <sect2> + <title>Connecting to USB Device Mode Serial Ports from + Linux</title> + + <para>To connect to a board configured to provide USB device + mode serial ports, connect the USB host, such as a laptop, + to the boards USB OTG or USB client port. To open the + connection, use:</para> + + <screen>&prompt.root; <userinput>minicom -D /dev/ttyACM0</userinput></screen> + </sect2> + + <sect2> + <title>Connecting to USB Device Mode Serial Ports from + Microsoft Windows 10</title> + + <para>To connect to a board configured to provide USB device + mode serial ports, connect the USB host, such as a laptop, + to the boards USB OTG or USB client port. To open a + connection you will need a serial terminal program, such as + <application>PuTTY</application>. To check the COM port name + used by Windows, run Device Manager, expand "Ports (COM & + LPT)". You will see a name similar to "USB Serial Device + (COM4)". Run serial terminal program of your choice, for + example <application>PuTTY</application>. In the + <application>PuTTY</application> dialog set "Connection type" + to "Serial", type the COMx obtained from Device Manager in the + "Serial line" dialog box and click Open.</para> + </sect2> + </sect1> + + <sect1 xml:id="usb-device-mode-network"> + + <title><acronym>USB</acronym> Device Mode Network + Interfaces</title> + + <para>Virtual network interfaces support is provided by templates + number 1, 8, and 10. Note that none of them works with + Microsoft Windows. Other host operating systems work with all + three templates. Both &man.usb.template.4; and &man.if.cdce.4; + kernel modules must be loaded.</para> + + <para>Make sure the necessary modules are loaded and the correct + template is set at boot by adding + those lines to <filename>/boot/loader.conf</filename>, creating + it if it does not already exist:</para> + + <screen>if_cdce_load="YES" +hw.usb.template=1</screen> + + <para>To load the module and set the template without rebooting + use:</para> + + <screen>&prompt.root; <userinput>kldload if_cdce</userinput> +&prompt.root; <userinput>sysctl hw.usb.template=1</userinput></screen> + </sect1> + + <sect1 xml:id="usb-device-mode-storage"> + <title><acronym>USB</acronym> Virtual Storage Device</title> + + <note> + <para>The &man.cfumass.4; driver is a <acronym>USB</acronym> + device mode driver first available in &os; 12.0.</para> + </note> + + <para>Mass Storage target is provided by templates 0 and 10. + Both &man.usb.template.4; and &man.cfumass.4; kernel modules + must be loaded. &man.cfumass.4; interfaces to the CTL + subsystem, the same one that is used for + <acronym>iSCSI</acronym> or Fibre Channel targets. + On the host side, <acronym>USB</acronym> Mass Storage + initiators can only access a single <acronym>LUN</acronym>, + <acronym>LUN</acronym> 0.</para> + + <sect2> + <title>Configuring USB Mass Storage Target Using the cfumass + Startup Script</title> + + <para>The simplest way to set up a read-only USB storage target + is to use the <filename>cfumass</filename> rc script. To + configure it this way, copy the files to be presented to the + USB host machine into the <literal>/var/cfumass</literal> + directory, and add this line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>cfumass_enable="YES"</programlisting> + + <para>To configure the target without restarting, + run this command:</para> + + <screen>&prompt.root; <userinput>service cfumass start</userinput></screen> + + <para>Differently from serial and network functionality, the + template should not be set to 0 or 10 in + <filename>/boot/loader.conf</filename>. This is because the + LUN must be set up before setting the template. The cfumass + startup script sets the correct template number automatically + when started.</para> + </sect2> + <sect2> + <title>Configuring USB Mass Storage Using Other Means</title> + + <para>The rest of this chapter provides detailed description of + setting the target without using the cfumass rc file. This is + necessary if eg one wants to provide a writeable LUN.</para> + + <para><acronym>USB</acronym> Mass Storage does not require the + &man.ctld.8; daemon to be running, although it can be used if + desired. This is different from <acronym>iSCSI</acronym>. + Thus, there are two ways to configure the target: + &man.ctladm.8;, or &man.ctld.8;. Both require the + <filename>cfumass.ko</filename> kernel module to be loaded. + The module can be loaded manually:</para> + + <screen>&prompt.root; <userinput>kldload cfumass</userinput></screen> + + <para>If <filename>cfumass.ko</filename> has not been built into + the kernel, <filename>/boot/loader.conf</filename> can be set + to load the module at boot:</para> + + <programlisting>cfumass_load="YES"</programlisting> + + <para>A <acronym>LUN</acronym> can be created without the + &man.ctld.8; daemon:</para> + + <screen>&prompt.root; <userinput>ctladm create -b block -o file=/data/target0</userinput></screen> + + <para>This presents the contents of the image file + <filename>/data/target0</filename> as a <acronym>LUN</acronym> + to the <acronym>USB</acronym> host. The file must exist + before executing the command. To configure the + <acronym>LUN</acronym> at system startup, add the command to + <filename>/etc/rc.local</filename>.</para> + + <para>&man.ctld.8; can also be used to manage + <acronym>LUN</acronym>s. Create + <filename>/etc/ctl.conf</filename>, add a line to + <filename>/etc/rc.conf</filename> to make sure &man.ctld.8; is + automatically started at boot, and then start the + daemon.</para> + + <para>This is an example of a simple + <filename>/etc/ctl.conf</filename> configuration file. Refer + to &man.ctl.conf.5; for a more complete description of the + options.</para> + + <programlisting>target naa.50015178f369f092 { + lun 0 { + path /data/target0 + size 4G + } +}</programlisting> + + <para>The example creates a single target with a single + <acronym>LUN</acronym>. The + <literal>naa.50015178f369f092</literal> is a device identifier + composed of 32 random hexadecimal digits. The + <literal>path</literal> line defines the full path to a file + or zvol backing the <acronym>LUN</acronym>. That file must + exist before starting &man.ctld.8;. The second line is + optional and specifies the size of the + <acronym>LUN</acronym>.</para> + + <para>To make sure the &man.ctld.8; daemon is started at + boot, add this line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ctld_enable="YES"</programlisting> + + <para>To start &man.ctld.8; now, run this command:</para> + + <screen>&prompt.root; <userinput>service ctld start</userinput></screen> + + <para>As the &man.ctld.8; daemon is started, it reads + <filename>/etc/ctl.conf</filename>. If this file is edited + after the daemon starts, reload the changes so they take + effect immediately:</para> + + <screen>&prompt.root; <userinput>service ctld reload</userinput></screen> + </sect2> + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201805291707.w4TH7oLR043174>