From owner-freebsd-arch@freebsd.org Sat Feb 13 07:22:07 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 D913B542F4F for ; Sat, 13 Feb 2021 07:22:07 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qv1-xf32.google.com (mail-qv1-xf32.google.com [IPv6:2607:f8b0:4864:20::f32]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dd1yl5fkLz3NcR for ; Sat, 13 Feb 2021 07:22:07 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qv1-xf32.google.com with SMTP id q8so894183qvx.11 for ; Fri, 12 Feb 2021 23:22:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bsdimp-com.20150623.gappssmtp.com; s=20150623; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=CZvA1LH1eGLb4kH939Yul0ZpVHAKshlrOqQXIgZCdLo=; b=EJY/b4nC/Tf9nz4dIiDzNmwvFCLEU99oZoFi0rPwMwFEQ2rGC0eaejkm1+ftkokDmq S1cxELd/vclh4BTIAecMq+UrTnJAABlvgV+seXrrRIa1vfa1eFO/q7MWCAGXIVNpXxN7 KDOh94/oypyJ9CHdz4e9YgcxwucVqdJJXc8ALTk/oaxmpPDUFceh4iEcs2jVzkMQQ2Dc DlduzeaYcI49efgMdTEFDwMes6qyj1n0EsP8uHN1moUUdhxrzR+CE49nHyFEeeQ1nzKV PkyhPtj10kZoTFXbZY+LSaQdmiyYiFUzCLDVBakfnmuSFvivZyGUtF6hIQducAFEF1iO W36A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=CZvA1LH1eGLb4kH939Yul0ZpVHAKshlrOqQXIgZCdLo=; b=p6+i/nQBh0svishg0PRHTlByGIFpF739HsJpRX8xAkMcFIA7VmUhmHCNAuAfzKhtHQ IKikoTo4WgY7DXrmEchnu+qSGllLMMWqQuiFEj5D05sQRSuKxX8nxZkreKiF+Sjcmio7 aV09bplKlq7hK/3FOyU/IZOL/i2wdCQTvp78TqsVmlnCDU9zwVr/rpg9vClkazzxhgB5 7awIlD8gdQav5oBb7/SORVSx8eNu7Ss+QNmaRSfiaxO6uEeES7+Fur93970kb/yXGN1r Di/yh7X4yGOm8qM/QwPX4b7O1V0Li2CcitTZUUjujUBfAtU3Z0iDSLTB67cFiSCdztEK yt2g== X-Gm-Message-State: AOAM530IOWUqeX7zTVZ4erepRqFFt82ljmpClu69VCSxCIECSPsa6KAC gQ0Jw0wnLhCGuVuynL7ffS0BwdumI3G+TYYIiVCHmhsHoXxxtQ== X-Google-Smtp-Source: ABdhPJwQgbTpdVb8nNTMoXLBVBaeJE4/2db1U4Uy3bFpQ0/W6fNPClXm2LAz6BWeLOUYkiQNljE4Kbr+kLpPdhTKEbU= X-Received: by 2002:ad4:576a:: with SMTP id r10mr5883920qvx.29.1613200926068; Fri, 12 Feb 2021 23:22:06 -0800 (PST) MIME-Version: 1.0 References: <20210211001505.GF31099@funkthat.com> <936bc860-c61d-ecc3-8e3f-496684bad68a@FreeBSD.org> In-Reply-To: <936bc860-c61d-ecc3-8e3f-496684bad68a@FreeBSD.org> From: Warner Losh Date: Sat, 13 Feb 2021 00:21:55 -0700 Message-ID: Subject: Re: adding a sysctl man section To: John Baldwin Cc: "freebsd-arch@freebsd.org" X-Rspamd-Queue-Id: 4Dd1yl5fkLz3NcR X-Spamd-Bar: ---- Authentication-Results: mx1.freebsd.org; none X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[] Content-Type: text/plain; charset="UTF-8" X-Content-Filtered-By: Mailman/MimeDel 2.1.34 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 07:22:07 -0000 On Fri, Feb 12, 2021 at 1:14 PM John Baldwin wrote: > On 2/10/21 4: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 since they are MLINKs, just have them live in the section of the > thing they are linking to. That is, if it is for foo.4, have it live > in section 4. If it's a sysctl that's documented as part of a syscall > (bar.2), have that MLINK live in section 2. This is how all the other > MLINKs work rather than needing a new section. > I agree. To the extent we do this, they should be in the same section. I still think that having thousands of symlinks is getting out of hand, but I'm open for experimentation here... > Does this meaning adding sysctl nodes as .Nm entries in the NAME section? > I'm torn on this. That would make apropos(1) or man -k more useful, but on the other hand, there's some devices that have dozens of sysctls that could get messy without a good plan. The alternative would be to have something new that wasn't in the NAME section that could appear in man -k. > I'm also a bit curious how to name per-instance sysctls vs global sysctls > (hw.cxgbe.* vs dev.cxgbe.N.*) as Warner mentioned. The global ones are > easy, > the per-instance ones would warrant some sort of consistent pattern. > Me too. I'm starting to think that the best place to start for some of these things would be hw.gxgbe and dev.cxgbe would be symlinks to cxgbe.4. And if we went this way, having only two .nm wouldn't be horrible. But it would limit the usefulness of finding some sysctls. kern.*, vm.* become more troublesome, but even here the pattern at least half works: kern.cam.da, already documented in da(4) at least in part, could be symlinks. However, the ioscheduler creates a bunch of additional items for all devices in the system support it, leading to kern.cam.da.iosched, kern.cam.ada.iosched, kern.cam.nda.iosched, atll being symlinks, even though it's really kern.cam.da.0.iosched.. Warner