From nobody Fri Mar 7 20:19:36 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 4Z8d1T4Q7Xz5q6BJ; Fri, 07 Mar 2025 20:19:41 +0000 (UTC) (envelope-from bz@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Z8d1T3VRTz47hj; Fri, 07 Mar 2025 20:19:41 +0000 (UTC) (envelope-from bz@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1741378781; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=XZ1veZjraIY8cuof0G5SSMqLX9fwtKvFB2a7+QpoTAA=; b=ouxUnOJqRRcVdHt5T4sKQr8Gi/wXj82C39GtPVta3syqtE5GxhAhDHFYSFFdWmFugQYuUE aexcNe8e1xlcF01dFKYPT8f3Dc0imYURlWs5aKLj0/P5tkGxWpM+n8FK7e06lwlU12UDQs sUl0EONAqHzorvWELiWHYGVMLONWBgcYOJOCXcivwzAfPIULAHDUw9eedimHPhfoWOv7se 4+QVaUtiYGvfHXt0UwhZhOmdhhbPSceOaHwkmjDj8kxhf3wxHF515gMyb8PDeVRMNHBdHV 86D14lcbhAGbrQpB5XtN44qqPsJqUJEMvX0bn4VJQYqiZjavwV7jzuSJT1/zQw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1741378781; a=rsa-sha256; cv=none; b=UuyRMEkWLFdhGog43hrc/Pce7ydYsVT1vowEGG7pJbeceT7tbdja0gGsyzJuDeLetTwOhx ofudwTtBHwzxeWDONvDuBjjIL2ANFCBBnfy1XQgQqagzWtCC526bQARn2PlZw7KQBbYeTz yWS35gTRDc0ZCuNtjuduC7EJsh/7KRfg7grD+ZkfOfrOSigctNFAuz+ogIoliRJ7VPUz3M 0G8c3siU3qEXhxuJjLwXKyvCGwVISCQkONbdlZgZbBfVeSgInvdsHKO9XgaMpDaCogi+YH mYLxGO4zv3JjEOgPs6jhrsaae1wirqeIGmIQevTy47kaHqyPyUN9Jbw/jxDwvA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1741378781; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=XZ1veZjraIY8cuof0G5SSMqLX9fwtKvFB2a7+QpoTAA=; b=rOBQnVg/AkolYIMQ/NqfOHCnsiMMpOF2r7mgqdBHqRIq4kZn5OFqEU4Dfgr22KekXgdts6 Mct6URNevf8ImHTY0RsAXScqo8jOtV5rjRi1VvZHCNJtQOi1ZroQzG/mZKJ6W+IU6BsuNm ZOi3h+5Bh2kgFRiXHdtKfel/jDtZLkGKHZxUqLDhZEUVIzcvW4hzpc/sny5hFl6vofydld bt1opjerDoF5Qn8TS1F3nSgxaXlZcb0iOCqaQ511Thgyw3bQcg3Wwc6hXBG/laSpLhgtxO Ng7qsS/8t6Ho3TuSD/MBZbEaQHIlpuRrAvQmeGOdQDmEUnRJ5luLpHSYAryMvw== Received: from mx-01.divo.sbone.de (mx-01.divo.sbone.de [IPv6:2003:a:140a:2200:6:594:fffe:19]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature ECDSA (prime256v1) client-digest SHA256) (Client CN "mx-01.divo.sbone.de", Issuer "E5" (verified OK)) (Authenticated sender: bz/mail) by smtp.freebsd.org (Postfix) with ESMTPSA id 4Z8d1T0hVBzLgK; Fri, 07 Mar 2025 20:19:41 +0000 (UTC) (envelope-from bz@freebsd.org) Received: from mail.sbone.de (mail.sbone.de [IPv6:fde9:577b:c1a9:4902:0:7404:2:1025]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by mx-01.divo.sbone.de (Postfix) with ESMTPS id 20325A64805; Fri, 07 Mar 2025 20:19:36 +0000 (UTC) Received: from content-filter.t4-02.sbone.de (content-filter.t4-02.sbone.de [IPv6:fde9:577b:c1a9:4902:0:7404:2:2742]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mail.sbone.de (Postfix) with ESMTPS id AA6802D029E0; Fri, 7 Mar 2025 20:19:38 +0000 (UTC) X-Virus-Scanned: amavisd-new at sbone.de Received: from mail.sbone.de ([IPv6:fde9:577b:c1a9:4902:0:7404:2:1025]) by content-filter.t4-02.sbone.de (content-filter.t4-02.sbone.de [IPv6:fde9:577b:c1a9:4902:0:7404:2:2742]) (amavisd-new, port 10024) with ESMTP id bSxYNEkTzy8E; Fri, 7 Mar 2025 20:19:37 +0000 (UTC) Received: from strong-rtwn0.sbone.de (strong-rtwn0.sbone.de [IPv6:fde9:577b:c1a9:4902:da44:89ff:fedd:d5ab]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mail.sbone.de (Postfix) with ESMTPSA id D6FAF2D029D8; Fri, 7 Mar 2025 20:19:36 +0000 (UTC) Date: Fri, 7 Mar 2025 20:19:36 +0000 (UTC) From: "Bjoern A. Zeeb" To: Alexander Ziaee cc: Warner Losh , John Baldwin , "Herbert J. Skuhra" , src-committers , dev-commits-src-all , dev-commits-src-main , Christos Margiolis Subject: Re: git: 4262dbc57982 - main - wifi manuals: Mlink + document description consistency In-Reply-To: Message-ID: <317ns91s-q982-7o54-r0sq-n805p6sqo297@serrofq.bet> References: X-OpenPGP-Key-Id: 0x14003F198FEFA3E77207EE8D2B58B8F83CCF1842 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 Content-Type: multipart/mixed; boundary="1098556516-1832358758-1741378777=:4001" This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. --1098556516-1832358758-1741378777=:4001 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8BIT On Thu, 6 Mar 2025, Alexander Ziaee wrote: > On 2025-03-04 12:07 -05:00 EST, "Warner Losh" wrote: >> On Tue, Mar 4, 2025 at 8:23 AM 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=4262dbc57982383eb61a8b7806de6dd4b7802da8 >>>>>> >>>>>> 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", 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. > > IIUC, all interfaces should be documented as $foo with an mlink (but no additional > name macro) to if_$foo. I've also been pushing for sound to become represented > the same way for consistency, which christos said (paraphrased) no objection. So someone should comment out/remove the old entry in ObsoleteFiles.inc so that the new man page is not deleted again? -- Bjoern A. Zeeb r15:7 --1098556516-1832358758-1741378777=:4001--