svn commit: r51744 - in head/en_US.ISO8859-1/books/handbook: . disks usb-device-mode
Edward Tomasz Napierala <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
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>[email protected]</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>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"