Re: [PATCH RFC 02/16] fs/bdev: Add atomic write support info to statx

From: John Garry <john.g.garry@oracle.com>
To: Dave Chinner <david@fromorbit.com>
Cc: axboe@kernel.dk, kbusch@kernel.org, hch@lst.de, sagi@grimberg.me,
	martin.petersen@oracle.com, djwong@kernel.org,
	viro@zeniv.linux.org.uk, brauner@kernel.org, dchinner@redhat.com,
	jejb@linux.ibm.com, linux-block@vger.kernel.org,
	linux-kernel@vger.kernel.org, linux-nvme@lists.infradead.org,
	linux-scsi@vger.kernel.org, linux-xfs@vger.kernel.org,
	linux-fsdevel@vger.kernel.org,
	linux-security-module@vger.kernel.org, paul@paul-moore.com,
	jmorris@namei.org, serge@hallyn.com,
	Prasad Singamsetty <prasad.singamsetty@oracle.com>
Subject: Re: [PATCH RFC 02/16] fs/bdev: Add atomic write support info to statx
Date: Fri, 5 May 2023 09:01:58 +0100	[thread overview]
Message-ID: <644fe4aa-cb89-0c14-4c90-cc93bcc6bbc2@oracle.com> (raw)
In-Reply-To: <20230504224033.GJ3223426@dread.disaster.area>

On 04/05/2023 23:40, Dave Chinner wrote:

Hi Dave,

>> No, not yet. Is it normally expected to provide a proposed man page update
>> in parallel? Or somewhat later, when the kernel API change has some
>> appreciable level of agreement?
> Normally we ask for man page updates to be presented at the same
> time, as the man page defines the user interface that is being
> implemented. In this case, we need updates for the pwritev2() man
> page to document RWF_ATOMIC semantics, and the statx() man page to
> document what the variables being exposed mean w.r.t. RWF_ATOMIC.
> 
> The pwritev2() man page is probably the most important one right now
> - it needs to explain the guarantees that RWF_ATOMIC is supposed to
> provide w.r.t. data integrity, IO ordering, persistence, etc.
> Indeed, it will need to explain exactly how this "multi-atomic-unit
> mulit-bio non-atomic RWF_ATOMIC" IO thing can be used safely and
> reliably, especially w.r.t. IO ordering and persistence guarantees
> in the face of crashes and power failures. Not to mention
> documenting error conditions specific to RWF_ATOMIC...
> 
> It's all well and good to have some implementation, but without
> actually defining and documenting the*guarantees*  that RWF_ATOMIC
> provides userspace it is completely useless for application
> developers. And from the perspective of a reviewer, without the
> documentation stating what the infrastructure actually guarantees
> applications, we can't determine if the implementation being
> presented is fit for purpose....

ok, understood. Obviously from any discussion so far there are many 
details which the user needs to know about how to use this interface and 
what to expect.

We'll look to start working on those man page details now.

Thanks,
John