From nobody Fri Oct 10 14:29:55 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4cjq046hnhz6C6m9 for ; Fri, 10 Oct 2025 14:30:12 +0000 (UTC) (envelope-from ziaee@FreeBSD.org) Received: from mailtransmit04.runbox.com (mailtransmit04.runbox.com [IPv6:2a0c:5a00:149::25]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4cjq044fldz3NqM; Fri, 10 Oct 2025 14:30:12 +0000 (UTC) (envelope-from ziaee@FreeBSD.org) Authentication-Results: mx1.freebsd.org; none Received: from mailtransmit02.runbox ([10.9.9.162] helo=aibo.runbox.com) by mailtransmit04.runbox.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.93) (envelope-from ) id 1v7E8D-00AWXe-71; Fri, 10 Oct 2025 16:30:05 +0200 Received: from [10.9.9.129] (helo=rmmprod07.runbox) by mailtransmit02.runbox with esmtp (Exim 4.86_2) (envelope-from ) id 1v7E84-0008SM-0a; Fri, 10 Oct 2025 16:29:56 +0200 Received: from mail by rmmprod07.runbox with local (Exim 4.86_2) (envelope-from ) id 1v7E83-0005DE-Ur; Fri, 10 Oct 2025 16:29:55 +0200 Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Received: from [Authenticated alias (960477)] by runbox.com with http (RMM6); Fri, 10 Oct 2025 14:29:55 GMT From: "Alexander Ziaee" To: "cyric" , "src-committers" , "dev-commits-src-all" , "dev-commits-src-main" Subject: Re: git: d8a4843cb76e - main - umass.4: Modernize driver loading instructions Date: Fri, 10 Oct 2025 14:29:55 +0000 (UTC) X-RMM-Aliasid: 960477 X-Mailer: RMM6 In-Reply-To: <4facb6f8-7f4b-4bc2-a303-efdfa8be2724@mm.st> Message-Id: X-Spamd-Bar: ---- X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:50304, ipnet:2a0c:5a00::/29, country:NO] X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-Rspamd-Queue-Id: 4cjq044fldz3NqM On 2025-10-10 09:37 -04:00 EDT, cyric@mm.st wrote: > Alexander Ziaee wrote: >> The branch main has been updated by ziaee: >>=20 >> URL: https://cgit.FreeBSD.org/src/commit/?id=3Dd8a4843cb76ec1b7da8d5defa= fb7eef9a6cc1c21 >>=20 >> commit d8a4843cb76ec1b7da8d5defafb7eef9a6cc1c21 >> Author: Alexander Ziaee >> AuthorDate: 2025-10-09 14:55:14 +0000 >> Commit: Alexander Ziaee >> CommitDate: 2025-10-09 21:06:50 +0000 >>=20 >> umass.4: Modernize driver loading instructions >>=20=20=20=20=20 >> + consolidate kernel configuration in SYNOPSIS >> + explain driver autoloading in DESCRIPTION >> + s/port/interface/ because of internal USBs >> + fix flow of remaining example >>=20=20=20=20=20 >> MFC after: 1 day >> --- >> share/man/man4/umass.4 | 56 +++++++++++++++++++++----------------------= ------- >> 1 file changed, 23 insertions(+), 33 deletions(-) >>=20 >> 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=3D"YES" >> -.Ed >> +.Cd umass_load >=20 > This now renders as the following - expected? >=20 > In loader.conf(5): > umass_load >=20 > I checked your previous similar changes and it seems to be inconsistent, > some include =3D"YES" (e.g. 52eb7e394a7) and some do not. It's been requested that we don't include the operand. Overall throughout t= he manual pages using this syntax (which are many more than I've touched ac= tually), there is a mix. I don't think the operand helps it, and it's diffi= cult 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? =46rom 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. T= hus it is a kernel configuration declaration. This lets people search the m= anual by kernel configuration, like so: apropos Cd=3Dumass=20 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 s= eparate >> -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. >>=20 >=20 >=20=