nrfcxx Namespace Reference

Primary namespace for nrfcxx functionality. More...

Namespaces
	board
	Namespace holding board-specific configuration data.
	clock
	Functions and classes related to clocks and time.
	crc
	Namespace providing pre-defined checksum algorithms.
	gpio
	Abstractions and constants around GPIO capability.
	led
	Abstractions and constants around LED capability.
	lpm
	Infrastructure to support low-power-mode operations.
	misc
	Namespace for abstractions that aren't handled in another namespace.
	nrf5
	Namespace holding support for bare nRF5 peripheral instances.
	periph
	Abstractions of nRF51 peripherals.
	sensor
	Namespace for abstractions of various sensors.
	utility
	Various utilities, probably not dependent on nRF51 at all.

Data Structures
class	event_set
	A record of events that occur asynchonously. More...
class	event_set_copy
	A helper class for processing snapshot nrfcxx::event_set values. More...
class	mutex_irq
	nvic_BlockIRQ as a template type. More...
class	null_mutex
	RAII class that performs no mutex operations. More...
class	nvic_BlockIRQ
	RAII class to block a peripheral interrupt. More...
class	primask
	RAII class to block exceptions. More...
class	systemState
	A class supporting watchdog configuration and cross-reset retention of state. More...
class	watchdog_extended_channel
	Support for extended watchdog channels. More...

Typedefs
using	notifier_type = std::function< void()>
	Type used to hold a notifier. More...

Enumerations
enum	FailSafeCode : unsigned int {   FailSafeCode::SYSTEM_BASE = 0xbad00000, FailSafeCode::NO_SUCH_PERIPHERAL = SYSTEM_BASE + 1, FailSafeCode::MEMORY_POOL = SYSTEM_BASE + 2, FailSafeCode::HEAP_OVERRUN = SYSTEM_BASE + 3,   FailSafeCode::STACK_OVERFLOW = SYSTEM_BASE + 4, FailSafeCode::PERSIST_VIOLATION = SYSTEM_BASE + 5, FailSafeCode::INTERNAL_ERROR = SYSTEM_BASE + 6, FailSafeCode::INCOMPLETE_SETUP = SYSTEM_BASE + 7,   FailSafeCode::RESOURCE_VIOLATION = SYSTEM_BASE + 8, FailSafeCode::API_VIOLATION = SYSTEM_BASE + 9, FailSafeCode::BOARD_INIT_FAILURE = SYSTEM_BASE + 10, FailSafeCode::EVENT_LOOP_TERMINATED = SYSTEM_BASE + 11,   FailSafeCode::APPLICATION_BASE = 0xbad10000 }
	Enumerated constants used in failsafe() calls. More...

Functions
void	delay_us (unsigned int number_of_us)
	Delay for exactly the specified duration. More...
void	sleep_ms (unsigned int dur_ms)
	Sleep for the specified duration. More...
static void	nvic_EnableIRQ (int irqn)
	Wrapper around NVIC_EnableIRQ to work around issues with peripheral::IRQn.
static void	nvic_DisableIRQ (int irqn)
	Wrapper around NVIC_DisableIRQ to work around issues with peripheral::IRQn.
static void	nvic_GetPendingIRQ (int irqn)
	Wrapper around NVIC_GetPending to work around issues with peripheral::IRQn.
static void	nvic_SetPendingIRQ (int irqn)
	Wrapper around NVIC_SetPending to work around issues with peripheral::IRQn.
static void	nvic_ClearPendingIRQ (int irqn)
	Wrapper around NVIC_ClearPending to work around issues with peripheral::IRQn.
static void	nvic_SetPriority (int irqn, uint32_t priority)
	Wrapper around NVIC_SetPriority to work around issues with peripheral::IRQn.
static void	nvic_GetPriority (int irqn)
	Wrapper around NVIC_GetPriority to work around issues with peripheral::IRQn.
static FailSafeCode	operator+ (const FailSafeCode &lhs, unsigned int incr)
void	failsafe (FailSafeCode code)
	Record a critical system failure and reset the system. More...
void	failsafe (unsigned int code)
int	stack_space_remaining ()
	Determine how much of the reserved stack space remains. More...
void	validate_stack_pointer ()
	Force a system failure if the stack is beyond its configured maximum depth. More...
unsigned int	stack_fill_unused (unsigned int marker)
	Fill all space between the top of the heap and the current stack pointer with the provided value. More...
unsigned int	stack_infer_highwater (unsigned int marker)
	Check the space between the top of the heap and the current stack pointer for matches to the provided marker. More...
uint32_t	application_crc32 (bool exclude_data=false)
	Calculate a checksum of the application content. More...

Variables
static constexpr auto	IRQ_PRIORITY_SD_HIGH = 0
	NVIC IRQ priority reserved for critical soft-device interrupts.
static constexpr auto	IRQ_PRIORITY_APP_HIGH = 1
	NVIC IRQ priority reserved for critical application interrupts.
static constexpr auto	IRQ_PRIORITY_SD_LOW = 2
	NVIC IRQ priority reserved for non-critical soft-device interrupts.
static constexpr auto	IRQ_PRIORITY_APP_LOW = 3
	NVIC IRQ priority reserved for non-critical application interrupts.
static constexpr auto	IRQ_PRIORITY_SD_HIGH = 0
	NVIC IRQ priority reserved for critical soft-device interrupts.
static constexpr auto	IRQ_PRIORITY_SD_MEMORY = 1
	NVIC IRQ priority reserved for critical soft-device memory isolation and runtime protection.
static constexpr auto	IRQ_PRIORITY_APP_HIGH = 2
	NVIC IRQ priority reserved for critical application interrupts.
static constexpr auto	IRQ_PRIORITY_SD_LOW = 4
	NVIC IRQ priority reserved for non-critical soft-device interrupts.
