On Fri, May 05, 2023 at 09:01:58AM +0100, John Garry wrote: > 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. Agreed. The manpage contents are what needs to get worked on at LSFMM where you'll have various block/fs/storage device people in the same room with which to discuss various issues and try to smooth out the misundertandings. (Also: I've decided to cancel my in-person attendance due to a sudden health issue. I'll still be in the room, just virtually now. :() --D > Thanks, > John
