Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

Store and manipulate bits in a bit array. More...

Macros

#define SYS_BITARRAY_DEFINE(name, total_bits)    _SYS_BITARRAY_DEFINE(name, total_bits,)
 Create a bitarray object.
 
#define SYS_BITARRAY_DEFINE_STATIC(name, total_bits)    _SYS_BITARRAY_DEFINE(name, total_bits, static)
 Create a static bitarray object.
 

Typedefs

typedef struct sys_bitarray sys_bitarray_t
 Bitarray structure.
 

Functions

int sys_bitarray_set_bit (sys_bitarray_t *bitarray, size_t bit)
 Set a bit in a bit array.
 
int sys_bitarray_clear_bit (sys_bitarray_t *bitarray, size_t bit)
 Clear a bit in a bit array.
 
int sys_bitarray_test_bit (sys_bitarray_t *bitarray, size_t bit, int *val)
 Test whether a bit is set or not.
 
int sys_bitarray_test_and_set_bit (sys_bitarray_t *bitarray, size_t bit, int *prev_val)
 Test the bit and set it.
 
int sys_bitarray_test_and_clear_bit (sys_bitarray_t *bitarray, size_t bit, int *prev_val)
 Test the bit and clear it.
 
int sys_bitarray_alloc (sys_bitarray_t *bitarray, size_t num_bits, size_t *offset)
 Allocate bits in a bit array.
 
int sys_bitarray_xor (sys_bitarray_t *dst, sys_bitarray_t *other, size_t num_bits, size_t offset)
 Calculates the bit-wise XOR of two bitarrays in a region.
 
int sys_bitarray_find_nth_set (sys_bitarray_t *bitarray, size_t n, size_t num_bits, size_t offset, size_t *found_at)
 Find nth bit set in region.
 
int sys_bitarray_popcount_region (sys_bitarray_t *bitarray, size_t num_bits, size_t offset, size_t *count)
 Count bits set in a bit array region.
 
int sys_bitarray_free (sys_bitarray_t *bitarray, size_t num_bits, size_t offset)
 Free bits in a bit array.
 
bool sys_bitarray_is_region_set (sys_bitarray_t *bitarray, size_t num_bits, size_t offset)
 Test if bits in a region is all set.
 
bool sys_bitarray_is_region_cleared (sys_bitarray_t *bitarray, size_t num_bits, size_t offset)
 Test if bits in a region is all cleared.
 
int sys_bitarray_set_region (sys_bitarray_t *bitarray, size_t num_bits, size_t offset)
 Set all bits in a region.
 
int sys_bitarray_test_and_set_region (sys_bitarray_t *bitarray, size_t num_bits, size_t offset, bool to_set)
 Test if all bits in a region are cleared/set and set/clear them in a single atomic operation.
 
int sys_bitarray_clear_region (sys_bitarray_t *bitarray, size_t num_bits, size_t offset)
 Clear all bits in a region.
 

Detailed Description

Store and manipulate bits in a bit array.

Macro Definition Documentation

◆ SYS_BITARRAY_DEFINE

#define SYS_BITARRAY_DEFINE (   name,
  total_bits 
)     _SYS_BITARRAY_DEFINE(name, total_bits,)

#include <zephyr/sys/bitarray.h>

Create a bitarray object.

Parameters
nameName of the bitarray object.
total_bitsTotal number of bits in this bitarray object.

◆ SYS_BITARRAY_DEFINE_STATIC

#define SYS_BITARRAY_DEFINE_STATIC (   name,
  total_bits 
)     _SYS_BITARRAY_DEFINE(name, total_bits, static)

#include <zephyr/sys/bitarray.h>

Create a static bitarray object.

Parameters
nameName of the bitarray object.
total_bitsTotal number of bits in this bitarray object.

Typedef Documentation

◆ sys_bitarray_t

typedef struct sys_bitarray sys_bitarray_t

#include <zephyr/sys/bitarray.h>

Bitarray structure.

Function Documentation

◆ sys_bitarray_alloc()

int sys_bitarray_alloc ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t offset 
)

#include <zephyr/sys/bitarray.h>

Allocate bits in a bit array.

This finds a number of bits (num_bits) in a contiguous of previously unallocated region. If such a region exists, the bits are marked as allocated and the offset to the start of this region is returned via offset.

Parameters
[in]bitarrayBitarray struct
[in]num_bitsNumber of bits to allocate
[out]offsetOffset to the start of allocated region if successful
Return values
0Allocation successful
-EINVALInvalid argument (e.g. allocating more bits than the bitarray has, trying to allocate 0 bits, etc.)
-ENOSPCNo contiguous region big enough to accommodate the allocation

◆ sys_bitarray_clear_bit()

int sys_bitarray_clear_bit ( sys_bitarray_t bitarray,
size_t  bit 
)

#include <zephyr/sys/bitarray.h>

Clear a bit in a bit array.

Parameters
[in]bitarrayBitarray struct
[in]bitThe bit to be cleared
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to clear exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_clear_region()

int sys_bitarray_clear_region ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Clear all bits in a region.

This clears the number of bits (num_bits) in region starting from offset.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to test
offsetStarting bit position to test
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to set exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_find_nth_set()

int sys_bitarray_find_nth_set ( sys_bitarray_t bitarray,
size_t  n,
size_t  num_bits,
size_t  offset,
size_t found_at 
)

#include <zephyr/sys/bitarray.h>

Find nth bit set in region.

