Bit array

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

name	Name of the bitarray object.
total_bits	Total 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

name	Name of the bitarray object.
total_bits	Total 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]	bitarray	Bitarray struct
[in]	num_bits	Number of bits to allocate
[out]	offset	Offset to the start of allocated region if successful

Return values

0	Allocation successful
-EINVAL	Invalid argument (e.g. allocating more bits than the bitarray has, trying to allocate 0 bits, etc.)
-ENOSPC	No 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]	bitarray	Bitarray struct
[in]	bit	The bit to be cleared

Return values

0	Operation successful
-EINVAL	Invalid 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

bitarray	Bitarray struct
num_bits	Number of bits to test
offset	Starting bit position to test

Return values

0	Operation successful
-EINVAL	Invalid 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]	bitarray	Bitarray struct
[in]	n	Nth bit set to look for
[in]	num_bits	Number of bits to check, must be larger than 0
[in]	offset	Starting bit position
[out]	found_at	Index of the nth bit set, if found

Return values

0	Operation successful
1	Nth bit set was not found in region
-EINVAL	Invalid 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

bitarray	Bitarray struct
num_bits	Number of bits to free
offset	Starting bit position to free

Return values

0	Free is successful
-EINVAL	Invalid argument (e.g. try to free more bits than the bitarray has, trying to free 0 bits, etc.)
-EFAULT	The 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

bitarray	Bitarray struct
num_bits	Number of bits to test
offset	Starting bit position to test

Return values

true	All bits are cleared.
false	Not 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

bitarray	Bitarray struct
num_bits	Number of bits to test
offset	Starting bit position to test

Return values

true	All bits are set.
false	Not 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]	bitarray	Bitarray struct
[in]	num_bits	Number of bits to check, must be larger than 0
[in]	offset	Starting bit position
[out]	count	Number of bits set in the region if successful

Return values

0	Operation successful
-EINVAL	Invalid 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]	bitarray	Bitarray struct
[in]	bit	The bit to be set

Return values

0	Operation successful
-EINVAL	Invalid 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

bitarray	Bitarray struct
num_bits	Number of bits to test
offset	Starting bit position to test

Return values

0	Operation successful
-EINVAL	Invalid 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]	bitarray	Bitarray struct
[in]	bit	The bit to be tested and cleared
[out]	prev_val	Previous value of the bit (0 or 1)

Return values

0	Operation successful
-EINVAL	Invalid 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]	bitarray	Bitarray struct
[in]	bit	The bit to be tested and set
[out]	prev_val	Previous value of the bit (0 or 1)

Return values

0	Operation successful
-EINVAL	Invalid 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

bitarray	Bitarray struct
num_bits	Number of bits to test and set
offset	Starting bit position to test and set
to_set	if 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

0	Operation successful
-EINVAL	Invalid argument (e.g. bit to set exceeds the number of bits in bit array, etc.)
-EEXIST	at 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]	bitarray	Bitarray struct
[in]	bit	The bit to be tested
[out]	val	The value of the bit (0 or 1)

Return values

0	Operation successful
-EINVAL	Invalid 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

dst	Bitarray struct
other	Bitarray struct
num_bits	Number of bits in the region, must be larger than 0
offset	Starting bit location

Return values

0	Operation successful
-EINVAL	Invalid argument (e.g. out-of-bounds access, mismatching bitarrays, trying to xor 0 bits, etc.)