static constexpr auto	IRQ_PRIORITY_APP_LOW = 5
	NVIC IRQ priority reserved for non-critical application interrupts.

Detailed Description

Primary namespace for nrfcxx functionality.

Typedef Documentation

notifier_type

using nrfcxx::notifier_type = typedef std::function<void()>

Type used to hold a notifier.

This type is used when an operation must record a callback to be invoked when it completes, and that callback does not transfer any information outside of the fact of its being invoked.

Values compatible with this are nullary static functions and lambdas with no arguments. A common source for such a value is event_set::make_setter().

Enumeration Type Documentation

FailSafeCode

enum nrfcxx::FailSafeCode : unsigned int

strong

Enumerated constants used in failsafe() calls.

The values of codes listed here are public API and shall not change.

Enumerator
SYSTEM_BASE	Base for system-assigned fail-safe codes.
NO_SUCH_PERIPHERAL	Application attempted to retrieve a non-existent peripheral instance.
MEMORY_POOL	Exceeded allocated space of a memory pool.
HEAP_OVERRUN	Allocated too much from system heap.
STACK_OVERFLOW	Detected stack pointer into heap memory.
PERSIST_VIOLATION	Default code for violation of a persisted memory region. A candidate recovery method is to perform a factory reset of persisted configuration data.
INTERNAL_ERROR	Unspecified internal error.
INCOMPLETE_SETUP	Application failed to perform all steps required to run.
RESOURCE_VIOLATION	Application attempted to allocate more resources than available. An example would be creating multiple instances of a class for which a single instance is allowed, or logging a failure in PPI allocation.
API_VIOLATION	Application tried something that isn't allowed.
BOARD_INIT_FAILURE	Board setup failed in some critical way. This is used for board-specific setup that identifies and configures crucial resources without which the system is not operationally viable. An example might be allocation of the TWI controller used to configure and manipulate an IO extender. If this failure occurs the only part of the system that can be assumed to be functional is the Nordic MCU itself.
EVENT_LOOP_TERMINATED	Application left the main loop. Use this when something totally unexpected happens and the temporary fix is to break out of the event loop and exit main().
APPLICATION_BASE	Base for application-assigned fail-safe codes. Type-correct application code values can be obtained by adding to this value, as with: FailSafeCode mycode{FailSafeCode::APPLICATION_BASE + 2}

Function Documentation

application_crc32()

uint32_t nrfcxx::application_crc32

(

bool

exclude_data = false

)

Calculate a checksum of the application content.

This covers all application code and, optionally, read-only data. It can be used to identify what image is running on the board, assuming a record of that checksum is retained. It should be equivalent to:

arm-none-eabi-objcopy -Obinary app.elf app.bin
crc32 app.bin

See scripts/appcrc in the nrfcxx source code.

Note

If the application includes the value of the pre-defined __TIME__ or __DATE__ macros the checksum will change across builds.

Parameters

exclude_data

allows exclusion of the material that initializes RAM data. If this is true you need to add -R .data to the objcopy line to get the correct comparison checksum.

delay_us()

void nrfcxx::delay_us ( unsigned int  number_of_us )

inline

Delay for exactly the specified duration.

The implementation is series-specific.

failsafe()

void nrfcxx::failsafe ( FailSafeCode  code )

inline

Record a critical system failure and reset the system.

This API should be used in lieu of systemState::reset() in situations where normal operation followed a path that led to an unrecoverable fatal error, such as running out of memory during system initialization. The failure is marked by RESET_REAS_FAILSAFE being set in state().reset_reas.

Applications should react to this failure by either automatically resetting to a default configuration or by providing a minimal capability allowing the fact of the failure to be detected and configuration to mitigate it.

Warning

This function may be invoked by the infrastructure regardless of whether a systemState instance has been installed, preventing the fact of the failure from being discovered. In that situation the device will likely continually reset and may not provide a mechanism to recover. Any operational firmware should install a system state instance and be prepared to process a failsafe reset.

sleep_ms()

void nrfcxx::sleep_ms

(

unsigned int

dur_ms

)

Sleep for the specified duration.

Note

This delegates to clock::uptime::sleep(). If the uptime clock is not running this function may not return. Durations at or above PT18H12M16S may misbehave.

If interrupts occur during the sleep this function will return to sleep until the requested duration passes. If early exit is desired use clock::uptime::sleep().

Parameters

dur_ms

the time to sleep, in milliseconds.

stack_fill_unused()

unsigned int nrfcxx::stack_fill_unused

(

unsigned int

marker

)

Fill all space between the top of the heap and the current stack pointer with the provided value.

Returns

the number of bytes between the top of the heap and the start of the stack.

stack_infer_highwater()

unsigned int nrfcxx::stack_infer_highwater

(

unsigned int

marker

)

Check the space between the top of the heap and the current stack pointer for matches to the provided marker.

Returns

the number of bytes between the top of heap and the first word that did not match the marker.

stack_space_remaining()

int nrfcxx::stack_space_remaining ( )

inline

Determine how much of the reserved stack space remains.

Return the signed difference between the current stack pointer against the bottom of the reserved stack space. Negative values indicate the stack has gone below the expected lower limit.

Note

Going below the lower limit of the configured space is not necessarily fatal, though with the default _sbrk implementation it is possible that doing so will overrun heap-allocated memory.

The reserved system stack space is 1 KiBy or 256 words. The application and soft-device modules can increase this by declaring objects that will force that space to be expanded, as with:

__attribute__((__section__(".stack.extension")))
volatile uint32_t extend_by_512_words[512];

validate_stack_pointer()

void nrfcxx::validate_stack_pointer ( )

inline

Force a system failure if the stack is beyond its configured maximum depth.

See also

stack_space_remaining