Re: git: d8a4843cb76e - main - umass.4: Modernize driver loading instructions
Date: Fri, 10 Oct 2025 14:29:55 UTC
On 2025-10-10 09:37 -04:00 EDT, cyric@mm.st wrote: > Alexander Ziaee wrote: >> The branch main has been updated by ziaee: >> >> URL: https://cgit.FreeBSD.org/src/commit/?id=d8a4843cb76ec1b7da8d5defafb7eef9a6cc1c21 >> >> commit d8a4843cb76ec1b7da8d5defafb7eef9a6cc1c21 >> Author: Alexander Ziaee <ziaee@FreeBSD.org> >> AuthorDate: 2025-10-09 14:55:14 +0000 >> Commit: Alexander Ziaee <ziaee@FreeBSD.org> >> CommitDate: 2025-10-09 21:06:50 +0000 >> >> umass.4: Modernize driver loading instructions >> >> + consolidate kernel configuration in SYNOPSIS >> + explain driver autoloading in DESCRIPTION >> + s/port/interface/ because of internal USBs >> + fix flow of remaining example >> >> MFC after: 1 day >> --- >> share/man/man4/umass.4 | 56 +++++++++++++++++++++----------------------------- >> 1 file changed, 23 insertions(+), 33 deletions(-) >> >> diff --git a/share/man/man4/umass.4 b/share/man/man4/umass.4 >> index db4e6f0890f2..8c6b03a3afea 100644 >> --- a/share/man/man4/umass.4 >> +++ b/share/man/man4/umass.4 >> @@ -25,44 +25,44 @@ >> .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF >> .\" SUCH DAMAGE. >> .\" >> -.Dd October 2, 2025 >> +.Dd October 9, 2025 >> .Dt UMASS 4 >> .Os >> .Sh NAME >> .Nm umass >> .Nd USB Mass Storage Devices driver >> .Sh SYNOPSIS >> -To compile this driver into the kernel, >> -place the following line in your >> -kernel configuration file: >> -.Bd -ragged -offset indent >> +.Cd "device da" >> .Cd "device scbus" >> +.Cd "device pass" >> .Cd "device usb" >> .Cd "device umass" >> -.Ed >> .Pp >> -Alternatively, to load the driver as a >> -module at boot time, place the following line in >> +In >> .Xr loader.conf 5 : >> -.Bd -literal -offset indent >> -umass_load="YES" >> -.Ed >> +.Cd umass_load > > This now renders as the following - expected? > > In loader.conf(5): > umass_load > > I checked your previous similar changes and it seems to be inconsistent, > some include ="YES" (e.g. 52eb7e394a7) and some do not. It's been requested that we don't include the operand. Overall throughout the manual pages using this syntax (which are many more than I've touched actually), there is a mix. I don't think the operand helps it, and it's difficult sometimes when the operand isn't straightforward. Suggestions are welcome. > Also I don't think .Cd is applicable here, shouldn't it rather be .Va > (seems more appropriate) or even literal text? From mdoc(7): Cd line Kernel configuration declaration. Va [type] identifier ... A variable name. The line is telling the loader to load the kernel module into the kernel. Thus it is a kernel configuration declaration. This lets people search the manual by kernel configuration, like so: apropos Cd=umass HTH. >> .Sh DESCRIPTION >> The >> .Nm >> driver provides support for Mass Storage devices that attach to the USB >> -port. >> +interface. >> .Pp >> -To use the >> -.Nm >> -driver, >> +If the appropriate hardware is detected, >> +the driver will be loaded automatically by >> +.Xr devmatch 8 . >> +To load the driver manually at boot time, use the >> +.Cm umass_load >> +command at the >> +.Xr loader 8 >> +prompt, or add it to >> +.Xr loader.conf 5 . >> +.Pp >> +To use the driver in a custom kernel, >> .Xr usb 4 >> -and one of >> -.Xr uhci 4 >> -or >> -.Xr ohci 4 >> -or >> -.Xr ehci 4 >> +and at least one of >> +.Xr uhci 4 , >> +.Xr ohci 4 , >> +.Xr ehci 4 , >> or >> .Xr xhci 4 >> must be configured in the kernel. >> @@ -88,16 +88,8 @@ USB hard disk drives >> USB floppy drives >> .El >> .Sh EXAMPLES >> -.Bd -literal -offset indent >> -device umass >> -device scbus >> -device da >> -device pass >> -.Ed >> -.Pp >> -Add the >> -.Nm >> -driver to the kernel. >> +Rescan all slots on a multi-slot flash reader, >> +where the slots map to separate LUNs on a single SCSI ID: >> .Bd -literal -offset indent >> camcontrol rescan 0:0:0 >> camcontrol rescan 0:0:1 >> @@ -105,8 +97,6 @@ camcontrol rescan 0:0:2 >> camcontrol rescan 0:0:3 >> .Ed >> .Pp >> -Rescan all slots on a multi-slot flash reader, where the slots map to separate >> -LUNs on a single SCSI ID. >> Typically only the first slot will be enabled at boot time. >> This assumes that >> the flash reader is the first SCSI bus in the system and has 4 slots. >> > >