This counts the number of bits set (count) in a region (offset, num_bits) and returns the index (found_at) of the nth set bit, if it exists, as long with a zero return value.

If it does not exist, found_at is not updated and the method returns

Parameters
[in]bitarrayBitarray struct
[in]nNth bit set to look for
[in]num_bitsNumber of bits to check, must be larger than 0
[in]offsetStarting bit position
[out]found_atIndex of the nth bit set, if found
Return values
0Operation successful
1Nth bit set was not found in region
-EINVALInvalid argument (e.g. out-of-bounds access, trying to count 0 bits, etc.)

◆ sys_bitarray_free()

int sys_bitarray_free ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Free bits in a bit array.

This marks the number of bits (num_bits) starting from offset as no longer allocated.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to free
offsetStarting bit position to free
Return values
0Free is successful
-EINVALInvalid argument (e.g. try to free more bits than the bitarray has, trying to free 0 bits, etc.)
-EFAULTThe bits in the indicated region are not all allocated.

◆ sys_bitarray_is_region_cleared()

bool sys_bitarray_is_region_cleared ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Test if bits in a region is all cleared.

This tests if the number of bits (num_bits) in region starting from offset are all cleared.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to test
offsetStarting bit position to test
Return values
trueAll bits are cleared.
falseNot all bits are cleared.

◆ sys_bitarray_is_region_set()

bool sys_bitarray_is_region_set ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Test if bits in a region is all set.

This tests if the number of bits (num_bits) in region starting from offset are all set.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to test
offsetStarting bit position to test
Return values
trueAll bits are set.
falseNot all bits are set.

◆ sys_bitarray_popcount_region()

int sys_bitarray_popcount_region ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset,
size_t count 
)

#include <zephyr/sys/bitarray.h>

Count bits set in a bit array region.

This counts the number of bits set (count) in a region (offset, num_bits).

Parameters
[in]bitarrayBitarray struct
[in]num_bitsNumber of bits to check, must be larger than 0
[in]offsetStarting bit position
[out]countNumber of bits set in the region if successful
Return values
0Operation successful
-EINVALInvalid argument (e.g. out-of-bounds access, trying to count 0 bits, etc.)

◆ sys_bitarray_set_bit()

int sys_bitarray_set_bit ( sys_bitarray_t bitarray,
size_t  bit 
)

#include <zephyr/sys/bitarray.h>

Set a bit in a bit array.

Parameters
[in]bitarrayBitarray struct
[in]bitThe bit to be set
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to set exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_set_region()

int sys_bitarray_set_region ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Set all bits in a region.

This sets the number of bits (num_bits) in region starting from offset.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to test
offsetStarting bit position to test
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to set exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_test_and_clear_bit()

int sys_bitarray_test_and_clear_bit ( sys_bitarray_t bitarray,
size_t  bit,
int *  prev_val 
)

#include <zephyr/sys/bitarray.h>

Test the bit and clear it.

Parameters
[in]bitarrayBitarray struct
[in]bitThe bit to be tested and cleared
[out]prev_valPrevious value of the bit (0 or 1)
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to test exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_test_and_set_bit()

int sys_bitarray_test_and_set_bit ( sys_bitarray_t bitarray,
size_t  bit,
int *  prev_val 
)

#include <zephyr/sys/bitarray.h>

Test the bit and set it.

Parameters
[in]bitarrayBitarray struct
[in]bitThe bit to be tested and set
[out]prev_valPrevious value of the bit (0 or 1)
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to test exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_test_and_set_region()

int sys_bitarray_test_and_set_region ( sys_bitarray_t bitarray,
size_t  num_bits,
size_t  offset,
bool  to_set 
)

#include <zephyr/sys/bitarray.h>

Test if all bits in a region are cleared/set and set/clear them in a single atomic operation.

This checks if all the bits (num_bits) in region starting from offset are in required state. If even one bit is not, -EEXIST is returned. If the whole region is set/cleared it is set to opposite state. The check and set is performed as a single atomic operation.

Parameters
bitarrayBitarray struct
num_bitsNumber of bits to test and set
offsetStarting bit position to test and set
to_setif true the region will be set if all bits are cleared if false the region will be cleard if all bits are set
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to set exceeds the number of bits in bit array, etc.)
-EEXISTat least one bit in the region is set/cleared, operation cancelled

◆ sys_bitarray_test_bit()

int sys_bitarray_test_bit ( sys_bitarray_t bitarray,
size_t  bit,
int *  val 
)

#include <zephyr/sys/bitarray.h>

Test whether a bit is set or not.

Parameters
[in]bitarrayBitarray struct
[in]bitThe bit to be tested
[out]valThe value of the bit (0 or 1)
Return values
0Operation successful
-EINVALInvalid argument (e.g. bit to test exceeds the number of bits in bit array, etc.)

◆ sys_bitarray_xor()

int sys_bitarray_xor ( sys_bitarray_t dst,
sys_bitarray_t other,
size_t  num_bits,
size_t  offset 
)

#include <zephyr/sys/bitarray.h>

Calculates the bit-wise XOR of two bitarrays in a region.

The result is stored in the first bitarray passed in (dst). Both bitarrays must be of the same size.

Parameters
dstBitarray struct
otherBitarray struct
num_bitsNumber of bits in the region, must be larger than 0
offsetStarting bit location
Return values
0Operation successful
-EINVALInvalid argument (e.g. out-of-bounds access, mismatching bitarrays, trying to xor 0 bits, etc.)