Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.37 as permitted sender) client-ip=23.128.96.37;
MIME-Version: 1.0
References: <20231025083812.456916-1-glider@google.com> <ZTpYbCa0Qmry0HGH@smile.fi.intel.com>
In-Reply-To: <ZTpYbCa0Qmry0HGH@smile.fi.intel.com>
From:   Alexander Potapenko <glider@google.com>
Date:   Thu, 26 Oct 2023 15:28:25 +0200
Message-ID: <CAG_fn=Uv+ox4a1x=-w8DTU_Pj9VPh9TYhBRcDsPh+=Kc2Jsg5w@mail.gmail.com>
Subject: Re: [PATCH v9 1/2] lib/bitmap: add bitmap_{read,write}()
To:     Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Cc:     catalin.marinas@arm.com, will@kernel.org, pcc@google.com,
        andreyknvl@gmail.com, aleksander.lobakin@intel.com,
        linux@rasmusvillemoes.dk, yury.norov@gmail.com,
        alexandru.elisei@arm.com, linux-kernel@vger.kernel.org,
        linux-arm-kernel@lists.infradead.org, eugenis@google.com,
        syednwaris@gmail.com, william.gray@linaro.org,
        Arnd Bergmann <arnd@arndb.de>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

> >   *  bitmap_to_arr64(buf, src, nbits)            Copy nbits from buf to u64[] dst
> >   *  bitmap_get_value8(map, start)               Get 8bit value from map at start
> >   *  bitmap_set_value8(map, value, start)        Set 8bit value to map at start
> > + *  bitmap_read(map, start, nbits)              Read an nbits-sized value from
> > + *                                              map at start
> > + *  bitmap_write(map, value, start, nbits)      Write an nbits-sized value to
> > + *                                              map at start
>
> I still didn't get the grouping you implied with this...

Given your second reply, I can disregard this one, right?

>
> >   * Note, bitmap_zero() and bitmap_fill() operate over the region of
> >   * unsigned longs, that is, bits behind bitmap till the unsigned long
>
> ...
>
> > +/**
> > + * bitmap_read - read a value of n-bits from the memory region
> > + * @map: address to the bitmap memory region
> > + * @start: bit offset of the n-bit value
> > + * @nbits: size of value in bits, nonzero, up to BITS_PER_LONG
> > + *
> > + * Returns: value of nbits located at the @start bit offset within the @map
> > + * memory region.
> > + *
> > + * Note: callers on 32-bit systems must be careful to not attempt reading more
> > + * than sizeof(unsigned long).
>
> sizeof() here is misleading, We talk about bits, BITS_PER_LONG (which is 32),
> here it's better to be explicit that reading more than 32 bits at a time on
> 32-bit platform will return 0. Actually what you need is to describe...
>
> > + */
> > +static inline unsigned long bitmap_read(const unsigned long *map,
> > +                                     unsigned long start,
> > +                                     unsigned long nbits)
> > +{
> > +     size_t index = BIT_WORD(start);
> > +     unsigned long offset = start % BITS_PER_LONG;
> > +     unsigned long space = BITS_PER_LONG - offset;
> > +     unsigned long value_low, value_high;
> > +
> > +     if (unlikely(!nbits || nbits > BITS_PER_LONG))
> > +             return 0;
>
> ...this return in the Return section.
>

Parameter description for @nbits actually mentions BITS_PER_LONG
already, so would it be ok to drop the Note: and extend the Returns:
section as follows:

+ * Returns: value of nbits located at the @start bit offset within the @map
+ * memory region. For @nbits = 0 and @nbits > BITS_PER_LONG the return value
+ * is undefined.

?

(Yury didn't want the zero return value to be part of the contract here).