On Tue, Mar 4, 2025 at 8:23 AM John Baldwin <j...@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=4262dbc57982383eb61a8b7806de6dd4b7802da8 > >>> > >>> commit 4262dbc57982383eb61a8b7806de6dd4b7802da8 > >>> Author: Alexander Ziaee <zi...@freebsd.org> > >>> AuthorDate: 2025-02-19 15:54:27 +0000 > >>> Commit: Alexander Ziaee <zi...@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", except > 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+=ptnet.4 if_ptnet.4 > >>> MLINKS+=ral.4 if_ral.4 > >>> MLINKS+=re.4 if_re.4 > >>> MLINKS+=rl.4 if_rl.4 > >>> -MLINKS+=rtwn_pci.4 if_rtwn_pci.4 > >>> +MLINKS+=rtw88.4 if_rtw89.4 > >>> +MLINKS+=rtw89.4 if_rtw89.4 > >>> +MLINKS+=rtwn.4 if_rtwn.4 > >> ^^^^^^^^^ > >> $ grep if_rtwn.4 ObsoleteFiles.inc > >> OLD_FILES+=usr/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 know > > better). > > > > But everyone is just referring to the driver as rtwn and I fear if there > > 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 driver > regardless of the attachment. If the driver has separate modules that can > 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 dmesg. > Yea, the man page should mention the detail that we have separate .ko's, but otherwise I agree with John here. Warner
