From owner-freebsd-arch@freebsd.org Thu Feb 11 02:10:40 2021 Return-Path: Delivered-To: freebsd-arch@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 5407F534DE2 for ; Thu, 11 Feb 2021 02:10:40 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: from mailman.nyi.freebsd.org (mailman.nyi.freebsd.org [IPv6:2610:1c1:1:606c::50:13]) by mx1.freebsd.org (Postfix) with ESMTP id 4Dbg8J0Mktz4X34 for ; Thu, 11 Feb 2021 02:10:40 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: by mailman.nyi.freebsd.org (Postfix) id 0C8E6534DE1; Thu, 11 Feb 2021 02:10:40 +0000 (UTC) Delivered-To: arch@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 0C57A534EA5 for ; Thu, 11 Feb 2021 02:10:40 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: from gold.funkthat.com (gate2.funkthat.com [208.87.223.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "gate2.funkthat.com", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dbg8H6B2Lz4X0F for ; Thu, 11 Feb 2021 02:10:39 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: from gold.funkthat.com (localhost [127.0.0.1]) by gold.funkthat.com (8.15.2/8.15.2) with ESMTPS id 11B2AaFV045699 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Wed, 10 Feb 2021 18:10:36 -0800 (PST) (envelope-from jmg@gold.funkthat.com) Received: (from jmg@localhost) by gold.funkthat.com (8.15.2/8.15.2/Submit) id 11B2Aa8o045698; Wed, 10 Feb 2021 18:10:36 -0800 (PST) (envelope-from jmg) Date: Wed, 10 Feb 2021 18:10:36 -0800 From: John-Mark Gurney To: Warner Losh Cc: "freebsd-arch@freebsd.org" Subject: Re: adding a sysctl man section Message-ID: <20210211021036.GG31099@funkthat.com> Mail-Followup-To: Warner Losh , "freebsd-arch@freebsd.org" References: <20210211001505.GF31099@funkthat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Operating-System: FreeBSD 11.3-STABLE amd64 X-PGP-Fingerprint: D87A 235F FB71 1F3F 55B7 ED9B D5FF 5A51 C0AC 3D65 X-Files: The truth is out there X-URL: https://www.funkthat.com/ X-Resume: https://www.funkthat.com/~jmg/resume.html X-TipJar: bitcoin:13Qmb6AeTgQecazTWph4XasEsP7nGRbAPE X-to-the-FBI-CIA-and-NSA: HI! HOW YA DOIN? can i haz chizburger? User-Agent: Mutt/1.6.1 (2016-04-27) X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (gold.funkthat.com [127.0.0.1]); Wed, 10 Feb 2021 18:10:36 -0800 (PST) X-Rspamd-Queue-Id: 4Dbg8H6B2Lz4X0F X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[] X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Feb 2021 02:10:40 -0000 Warner Losh wrote this message on Wed, Feb 10, 2021 at 18:37 -0700: > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney wrote: > > > Inspired by: https://twitter.com/michaeldexter/status/1359614809365311490 > > > > I realized that we could/should create a new sysctl section. My initial > > thought was section s, but I'd be open for other recommendations. > > > > Then, any page that describes a sysctl, would add an MLINK to it: > > MLINK+= xhci.4 hw.usb.xhci.debug.s > > > > This section would be added to the default search, and then users > > would simply be able to type: man and get directed to the > > page that has information about it. > > > > Any objections? > > I think adding the sysctl to the man page is great. > > However, I have a concern about the links: > > % sysctl -a | wc > 38632 78349 1423715 Since the links are stored in inodes (because they should be small), we're looking at maybe a 5MB of additional storage, assuming we manage to get all 38k unique links... We already have 11k man pages + links, of which only 4k are uniq.. root@test:/usr/share/man # find . -type f | wc 11306 11306 286610 root@test:/usr/share/man # find . -type f -ls | awk '{ print $1 }' | sort -u | wc -l 4014 Also, it is doubtful that we'd even come close to having 50% coverage of those nodes in the coming years... > This suggests a lot of links if this idea were to be fully populated > (though maybe not 30k) If we follow delphij's suggestion of doing only the most relevant parent node, this would reduce the count, but would require extra code to handle looking up the parent until one is found... Each root sysctl node would then also linkly need their own page so that when someone looks up a completely undocumented sysctl, the have a place to start... > Also, how do you document things like the dev hierarchy which has a unit > number tossed into the middle? > > dev.uhub.1.%parent: usbus1 > dev.uhub.1.%pnpinfo: > dev.uhub.1.%location: > dev.uhub.1.%driver: uhub > dev.uhub.1.%desc: 0x1022 XHCI root HUB, class 9/0, rev 3.00/1.00, addr 1 > dev.uhub.0.disable_port_power: 0 > dev.uhub.0.disable_enumeration: 0 > dev.uhub.0.%domain: 0 > dev.uhub.0.%parent: usbus0 > dev.uhub.0.%pnpinfo: > dev.uhub.0.%location: > dev.uhub.0.%driver: uhub > > Also, all the nodes have the %parent, %pnp, %location, %driver and %desc > nodes. Those are provided by newbus, while everything else is dependent on > the driver... Well, likely a user would hopefully just look at dev.uhub... Also, every dev should have a man page, and hopefully our users are smart enough to be able to type: man uhub, or what ever dev name follows dev, but that uhub.4 doesn't exist is part of the problem... if uhub(4) existed, it should list all the sub sysctl nodes that it adds, and to handle the newbus generic nodes, link to a man page that describs them.. I did a quick grep and couldn't find anywhere where %parent was documented in the FreeBSD man pages... So yet more documentation that needs to be written... (and this means that your 38k number is likely way large since it includes lots of these lines which will be served by a single entry)... -- John-Mark Gurney Voice: +1 415 225 5579 "All that I will do, has been done, All that I have, has not."