Date: Tue, 4 Mar 2025 09:07:32 -0800 From: Warner Losh <imp@bsdimp.com> To: John Baldwin <jhb@freebsd.org> Cc: "Bjoern A. Zeeb" <bz@freebsd.org>, "Herbert J. Skuhra" <herbert@gojira.at>, Alexander Ziaee <ziaee@freebsd.org>, Adrian Chadd <adrian@freebsd.org>, src-committers@freebsd.org, dev-commits-src-all@freebsd.org, dev-commits-src-main@freebsd.org Subject: Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency Message-ID: <CANCZdfpos8fqO7a=k96K_SiFwGQ9HijcWayeYOjcJQM35P=gVQ@mail.gmail.com> In-Reply-To: <e33373f5-7774-4063-bfc5-d5e1ba55691f@FreeBSD.org> References: <202502272222.51RMM0fg033513@gitrepo.freebsd.org> <87bjugsx7t.wl-herbert@gojira.at> <95401978-p196-n4n8-4458-98qs07n2162n@SerrOFQ.bet> <e33373f5-7774-4063-bfc5-d5e1ba55691f@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 <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=3D4262dbc57982383eb61a8b7806de6dd= 4b7802da8 > >>> > >>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8 > >>> Author: Alexander Ziaee <ziaee@FreeBSD.org> > >>> AuthorDate: 2025-02-19 15:54:27 +0000 > >>> Commit: Alexander Ziaee <ziaee@FreeBSD.org> > >>> 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 <div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote g= mail_quote_container"><div dir=3D"ltr" class=3D"gmail_attr">On Tue, Mar 4, = 2025 at 8:23=E2=80=AFAM John Baldwin <<a href=3D"mailto:jhb@freebsd.org"= >jhb@freebsd.org</a>> wrote:<br></div><blockquote class=3D"gmail_quote" = style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);pa= dding-left:1ex">On 3/4/25 09:25, Bjoern A. Zeeb wrote:<br> > On Tue, 4 Mar 2025, Herbert J. Skuhra wrote:<br> > <br> >> On Thu, 27 Feb 2025 23:22:00 +0100, Alexander Ziaee wrote:<br> >>><br> >>> The branch main has been updated by ziaee:<br> >>><br> >>> URL: <a href=3D"https://cgit.FreeBSD.org/src/commit/?id=3D4262= dbc57982383eb61a8b7806de6dd4b7802da8" rel=3D"noreferrer" target=3D"_blank">= https://cgit.FreeBSD.org/src/commit/?id=3D4262dbc57982383eb61a8b7806de6dd4b= 7802da8</a><br> >>><br> >>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8<br> >>> Author:=C2=A0 =C2=A0 =C2=A0Alexander Ziaee <ziaee@FreeBSD.o= rg><br> >>> AuthorDate: 2025-02-19 15:54:27 +0000<br> >>> Commit:=C2=A0 =C2=A0 =C2=A0Alexander Ziaee <ziaee@FreeBSD.o= rg><br> >>> CommitDate: 2025-02-27 22:20:22 +0000<br> >>><br> >>>=C2=A0 =C2=A0 =C2=A0 wifi manuals: Mlink + document description= consistency<br> >>><br> >>>=C2=A0 =C2=A0 =C2=A0 Interfaces all have an mlink to if_$foo. A= dd these for the missing ones<br> >>>=C2=A0 =C2=A0 =C2=A0 and remove an incorrect one from rtwn_pci.= Wireless network drivers are<br> >>>=C2=A0 =C2=A0 =C2=A0 all accessible via `apropos -s4 "wire= less network driver", except two<br> >>>=C2=A0 =C2=A0 =C2=A0 which are "wireless network device&qu= ot;. I actually prefer the latter, but<br> >>>=C2=A0 =C2=A0 =C2=A0 make them all consistent upon the more com= mon parlance. Tag SPDX on one<br> >>>=C2=A0 =C2=A0 =C2=A0 of the files I touched, while here.<br> >>><br> >>>=C2=A0 =C2=A0 =C2=A0 MFC after:=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 3 days<br> >>>=C2=A0 =C2=A0 =C2=A0 Reviewed by:=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 bz, carlavilla, mhorne<br> >>>=C2=A0 =C2=A0 =C2=A0 Approved by:=C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 carlavilla, mhorne (mentors)<br> >>>=C2=A0 =C2=A0 =C2=A0 Differential Revision:=C2=A0 <a href=3D"ht= tps://reviews.freebsd.org/D49063" rel=3D"noreferrer" target=3D"_blank">http= s://reviews.freebsd.org/D49063</a><br> >>> ---<br> >>>=C2=A0 =C2=A0share/man/man4/Makefile | 4 +++-<br> >>>=C2=A0 =C2=A0share/man/man4/uath.4=C2=A0 =C2=A0| 4 +++-<br> >>>=C2=A0 =C2=A0share/man/man4/upgt.4=C2=A0 =C2=A0| 2 +-<br> >>>=C2=A0 =C2=A03 files changed, 7 insertions(+), 3 deletions(-)<b= r> >>><br> >>> diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile= <br> >>> index 13afc9b8d399..8e0af19eec3d 100644<br> >>> --- a/share/man/man4/Makefile<br> >>> +++ b/share/man/man4/Makefile<br> >>> @@ -764,7 +764,9 @@ MLINKS+=3Dptnet.4 if_ptnet.4<br> >>>=C2=A0 =C2=A0MLINKS+=3Dral.4 if_ral.4<br> >>>=C2=A0 =C2=A0MLINKS+=3Dre.4 if_re.4<br> >>>=C2=A0 =C2=A0MLINKS+=3Drl.4 if_rl.4<br> >>> -MLINKS+=3Drtwn_pci.4 if_rtwn_pci.4<br> >>> +MLINKS+=3Drtw88.4 if_rtw89.4<br> >>> +MLINKS+=3Drtw89.4 if_rtw89.4<br> >>> +MLINKS+=3Drtwn.4 if_rtwn.4<br> >>=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0^^^^^^^^^<br> >> $ grep if_rtwn.4 ObsoleteFiles.inc<br> >> OLD_FILES+=3Dusr/share/man/man4/if_rtwn.4.gz<br> > <br> > In fact that is probably correct but things are confusing.<br> > <br> > The modules are called if_rtwn_usb.ko and if_rtwn_pci.ko and those<br> > should have the man page and links (so contrary to what was done).<br> > rtwn.ko is just the common code if I am not mistaken (Adrian should kn= ow<br> > better).<br> > <br> > But everyone is just referring to the driver as rtwn and I fear if the= re<br> > is no man page to be found as man rtwn / man if_rtwn people will be<br= > > confused.<br> > <br> > I wanted to do the same with rtw88 but was told to keep it all togethe= r<br> > as one so rtwn is an excemption.<br> > <br> > That all said, yes, it needs a further cleanup.<br> <br> The manpages should just be rtwn/if_rtwn.=C2=A0 The bus attachment doesn= 9;t matter.<br> We don't have separate manpages when a storage adapter has been support= ed<br> on both PCI and ISA in the past, you just had the ahc(4) driver (for exampl= e).<br> USB vs PCI is the same.=C2=A0 It should just be a single manpage for the dr= iver<br> regardless of the attachment.=C2=A0 If the driver has separate modules that= can<br> 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= <br> particular, the thing a user sees in dmesg is 'rtwn0', not 'rtw= n_pci0' so<br> the manpage needs to be tied to what a user sees as a device name in dmesg.= <br></blockquote><div><br></div><div>Yea, the man page should mention the d= etail that we have separate .ko's, but</div><div>otherwise I agree with= John here.</div><div><br></div><div>Warner=C2=A0</div></div></div> --0000000000009bf715062f874f5e--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfpos8fqO7a=k96K_SiFwGQ9HijcWayeYOjcJQM35P=gVQ>