From nobody Tue Mar 4 17:07:32 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 4Z6hvQ6Qydz5qNhk for ; Tue, 04 Mar 2025 17:07:46 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-pj1-x102f.google.com (mail-pj1-x102f.google.com [IPv6:2607:f8b0:4864:20::102f]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "WR4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Z6hvQ2KtKz3ksP for ; Tue, 04 Mar 2025 17:07:46 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Authentication-Results: mx1.freebsd.org; none Received: by mail-pj1-x102f.google.com with SMTP id 98e67ed59e1d1-2f9b9c0088fso3811a91.0 for ; Tue, 04 Mar 2025 09:07:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20230601.gappssmtp.com; s=20230601; t=1741108063; x=1741712863; darn=freebsd.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=wuMJyCuuAm7PLMzJGqvNmSWAwanhtj73QNSH38kTItA=; b=E58JTO+G9HT+TJG7Ezwj4OTmDp67rVTgM7l/D5mXFR9Zn3+WBexk8Bd+N5jajZ9tms fwXmp/bRgAh3VftOH+nYbXmOe2L8FqxHi3je17gMhBkFcSIyFeXJ3HBFbzJLBSNTv7VB ACgMaqpFQThj7JUf3hUx+lc6Ni7iBCtIKGveL9Ni03vsDLj3Yf6YRlza/YKhbOzDFsyg 8uA5S3zKAkc/DGwyZqhgxxw3TNdoLn3yeqbLXzQN9l4+6zDU2z6/cAz28tBx3WYJYovJ gApb6obBfhOa3UeheZieU0PHybeq5+s3n4+nefCIdFY97YGRcT+5BCQp/YWERS9ybQqx 9fQQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1741108063; x=1741712863; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=wuMJyCuuAm7PLMzJGqvNmSWAwanhtj73QNSH38kTItA=; b=VWRVdwSwZTekTyElIU96fTBICBUST1yOHqklR47V2MxAx+7wdCw1BK8komQRcyw9m6 mj+M6zqMiHOYmBBVuzCrAd5fB40VCg1B5yiLSsulaBqNDe19PWVK8B8zEQyomTdRQRXQ qKfi5oPDsT9+h4jRVJY6F0vqQ1KoWpZNdfMqJ/UOk5PKU4RBhvm3k9oyiUlSVZfclmsk VPaOcrNFOBMlTmkx+u5d+w5rdEcupXnFt35IRxHHHHbvCozzTftF+NQxoP7e3WG4puVX 4dI+9/8MumkHx8sMqxdFgxrTrwqeFE9j/c7yPmMjaFkuSDHlQGjW5GfZ0Fhf4vVNU+FL 6Q2A== X-Forwarded-Encrypted: i=1; AJvYcCVXgc20Q8laGlIF2abUGJB3hVhhgnt05PyHNrzFD/t3fY/nsaFd/wbZ4JWhITrTSHe4FzQmrc7C6GQ/si2mxBx6MbWY@freebsd.org X-Gm-Message-State: AOJu0Yx73g6b5BkRIHBmzpU8s/EiPKjoWdRzzMlgqSQIDHVU2nGj/Cab oBbK42YJ/9UTY5CHiU3Wdwh69R4Uir6fIDZHNrMdRmICrsLlL8nTpR6hRDEpu7zzKOBtjGLWRQ8 dedegyRaar8PVLLB3ZT2SHBsirfJfjDYNH2CkpADoDOb7AmIeEQo= X-Gm-Gg: ASbGncsEzAD6FfC8IwfijsCzyZHbq667xYYJSE0KTg21B5EPoLkbacXceFWRIgXWtuP VwvjTMDsSvT4Hr7bTs4iCvddU6+ttUJk6A5YVbolyfiiEx2adSaMJdP/LYtq0IfVtPMP34VSI2m brZC0ThQCDXappz+/YcjBee37n X-Google-Smtp-Source: AGHT+IFIExQwPpf8Tlj8YMYc5RUeCRkNoHs9kSpEPHZ+ezB8rXHpccVqhyrxwFnZwGUCFV0jGgNp8lwFf8+OiI8lIiU= X-Received: by 2002:a17:90b:2e44:b0:2ee:8cbb:de28 with SMTP id 98e67ed59e1d1-2ff33b9da35mr7155559a91.8.1741108062967; Tue, 04 Mar 2025 09:07:42 -0800 (PST) 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 References: <202502272222.51RMM0fg033513@gitrepo.freebsd.org> <87bjugsx7t.wl-herbert@gojira.at> <95401978-p196-n4n8-4458-98qs07n2162n@SerrOFQ.bet> In-Reply-To: From: Warner Losh Date: Tue, 4 Mar 2025 09:07:32 -0800 X-Gm-Features: AQ5f1Jp8wL43PosVCrEhCC83USLxLGtHU82ORCuS_bnpOoEq6Yzzyt0fInwmHzs Message-ID: Subject: Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency To: John Baldwin Cc: "Bjoern A. Zeeb" , "Herbert J. Skuhra" , Alexander Ziaee , Adrian Chadd , src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Content-Type: multipart/alternative; boundary="0000000000009bf715062f874f5e" X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US] X-Rspamd-Queue-Id: 4Z6hvQ2KtKz3ksP X-Spamd-Bar: ---- --0000000000009bf715062f874f5e Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Tue, Mar 4, 2025 at 8:23=E2=80=AFAM John Baldwin wrote= : > On 3/4/25 09:25, Bjoern A. Zeeb wrote: > > On Tue, 4 Mar 2025, Herbert J. Skuhra wrote: > > > >> On Thu, 27 Feb 2025 23:22:00 +0100, Alexander Ziaee wrote: > >>> > >>> The branch main has been updated by ziaee: > >>> > >>> URL: > https://cgit.FreeBSD.org/src/commit/?id=3D4262dbc57982383eb61a8b7806de6dd= 4b7802da8 > >>> > >>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8 > >>> Author: Alexander Ziaee > >>> AuthorDate: 2025-02-19 15:54:27 +0000 > >>> Commit: Alexander Ziaee > >>> CommitDate: 2025-02-27 22:20:22 +0000 > >>> > >>> wifi manuals: Mlink + document description consistency > >>> > >>> Interfaces all have an mlink to if_$foo. Add these for the > missing ones > >>> and remove an incorrect one from rtwn_pci. Wireless network > drivers are > >>> all accessible via `apropos -s4 "wireless network driver", excep= t > two > >>> which are "wireless network device". I actually prefer the > latter, but > >>> make them all consistent upon the more common parlance. Tag SPDX > on one > >>> of the files I touched, while here. > >>> > >>> MFC after: 3 days > >>> Reviewed by: bz, carlavilla, mhorne > >>> Approved by: carlavilla, mhorne (mentors) > >>> Differential Revision: https://reviews.freebsd.org/D49063 > >>> --- > >>> share/man/man4/Makefile | 4 +++- > >>> share/man/man4/uath.4 | 4 +++- > >>> share/man/man4/upgt.4 | 2 +- > >>> 3 files changed, 7 insertions(+), 3 deletions(-) > >>> > >>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile > >>> index 13afc9b8d399..8e0af19eec3d 100644 > >>> --- a/share/man/man4/Makefile > >>> +++ b/share/man/man4/Makefile > >>> @@ -764,7 +764,9 @@ MLINKS+=3Dptnet.4 if_ptnet.4 > >>> MLINKS+=3Dral.4 if_ral.4 > >>> MLINKS+=3Dre.4 if_re.4 > >>> MLINKS+=3Drl.4 if_rl.4 > >>> -MLINKS+=3Drtwn_pci.4 if_rtwn_pci.4 > >>> +MLINKS+=3Drtw88.4 if_rtw89.4 > >>> +MLINKS+=3Drtw89.4 if_rtw89.4 > >>> +MLINKS+=3Drtwn.4 if_rtwn.4 > >> ^^^^^^^^^ > >> $ grep if_rtwn.4 ObsoleteFiles.inc > >> OLD_FILES+=3Dusr/share/man/man4/if_rtwn.4.gz > > > > In fact that is probably correct but things are confusing. > > > > The modules are called if_rtwn_usb.ko and if_rtwn_pci.ko and those > > should have the man page and links (so contrary to what was done). > > rtwn.ko is just the common code if I am not mistaken (Adrian should kno= w > > better). > > > > But everyone is just referring to the driver as rtwn and I fear if ther= e > > is no man page to be found as man rtwn / man if_rtwn people will be > > confused. > > > > I wanted to do the same with rtw88 but was told to keep it all together > > as one so rtwn is an excemption. > > > > That all said, yes, it needs a further cleanup. > > The manpages should just be rtwn/if_rtwn. The bus attachment doesn't > matter. > We don't have separate manpages when a storage adapter has been supported > on both PCI and ISA in the past, you just had the ahc(4) driver (for > example). > USB vs PCI is the same. It should just be a single manpage for the drive= r > regardless of the attachment. If the driver has separate modules that ca= n > be documented in the one manpage, but the list of supported chipsets, etc= . > is presumably shared hence the shared driver name and common code. In > particular, the thing a user sees in dmesg is 'rtwn0', not 'rtwn_pci0' so > the manpage needs to be tied to what a user sees as a device name in dmes= g. > Yea, the man page should mention the detail that we have separate .ko's, bu= t otherwise I agree with John here. Warner --0000000000009bf715062f874f5e Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Tue, Mar 4, = 2025 at 8:23=E2=80=AFAM John Baldwin <jhb@freebsd.org> wrote:
On 3/4/25 09:25, Bjoern A. Zeeb wrote:
> On Tue, 4 Mar 2025, Herbert J. Skuhra wrote:
>
>> On Thu, 27 Feb 2025 23:22:00 +0100, Alexander Ziaee wrote:
>>>
>>> The branch main has been updated by ziaee:
>>>
>>> URL: = https://cgit.FreeBSD.org/src/commit/?id=3D4262dbc57982383eb61a8b7806de6dd4b= 7802da8
>>>
>>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8
>>> Author:=C2=A0 =C2=A0 =C2=A0Alexander Ziaee <ziaee@FreeBSD.o= rg>
>>> AuthorDate: 2025-02-19 15:54:27 +0000
>>> Commit:=C2=A0 =C2=A0 =C2=A0Alexander Ziaee <ziaee@FreeBSD.o= rg>
>>> CommitDate: 2025-02-27 22:20:22 +0000
>>>
>>>=C2=A0 =C2=A0 =C2=A0 wifi manuals: Mlink + document description= consistency
>>>
>>>=C2=A0 =C2=A0 =C2=A0 Interfaces all have an mlink to if_$foo. A= dd these for the missing ones
>>>=C2=A0 =C2=A0 =C2=A0 and remove an incorrect one from rtwn_pci.= Wireless network drivers are
>>>=C2=A0 =C2=A0 =C2=A0 all accessible via `apropos -s4 "wire= less network driver", except two
>>>=C2=A0 =C2=A0 =C2=A0 which are "wireless network device&qu= ot;. I actually prefer the latter, but
>>>=C2=A0 =C2=A0 =C2=A0 make them all consistent upon the more com= mon parlance. Tag SPDX on one
>>>=C2=A0 =C2=A0 =C2=A0 of the files I touched, while here.
>>>
>>>=C2=A0 =C2=A0 =C2=A0 MFC after:=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 3 days
>>>=C2=A0 =C2=A0 =C2=A0 Reviewed by:=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 bz, carlavilla, mhorne
>>>=C2=A0 =C2=A0 =C2=A0 Approved by:=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 carlavilla, mhorne (mentors)
>>>=C2=A0 =C2=A0 =C2=A0 Differential Revision:=C2=A0 http= s://reviews.freebsd.org/D49063
>>> ---
>>>=C2=A0 =C2=A0share/man/man4/Makefile | 4 +++-
>>>=C2=A0 =C2=A0share/man/man4/uath.4=C2=A0 =C2=A0| 4 +++-
>>>=C2=A0 =C2=A0share/man/man4/upgt.4=C2=A0 =C2=A0| 2 +-
>>>=C2=A0 =C2=A03 files changed, 7 insertions(+), 3 deletions(-) >>>
>>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile=
>>> index 13afc9b8d399..8e0af19eec3d 100644
>>> --- a/share/man/man4/Makefile
>>> +++ b/share/man/man4/Makefile
>>> @@ -764,7 +764,9 @@ MLINKS+=3Dptnet.4 if_ptnet.4
>>>=C2=A0 =C2=A0MLINKS+=3Dral.4 if_ral.4
>>>=C2=A0 =C2=A0MLINKS+=3Dre.4 if_re.4
>>>=C2=A0 =C2=A0MLINKS+=3Drl.4 if_rl.4
>>> -MLINKS+=3Drtwn_pci.4 if_rtwn_pci.4
>>> +MLINKS+=3Drtw88.4 if_rtw89.4
>>> +MLINKS+=3Drtw89.4 if_rtw89.4
>>> +MLINKS+=3Drtwn.4 if_rtwn.4
>>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0^^^^^^^^^
>> $ grep if_rtwn.4 ObsoleteFiles.inc
>> OLD_FILES+=3Dusr/share/man/man4/if_rtwn.4.gz
>
> In fact that is probably correct but things are confusing.
>
> The modules are called if_rtwn_usb.ko and if_rtwn_pci.ko and those
> should have the man page and links (so contrary to what was done).
> rtwn.ko is just the common code if I am not mistaken (Adrian should kn= ow
> better).
>
> But everyone is just referring to the driver as rtwn and I fear if the= re
> is no man page to be found as man rtwn / man if_rtwn people will be > confused.
>
> I wanted to do the same with rtw88 but was told to keep it all togethe= r
> as one so rtwn is an excemption.
>
> That all said, yes, it needs a further cleanup.

The manpages should just be rtwn/if_rtwn.=C2=A0 The bus attachment doesn= 9;t matter.
We don't have separate manpages when a storage adapter has been support= ed
on both PCI and ISA in the past, you just had the ahc(4) driver (for exampl= e).
USB vs PCI is the same.=C2=A0 It should just be a single manpage for the dr= iver
regardless of the attachment.=C2=A0 If the driver has separate modules that= can
be documented in the one manpage, but the list of supported chipsets, etc.<= br> is presumably shared hence the shared driver name and common code.=C2=A0 In=
particular, the thing a user sees in dmesg is 'rtwn0', not 'rtw= n_pci0' so
the manpage needs to be tied to what a user sees as a device name in dmesg.=

Yea, the man page should mention the d= etail that we have separate .ko's, but
otherwise I agree with= John here.

Warner=C2=A0
--0000000000009bf715062f874f5e--