From owner-freebsd-arch@freebsd.org Sat Feb 13 20:45:08 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 697FC53A9D2 for ; Sat, 13 Feb 2021 20:45:08 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DdMnH6w9Lz3JWD for ; Sat, 13 Feb 2021 20:45:07 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: by mailman.nyi.freebsd.org (Postfix) id ED5F053ACE4; Sat, 13 Feb 2021 20:45:07 +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 ED1DC53ACE3 for ; Sat, 13 Feb 2021 20:45:07 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from wnew1-smtp.messagingengine.com (wnew1-smtp.messagingengine.com [64.147.123.26]) (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 did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4DdMnH5cDJz3Jsn for ; Sat, 13 Feb 2021 20:45:07 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from compute6.internal (compute6.nyi.internal [10.202.2.46]) by mailnew.west.internal (Postfix) with ESMTP id 68AB2953; Sat, 13 Feb 2021 15:45:05 -0500 (EST) Received: from mailfrontend1 ([10.202.2.162]) by compute6.internal (MEProxy); Sat, 13 Feb 2021 15:45:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yuripv.dev; h= subject:to:cc:references:from:message-id:date:mime-version :in-reply-to:content-type:content-transfer-encoding; s=fm1; bh=1 +GpMi8IeeE4+CEAIbeJ3ndgkk9ikyj8+6oxYfMkrdw=; b=AoyLE9prcqSQ1YgEP HVqfEzUJ70taAfYBDWWNKjVLwVRDgNTjMahi8IkDUVDkKqulbTa4sD221513V8SV tg3k1JT8cHdzJCnR3oF6gsyqgn5vNQmD55gTUUjm5T06VPHlxtUZumiJko89oENJ fvFDlznVHG2TDOMzhYrj0ehtqxG7OF0URnv+zX3z8ZkGDKq+WxrDLnU+Qnu1O21I HzXO1Ks3Uajm/znEDCIvcDZ/2MTcPAR2KxVAok9/234YjuUV5QYDZ0jwyYED3RrT ChXDa99t2Bt6X41lrBelRIlSSHSxmkovSW8gaPCe1dEV8wX4QKTTy0ZzW/7xtaW3 5QvPA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm2; bh=1+GpMi8IeeE4+CEAIbeJ3ndgkk9ikyj8+6oxYfMkr dw=; b=QI/DFRvFFNZx9Q1i6ADeAXZOZ1BGw5y9YCCKyGGlla7tsebUtjPxmScQl E1zEQTod9ZHeat2/UK8BSdtytXAyxAABn7iLdEICpWMUwGdU7lLDCycaKoDiConH jK1+32/d5EFhdgyJhg9oJGt0l69FYzxBEgjHpH13FeUmEAg6xcUbAsnue0KUm4Dx bQfJB1qo+4cqypncWtihSDCbOor/m8UQ58s9dpnIck+NhTbfEaNRsY+LCmYfPegy kYgdjdeusI8J/pndEEfHCPq8m2EQV7sFiqU+MSRA8cCZlVMpoSMmZujXMxKMcplk 4+30WcuJHj8vl+pTAEJgxoI/C+6mw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrieefgddufeejucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefuvfhfhffkffgfgggjtgfgsehtje ertddtfeejnecuhfhrohhmpegjuhhrihcurfgrnhhkohhvuceohihurhhiphhvseihuhhr ihhpvhdruggvvheqnecuggftrfgrthhtvghrnhepvddvueehhfekleffudeifffffeevvd duleekjedttddvleelgefgteeljeduueefnecuffhomhgrihhnpehtfihithhtvghrrdgt ohhmpdhfrhgvvggsshgurdhorhhgpdhfohhrrdhvrgenucfkphepledurddvgedtrdduvd egrddufeejnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhho mhephihurhhiphhvseihuhhrihhpvhdruggvvh X-ME-Proxy: Received: from [192.168.1.6] (unknown [91.240.124.137]) by mail.messagingengine.com (Postfix) with ESMTPA id BA06024005C; Sat, 13 Feb 2021 15:45:03 -0500 (EST) Subject: Re: adding a sysctl man section To: Warner Losh Cc: "freebsd-arch@freebsd.org" References: <20210211001505.GF31099@funkthat.com> From: Yuri Pankov Message-ID: Date: Sat, 13 Feb 2021 23:45:01 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.7.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4DdMnH5cDJz3Jsn 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: Sat, 13 Feb 2021 20:45:08 -0000 Warner Losh wrote: > On Sat, Feb 13, 2021 at 8:09 AM Yuri Pankov wrote: > >> Yuri Pankov wrote: >>> 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 like the idea of documenting the sysctls, not the implementation idea >>> though -- MLINKS are clutter, and we already have the tooling to drop >>> them entirely, in base at least (that's something for another time >>> though), as all the metadata we need is in man pages and stored in >>> makewhatis (mandocdb) database. >>> >>> I have put up simple PoC introducing new mdoc macro (.Sl, could be .Ctl >>> or anything else not taken, doesn't matter much) specifically for >>> sysctls, and implementing Sl keyword search as last resort in man(1). >>> The idea is that .Sl would have the special meaning only when found in >>> SYNOPSIS section (not implemented yet, trivial), and could (should) be >>> extended to provide type, r/o flag, alias flag for when we want sysctl >>> to be searchable, but not displayed (e.g. for ioscheduler items Warner >>> mentioned), and anything else I missed. >>> >>> The downside here is the addition of new macro, I guess we would have to >>> somehow standardize it so that reading FreeBSD man pages on other >>> systems would render at least something sensible; I don't think it's >>> that big problem though. >>> >>> Code is here: https://reviews.freebsd.org/D28642, there isn't lot to >>> comment on yet, but it's already somewhat working with the xhci.4 man >>> page modified to include .Sl: >> [...] >> >> Or, if adding new macro is really undesirable, we could do with what we >> already have and have special meaning for .Va/.Vt in "SYSCTL VARIABLES" >> section depending on that section being consistent throughout the tree. >> The idea stays the same though -- don't use MLINKS, rather embed >> metadata in man pages and let existing man tools do the rest. >> >> One thing I missed are the variables with unit numbers, these should be >> trivial as well once we agree on wildcard symbols to use ('#'?). >> > > Can you do one man page each way so we can (a) see the markup and (b) see > what the other tools do? No changes other than properly defining the variables in their respective sections should be needed, see below, but I'd say those should be done anyway. > I rather like this idea. I like the idea of looking for the sysctl 'fred' > and being able to know that this is a kern.cam.da.0.fred vs hw.mpr.fred vs > dev.mpr.0.fred vs vfs.foofs.fred without crazy gymnastics for dealing with > thousands of additions to the tree. > > I tend to agree on symlinks, btw, but that implementation detail we should > table until we work out if similar means can achieve similar or better > results. I have updated the review at https://reviews.freebsd.org/D28642 implementing the .Va idea which turned out to be much better and easier than introducing new macro. The requirements are that all tunables should be in their respective sections, loader ones in "LOADER TUNABLES" and sysctl ones in "SYSCTL VARIABLES" (names should be exact as already found in a lot of man pages, diff fixes ixl.4 as an example). Usage is e.g. `man hw.usb.xhci.debug` or fixed `man hw.ixl.rx_itr`. This does not yet implement the special handling for wildcards as those differ between man pages (ones that I found are '%s' for string, '%d' or '#' for numbers), but should be easy to do as well once agreed on format. At the moment, this works for ~300 sysctl names out of ~14000 found on my system.