Document USB Mass Storage CTL frontend.

[trasz]

Summary

Document USB Mass Storage CTL frontend; https://reviews.freebsd.org/D8787

[wblock]

en_US.ISO8859-1/books/handbook/disks/chapter.xml

585

Capitalize "target".

588

The indentation and wrapping is wrong here, and the sentence is not clear. It sounds like cfumass has been around but not supported until 12.0. Doesn't really tell what cfumass is or does, either.

<note>
  <para>The cfumass driver is a <acronym>USB</acronym> device mode 
    driver that first became available in &os;&nbsp12.0-CURRENT.</para>
</note>

Is there a cfumass(4) man page to make that a link?

594

This sentence has an aside, which makes it more complex and should be avoided. Suggestion:
"When running on <acronym>USB</acronym> <acronym>OTG</acronym>-compliant hardware
like that built into many embedded boards, the <acronym>USB</acronym> stack can run in device mode."

OTG is used here and below, and should be defined.

595

"This" is nonspecific:
"Device mode makes it possible..."

The quotes around "emulate" make it look sarcastic. Is it a false emulation? If it's real, the quotes can just be removed.

597

Break the sentence to keep it from becoming too long and complicated.

network adapters, and mass storage.  A <acronym>USB</acronym>

598

Please avoid emdashes and asides.

host like a laptop or desktop computer is able to access them just like physical

601

Use the &man.usb_template.4; entity to make this a link to the man page.
(Might need an additional entity defined for it, I can help with that.)

604

This sentence is unclear. "It" can be read as "device mode" rather than the kernel module. What switches? What do host-side and device-side mean?

Also, please do not use contractions.

605

Try to use active rather than passive wording:
s/will make/makes/

Try to avoid semicolons, they usually just splice sentences together.
Try to avoid asides, they are an interruption in the train of thought.

"Connecting a <acronym>USB</acronym> device like a memory stick to the <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."

608

Avoid contractions.

609

Use separate <acronym> tags for the terms, but we are already talking about USB, so can probably just say <acronym>OTG</acronym> here.

"It is not possible to connect the <acronym>OTG</acronym> port to both the device and another host at the same time."

But that is misleading. It's physically possible to do that, just won't work.

614

Use &man.usb_template.4; here.

615

"in order" is not needed here

616

s/needs to be/must be/

617

Does not seem necessary to repeat the section in parens.

618

Needs an article:
s/in system/in a system/

The "In case of" beginning to the next sentence is covered below.

619

"When &os; is running on the host, the <command>reset</command> subcommand of"

620

&man.usbconfig.8; command can be used. This also must be done

623

<acronym>OTG</acronym> socket.<para>

625

"By default, the <varname>hw.usb.template</varname> sysctl is set to 0, making &os; work as a <acronym>USB</acronym> Mass Storage target."

628

This sentence needs some kind of point, like "To <do something>, both the &man.usb_template.4; and &man.cfumass.4; kernel modules must be loaded."

629

"The &man.cfumass.4; driver interfaces..."

631

Avoid overusing "Note". And the part in parens is another aside, an interruption in the thought.
"On the host side, <acronym>USB</acronym> Mass Storage initiators can only access a single <acronym>LUN</acronym>, LUN 0."

635

Better to tell what it does, then say afterward that "This is different from iSCSI."

"<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 iSCSI."

638

Simplify:
"configure the target: &man.ctladm.8; or &man.ctld.8;."

645

s/the//

652

Here is another aside. Rearrange it to avoid that:

<para>A <acronym>LUN</acronym> can be created without the &man.ctld.8; daemon running:</para>

657

Passive -> active:
s/will present/presents/

but it needs an article, too:

"This presents the contents the image file..."

658

"target0" is kind of a confusing name. I suspect the file can have any name, but this implies that they have a special naming format.

Suspect also that it should say "as a target LUN", but not sure.

659

What must exist? The path, or the file itself?

661

s/this/the/

663

"Alternatively" is probably not needed. (Wrapping not exact.)

<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 the &man.ctld.8; daemon is automatically started at boot, and then start the
  daemon.</para>

675

Don't need this blank line. And content that is not indented should start immediately after the tag:

<programlisting>target naa.50015178f369f092 {
	​        lun 0 {
	​                path /data/target0
	​                size 4G
	​        }
}</programlisting>

685

Break the sentence, don't use semicolons to glue two sentences together. Also, don't use contractions:

identifier.  It is made of 32 random hexadecimal digits.

688

Path? Or file?

692

s/Next, to/To/

704

"after the daemon starts, reload the changes so they take effect immediately:</para>"

[emaste]

en_US.ISO8859-1/books/handbook/disks/chapter.xml

588

In D8787

595

I think we could also just drop emulate and use a different phrasing. We're not really emulating a USB device class device, we're implementing one. One might think of this code as emulating a USB flash drive, but it's more the form factor and such that's different, not the fundamental essence of the thing. Regardless of if a cheapie flash drive or a Beaglebone Black running FreeBSD with this code is plugged into a host there's a controller running some firmware and some storage.

[wblock]

en_US.ISO8859-1/books/handbook/disks/chapter.xml

588

That will need to be added to the man page entities in doc/share/xml/man-refs.ent. Then this can use &man.cfumass.1;.

[trasz]

Incorporate fixes from wblock@.

[trasz]

Thanks. One thing I'm not sure about is the "USB OTG" stuff. "OTG" is not an acronym it itself, I think; "USB OTG" is. As in, the whole stuff.

[emaste]

In D8788#201022, @trasz wrote:

Thanks. One thing I'm not sure about is the "USB OTG" stuff. "OTG" is not an acronym it itself, I think; "USB OTG" is. As in, the whole stuff.

Hrm, this is tricky. I see some instances of just OTG but I agree with @trasz that it doesn't really stand alone. For a question like "what interface does that use" OTG doesn't sound like a reasonable/sufficient answer. The other tricky bit is that I'd say USB OTG stands for USB On-The-Go.

[trasz]

So, hm, is it good to go? Warren?

[wblock]

Mine...

[wblock]

Edited. Lots of whitespace fixes, some text editing for clarity.

[trasz]

en_US.ISO8859-1/books/handbook/boot/chapter.xml

908 ↗

(On Diff #25769)

Erm, this wasn't supposed to be part of the commit.

949 ↗

(On Diff #25769)

(mostly because this part doesn't exist.)

[wblock]

en_US.ISO8859-1/books/handbook/boot/chapter.xml

908 ↗

(On Diff #25769)

Please hang on to this for the future, then. :)

[trasz]

Hm, something is wrong:

svn: E175013: Commit failed (details follow):
svn: E175013: Access to '/doc/!svn/me' forbidden

[trasz]

Reroot part moved to https://reviews.freebsd.org/D9834.

[trasz]

Committed by wblock@ as r50019.