Date: Fri, 10 Oct 2025 10:08:03 -0500 From: Kyle Evans <kevans@FreeBSD.org> To: Alexander Ziaee <ziaee@FreeBSD.org>, cyric <cyric@mm.st>, src-committers <src-committers@FreeBSD.org>, dev-commits-src-all <dev-commits-src-all@FreeBSD.org>, dev-commits-src-main <dev-commits-src-main@FreeBSD.org> Subject: Re: git: d8a4843cb76e - main - umass.4: Modernize driver loading instructions Message-ID: <022f86c5-7d0d-4f87-8c2a-d2cf7f514563@FreeBSD.org> In-Reply-To: <E1v7E83-0005DE-Ur@rmmprod07.runbox> References: <E1v7E83-0005DE-Ur@rmmprod07.runbox>
next in thread | previous in thread | raw e-mail | index | archive | help
On 10/10/25 09:29, Alexander Ziaee wrote: > > 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: > Your interpretation doesn't line up with the rest of Cd's description: "This denotes strings accepted by config(8)." That's further supported by the OpenBSD-ish example. Cd here would be something like: .Cd device umass Because that is the config(8) description that you would put into a kernel config(5). What we put in loader.conf is more akin to an environment variable, and loader itself loads the module. Thanks, Kyle Evans
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?022f86c5-7d0d-4f87-8c2a-d2cf7f514563>