Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 7d7363e4 authored by Randy Dunlap's avatar Randy Dunlap Committed by Jonathan Corbet
Browse files

documentation: kernel-api: add more info on bitmap functions 



There are some good comments about bitmap operations in lib/bitmap.c
and include/linux/bitmap.h, so format them for document generation and
pull them into core-api/kernel-api.rst.

I converted the "tables" of functions from using tabs to using spaces
so that they are more readable in the source file and in the generated
output.

Signed-off-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 718d50ec

Documentation/core-api/kernel-api.rst

+12 −0
Original line number Diff line number Diff line
@@ -53,6 +53,18 @@ The Linux kernel provides more basic utility functions. 
Bitmap Operations

-----------------



.. kernel-doc:: lib/bitmap.c

   :doc: bitmap introduction



.. kernel-doc:: include/linux/bitmap.h

   :doc: declare bitmap



.. kernel-doc:: include/linux/bitmap.h

   :doc: bitmap overview



.. kernel-doc:: include/linux/bitmap.h

   :doc: bitmap bitops



.. kernel-doc:: lib/bitmap.c

   :export:

include/linux/bitmap.h

+57 −48
Original line number Diff line number Diff line
@@ -21,13 +21,17 @@ 
 * See lib/bitmap.c for more details.

 */



/*

/**

 * DOC: bitmap overview

 *

 * The available bitmap operations and their rough meaning in the

 * case that the bitmap is a single unsigned long are thus:

 *

 * Note that nbits should be always a compile time evaluable constant.

 * Otherwise many inlines will generate horrible code.

 *

 * ::

 *

 *  bitmap_zero(dst, nbits)                     *dst = 0UL

 *  bitmap_fill(dst, nbits)                     *dst = ~0UL

 *  bitmap_copy(dst, src, nbits)                *dst = *src
@@ -61,10 +65,13 @@ 
 *  bitmap_allocate_region(bitmap, pos, order)  Allocate specified bit region

 *  bitmap_from_u32array(dst, nbits, buf, nwords)  *dst = *buf (nwords 32b words)

 *  bitmap_to_u32array(buf, nwords, src, nbits) *buf = *dst (nwords 32b words)

 *

 */



/*

 * Also the following operations in asm/bitops.h apply to bitmaps.

/**

 * DOC: bitmap bitops

 *

 * Also the following operations in asm/bitops.h apply to bitmaps.::

 *

 *  set_bit(bit, addr)                  *addr |= bit

 *  clear_bit(bit, addr)                *addr &= ~bit
@@ -77,9 +84,11 @@ 
 *  find_first_bit(addr, nbits)         Position first set bit in *addr

 *  find_next_zero_bit(addr, nbits, bit)  Position next zero bit in *addr >= bit

 *  find_next_bit(addr, nbits, bit)     Position next set bit in *addr >= bit

 *

 */



/*

/**

 * DOC: declare bitmap

 * The DECLARE_BITMAP(name,bits) macro, in linux/types.h, can be used

 * to declare an array named 'name' of just enough unsigned longs to

 * contain all bit positions from 0 to 'bits' - 1.

lib/bitmap.c

+3 −1
Original line number Diff line number Diff line
@@ -18,7 +18,9 @@ 


#include <asm/page.h>



/*

/**

 * DOC: bitmap introduction

 *

 * bitmaps provide an array of bits, implemented using an an

 * array of unsigned longs.  The number of valid bits in a

 * given bitmap does _not_ need to be an exact multiple of