Re: [PATCH v9 1/2] lib/bitmap: add bitmap_{read,write}()

[Alexander Potapenko]

> >   *  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).