svn commit: r50019 - in head: en_US.ISO8859-1/books/handbook/disks share/xml
Warren Block <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: wblock
Date: Tue Feb 28 21:57:26 2017
New Revision: 50019
URL: https://svnweb.freebsd.org/changeset/doc/50019
Log:
Submit documentation from trasz for his Foundation-sponsored work on the
USB Mass Storage CTL front end.
Submitted by: trasz
Reviewed by: wblock
Sponsored by: The FreeBSD Foundation and iXsystems
Differential Revision: https://reviews.freebsd.org/D8788
Modified:
head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
head/share/xml/man-refs.ent
Modified: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Feb 28 16:37:05 2017 (r50018)
+++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml Tue Feb 28 21:57:26 2017 (r50019)
@@ -580,6 +580,134 @@ da0: <STECH Simple Drive 1.04> s/n
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 that first became available in
+ &os; 12.0-CURRENT.</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">
Modified: head/share/xml/man-refs.ent
==============================================================================
--- head/share/xml/man-refs.ent Tue Feb 28 16:37:05 2017 (r50018)
+++ head/share/xml/man-refs.ent Tue Feb 28 21:57:26 2017 (r50019)
@@ -7060,6 +7060,7 @@
<!ENTITY man.central.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>central</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
<!ENTITY man.cfi.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>cfi</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
<!ENTITY man.cfid.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>cfid</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
+<!ENTITY man.cfumass.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>cfumass</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
<!ENTITY man.ch.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>ch</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
<!ENTITY man.ciss.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>ciss</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
<!ENTITY man.clkbrd.4 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>clkbrd</refentrytitle><manvolnum>4</manvolnum></citerefentry>">
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"