Atomic flags (bitmaps)

This module implements atomic flags as bitmaps. More...

Macros
#define	NRF_ATFLAGS_FLAGS_PER_ELEMENT   (sizeof(nrf_atflags_t) * 8)
	Number of flags per nrf_atflags_t.
#define	NRF_ATFLAGS_ARRAY_LEN(flag_count)   ((flag_count - 1) / NRF_ATFLAGS_FLAGS_PER_ELEMENT) + 1
	Macro for the length of an array of nrf_atflags_t needed to keep flag_count flags. More...
#define	NRF_ATFLAGS_DEF(_name, flag_count)   nrf_atflags_t _name[NRF_ATFLAGS_ARRAY_LEN((flag_count))] = {0}
	Macro for declaring a flag array with the right size and initial value. More...
#define	NRF_ATFLAGS_DEF_MEMBER(_name, flag_count)   nrf_atflags_t _name[NRF_ATFLAGS_ARRAY_LEN((flag_count))]
	Macro for declaring a flag array with the right size as a member of a struct. More...

Typedefs
typedef volatile uint32_t	nrf_atflags_t
	Array of atomic flags.

Functions
uint32_t	nrf_atflags_init (nrf_atflags_t *p_flags, uint32_t flags_array_len, uint32_t flag_count)
	Function for safely initializing a flag array to 0. More...
void	nrf_atflags_set (nrf_atflags_t *p_flags, uint32_t flag_index)
	Function for atomically setting a flag to 1. More...
bool	nrf_atflags_fetch_set (nrf_atflags_t *p_flags, uint32_t flag_index)
	Function for atomically setting a flag to 1, returning the previous value of the flag. More...
void	nrf_atflags_clear (nrf_atflags_t *p_flags, uint32_t flag_index)
	Function for atomically setting a flag to 0. More...
bool	nrf_atflags_fetch_clear (nrf_atflags_t *p_flags, uint32_t flag_index)
	Function for atomically setting a flag to 0, returning the previous value of the flag. More...
bool	nrf_atflags_get (nrf_atflags_t const *p_flags, uint32_t flag_index)
	Function for getting the value of a flag in a flag array. More...
uint32_t	nrf_atflags_find_and_set_flag (nrf_atflags_t *p_flags, uint32_t flag_count)
	Function for finding a flag with value 0, and atomically setting it to one. More...
uint32_t	nrf_atflags_find_and_clear_flag (nrf_atflags_t *p_flags, uint32_t flag_count)
	Function for finding a flag with value 1, and atomically clearing it to 0. More...

Detailed Description

This module implements atomic flags as bitmaps.

Operations on the individual flags are atomic, meaning that you are always sure that the flag is set to the desired value, and you always know what value was there before. You also know that no other flags were affected by the operation.

Operations on the entire flag collection are NOT atomic. This essentially means that you can't know the order in which operations on different flags happened, and you can't know the state of the entire flag collection at any instant. These limitations can be overcome by protecting operations with a mutex.

Macro Definition Documentation

#define NRF_ATFLAGS_ARRAY_LEN

(

flag_count

)

((flag_count - 1) / NRF_ATFLAGS_FLAGS_PER_ELEMENT) + 1

Macro for the length of an array of nrf_atflags_t needed to keep flag_count flags.

Parameters

flag_count

Number of flags to keep in a flag array.

Returns

Length of the array needed to house flag_count flags.

#define NRF_ATFLAGS_DEF	(		_name,
			flag_count
	)		nrf_atflags_t _name[NRF_ATFLAGS_ARRAY_LEN((flag_count))] = {0}

Macro for declaring a flag array with the right size and initial value.

Note

When using this macro, no call to nrf_atflags_init is necessary for this array.

Parameters

_name	Name to be given to the array.
flag_count	Number of flags to be kept in the flag array.

Returns

Flag array definition.

#define NRF_ATFLAGS_DEF_MEMBER	(		_name,
			flag_count
	)		nrf_atflags_t _name[NRF_ATFLAGS_ARRAY_LEN((flag_count))]

Macro for declaring a flag array with the right size as a member of a struct.

Note

When using this macro, make sure to set the array to 0 or use nrf_atflags_init

Parameters

_name	Name to be given to the array.
flag_count	Number of flags to be kept in the flag array.

Returns

Flag array definition.

Function Documentation

void nrf_atflags_clear	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_index
	)

Function for atomically setting a flag to 0.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_index	Index of the flag in the array.

bool nrf_atflags_fetch_clear	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_index
	)

Function for atomically setting a flag to 0, returning the previous value of the flag.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_index	Index of the flag in the array.

Returns

Old flag value.

bool nrf_atflags_fetch_set	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_index
	)

Function for atomically setting a flag to 1, returning the previous value of the flag.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_index	Index of the flag in the array.

Returns

Old flag value.

uint32_t nrf_atflags_find_and_clear_flag	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_count
	)

Function for finding a flag with value 1, and atomically clearing it to 0.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_count	The number of flags in the array.

Returns

The index of the set flag that has been cleared.

uint32_t nrf_atflags_find_and_set_flag	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_count
	)

Function for finding a flag with value 0, and atomically setting it to one.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_count	Number of flags in the array.

Returns

Index of the cleared flag that has been set.

bool nrf_atflags_get	(	nrf_atflags_t const *	p_flags,
		uint32_t	flag_index
	)

Function for getting the value of a flag in a flag array.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_index	Index of the flag in the array.

Returns

Flag value.

uint32_t nrf_atflags_init	(	nrf_atflags_t *	p_flags,
		uint32_t	flags_array_len,
		uint32_t	flag_count
	)

Function for safely initializing a flag array to 0.

Parameters

p_flags	Flag array to initialize.
flags_array_len	Length of p_flags.
flag_count	Number of flags to be kept in the flag array.

Return values

0	if the given length is not sufficient to house flag_count flags in the array.

Returns

If successful: The actual length required.

void nrf_atflags_set	(	nrf_atflags_t *	p_flags,
		uint32_t	flag_index
	)

Function for atomically setting a flag to 1.

Parameters

[in]	p_flags	Atomic flag array.
[in]	flag_index	Index of the flag in the array.