Atomic flags (bitmaps)

nRF5 SDK v15.0.0
Macros | Typedefs | Functions

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.