Received-SPF: pass (google.com: domain of linux-kernel+bounces-147049-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
Date: Tue, 16 Apr 2024 08:44:55 -0600
From: Keith Busch <kbusch@kernel.org>
To: Lennart Poettering <mzxreary@0pointer.de>
Cc: Christoph Hellwig <hch@lst.de>,
	Linux regressions mailing list <regressions@lists.linux.dev>,
	linux-block@vger.kernel.org, LKML <linux-kernel@vger.kernel.org>,
	Jens Axboe <axboe@kernel.dk>
Subject: Re: API break, sysfs "capability" file
Message-ID: <Zh6O5zTBs5JtV4D2@kbusch-mbp>
References: <ZhQJf8mzq_wipkBH@gardel-login>
 <54e3c969-3ee8-40d8-91d9-9b9402001d27@leemhuis.info>
 <ZhQ6ZBmThBBy_eEX@kbusch-mbp.dhcp.thefacebook.com>
 <ZhRSVSmNmb_IjCCH@gardel-login>
 <ZhRyhDCT5cZCMqYj@kbusch-mbp.dhcp.thefacebook.com>
 <ZhT5_fZ9SrM0053p@gardel-login>
 <20240409141531.GB21514@lst.de>
 <Zh6J75OrcMY3dAjY@gardel-login>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <Zh6J75OrcMY3dAjY@gardel-login>

On Tue, Apr 16, 2024 at 04:23:43PM +0200, Lennart Poettering wrote:
> On Di, 09.04.24 16:15, Christoph Hellwig (hch@lst.de) wrote:
> 11;rgb:1717/1414/2121
> > On Tue, Apr 09, 2024 at 10:19:09AM +0200, Lennart Poettering wrote:
> > > All I am looking for is a very simple test that returns me a boolean:
> > > is there kernel-level partition scanning enabled on this device or
> > > not.
> >
> > And we can add a trivial sysfs attribute for that.
> >
> > > At this point it's not clear to me if I can write this at all in
> > > a way that works reasonably correctly on any kernel since let's say
> > > 4.15 (which is systemd's "recommended baseline" right now).
> > >
> > > I am really not sure how to salvage this mess at all. AFAICS there's
> > > currently no way to write such a test correctly.
> >
> > You can't.  Maybe that's a lesson to not depend on undocumented internal
> > flags exposed by accident by a weirdo interface.  Just talk to
> > people.
> 
> Undocumented? Internal?
> 
> It's was actually one of the *best* documented kernel *public* APIs I
> ever came across:
> 
>    https://www.kernel.org/doc/html/v5.16/block/capability.html
> 
> So much detail, I love it!
>
> I mean, you did good work here, documented it, with all flags in all
> details. I think that's great work! You should take pride in this, not
> try to deny its existance!

The patch that introduced this was submitted not because the API was
stable; it was committed to encourage developers to update it as it
changed because it is *not* stable. That's not the kind of interface you
want exported for users to rely on, but no one should have to search
commit logs to understand why the doc exists, so I think exporting it
was just a mistake on the kernel side. To say this doc is "good"
misunderstands what it was trying to accomplish, and what it ultimately
created instead: technical debt.

The block interfaces documented in Documetation/ABI/stable/ are reliably
stable, though.