Date: Tue, 28 Feb 2017 21:57:26 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r50019 - in head: en_US.ISO8859-1/books/handbook/disks share/xml Message-ID: <201702282157.v1SLvQXJ060300@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>">;
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201702282157.v1SLvQXJ060300>