From owner-freebsd-arch@freebsd.org Sun Feb 7 04:26:52 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 D3EF5547290 for ; Sun, 7 Feb 2021 04:26:52 +0000 (UTC) (envelope-from bapt@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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DYGMJ5TzFz3PsC; Sun, 7 Feb 2021 04:26:52 +0000 (UTC) (envelope-from bapt@FreeBSD.org) Received: from ivaldir.etoilebsd.net (etoilebsd.net [178.32.217.76]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) (Authenticated sender: bapt) by smtp.freebsd.org (Postfix) with ESMTPSA id 964195FBD; Sun, 7 Feb 2021 04:26:52 +0000 (UTC) (envelope-from bapt@FreeBSD.org) Received: by ivaldir.etoilebsd.net (Postfix, from userid 1001) id C5EB21378C0; Sun, 7 Feb 2021 05:26:51 +0100 (CET) Date: Sun, 7 Feb 2021 05:26:51 +0100 From: Baptiste Daroussin To: Kyle Evans Cc: "freebsd-arch@freebsd.org" , Brooks Davis Subject: Re: Deprecate/remove fmtree(8)? Message-ID: <20210207042651.t2ai2nna4tx7uzhf@ivaldir.net> References: MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="nqcvyjkvaqimyslu" Content-Disposition: inline In-Reply-To: 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: Sun, 07 Feb 2021 04:26:52 -0000 --nqcvyjkvaqimyslu Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Feb 06, 2021 at 03:37:30PM -0600, Kyle Evans wrote: > Hi, >=20 > I was reviewing build options, and noticed that we're still building > and installing fmtree by default. >=20 > Brooks imported nmtree about 8 years ago, made it the default about 7 > years ago. Since then, fmtree has seen approximately ~0 work besides > build fixes from tangentially related work or fixes for bugs that > nmtree inherited from fmtree. >=20 > Is anyone actually using this? This feels like a pretty clear case of > maintenance burden at a glance... >=20 > Thanks, >=20 Yes please! This was on my todo list, happy to see someone else doing it ;) Best regards, Bapt --nqcvyjkvaqimyslu Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEgOTj3suS2urGXVU3Y4mL3PG3PloFAmAfbAsACgkQY4mL3PG3 PlpfwhAAnUkO8pBzh+V9qlUe4AN9kDzkNci4riwlapygRDFjTwRSOQpTWvjPyVDP GCh6KdNKlY7tEMF/HoRHOioOxLBSwQqBGKw1HDIK/rMzsb0WaxgodsuO80+hI1Ud drt8AzVegTKWuOU4m7U38+oz5azhpG/w8bsK2lpaYAcafKs+3KafYexfH2UM2xSz 6JKJNbFRb8ezjVwHhkHIAH2WPVAUh+EYQmAdL/r+2eSrOc7eHo8lr01tnIzsAYMY LXvF7DgeFnNXpY+EhgazeAle4/MCY5CoXZuMgHpdd6GOuv588ADZb3x+e+IcQGms SCCfZqe3srlrYyBUZ4s9WL2djshAxzGPw1K4g31ryoLxCdK31bSNCvEyBX3UUaaN ATvM9SKcAAJaUVAsnR9Xl4QzgiVCMX1uqhrO0qXbcqcJxtRo5oIVRfCMbJ+JHzoG k1er1pfkZp6TMGWupTn3KSHwRZiO+J2NGaNqd+eGpV9kVoZrIbNRYsm9HQff46vY nl5W9UhSDqBY+Vi3MNlEceTzIrhYzFqux7BuLNozBDjhqRgV3g4l3EwoLysVT+P2 vBdIH3Lag8lSXgTE+7uUjr5fix2OkmIOo6073WzffMO3IBs3T29lKQRCPqiNAReE d7bMXQ0h6zrH+g5Icy+ZY+pnsoybDcbt8Fs+qm7HVSf8YnxCHYM= =+9SG -----END PGP SIGNATURE----- --nqcvyjkvaqimyslu-- From owner-freebsd-arch@freebsd.org Wed Feb 10 15:19:26 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 A086F549A2B for ; Wed, 10 Feb 2021 15:19:26 +0000 (UTC) (envelope-from kevans@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DbNht3j51z4bpr for ; Wed, 10 Feb 2021 15:19:26 +0000 (UTC) (envelope-from kevans@freebsd.org) Received: from mail-qk1-f178.google.com (mail-qk1-f178.google.com [209.85.222.178]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) (Authenticated sender: kevans) by smtp.freebsd.org (Postfix) with ESMTPSA id 6D018CD1E for ; Wed, 10 Feb 2021 15:19:26 +0000 (UTC) (envelope-from kevans@freebsd.org) Received: by mail-qk1-f178.google.com with SMTP id x14so1960497qkm.2 for ; Wed, 10 Feb 2021 07:19:26 -0800 (PST) X-Gm-Message-State: AOAM533FsU6uk68sVx5hIsdpYbh94S5ttaYEPhNqpV6iZntdzwg38eWA oY6eaWNimI1fIw0tH3X7qdA2EcWWb3XpWUPp4Qw= X-Google-Smtp-Source: ABdhPJz8TDlqNqU/gJTlbP/0m6jA84SSmhhQE2xJ2jDzLn1sqCjg0+Bm8qBzOZ/eR2YtmaJSgZ1erbufwJffUr9v03E= X-Received: by 2002:a05:620a:b8a:: with SMTP id k10mr4080573qkh.120.1612970366057; Wed, 10 Feb 2021 07:19:26 -0800 (PST) MIME-Version: 1.0 References: In-Reply-To: From: Kyle Evans Date: Wed, 10 Feb 2021 09:19:12 -0600 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: Deprecate/remove fmtree(8)? To: "freebsd-arch@freebsd.org" Content-Type: text/plain; charset="UTF-8" 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: Wed, 10 Feb 2021 15:19:26 -0000 On Sat, Feb 6, 2021 at 3:37 PM Kyle Evans wrote: > > Hi, > > I was reviewing build options, and noticed that we're still building > and installing fmtree by default. > > Brooks imported nmtree about 8 years ago, made it the default about 7 > years ago. Since then, fmtree has seen approximately ~0 work besides > build fixes from tangentially related work or fixes for bugs that > nmtree inherited from fmtree. > > Is anyone actually using this? This feels like a pretty clear case of > maintenance burden at a glance... > The only feedback I've received from this is Baptiste's "Yes!", so I've staged a review here for a deprecation notice and turning off the option by default: https://reviews.freebsd.org/D28573 Thanks, Kyle Evans From owner-freebsd-arch@freebsd.org Thu Feb 11 00:15:13 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 0A49352F0E2 for ; Thu, 11 Feb 2021 00:15:13 +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 4Dbcb45y3Sz3mRS for ; Thu, 11 Feb 2021 00:15:12 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: by mailman.nyi.freebsd.org (Postfix) id CA8CC52F694; Thu, 11 Feb 2021 00:15:12 +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 CA4A652F0E1 for ; Thu, 11 Feb 2021 00:15:12 +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 4Dbcb35XHzz3mP4 for ; Thu, 11 Feb 2021 00:15:08 +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 11B0F5tO037540 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO) for ; Wed, 10 Feb 2021 16:15:06 -0800 (PST) (envelope-from jmg@gold.funkthat.com) Received: (from jmg@localhost) by gold.funkthat.com (8.15.2/8.15.2/Submit) id 11B0F58S037539 for arch@FreeBSD.org; Wed, 10 Feb 2021 16:15:05 -0800 (PST) (envelope-from jmg) Date: Wed, 10 Feb 2021 16:15:05 -0800 From: John-Mark Gurney To: arch@FreeBSD.org Subject: adding a sysctl man section Message-ID: <20210211001505.GF31099@funkthat.com> Mail-Followup-To: arch@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline 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 16:15:06 -0800 (PST) X-Rspamd-Queue-Id: 4Dbcb35XHzz3mP4 X-Spamd-Bar: - Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=none (mx1.freebsd.org: domain of jmg@gold.funkthat.com has no SPF policy when checking 208.87.223.18) smtp.mailfrom=jmg@gold.funkthat.com X-Spamd-Result: default: False [-1.80 / 15.00]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; FREEFALL_USER(0.00)[jmg]; FROM_HAS_DN(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[208.87.223.18:from]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MID_RHS_MATCH_FROM(0.00)[]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; TO_DN_NONE(0.00)[]; AUTH_NA(1.00)[]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[208.87.223.18:from:127.0.2.255]; DMARC_NA(0.00)[funkthat.com]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_SHORT(-1.00)[-1.000]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; R_SPF_NA(0.00)[no SPF record]; FORGED_SENDER(0.30)[jmg@funkthat.com,jmg@gold.funkthat.com]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:32354, ipnet:208.87.216.0/21, country:US]; FROM_NEQ_ENVFROM(0.00)[jmg@funkthat.com,jmg@gold.funkthat.com]; MAILMAN_DEST(0.00)[arch]; RCVD_COUNT_TWO(0.00)[2] 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 00:15:13 -0000 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? -- John-Mark Gurney Voice: +1 415 225 5579 "All that I will do, has been done, All that I have, has not." From owner-freebsd-arch@freebsd.org Thu Feb 11 00:18:50 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 205D552F90F for ; Thu, 11 Feb 2021 00:18:50 +0000 (UTC) (envelope-from fuz@fuz.su) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DbcgF6m2Xz3mKW for ; Thu, 11 Feb 2021 00:18:49 +0000 (UTC) (envelope-from fuz@fuz.su) Received: by mailman.nyi.freebsd.org (Postfix) id E801C52F676; Thu, 11 Feb 2021 00:18:49 +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 E7CBB52F7E6 for ; Thu, 11 Feb 2021 00:18:49 +0000 (UTC) (envelope-from fuz@fuz.su) Received: from fuz.su (fuz.su [IPv6:2001:41d0:8:e508::1]) (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 (2048 bits) client-digest SHA256) (Client CN "amnesiac", Issuer "amnesiac" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DbcgF0qBnz3mbh for ; Thu, 11 Feb 2021 00:18:48 +0000 (UTC) (envelope-from fuz@fuz.su) Received: from fuz.su (localhost [127.0.0.1]) by fuz.su (8.16.1/8.16.1) with ESMTPS id 11B0IfdP065079 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO) for ; Thu, 11 Feb 2021 01:18:41 +0100 (CET) (envelope-from fuz@fuz.su) Received: (from fuz@localhost) by fuz.su (8.16.1/8.16.1/Submit) id 11B0Ifmv065078 for arch@freebsd.org; Thu, 11 Feb 2021 01:18:41 +0100 (CET) (envelope-from fuz) Date: Thu, 11 Feb 2021 01:18:41 +0100 From: Robert Clausecker To: arch@freebsd.org Subject: Re: adding a sysctl man section Message-ID: References: <20210211001505.GF31099@funkthat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210211001505.GF31099@funkthat.com> X-Rspamd-Queue-Id: 4DbcgF0qBnz3mbh X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of fuz@fuz.su designates 2001:41d0:8:e508::1 as permitted sender) smtp.mailfrom=fuz@fuz.su X-Spamd-Result: default: False [-3.30 / 15.00]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; MID_RHS_MATCH_FROM(0.00)[]; FROM_HAS_DN(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[2001:41d0:8:e508::1:from]; TO_MATCH_ENVRCPT_ALL(0.00)[]; R_SPF_ALLOW(-0.20)[+a]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; TO_DN_NONE(0.00)[]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[2001:41d0:8:e508::1:from:127.0.2.255]; DMARC_NA(0.00)[fuz.su]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_SHORT(-1.00)[-1.000]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:16276, ipnet:2001:41d0::/32, country:FR]; RCVD_COUNT_TWO(0.00)[2]; MAILMAN_DEST(0.00)[arch] 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 00:18:50 -0000 Why not add these to section 7 instead? The section is sparsely populated as is and those names with lots of dots in them are unlikely to collide. On second thought, no collisions would occur in section 4 either it seems. And since most of the links would go to section 4 anyway... Yours, Robert Clausecker Am Wed, Feb 10, 2021 at 04:15:05PM -0800 schrieb John-Mark Gurney: > 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? > > -- > John-Mark Gurney Voice: +1 415 225 5579 > > "All that I will do, has been done, All that I have, has not." > _______________________________________________ > freebsd-arch@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-arch > To unsubscribe, send any mail to "freebsd-arch-unsubscribe@freebsd.org" -- () ascii ribbon campaign - for an 8-bit clean world /\ - against html email - against proprietary attachments From owner-freebsd-arch@freebsd.org Thu Feb 11 01:37:13 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 D5178531F7E for ; Thu, 11 Feb 2021 01:37:13 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DbfPj4YT7z4SfX for ; Thu, 11 Feb 2021 01:37:13 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mailman.nyi.freebsd.org (Postfix) id 9C5A5531F7D; Thu, 11 Feb 2021 01:37:13 +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 9C23D531F7C for ; Thu, 11 Feb 2021 01:37:13 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qt1-x835.google.com (mail-qt1-x835.google.com [IPv6:2607:f8b0:4864:20::835]) (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 4DbfPh5P1vz4T2J for ; Thu, 11 Feb 2021 01:37:12 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qt1-x835.google.com with SMTP id h16so3087038qth.11 for ; Wed, 10 Feb 2021 17:37:12 -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; bh=AXIeM8ICuA67OgIhEc9rmekPyaHcr2whrdcqnhBTy08=; b=KX8bPgazWrZNU/ycI01F7y+hUos4D5uvINkII/IVHorOeiuZ8nwTGtAHaNZL+wjtSs cmcdvJ/vCQOSduGH5J2PEEcU8WBsKWLdO1WA5RjW3LmUfW+zIV+eoM3/AMhGXfPDeOzY yVyJTCFwSZEjc1lG03LX59ARoeeNShfG54myBDmGPv8ZPtVI7A0XSpvblMSNP78+pIBy XQS142pAN4u0Z5V41cpHuqMTK/lcm3fzBpCXm5qVn9ZCfiombEhKiBUYEZ8/3nQ+LMox hEzbQonCKPoxYy3mvE4XqbYVbqOaZ0kvpQFWQ/iSjNZLqdbAIYKQmU7wMgQl8rJw0oI0 kbYA== 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; bh=AXIeM8ICuA67OgIhEc9rmekPyaHcr2whrdcqnhBTy08=; b=uTreJvJs7NlUH7UxpVm/k9D69dBJu4kw5cYhovkkhRsHihGGICacarT7vzBLDp76/a 7PR35CR6gitfdbdKVY+nUKg7dPc1zVAimd8FvTnOClG6j3cmUEFRCiUwJWl7GTqsHKH6 TSuLjUjEOikA5VxwnQ0xqNRZCtPg2KN58R0JDlQuVg0plonXccJTQO2n11ts9YZwLJo7 S753Ag2RYOhw9k9oZ8HrIQV3v5MXCfs/sPK+H7rUON+6svdUAIwYyZDq5Nh7C1hGppxs ULj5OMnxAzQlP/NSHuhuUdpYiC+Qfz6TKGK6urcOkBeGj7I7KGAkcqUNIVh625qFocPa eLRA== X-Gm-Message-State: AOAM530hbrue7Dm/B/2VTRcvDoBuSjhQ8dXN6PVN3pK/FEJbuEch7tCP 7sPsb4cbnrH0FSe9G7Ne3Gq16yd4p+DZwC35FEWztoAfEGBcCkAw X-Google-Smtp-Source: ABdhPJwEOo5eWmJfGyj4CzfVX4rcKdAdpqjkiQ67reDqid4pbsLcN+TJFRWS2etLJ36iL0aGS9y1FGUyJQhS3v1jAKU= X-Received: by 2002:ac8:6c48:: with SMTP id z8mr5566496qtu.73.1613007431235; Wed, 10 Feb 2021 17:37:11 -0800 (PST) MIME-Version: 1.0 References: <20210211001505.GF31099@funkthat.com> In-Reply-To: <20210211001505.GF31099@funkthat.com> From: Warner Losh Date: Wed, 10 Feb 2021 18:37:00 -0700 Message-ID: Subject: Re: adding a sysctl man section To: "freebsd-arch@freebsd.org" X-Rspamd-Queue-Id: 4DbfPh5P1vz4T2J X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=bsdimp-com.20150623.gappssmtp.com header.s=20150623 header.b=KX8bPgaz; dmarc=none; spf=none (mx1.freebsd.org: domain of wlosh@bsdimp.com has no SPF policy when checking 2607:f8b0:4864:20::835) smtp.mailfrom=wlosh@bsdimp.com X-Spamd-Result: default: False [-3.00 / 15.00]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; R_DKIM_ALLOW(-0.20)[bsdimp-com.20150623.gappssmtp.com:s=20150623]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[multipart/alternative,text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; DMARC_NA(0.00)[bsdimp.com]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[2607:f8b0:4864:20::835:from:127.0.2.255]; TO_DN_ALL(0.00)[]; DKIM_TRACE(0.00)[bsdimp-com.20150623.gappssmtp.com:+]; NEURAL_HAM_SHORT(-1.00)[-1.000]; RCVD_IN_DNSWL_NONE(0.00)[2607:f8b0:4864:20::835:from]; R_SPF_NA(0.00)[no SPF record]; FORGED_SENDER(0.30)[imp@bsdimp.com,wlosh@bsdimp.com]; MIME_TRACE(0.00)[0:+,1:+,2:~]; RBL_DBL_DONT_QUERY_IPS(0.00)[2607:f8b0:4864:20::835:from]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; FROM_NEQ_ENVFROM(0.00)[imp@bsdimp.com,wlosh@bsdimp.com]; MAILMAN_DEST(0.00)[arch]; RCVD_COUNT_TWO(0.00)[2] 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: Thu, 11 Feb 2021 01:37:13 -0000 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 This suggests a lot of links if this idea were to be fully populated (though maybe not 30k) 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... Warner > -- > John-Mark Gurney Voice: +1 415 225 5579 > > "All that I will do, has been done, All that I have, has not." > _______________________________________________ > freebsd-arch@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-arch > To unsubscribe, send any mail to "freebsd-arch-unsubscribe@freebsd.org" > 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." From owner-freebsd-arch@freebsd.org Thu Feb 11 07:55:26 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 0C7F053DEE7 for ; Thu, 11 Feb 2021 07:55:26 +0000 (UTC) (envelope-from lutz@iks-jena.de) 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 4Dbpp55m8jz4sn4 for ; Thu, 11 Feb 2021 07:55:25 +0000 (UTC) (envelope-from lutz@iks-jena.de) Received: by mailman.nyi.freebsd.org (Postfix) id C5AEB53DEE5; Thu, 11 Feb 2021 07:55:25 +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 C573753DEE4 for ; Thu, 11 Feb 2021 07:55:25 +0000 (UTC) (envelope-from lutz@iks-jena.de) Received: from annwfn.iks-jena.de (annwfn.iks-jena.de [IPv6:2001:4bd8::19]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dbpp53sMYz4sc8 for ; Thu, 11 Feb 2021 07:55:25 +0000 (UTC) (envelope-from lutz@iks-jena.de) X-SMTP-Sender: IPv6:2001:4bd8:0:666:248:54ff:fe12:ee3f Received: from belenus.iks-jena.de (belenus.iks-jena.de [IPv6:2001:4bd8:0:666:248:54ff:fe12:ee3f]) by annwfn.iks-jena.de (8.15.2/8.15.2) with ESMTPS id 11B7svIr007019 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Thu, 11 Feb 2021 08:54:57 +0100 X-MSA-Host: belenus.iks-jena.de Received: (from lutz@localhost) by belenus.iks-jena.de (8.14.3/8.14.1/Submit) id 11B7suwW007957; Thu, 11 Feb 2021 08:54:56 +0100 Date: Thu, 11 Feb 2021 08:54:56 +0100 From: Lutz Donnerhacke To: Warner Losh Cc: "freebsd-arch@freebsd.org" Subject: Re: adding a sysctl man section Message-ID: <20210211075456.GA7928@belenus.iks-jena.de> References: <20210211001505.GF31099@funkthat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-message-flag: Please send plain text messages only. Thank you. User-Agent: Mutt/1.5.17 (2007-11-01) X-Rspamd-Queue-Id: 4Dbpp53sMYz4sc8 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 07:55:26 -0000 On Wed, Feb 10, 2021 at 06:37:00PM -0700, Warner Losh wrote: > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney wrote: > > 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'd oppose, it will clutter the filesystem for a "man -k" (or similar) shortcut. > 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: Device driver man pages (like ixl) tend to document a # instead of the number. So this would be dev.uhub.#.%parent ... in the man page. From owner-freebsd-arch@freebsd.org Thu Feb 11 13:44:13 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 30E60528876 for ; Thu, 11 Feb 2021 13:44:13 +0000 (UTC) (envelope-from freebsd-rwg@gndrsh.dnsmgr.net) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DbyXX5qV1z3mGK for ; Thu, 11 Feb 2021 13:44:12 +0000 (UTC) (envelope-from freebsd-rwg@gndrsh.dnsmgr.net) Received: by mailman.nyi.freebsd.org (Postfix) id C7EFA528891; Thu, 11 Feb 2021 13:44:12 +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 C7BBD528578 for ; Thu, 11 Feb 2021 13:44:12 +0000 (UTC) (envelope-from freebsd-rwg@gndrsh.dnsmgr.net) Received: from gndrsh.dnsmgr.net (br1.CN84in.dnsmgr.net [69.59.192.140]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4DbyXX3N6Hz3m9s for ; Thu, 11 Feb 2021 13:44:11 +0000 (UTC) (envelope-from freebsd-rwg@gndrsh.dnsmgr.net) Received: from gndrsh.dnsmgr.net (localhost [127.0.0.1]) by gndrsh.dnsmgr.net (8.13.3/8.13.3) with ESMTP id 11BDi95u064581; Thu, 11 Feb 2021 05:44:09 -0800 (PST) (envelope-from freebsd-rwg@gndrsh.dnsmgr.net) Received: (from freebsd-rwg@localhost) by gndrsh.dnsmgr.net (8.13.3/8.13.3/Submit) id 11BDi9L5064580; Thu, 11 Feb 2021 05:44:09 -0800 (PST) (envelope-from freebsd-rwg) From: "Rodney W. Grimes" Message-Id: <202102111344.11BDi9L5064580@gndrsh.dnsmgr.net> Subject: Re: adding a sysctl man section In-Reply-To: To: Robert Clausecker Date: Thu, 11 Feb 2021 05:44:09 -0800 (PST) CC: arch@freebsd.org X-Mailer: ELM [version 2.4ME+ PL121h (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset=US-ASCII X-Rspamd-Queue-Id: 4DbyXX3N6Hz3m9s 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 13:44:13 -0000 > Why not add these to section 7 instead? The section is sparsely > populated as is and those names with lots of dots in them are > unlikely to collide. > > On second thought, no collisions would occur in section 4 either > it seems. And since most of the links would go to section 4 anyway... man 7 intro man 4 intro man 9 intro man sysctl Clearly this goes in section 9? > > Yours, > Robert Clausecker > > Am Wed, Feb 10, 2021 at 04:15:05PM -0800 schrieb John-Mark Gurney: > > 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? None other than location. Its blue, it goes in the blue section :-) > > -- > > John-Mark Gurney Voice: +1 415 225 5579 > > > > "All that I will do, has been done, All that I have, has not." > > _______________________________________________ > > freebsd-arch@freebsd.org mailing list > > https://lists.freebsd.org/mailman/listinfo/freebsd-arch > > To unsubscribe, send any mail to "freebsd-arch-unsubscribe@freebsd.org" > > -- > () ascii ribbon campaign - for an 8-bit clean world > /\ - against html email - against proprietary attachments > _______________________________________________ > freebsd-arch@freebsd.org mailing list > https://lists.freebsd.org/mailman/listinfo/freebsd-arch > To unsubscribe, send any mail to "freebsd-arch-unsubscribe@freebsd.org" > -- Rod Grimes rgrimes@freebsd.org From owner-freebsd-arch@freebsd.org Thu Feb 11 15:51:37 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 F406D52C89D for ; Thu, 11 Feb 2021 15:51:36 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4Dc1MX5MbFz4RqZ for ; Thu, 11 Feb 2021 15:51:36 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mailman.nyi.freebsd.org (Postfix) id B820752C763; Thu, 11 Feb 2021 15:51:36 +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 B7E8E52C7BD for ; Thu, 11 Feb 2021 15:51:36 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qt1-x833.google.com (mail-qt1-x833.google.com [IPv6:2607:f8b0:4864:20::833]) (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 4Dc1MX4hPTz4RqY for ; Thu, 11 Feb 2021 15:51:36 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qt1-x833.google.com with SMTP id w20so4481777qta.0 for ; Thu, 11 Feb 2021 07:51:36 -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=qA4OWrQMEFpfcYXlrQMjzDVtKfH1POXdtl392ZowftY=; b=XzsZKLX/g6ueqcUyCFahjoaPhbz5mAz754ZtSmbm4atnAQuiE+wYMfG8V5xP3UTkeW Wbj+oxM2i5/MvYIlUVpqmOkdbB5BHW25nGmiO5mBU2Gs+QRnLQMHrfSFfOy6YaWAcidU 0rvM4fcYWMXJuddubCyL4UdQJXtru6hIfGYZi9Ks5yCLghBpA3HWyAZs9TYAw+EHWpuL qIC7ddY1ILCf/BImXwrVrvx9vCxvMH9mBk6dHUQYqz37s8JfsZM2ZQyd/R918VzleMeb 9bw8/YwXvEbV3DyQcbEKqyBbImLFItZj26zAVNp0uNc0cKUKddJvAauym1iPqVp6CPUv UazA== 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=qA4OWrQMEFpfcYXlrQMjzDVtKfH1POXdtl392ZowftY=; b=NgE0XdAEWs0gqaF5F3FShv5GNspvKt7IH3CmZMyMn0aCC4dTNodVBlYWkzgSeLoTpO VXqMgNi6g1oiCSz7i7BJtcMWuk+PTZbhYZx53ZAbXxbH6JHxnIZ3M+eJC+kZbBOtcuvJ Ug5mVmVWPyHJCTL4hMsw3oprdL2LAcKVg5ARcjVFF/iQ7gYsAVEDRZ/H3XswYjmBxHlK HjQUJS/ia5L7IVK7RSBoxTu3NEuXbPUm1z6fqJG71tO2TML1LANDPyyCh5Eda+rzc3Br qViF9am0ApTtpBeAeQUkNb1aA42K5Al1MaWxnTIZI2GSq5NPUbcGsiROgAcY2ELkU4X2 JglQ== X-Gm-Message-State: AOAM533eJil5tEyxRLv4A2strJAcT+GvV4l9dI54Dt3/vmaJhr2iS9bV A6RIhXuBFKF+c6AmrtVcy4XTae5H3EMJcY5BAngZgPoYXyE= X-Google-Smtp-Source: ABdhPJwV3kHANxZFpiltPGUuK7ZSOGe6Ot/e7/xoPYJI9AmsSFD6Zd8Wik9/8sMTubnXs3UX/0q24+K0uOF558cX2NE= X-Received: by 2002:a05:622a:303:: with SMTP id q3mr7810756qtw.235.1613058695502; Thu, 11 Feb 2021 07:51:35 -0800 (PST) MIME-Version: 1.0 References: <20210211001505.GF31099@funkthat.com> <20210211075456.GA7928@belenus.iks-jena.de> In-Reply-To: <20210211075456.GA7928@belenus.iks-jena.de> From: Warner Losh Date: Thu, 11 Feb 2021 08:51:23 -0700 Message-ID: Subject: Re: adding a sysctl man section To: Lutz Donnerhacke Cc: "freebsd-arch@freebsd.org" X-Rspamd-Queue-Id: 4Dc1MX4hPTz4RqY 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: Thu, 11 Feb 2021 15:51:37 -0000 On Thu, Feb 11, 2021, 12:55 AM Lutz Donnerhacke wrote: > On Wed, Feb 10, 2021 at 06:37:00PM -0700, Warner Losh wrote: > > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney > wrote: > > > 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'd oppose, it will clutter the filesystem for a "man -k" (or similar) > shortcut. > > > 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: > > Device driver man pages (like ixl) tend to document a # instead of the > number. So this would be dev.uhub.#.%parent ... in the man page. > That part is easy. The symlink is what I worry about. Warner > From owner-freebsd-arch@freebsd.org Thu Feb 11 18:45:15 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 C28FE53155D for ; Thu, 11 Feb 2021 18:45:15 +0000 (UTC) (envelope-from khng@freebsdfoundation.org) Received: from mail-pg1-x52c.google.com (mail-pg1-x52c.google.com [IPv6:2607:f8b0:4864:20::52c]) (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 4Dc5Ct6DnZz4dlL for ; Thu, 11 Feb 2021 18:45:14 +0000 (UTC) (envelope-from khng@freebsdfoundation.org) Received: by mail-pg1-x52c.google.com with SMTP id z21so4533512pgj.4 for ; Thu, 11 Feb 2021 10:45:14 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:message-id:date:to; bh=Kx1uQpYBvHJMhIkaxz9kcmWkrTHUqQvhTxOsulKv2V4=; b=IJyWPhZkeXacMe6Ae497rNio6mC+HOBVXdw+kuxAVxcuxJXXMtu4O0B2lVmnQU/kN9 TPam0G6OWNaM29Btj8J3/VkwF9bgL1G7v97xvHW4/8NqtvyqYcukKsu5Vc8RNeKV0Ieh 4neMaYumuszHIaqwUpRFS5l89UAjK3NxHGtn3uMhvSUma0cTILrQEIvDchyST94YduVK ETrO7JEGCGzy/c7FVPw+wUtjf+pO9SIALASPQnPoSIILkfJkT0SSHTQuvpcSlF+JBKK6 AODJocefAeF2qTy+4V9x5QHb27gyqimS/QwLx42VhuXYb//DcKmMpferPRkvIVpqrGz6 xSjg== X-Gm-Message-State: AOAM5320wFuOgGrdWXYDWK3+juxv09xQPCsKuq2sMDDPENCKsDJbUz3z xGyC5rJls0ZxLwDBhGq9ASr48uZE/QsZytRyBmjWQgcdJSn0cNm0kvbonMjDq82eEsua0Ebpiw2 79YHNtZDbOiR85f5uQ5RvNIw+hH2Dpvl9Y7+1QxJtC5g0GJYONob8EwplEvGN5UUFC6s+0aHcsN Tx6jBs5C6OS8M= X-Google-Smtp-Source: ABdhPJzfL6rxcyHBhFZFkIzDVSgjlTwxYMkd/ZBlowZ/gPv/eO7o0aO7hl6pXGBl4qPcBkrRt8zX3g== X-Received: by 2002:aa7:8598:0:b029:1dd:9cb4:37ee with SMTP id w24-20020aa785980000b02901dd9cb437eemr9451179pfn.54.1613069112793; Thu, 11 Feb 2021 10:45:12 -0800 (PST) Received: from ?IPv6:2001:470:f816:0:914b:3a4a:6966:f48b? ([2001:470:f816:0:914b:3a4a:6966:f48b]) by smtp.gmail.com with ESMTPSA id c4sm6517029pfj.113.2021.02.11.10.45.11 for (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Thu, 11 Feb 2021 10:45:12 -0800 (PST) From: Ka Ho Ng Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.60.0.2.21\)) Subject: Proposing space management API to perform hole-punching Message-Id: <17D576F5-FBB9-425A-B6AB-B6CBA97ED785@freebsdfoundation.org> Date: Fri, 12 Feb 2021 02:45:08 +0800 To: freebsd-arch@freebsd.org X-Mailer: Apple Mail (2.3654.60.0.2.21) X-Rspamd-Queue-Id: 4Dc5Ct6DnZz4dlL X-Spamd-Bar: --- X-Spamd-Result: default: False [-3.50 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; MV_CASE(0.50)[]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36]; TO_DN_NONE(0.00)[]; RCVD_COUNT_THREE(0.00)[3]; DKIM_TRACE(0.00)[freebsdfoundation.org:+]; DMARC_POLICY_ALLOW(-0.50)[freebsdfoundation.org,quarantine]; NEURAL_HAM_SHORT(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; RBL_DBL_DONT_QUERY_IPS(0.00)[2607:f8b0:4864:20::52c:from]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; MID_RHS_MATCH_FROM(0.00)[]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; R_DKIM_ALLOW(-0.20)[freebsdfoundation.org:s=gfnp-20170908]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-arch@freebsd.org]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[2607:f8b0:4864:20::52c:from:127.0.2.255]; RCVD_IN_DNSWL_NONE(0.00)[2607:f8b0:4864:20::52c:from]; RCVD_TLS_ALL(0.00)[]; MAILMAN_DEST(0.00)[freebsd-arch] 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 18:45:15 -0000 Hi all, I am proposing https://reviews.freebsd.org/D28347 for performing space = management In FreeBSD. It also depends on = https://reviews.freebsd.org/D27194 which is a public KPI addition for = doing vm cache cleaning. This proposal is inspired by the discussions = around https://reviews.freebsd.org/D5126. The proposal contains fspacectl(2), VOP_DEALLOCATE(9) and = vn_deallocate(9). fspacectl(2) is a space management API that takes a = file descriptor, a command value, a range and flags. The system call is = responsible for doing space management operations such as punching = holes, which is the only operation supported so far. = SPACECTL_F_CANEXTEND flag is also provided such that the file size of = the affected file would be extended in case the operation range overlaps = with or goes pass file size. VOP_DEALLOCATE(9) is a VOP call which is to be implemented by file = system implementations. File system that supports sparse file could = implement this VOP call and wire it with its internal file bmap = facilities. A file system provided implementation also needs handle = operation range which isn=E2=80=99t aligned to, for instance, file = system block size by zeroing the partial allocation units. A fallback = implementation that zeroes all the non-hole region within operation = range. It is okay to return partial results to prevent holding vnode = lock for too long. vn_deallocate(9) is a public KPI which calls VOP_DEALLOCATE(9) with = control over vnode lock and range lock. vn_deallocate(9) also handles = the case that VOP_DEALLOCATE(9) returns partial result, and temporarily = releases the held vnode lock from time to time in such case internally.=20= I also plan to implement VOP_ALLOCATE(9) and the preallocation command = within fspacectl(2), and implement posix_fallocate(2) to call = fspacectl(2) instead. In case you are interested in the proposal, please feel free to look = into it. :) Ka Ho= From owner-freebsd-arch@freebsd.org Thu Feb 11 19:00:56 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 EC7F6531E40 for ; Thu, 11 Feb 2021 19:00:56 +0000 (UTC) (envelope-from phk@critter.freebsd.dk) Received: from phk.freebsd.dk (phk.freebsd.dk [130.225.244.222]) (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 4Dc5Yz6lxtz4fs9 for ; Thu, 11 Feb 2021 19:00:54 +0000 (UTC) (envelope-from phk@critter.freebsd.dk) Received: from critter.freebsd.dk (v-critter.freebsd.dk [192.168.55.3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by phk.freebsd.dk (Postfix) with ESMTPS id 69FBC8928B; Thu, 11 Feb 2021 19:00:47 +0000 (UTC) Received: from critter.freebsd.dk (localhost [127.0.0.1]) by critter.freebsd.dk (8.16.1/8.16.1) with ESMTPS id 11BJ0loX082974 (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384 bits=256 verify=NO); Thu, 11 Feb 2021 19:00:47 GMT (envelope-from phk@critter.freebsd.dk) Received: (from phk@localhost) by critter.freebsd.dk (8.16.1/8.16.1/Submit) id 11BJ0kXu082973; Thu, 11 Feb 2021 19:00:46 GMT (envelope-from phk) To: Ka Ho Ng , Ka Ho Ng via freebsd-arch Subject: Re: Proposing space management API to perform hole-punching In-reply-to: <17D576F5-FBB9-425A-B6AB-B6CBA97ED785@freebsdfoundation.org> From: "Poul-Henning Kamp" References: <17D576F5-FBB9-425A-B6AB-B6CBA97ED785@freebsdfoundation.org> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <82971.1613070046.1@critter.freebsd.dk> Content-Transfer-Encoding: quoted-printable Date: Thu, 11 Feb 2021 19:00:46 +0000 Message-ID: <82972.1613070046@critter.freebsd.dk> X-Rspamd-Queue-Id: 4Dc5Yz6lxtz4fs9 X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of phk@critter.freebsd.dk designates 130.225.244.222 as permitted sender) smtp.mailfrom=phk@critter.freebsd.dk X-Spamd-Result: default: False [-3.00 / 15.00]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; FREEFALL_USER(0.00)[phk]; FROM_HAS_DN(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[130.225.244.222:from]; R_SPF_ALLOW(-0.20)[+mx]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[freebsd.dk]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; SPAMHAUS_ZRD(0.00)[130.225.244.222:from:127.0.2.255]; RCVD_COUNT_THREE(0.00)[3]; TO_MATCH_ENVRCPT_SOME(0.00)[]; TO_DN_ALL(0.00)[]; NEURAL_HAM_SHORT(-1.00)[-1.000]; RCPT_COUNT_TWO(0.00)[2]; FORGED_SENDER(0.30)[phk@phk.freebsd.dk,phk@critter.freebsd.dk]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:1835, ipnet:130.225.0.0/16, country:EU]; FROM_NEQ_ENVFROM(0.00)[phk@phk.freebsd.dk,phk@critter.freebsd.dk]; MAILMAN_DEST(0.00)[freebsd-arch] 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 19:00:57 -0000 -------- Ka Ho Ng via freebsd-arch writes: > The proposal contains fspacectl(2), VOP_DEALLOCATE(9) and vn_deallocate(= 9). fspacectl(2) is a space management API that takes a file descriptor, a= command value, a range and flags. The system call is responsible for doi= ng space management operations such as punching holes, which is the only o= peration supported so far. [...] 1. Which other operations are/can be foreseen ? 2. What arguments would they need ? 3. Should the syscall definition take this into account already now ? 4. Are there any existing APIs for this ? 5. Should we stick closely to them ? If not, why not ? -- = Poul-Henning Kamp | UNIX since Zilog Zeus 3.20 phk@FreeBSD.ORG | TCP/IP since RFC 956 FreeBSD committer | BSD since 4.3-tahoe = Never attribute to malice what can adequately be explained by incompetence= . From owner-freebsd-arch@freebsd.org Thu Feb 11 19:11:59 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 9AD02532526 for ; Thu, 11 Feb 2021 19:11:59 +0000 (UTC) (envelope-from khng@freebsdfoundation.org) Received: from mail-pj1-x1031.google.com (mail-pj1-x1031.google.com [IPv6:2607:f8b0:4864:20::1031]) (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 4Dc5pk4pV5z4gQS for ; Thu, 11 Feb 2021 19:11:58 +0000 (UTC) (envelope-from khng@freebsdfoundation.org) Received: by mail-pj1-x1031.google.com with SMTP id cl8so3968881pjb.0 for ; Thu, 11 Feb 2021 11:11:58 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:subject:from:in-reply-to:date:cc :content-transfer-encoding:message-id:references:to; bh=HBkkpezbXNZxoV7OLNNW1mBWG7jtTCL0K0FL0lmBguo=; b=MO+Xok950F2PONn7AVJFM3/6KgJadoELeu4TZz2vNt1CwEdCqN2XYnUFIvrvh4CqAU KXizcrFXCJyQYGlQLLj3HjeSzs8iwnySwuMs5BYSEUvE0WcC5Pdl4/ntQuElRnPD4M8y WKgGh8j+PHVuVYdN2Or9IIcHGVP1bqEYe7yN91nZloH0ggQiTWOVBJgQh4Ztr7RjszeI ehMK8NcfeMgrNFcvAZQvB/8znGkJit8W7RSUZWMr5jhi6hYWCpp0ASALwjbVMJ2Myv/0 m1OozsxkMknDBKVQ2O6GWfsBtr9aD5Wa2zvk9+0n7OQzpI5MnXvDxbC0nCXlPEuDuq3l u59w== X-Gm-Message-State: AOAM531imfARxjkyh+HIz0yDnfN5lHNjPXW1H7qAcoNwEhkHV7B4gCro wEkUQRnS8wjp2pCd3xL1Qtin2I23suNpQZ0p5ok= X-Google-Smtp-Source: ABdhPJwaymzfn4Nvei/SI5fcwV9ACKUY39FU8LlCoMaZs7DeUzw5+w6atEOdQ8mVx0KnFRdO9st6jA== X-Received: by 2002:a17:902:d2cb:b029:de:757c:1f0c with SMTP id n11-20020a170902d2cbb02900de757c1f0cmr8803145plc.40.1613070717204; Thu, 11 Feb 2021 11:11:57 -0800 (PST) Received: from ?IPv6:2001:470:f816:0:914b:3a4a:6966:f48b? ([2001:470:f816:0:914b:3a4a:6966:f48b]) by smtp.gmail.com with ESMTPSA id h11sm6553772pfr.201.2021.02.11.11.11.55 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Thu, 11 Feb 2021 11:11:56 -0800 (PST) Content-Type: text/plain; charset=utf-8 Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.60.0.2.21\)) Subject: Re: Proposing space management API to perform hole-punching From: Ka Ho Ng In-Reply-To: <82972.1613070046@critter.freebsd.dk> Date: Fri, 12 Feb 2021 03:11:55 +0800 Cc: Ka Ho Ng via freebsd-arch Content-Transfer-Encoding: quoted-printable Message-Id: <39A2A13C-22C9-4386-B30F-0EBEE5E89AC4@freebsdfoundation.org> References: <17D576F5-FBB9-425A-B6AB-B6CBA97ED785@freebsdfoundation.org> <82972.1613070046@critter.freebsd.dk> To: Poul-Henning Kamp X-Mailer: Apple Mail (2.3654.60.0.2.21) X-Rspamd-Queue-Id: 4Dc5pk4pV5z4gQS X-Spamd-Bar: --- X-Spamd-Result: default: False [-3.50 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; MV_CASE(0.50)[]; R_SPF_ALLOW(-0.20)[+ip6:2607:f8b0:4000::/36]; RCVD_COUNT_THREE(0.00)[3]; TO_DN_ALL(0.00)[]; DKIM_TRACE(0.00)[freebsdfoundation.org:+]; RCPT_COUNT_TWO(0.00)[2]; DMARC_POLICY_ALLOW(-0.50)[freebsdfoundation.org,quarantine]; NEURAL_HAM_SHORT(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; RBL_DBL_DONT_QUERY_IPS(0.00)[2607:f8b0:4864:20::1031:from]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US]; MID_RHS_MATCH_FROM(0.00)[]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; R_DKIM_ALLOW(-0.20)[freebsdfoundation.org:s=gfnp-20170908]; FROM_HAS_DN(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-arch@freebsd.org]; SPAMHAUS_ZRD(0.00)[2607:f8b0:4864:20::1031:from:127.0.2.255]; TO_MATCH_ENVRCPT_SOME(0.00)[]; RCVD_IN_DNSWL_NONE(0.00)[2607:f8b0:4864:20::1031:from]; RCVD_TLS_ALL(0.00)[]; MAILMAN_DEST(0.00)[freebsd-arch] 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 19:11:59 -0000 > On Feb 12, 2021, at 3:00 AM, Poul-Henning Kamp = wrote: >=20 > -------- >=20 > Ka Ho Ng via freebsd-arch writes: >=20 >> The proposal contains fspacectl(2), VOP_DEALLOCATE(9) and = vn_deallocate(9). fspacectl(2) is a space management API that takes a = file descriptor, a command value, a range and flags. The system call is = responsible for doing space management operations such as punching = holes, which is the only operation supported so far. [...] >=20 > 1. Which other operations are/can be foreseen ? Besides SPACECTL_DEALLOC, it would be foreseeable to implement = SPACECTL_ALLOC. >=20 > 2. What arguments would they need ? The same, a tuple of offset and length. >=20 > 3. Should the syscall definition take this into account already now ? kib@ thinks it is a bonus to simplify the number of system calls in the = original fdeallocate(2) + fzero(2) draft under the same differential, as we already got = posix_fallocate. Besides, one of the consideration behind is to implement linuxulator=E2=80= =99s fallocate, which does also does FALLOC_FL_KEEP_SIZE.=20 >=20 > 4. Are there any existing APIs for this ? > 5. Should we stick closely to them ? If not, why not ? posix_fallocate. The system call however does not consider the case if = file extending is not required, nor does it do hole-punching. >=20 > --=20 > Poul-Henning Kamp | UNIX since Zilog Zeus 3.20 > phk@FreeBSD.ORG | TCP/IP since RFC 956 > FreeBSD committer | BSD since 4.3-tahoe =20 > Never attribute to malice what can adequately be explained by = incompetence. From owner-freebsd-arch@freebsd.org Fri Feb 12 00:12:28 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 46EDC53B4B8 for ; Fri, 12 Feb 2021 00:12:28 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 4DcDTS09yTz3Jsv for ; Fri, 12 Feb 2021 00:12:28 +0000 (UTC) (envelope-from jmg@gold.funkthat.com) Received: by mailman.nyi.freebsd.org (Postfix) id 0448B53B2E9; Fri, 12 Feb 2021 00:12:28 +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 040C653B41D for ; Fri, 12 Feb 2021 00:12:28 +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 4DcDTR4k69z3Jyf for ; Fri, 12 Feb 2021 00:12:27 +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 11C0C9Ui029899 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Thu, 11 Feb 2021 16:12:09 -0800 (PST) (envelope-from jmg@gold.funkthat.com) Received: (from jmg@localhost) by gold.funkthat.com (8.15.2/8.15.2/Submit) id 11C0C94Q029898; Thu, 11 Feb 2021 16:12:09 -0800 (PST) (envelope-from jmg) Date: Thu, 11 Feb 2021 16:12:09 -0800 From: John-Mark Gurney To: Lutz Donnerhacke Cc: Warner Losh , "freebsd-arch@freebsd.org" Subject: Re: adding a sysctl man section Message-ID: <20210212001209.GI31099@funkthat.com> Mail-Followup-To: Lutz Donnerhacke , Warner Losh , "freebsd-arch@freebsd.org" References: <20210211001505.GF31099@funkthat.com> <20210211075456.GA7928@belenus.iks-jena.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable In-Reply-To: <20210211075456.GA7928@belenus.iks-jena.de> 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]); Thu, 11 Feb 2021 16:12:09 -0800 (PST) X-Rspamd-Queue-Id: 4DcDTR4k69z3Jyf 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: Fri, 12 Feb 2021 00:12:28 -0000 Lutz Donnerhacke wrote this message on Thu, Feb 11, 2021 at 08:54 +0100: > On Wed, Feb 10, 2021 at 06:37:00PM -0700, Warner Losh wrote: > > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney wro= te: > > > Then, any page that describes a sysctl, would add an MLINK to it: > > > MLINK+=3D 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? >=20 > I'd oppose, it will clutter the filesystem for a "man -k" (or similar) > shortcut. Can you expand exactly how/why this would happen? I assume you mean clutter the output from "man -k", but as "man -k" uses a db for it's data, it'd only slightly expand that db, but it wouldn't clutter the file system anymore, unless I'm missing something... So, in one test case, this is what you'd see (or maybe section 9, which I'm find with): # man -k xhci xhci, hw.usb.xhci.ctlquirk, hw.usb.xhci.ctlstep, hw.usb.xhci.debug, hw.usb.= xhci.dma32, hw.usb.xhci.streams, hw.usb.xhci.use_polling, hw.usb.xhci.xhci_= port_route(4, s) - USB eXtensible Host Controller driver yes, if you do a search for a generic term like debug, you'll end up a lot more extra output, BUT, "man -k debug" already outputs a wall of text that you're likely to need to filter anyways, so I don't see a major difference/problem here. I will say I'm a bit surprised there isn't an option to apropos to allow only displaying the first matching man page to shorten the lines a bit, but we already have this problem for some man pages: # find . -type f -ls | awk '{ print $1 }' | sort | uniq -c | sort | tail -n= 5 95 409059 98 405230 102 408573 116 397987 118 396855 409059 is nv(9) 405230 is snmpmod(3) 408573 is bhnd(9) 397987 is libusb(3) 396855 is curs_sp_funcs(3X) for example. # man -k libnv nvlist_create, nvlist_clone, nvlist_destroy, nvlist_dump, nvlist_empty, nvl= ist_error, nvlist_exists, nvlist_fdump, nvlist_flags, nvlist_free, nvlist_n= ext, nvlist_pack, nvlist_recv, nvlist_send, nvlist_set_error, nvlist_size, = nvlist_unpack, nvlist_xfer, nvlist_add_binary, nvlist_add_bool, nvlist_add_= bool_array, nvlist_add_descriptor, nvlist_add_descriptor_array, nvlist_add_= null, nvlist_add_number, nvlist_add_number_array, nvlist_add_nvlist, nvlist= _add_nvlist_array, nvlist_add_string, nvlist_add_string_array, nvlist_add_s= tringf, nvlist_add_stringv, nvlist_append_bool_array, nvlist_append_descrip= tor_array, nvlist_append_number_array, nvlist_append_nvlist_array, nvlist_a= ppend_string_array, nvlist_exists_binary, nvlist_exists_bool, nvlist_exists= _bool_array, nvlist_exists_descriptor, nvlist_exists_descriptor_array, nvli= st_exists_null, nvlist_exists_number, nvlist_exists_number_array, nvlist_ex= ists_nvlist, nvlist_exists_nvlist_array, nvlist_exists_string, nvlist_exist= s_type, nvlist_free_binary, nvlist_free_bool, nvlist_free_bool_array, nvlis= t_free_descriptor, nvlist_free_descriptor_array, nvlist_free_null, nvlist_f= ree_number, nvlist_free_number_array, nvlist_free_nvlist, nvlist_free_nvlis= t_array, nvlist_free_string, nvlist_free_string_array, nvlist_free_type, nv= list_get_binary, nvlist_get_bool, nvlist_get_bool_array, nvlist_get_descrip= tor, nvlist_get_descriptor_array, nvlist_get_number, nvlist_get_number_arra= y, nvlist_get_nvlist, nvlist_get_nvlist_array, nvlist_get_parent, nvlist_ge= t_string, nvlist_get_string_array, nvlist_move_binary, nvlist_move_descript= or, nvlist_move_descriptor_array, nvlist_move_nvlist, nvlist_move_nvlist_ar= ray, nvlist_move_string, nvlist_move_string_array, nvlist_take_binary, nvli= st_take_bool, nvlist_take_bool_array, nvlist_take_descriptor, nvlist_take_d= escriptor_array, nvlist_take_number, nvlist_take_number_array, nvlist_take_= nvlist, nvlist_take_nvlist_array, nvlist_take_string, nvlist_take_string_ar= ray, libnv, nv, nvlist, nvlist_in_array, nvlist_add, nvlist_append, nvlist_= get, nvlist_move, nvlist_take(9) - library for name/value pairs --=20 John-Mark Gurney Voice: +1 415 225 5579 "All that I will do, has been done, All that I have, has not." From owner-freebsd-arch@freebsd.org Fri Feb 12 07:14:26 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 8CA8F5466C8 for ; Fri, 12 Feb 2021 07:14:26 +0000 (UTC) (envelope-from gljennjohn@gmail.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 4DcPrL28Kbz4X1x for ; Fri, 12 Feb 2021 07:14:26 +0000 (UTC) (envelope-from gljennjohn@gmail.com) Received: by mailman.nyi.freebsd.org (Postfix) id 47D695466C7; Fri, 12 Feb 2021 07:14:26 +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 467E35466C6 for ; Fri, 12 Feb 2021 07:14:26 +0000 (UTC) (envelope-from gljennjohn@gmail.com) Received: from mail-wr1-x433.google.com (mail-wr1-x433.google.com [IPv6:2a00:1450:4864:20::433]) (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 4DcPrL16kJz4WVs for ; Fri, 12 Feb 2021 07:14:26 +0000 (UTC) (envelope-from gljennjohn@gmail.com) Received: by mail-wr1-x433.google.com with SMTP id b3so6731490wrj.5 for ; Thu, 11 Feb 2021 23:14:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:in-reply-to:references:reply-to :mime-version:content-transfer-encoding; bh=x3ieRekpkiRYeNvatANt9qUwskuXZyKN7MvjN1wojOY=; b=LwTf9ZPAT65TRf198jG+gerzybtQGR9fUTdxj5ao0nekeoHlYWLagNyh8qgq+Xy7kt 0P5UWqXjXAaOtOqHcUFr97wVPrPo7M4R16J6DMpN9kgxrb7fRIsGIgFcInYI1El5u3ik UNMMknM8fkobYVQ5AKPwQbHsxeokbtGdnxWJ5hAg6akb72Bh7PtUcpPenL+ApQ89Ni4Z LSJ54/XIHB0DWBFsH5DlEw0msnpTyYyEYfeZKnDxP0CyH5ClzZLLZ1g0Trzd3K+3uS/r 01kOlB1vna0WB5cP0rvIM4/8jMLcF3ZHSeY3gt1hkLaJLCr7IwZ8N96iucHjnNZbf2Pq JfuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:in-reply-to :references:reply-to:mime-version:content-transfer-encoding; bh=x3ieRekpkiRYeNvatANt9qUwskuXZyKN7MvjN1wojOY=; b=PpR+GsUV0rglFLvKGbWblBAwQrA1XydguahrzUsqJ/Lyu5HoQfBdgRb1CAaLQRQWWH IPOKODTe9ZKBsl12kJ3e8oaaa5ISjgz0RUHzgN0kvR5CwTSjnc5/BxcmDREebOHGSV+O UbSPDervrMaCb5KoNoQirKNDKMgOQ3IEfmwR2rKN9T3cDuxUEoUwQJKGf70tqEJ2di8o 5Qbr0wEnnnq0s8dqHkshZEA4FJCjdc1VIMuRWKh2inNTQW1nOLnt4nYjGkivVo61I+Mk REuB/MC7I34+3bRvgcrVIYbD0zzPPuSvhns2NFkDic2oX7iSFGEjS96jh1ovRY64lDfQ 0k0g== X-Gm-Message-State: AOAM530P3b33CdlKGZpFvJFoh60QwsN8R76XOlhpPR77aSvBn63MfFmD 3vpyhzZLbw48/+o4Q4FwyVu4mQaRmro= X-Google-Smtp-Source: ABdhPJzNPTVChAy640ZkEKukma0CgiUUv/9UvmwsNHnmphCxhcrUaAFdseUO4nqGIfKKRMJJ7yMkHw== X-Received: by 2002:adf:a501:: with SMTP id i1mr1729152wrb.149.1613114064941; Thu, 11 Feb 2021 23:14:24 -0800 (PST) Received: from ernst.home ([91.2.53.14]) by smtp.gmail.com with ESMTPSA id z15sm11895386wmi.38.2021.02.11.23.14.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 11 Feb 2021 23:14:24 -0800 (PST) Date: Fri, 12 Feb 2021 08:13:48 +0100 From: Gary Jennejohn To: John-Mark Gurney Cc: Lutz Donnerhacke , "freebsd-arch@freebsd.org" Subject: Re: adding a sysctl man section Message-ID: <20210212071348.42f61156@ernst.home> In-Reply-To: <20210212001209.GI31099@funkthat.com> References: <20210211001505.GF31099@funkthat.com> <20210211075456.GA7928@belenus.iks-jena.de> <20210212001209.GI31099@funkthat.com> Reply-To: gljennjohn@gmail.com X-Mailer: Claws Mail 3.17.5 (GTK+ 2.24.33; amd64-portbld-freebsd13.0) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4DcPrL16kJz4WVs 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: Fri, 12 Feb 2021 07:14:26 -0000 On Thu, 11 Feb 2021 16:12:09 -0800 John-Mark Gurney wrote: > Lutz Donnerhacke wrote this message on Thu, Feb 11, 2021 at 08:54 +0100: > > On Wed, Feb 10, 2021 at 06:37:00PM -0700, Warner Losh wrote: > > > On Wed, Feb 10, 2021 at 5:15 PM John-Mark Gurney wrote: > > > > 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'd oppose, it will clutter the filesystem for a "man -k" (or similar) > > shortcut. > > Can you expand exactly how/why this would happen? I assume you mean > clutter the output from "man -k", but as "man -k" uses a db for it's > data, it'd only slightly expand that db, but it wouldn't clutter the > file system anymore, unless I'm missing something... > > So, in one test case, this is what you'd see (or maybe section 9, > which I'm find with): > # man -k xhci > xhci, hw.usb.xhci.ctlquirk, hw.usb.xhci.ctlstep, hw.usb.xhci.debug, hw.usb.xhci.dma32, hw.usb.xhci.streams, hw.usb.xhci.use_polling, hw.usb.xhci.xhci_port_route(4, s) - USB eXtensible Host Controller driver > > yes, if you do a search for a generic term like debug, you'll end up > a lot more extra output, BUT, "man -k debug" already outputs a wall > of text that you're likely to need to filter anyways, so I don't see > a major difference/problem here. > > I will say I'm a bit surprised there isn't an option to apropos to allow > only displaying the first matching man page to shorten the lines a bit, > but we already have this problem for some man pages: > # find . -type f -ls | awk '{ print $1 }' | sort | uniq -c | sort | tail -n 5 > 95 409059 > 98 405230 > 102 408573 > 116 397987 > 118 396855 > > 409059 is nv(9) > 405230 is snmpmod(3) > 408573 is bhnd(9) > 397987 is libusb(3) > 396855 is curs_sp_funcs(3X) > > for example. > # man -k libnv > nvlist_create, nvlist_clone, nvlist_destroy, nvlist_dump, nvlist_empty, nvlist_error, nvlist_exists, nvlist_fdump, nvlist_flags, nvlist_free, nvlist_next, nvlist_pack, nvlist_recv, nvlist_send, nvlist_set_error, nvlist_size, nvlist_unpack, nvlist_xfer, nvlist_add_binary, nvlist_add_bool, nvlist_add_bool_array, nvlist_add_descriptor, nvlist_add_descriptor_array, nvlist_add_null, nvlist_add_number, nvlist_add_number_array, nvlist_add_nvlist, nvlist_add_nvlist_array, nvlist_add_string, nvlist_add_string_array, nvlist_add_stringf, nvlist_add_stringv, nvlist_append_bool_array, nvlist_append_descriptor_array, nvlist_append_number_array, nvlist_append_nvlist_array, nvlist_append_string_array, nvlist_exists_binary, nvlist_exists_bool, nvlist_exists_bool_array, nvlist_exists_descriptor, nvlist_exists_descriptor_array, nvlist_exists_null, nvlist_exists_number, nvlist_exists_number_array, nvlist_exists_nvlist, nvlist_exists_nvlist_array, nvlist_exists_string, nvlist_exists_type, nvlist_free_b in > ary, nvlist_free_bool, nvlist_free_bool_array, nvlist_free_descriptor, nvlist_free_descriptor_array, nvlist_free_null, nvlist_free_number, nvlist_free_number_array, nvlist_free_nvlist, nvlist_free_nvlist_array, nvlist_free_string, nvlist_free_string_array, nvlist_free_type, nvlist_get_binary, nvlist_get_bool, nvlist_get_bool_array, nvlist_get_descriptor, nvlist_get_descriptor_array, nvlist_get_number, nvlist_get_number_array, nvlist_get_nvlist, nvlist_get_nvlist_array, nvlist_get_parent, nvlist_get_string, nvlist_get_string_array, nvlist_move_binary, nvlist_move_descriptor, nvlist_move_descriptor_array, nvlist_move_nvlist, nvlist_move_nvlist_array, nvlist_move_string, nvlist_move_string_array, nvlist_take_binary, nvlist_take_bool, nvlist_take_bool_array, nvlist_take_descriptor, nvlist_take_descriptor_array, nvlist_take_number, nvlist_take_number_array, nvlist_take_nvlist, nvlist_take_nvlist_array, nvlist_take_string, nvlist_take_string_array, libnv, nv, nvlist, nvlist_in_array, nv li > st_add, nvlist_append, nvlist_get, nvlist_move, nvlis > t_take(9) - library for name/value pairs > I tend to agree with John-Mark here. In my experience with man -k most of the clutter comes from man pages installed by ports. -- Gary Jennejohn From owner-freebsd-arch@freebsd.org Fri Feb 12 20:14:02 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 7321052F945 for ; Fri, 12 Feb 2021 20:14:02 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dcl7t2szVz3s5H for ; Fri, 12 Feb 2021 20:14:02 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from John-Baldwins-MacBook-Pro.local (unknown [IPv6:2601:648:8681:1cb0:f49a:fe25:79c8:c3ed]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (Client did not present a certificate) (Authenticated sender: jhb) by smtp.freebsd.org (Postfix) with ESMTPSA id 280485A1F for ; Fri, 12 Feb 2021 20:14:02 +0000 (UTC) (envelope-from jhb@FreeBSD.org) To: freebsd-arch@freebsd.org References: <20210211001505.GF31099@funkthat.com> From: John Baldwin Subject: Re: adding a sysctl man section Message-ID: <936bc860-c61d-ecc3-8e3f-496684bad68a@FreeBSD.org> Date: Fri, 12 Feb 2021 12:14:00 -0800 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:78.0) Gecko/20100101 Thunderbird/78.7.0 MIME-Version: 1.0 In-Reply-To: <20210211001505.GF31099@funkthat.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 8bit 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: Fri, 12 Feb 2021 20:14:02 -0000 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. Does this meaning adding sysctl nodes as .Nm entries in the NAME section? 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. -- John Baldwin 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 From owner-freebsd-arch@freebsd.org Sat Feb 13 09:11:31 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 653B1546426 for ; Sat, 13 Feb 2021 09:11:31 +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 4Dd4Nz182Nz3kyh for ; Sat, 13 Feb 2021 09:11:31 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: by mailman.nyi.freebsd.org (Postfix) id 273A15463D4; Sat, 13 Feb 2021 09:11:31 +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 2700C546377 for ; Sat, 13 Feb 2021 09:11:31 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from wnew4-smtp.messagingengine.com (wnew4-smtp.messagingengine.com [64.147.123.18]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4Dd4Ny42XSz3kt3 for ; Sat, 13 Feb 2021 09:11:30 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.west.internal (Postfix) with ESMTP id 377088B9 for ; Sat, 13 Feb 2021 03:59:06 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Sat, 13 Feb 2021 03:59:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yuripv.dev; h= subject:to:references:from:message-id:date:mime-version :in-reply-to:content-type:content-transfer-encoding; s=fm1; bh=Y OQW22NKKBMWnIlGc1HS4nLEI8nw6wWUIR/Ot9IWFU4=; b=KwXTUb0QguICpE2oG JnnkS5Hc2RgnXQ6kCNKVQfWlXqnOgcK4EhrLopZBZAilXsrYhn+rEy7RHaCj36YJ SbWV/LBuqoagYBuEKo8vx/Pvq0jA4tCBIzj7GUL96lMwMyIy9pfWSms1cE0syxDL 2rKr+6zKXnua2Pj00++ODG7mf/UcIWWyZ+SEAt0c7uLlLibElu4UiHYnYlQrH/Fc P44KCUTdzEjAD9G5PgcWrjqRfsHf1gGWETr3C/BP3GWQEa33ttyHdgAClFu9nW3a BnXKRPIqIa9w8jb5qUMMQjl7oMGnfnrkxu0DWSXKpnjOHbYUCYDL75do2uS8/jcL jiLzQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=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=YOQW22NKKBMWnIlGc1HS4nLEI8nw6wWUIR/Ot9IWF U4=; b=OISVXu4ZqWfj4/8GYSnL6rBRy57kVEXSjT5RZWpX5lQq089FE+fSC+4yH 0Oz1JD7lDKZXV05I9ZhAdqeer6SMK109T6Qlqf5iVmCUhN6NmHrxTH5HxzfNmpZ2 vs7UwL3EI1FiXEg5pVRwd0lKG8HmLRqEDNL4yOVgflSgf+ereTiNf1Q4AdPwCr+E KZ0H0UcFmF6+EGzd19zuSdFIdaM8A6NUQ0GAkFPZ5mUZZ32bzyQakzkuIXAvQ6gU xhjGJ87+u+crtUjvFtbsPasKc9rpsfzBLYN+r/a0gum/YXATjhV/zzEyzx5e7wML UbTUVZQg6jVGGg4zNcQ4JuQPP8x/w== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledriedvgdduvdejucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefuvfhfhffkffgfgggjtgfgsehtje ertddtfeejnecuhfhrohhmpegjuhhrihcurfgrnhhkohhvuceohihurhhiphhvseihuhhr ihhpvhdruggvvheqnecuggftrfgrthhtvghrnhepvefhheefieekleegledvteehleffle eiheejteeiffefteffvdekjedthfeuueevnecuffhomhgrihhnpehtfihithhtvghrrdgt ohhmpdhfrhgvvggsshgurdhorhhgnecukfhppeeluddrvdegtddruddvgedrudefjeenuc evlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpeihuhhrihhp vheshihurhhiphhvrdguvghv X-ME-Proxy: Received: from [192.168.1.6] (unknown [91.240.124.137]) by mail.messagingengine.com (Postfix) with ESMTPA id DCA9B1080059 for ; Sat, 13 Feb 2021 03:59:04 -0500 (EST) Subject: Re: adding a sysctl man section To: arch@FreeBSD.org References: <20210211001505.GF31099@funkthat.com> From: Yuri Pankov Message-ID: Date: Sat, 13 Feb 2021 11:59:04 +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: <20210211001505.GF31099@funkthat.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4Dd4Ny42XSz3kt3 X-Spamd-Bar: +++++++++ Authentication-Results: mx1.freebsd.org; dkim=pass header.d=yuripv.dev header.s=fm1 header.b=KwXTUb0Q; dkim=pass header.d=messagingengine.com header.s=fm2 header.b=OISVXu4Z; dmarc=none; spf=pass (mx1.freebsd.org: domain of yuripv@yuripv.dev designates 64.147.123.18 as permitted sender) smtp.mailfrom=yuripv@yuripv.dev X-Spamd-Result: default: False [9.93 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; R_SPF_ALLOW(0.00)[+ip4:64.147.123.18:c]; TO_DN_NONE(0.00)[]; RCVD_COUNT_THREE(0.00)[4]; DKIM_TRACE(0.00)[yuripv.dev:+,messagingengine.com:+]; NEURAL_HAM_SHORT(-0.97)[-0.968]; FROM_EQ_ENVFROM(0.00)[]; RCVD_TLS_LAST(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[64.147.123.18:from]; ASN(0.00)[asn:11403, ipnet:64.147.123.0/24, country:US]; MIME_TRACE(0.00)[0:+]; MID_RHS_MATCH_FROM(0.00)[]; RCVD_IN_DNSWL_LOW(-0.10)[64.147.123.18:from]; ARC_NA(0.00)[]; RECEIVED_SPAMHAUS_XBL(5.00)[91.240.124.137:received]; R_DKIM_ALLOW(0.00)[yuripv.dev:s=fm1,messagingengine.com:s=fm2]; FREEFALL_USER(0.00)[yuripv]; FROM_HAS_DN(0.00)[]; RECEIVED_SPAMHAUS_CSS(4.00)[91.240.124.137:received]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; DMARC_NA(0.00)[yuripv.dev]; NEURAL_SPAM_MEDIUM(1.00)[1.000]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[64.147.123.18:from:127.0.2.255]; BAD_REP_POLICIES(0.10)[]; NEURAL_SPAM_LONG(1.00)[1.000]; GREYLIST(0.00)[pass,body]; MAILMAN_DEST(0.00)[arch] 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 09:11:31 -0000 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: $ man -d hw.usb.xhci.debug -- Using architecture: amd64:amd64 -- Using pager: less -ins -- Using manual sections: 1:8:2:3:3lua:n:4:5:6:7:9:l -- Searching PATH for man directories -- Adding /usr/share/man to manpath -- Adding /usr/local/man to manpath -- Adding default manpath entries -- Adding /usr/share/openssl/man to manpath -- Parsing config file: /usr/local/etc/man.d/perl5.conf -- Adding /usr/local/lib/perl5/site_perl/man to manpath -- Adding /usr/local/lib/perl5/5.32/perl/man to manpath -- Using manual path: /usr/share/man:/usr/local/man:/usr/share/openssl/man:/usr/local/lib/perl5/site_perl/man:/usr/local/lib/perl5/5.32/perl/man -- Using locale paths: . -- Using standard page width -- Searching for hw.usb.xhci.debug -- Found a usable page, displaying that -- Command: /usr/bin/zcat /usr/share/man/man4/xhci.4.gz | mandoc | less -ins From owner-freebsd-arch@freebsd.org Sat Feb 13 15:09:05 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 16E1652FBB0 for ; Sat, 13 Feb 2021 15:09:05 +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 4DdDKX5ymXz4dSM for ; Sat, 13 Feb 2021 15:09:04 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: by mailman.nyi.freebsd.org (Postfix) id CCBD752F83C; Sat, 13 Feb 2021 15:09:04 +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 CC86952F7E9 for ; Sat, 13 Feb 2021 15:09:04 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from wnew3-smtp.messagingengine.com (wnew3-smtp.messagingengine.com [64.147.123.17]) (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 4DdDKW6zSpz4dVM for ; Sat, 13 Feb 2021 15:09:03 +0000 (UTC) (envelope-from yuripv@yuripv.dev) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailnew.west.internal (Postfix) with ESMTP id E0AC5C9A for ; Sat, 13 Feb 2021 10:09:01 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute1.internal (MEProxy); Sat, 13 Feb 2021 10:09:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yuripv.dev; h= subject:from:to:references:message-id:date:mime-version :in-reply-to:content-type:content-transfer-encoding; s=fm1; bh=I JcRZ/CWHxSLYKn2outR8KQ0w6urUhQjzJ0Mj1Vduic=; b=HxlcyL3nPLl7GKYhQ 8EdXdLe8jUwrlZgB0uRBsY1yVzBgUYUvqBbUSenGqP6O1+O+pY/qhhaxodOP7Z0f fmE8mjQY7AiQ26slsuSlk2vSvsI0zlQGjWaFxb/D4KrZBZOa/qqHIMycQF3I/SSj y+0VZ1IaZv8FBQwrtQCiE3tW/Xf4TDIU1pdGvx5eYADQf2F2VnwHUKTqMum3BFeo 9J4z6Vlcf4tMhoTxZWvSLYJGHFLMGVj/S1F2qal2x5NZLUOjrfOTBOK5DlyI3YZL z6zh1cPmcOzFWhSB0zU71/78eByL/iOOy3JlVYhpb7zLD8eWQ3A2fH1eORrhQoyH z8eYg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=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=IJcRZ/CWHxSLYKn2outR8KQ0w6urUhQjzJ0Mj1Vdu ic=; b=lWcLOvRkty+OagsCPqQ34xGzR7p8D8T3USsIa8OeFFMzyaAyqD/5xvrwC BIFTyNWMcEeCCIivbbAipGzLZAIf6cTD3wicavJHQhsmhzqEPFTEOYM1hVLYFG7l 8SHskEaJxswinvtNg0MFNHSljs65Tt/gnKl66C77xLp0uU63snqdMUB0elCRTCqj Y+2qAm7al7RKo+IWsGf5LtvZPwAWGiYIqRxuRlZ2clqKIUVVybK7jU/t1pIsATpq o3JoP6A3SQVTYXguNcJVxsa2rotZgj5g1wHB9ZV2MpZ/jIkf//nUufYoYKdI8Qog Yw13ts22cGWxsBng6wtL5fGS659uA== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduledrieefgdeikecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecunecujfgurhepuffhvfhfkffffgggjggtgfesthejre dttdefjeenucfhrhhomhepjghurhhiucfrrghnkhhovhcuoeihuhhrihhpvheshihurhhi phhvrdguvghvqeenucggtffrrghtthgvrhhnpeejkedtiedtteekueelueegteeiteduge fhjefhudejteefvdfgtefhlefgtdfhteenucffohhmrghinhepthifihhtthgvrhdrtgho mhdpfhhrvggvsghsugdrohhrghdpfhhorhdrvhgrnecukfhppeeluddrvdegtddruddvge drudefjeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhm peihuhhrihhpvheshihurhhiphhvrdguvghv X-ME-Proxy: Received: from [192.168.1.6] (unknown [91.240.124.137]) by mail.messagingengine.com (Postfix) with ESMTPA id 90CB11080059 for ; Sat, 13 Feb 2021 10:09:00 -0500 (EST) Subject: Re: adding a sysctl man section From: Yuri Pankov To: arch@FreeBSD.org References: <20210211001505.GF31099@funkthat.com> Message-ID: Date: Sat, 13 Feb 2021 18:08:58 +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: 4DdDKW6zSpz4dVM X-Spamd-Bar: +++++++++ Authentication-Results: mx1.freebsd.org; dkim=pass header.d=yuripv.dev header.s=fm1 header.b=HxlcyL3n; dkim=pass header.d=messagingengine.com header.s=fm2 header.b=lWcLOvRk; dmarc=none; spf=pass (mx1.freebsd.org: domain of yuripv@yuripv.dev designates 64.147.123.17 as permitted sender) smtp.mailfrom=yuripv@yuripv.dev X-Spamd-Result: default: False [9.90 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; R_SPF_ALLOW(0.00)[+ip4:64.147.123.17]; TO_DN_NONE(0.00)[]; RCVD_COUNT_THREE(0.00)[4]; DKIM_TRACE(0.00)[yuripv.dev:+,messagingengine.com:+]; NEURAL_HAM_SHORT(-1.00)[-1.000]; FROM_EQ_ENVFROM(0.00)[]; RCVD_TLS_LAST(0.00)[]; RBL_DBL_DONT_QUERY_IPS(0.00)[64.147.123.17:from]; ASN(0.00)[asn:11403, ipnet:64.147.123.0/24, country:US]; MIME_TRACE(0.00)[0:+]; MID_RHS_MATCH_FROM(0.00)[]; RCVD_IN_DNSWL_LOW(-0.10)[64.147.123.17:from]; ARC_NA(0.00)[]; RECEIVED_SPAMHAUS_XBL(5.00)[91.240.124.137:received]; RECEIVED_SPAMHAUS_CSS(4.00)[91.240.124.137:received]; FREEFALL_USER(0.00)[yuripv]; FROM_HAS_DN(0.00)[]; R_DKIM_ALLOW(0.00)[yuripv.dev:s=fm1,messagingengine.com:s=fm2]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[arch@freebsd.org]; DMARC_NA(0.00)[yuripv.dev]; NEURAL_SPAM_MEDIUM(1.00)[1.000]; RCPT_COUNT_ONE(0.00)[1]; SPAMHAUS_ZRD(0.00)[64.147.123.17:from:127.0.2.255]; BAD_REP_POLICIES(0.10)[]; NEURAL_SPAM_LONG(1.00)[1.000]; GREYLIST(0.00)[pass,meta]; MAILMAN_DEST(0.00)[arch] 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 15:09:05 -0000 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 ('#'?). From owner-freebsd-arch@freebsd.org Sat Feb 13 16:54:45 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 3D8C3531D76 for ; Sat, 13 Feb 2021 16:54:45 +0000 (UTC) (envelope-from wlosh@bsdimp.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 4DdGgS6TMbz4k7W for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mailman.nyi.freebsd.org (Postfix) id DE40F532098; Sat, 13 Feb 2021 16:54:44 +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 DE0B0531E45 for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: from mail-qk1-x729.google.com (mail-qk1-x729.google.com [IPv6:2607:f8b0:4864:20::729]) (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 4DdGgS5nCpz4k9V for ; Sat, 13 Feb 2021 16:54:44 +0000 (UTC) (envelope-from wlosh@bsdimp.com) Received: by mail-qk1-x729.google.com with SMTP id w19so2657738qki.13 for ; Sat, 13 Feb 2021 08:54:44 -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=53N4uKE24NychRVMSyU2PAFt8pHEzbbfsG7wu8xmc6g=; b=JJr4V+9uMvJzZh+FW5NwdiGE7tAbVFFcFfXz5+6qPp71PkeMY8LuiTa0+mCHSJBYzN rXo5gIiE3hSTwxXvLx/spMjNji4ciIlX0t98vXfHEjUh9vBgixcG33kueFo0sZhgdU30 qGF3wBAMHMNFpL7GDEOs+9595IfyTngOhk4iCSZCD5GVjdeOslH2Tt8w4MPkaYleyefk zff0ykJK3/bTApt1J+bBpQ5DVYos4kkM1NPfxXrTXTReA8IXOgrM4n229FJk6HF32Foh DJ0uqlbt9XMqBHPbZZfV11xRwbYVmCdX1EinXRSjg9d3EOxMtGb80K5ho1aepof8iJm+ K1Ow== 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=53N4uKE24NychRVMSyU2PAFt8pHEzbbfsG7wu8xmc6g=; b=a+hBCkEneW9a9iu+p0sxMpgnZFgi/6FixsZni8dFkUM31Yt3KnMp4q9WXNpEUTvnis CgaZHmbQSnDWRQwVcqFAbgFqecUd8MGnkH8Saq0cJmkbj2PugLb8WaMJKAvhtURfjL+S X8zZ4qDlPXYqM3phRzE6e67nVRjNjZmoLR3l6U+Hm+wsQKmQyB/ScQP9H3YUAH7fBkiB uoImLw2S5WiwKSXuTQCJ4kFgf3TSgM4l27BhDOAGMmLoskaUcMikkNN9krfuKKawIsaX YVRZr7WyPEZieJ7w42D0yNEl8TUFvEaSnLqIvSca8//i7RZ5VHY+mpKDCioOYzGQ3Kxn NJcQ== X-Gm-Message-State: AOAM533j4lEdhXDDjwupFtmPPKdZnKd+Y56c7G8ZnsM0RICQQwrdJAI9 SWXYNhzWBrvuLzpBGUQ19SO3rr6BxFWz88RynG0igc61m4boBQ== X-Google-Smtp-Source: ABdhPJz21n4tVU3wYKLbvUA0AEO4njfzuT4iF8pjwRbwwfveJILSUihrR4S2gcJBukW6x4c8O6O+D9NyVGE0I8lGdU0= X-Received: by 2002:a05:620a:12d1:: with SMTP id e17mr7712427qkl.89.1613235283569; Sat, 13 Feb 2021 08:54:43 -0800 (PST) MIME-Version: 1.0 References: <20210211001505.GF31099@funkthat.com> In-Reply-To: From: Warner Losh Date: Sat, 13 Feb 2021 09:54:32 -0700 Message-ID: Subject: Re: adding a sysctl man section To: Yuri Pankov Cc: "freebsd-arch@freebsd.org" X-Rspamd-Queue-Id: 4DdGgS5nCpz4k9V 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 16:54:45 -0000 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? 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. Warner 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.