Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:6 as permitted sender) client-ip=2620:137:e000::3:6;
Date:   Thu, 5 Oct 2023 09:48:24 +1100
From:   Dave Chinner <david@fromorbit.com>
To:     John Garry <john.g.garry@oracle.com>
Cc:     Bart Van Assche <bvanassche@acm.org>, linux-kernel@vger.kernel.org,
        linux-api@vger.kernel.org, martin.petersen@oracle.com,
        djwong@kernel.org, himanshu.madhani@oracle.com
Subject: Re: [PATCH 2/4] readv.2: Document RWF_ATOMIC flag
Message-ID: <ZR3ruIg5tpKSG0mp@dread.disaster.area>
References: <20230929093717.2972367-1-john.g.garry@oracle.com>
 <20230929093717.2972367-3-john.g.garry@oracle.com>
 <9ba10b14-931b-42db-b7c2-e6f9aa95e477@acm.org>
 <dee45e9a-6a45-e949-2b46-1373fea8dcda@oracle.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <dee45e9a-6a45-e949-2b46-1373fea8dcda@oracle.com>
Precedence: bulk

On Wed, Oct 04, 2023 at 09:47:24AM +0100, John Garry wrote:
> On 03/10/2023 20:25, Bart Van Assche wrote:
> > On 9/29/23 02:37, John Garry wrote:
> > > +.BR RWF_ATOMIC " (since Linux 6.7)"
> > > +Allows block-based filesystems to indicate that write operations
> > > will be issued
> > > +with torn-write protection. Torn-write protection means that for a
> > > power or any
> > > +other hardware failure, all or none of the data from the write will
> > > be stored,
> > > +but never a mix of old and new data. This flag is meaningful only for
> > > +.BR pwritev2 (),
> > > +and its effect applies only to the data range written by the system
> > > call.
> > > +The total write length must be power-of-2 and must be sized between
> > > +stx_atomic_write_unit_min and stx_atomic_write_unit_max, both
> > > inclusive. The
> > > +write must be at a natural offset within the file with respect to
> > > the total
> > > +write length. Torn-write protection only works with
> > > +.B O_DIRECT
> > > +flag, i.e. buffered writes are not supported. To guarantee
> > > consistency from
> > > +the write between a file's in-core state with the storage device,
> > 
> > It seems wrong to me to start the first sentence with "Allows". Atomic
> > behavior should be mandatory if RWF_ATOMIC has been set.
> 
> Yes, I agree that this has been poorly worded. Flag RWF_ATOMIC does not
> indicate anything. I will fix it.
> 
> > 
> > Additionally, shouldn't it be documented what value will be stored in
> > errno if the atomic write has been rejected?
> 
> So I was treating all atomic writes errors which don't follow the "rules" as
> low-level I/O errors, which is -EIO. However, yes, I can document this.
> Further to that, based on description of an error for O_DIRECT, which is to
> return -EINVAL for misaligned, I think that -EINVAL may be better for any
> atomic write rule violations. OK?

Agreed - I was going to make that comment myself about using EINVAL
instead of EIO...

-Dave.
-- 
Dave Chinner
david@fromorbit.com