Re: [PATCH 1/1] block: Use bits.h macros to improve readability

[Leonardo Bras <leonardo@linux.ibm.com>]

[-- Attachment #1: Type: text/plain, Size: 2452 bytes --]

On Fri, 2019-08-02 at 21:18 -0700, Jens Axboe wrote:
> On 8/1/19 6:00 PM, Leonardo Bras wrote:
> > Applies some bits.h macros in order to improve readability of
> > linux/blk_types.h.
> > 
> > Signed-off-by: Leonardo Bras <leonardo@linux.ibm.com>
> > ---
> >   include/linux/blk_types.h | 55 ++++++++++++++++++++-------------------
> >   1 file changed, 28 insertions(+), 27 deletions(-)
> > 
> > diff --git a/include/linux/blk_types.h b/include/linux/blk_types.h
> > index 95202f80676c..31c8c6d274f6 100644
> > --- a/include/linux/blk_types.h
> > +++ b/include/linux/blk_types.h
> > @@ -9,6 +9,7 @@
> >   #include <linux/types.h>
> >   #include <linux/bvec.h>
> >   #include <linux/ktime.h>
> > +#include <linux/bits.h>
> >   
> >   struct bio_set;
> >   struct bio;
> > @@ -101,13 +102,13 @@ static inline bool blk_path_error(blk_status_t error)
> >   #define BIO_ISSUE_SIZE_BITS     12
> >   #define BIO_ISSUE_RES_SHIFT     (64 - BIO_ISSUE_RES_BITS)
> >   #define BIO_ISSUE_SIZE_SHIFT    (BIO_ISSUE_RES_SHIFT - BIO_ISSUE_SIZE_BITS)
> > -#define BIO_ISSUE_TIME_MASK     ((1ULL << BIO_ISSUE_SIZE_SHIFT) - 1)
> > +#define BIO_ISSUE_TIME_MASK     GENMASK_ULL(BIO_ISSUE_SIZE_SHIFT - 1, 0)
> 
> Not sure why we even have these helpers, I'd argue that patches like
> this HURT readability, not improve it. When I see
> 
> ((1ULL << SOME_SHIFT) - 1)
> 
> I know precisely what that does, whereas I have to think about the other
> one, maybe even look it up to be sure. For instance, without looking
> now, I have no idea what the second argument is. Looking at the git log,
> I see numerous instances of:
> 
> "xxx: Fix misuses of GENMASK macro
> 
>  Arguments are supposed to be ordered high then low."
> 
> Hence it seems GENMASK_ULL is easy to misuse or get wrong, the very
> opposite of what you'd want in a helper. How is it helping readability
> if the helper is easy to misuse?
> 
> Ditto with
> 
> (1ULL << SOME_SHIFT)
> 
> vs BIT_ULL. But at least that one doesn't have a mysterious 2nd
> argument.
> 
> Hence I'm not inclined to apply this patch.
> 

Well, as a newbie, macros like GENMASK(a,b) look way simpler. I to read
than (((1 << a) - 1) << b), or (~((1 << c) - 1)).
I mean, in GENMASK all bits >= a, <=b are set. 

But I agree that once you get used to reading masks created with <<, it
doesn't look that harder.

Well, thanks for this feedback.

Regards, 
Leonardo Brás

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 833 bytes --]