Baremetal helper functions for waiting

Helper 'wait' framework for blocking functions. More...

Collaboration diagram for Baremetal helper functions for waiting:

Functions
void	WAIT_ms (uint32_t ticks)
	Wait for a given number of milliseconds. More...
ca_error	WAIT_Callback (uint8_t aCommandId, uint32_t aTimeoutMs, void *aCallbackContext, struct ca821x_dev *pDeviceRef)
	Wait for an asynchronous callback to be triggered. More...
ca_error	WAIT_CallbackSwap (uint8_t aCommandId, ca821x_generic_callback aCallback, uint32_t aTimeoutMs, void *aCallbackContext, struct ca821x_dev *pDeviceRef)
	Wait for an asynchronous callback to be triggered, with a given callback swapped in. More...
void *	WAIT_GetContext (void)
	Get the callback context from within a callback being waited for. More...

Detailed Description

Helper 'wait' framework for blocking functions.

Function Documentation

WAIT_Callback()

ca_error WAIT_Callback	(	uint8_t	aCommandId,
		uint32_t	aTimeoutMs,
		void *	aCallbackContext,
		struct ca821x_dev *	pDeviceRef
	)

Wait for an asynchronous callback to be triggered.

This is a helper function which blocks until a specific SPI indication/confirm message has been received from the CA821x. Think carefully before using this function, as overuse can lead to programs which are inflexible in their flow. It has been designed specifically for use with asynchronous messages, and can correctly handle other commands received out of order. This function preserves message order, so every callback will be triggered in order, regardless of whether it is the one being waited on or not.

This function is strictly not re-entrant. It will fail if you try to call it while it is already waiting. Do not use from an IRQ context.

Parameters

aCommandId	- Asynchronous, incoming command ID that is to be waited upon
aTimeoutMs	- Timeout in milliseconds to wait for message before giving up
aCallbackContext	- Generic pointer that can be retreived in the callback using WAIT_GetContext()
pDeviceRef	- Pointer to initialised ca821x_dev struct

Returns

Status

Return values

CA_ERROR_SUCCESS	Success
CA_ERROR_INVALID_STATE	System in invalid state - did you try and use from a callback?
CA_ERROR_SPI_WAIT_TIMEOUT	Timed out waiting for message

WAIT_CallbackSwap()

ca_error WAIT_CallbackSwap	(	uint8_t	aCommandId,
		ca821x_generic_callback	aCallback,
		uint32_t	aTimeoutMs,
		void *	aCallbackContext,
		struct ca821x_dev *	pDeviceRef
	)

Wait for an asynchronous callback to be triggered, with a given callback swapped in.

This is a helper function which blocks until a specific SPI indication/confirm message has been received from the CA821x. Think carefully before using this function, as overuse can lead to programs which are inflexible in their flow. It has been designed specifically for use with asynchronous messages, and can correctly handle other commands received out of order. This function preserves message order, so every callback will be triggered in order, regardless of whether it is the one being waited on or not.

The callback should return a value following the normal callback rules defined in ca821x_api.c (return 1 to consume the callback, return 0 to not consume, return a negative number for error).

This function is strictly not re-entrant. It will fail if you try to call it while it is already waiting. Do not use from an IRQ context.

Parameters

aCommandId	- The commandId of the Asynchronous upstream command to be captured
aCallback	- A function pointer to the callback to be swapped in during the wait
aTimeoutMs	- Timeout in milliseconds to wait for message before giving up
aCallbackContext	- Provide a pointer to a context, which can be retrieved in the callback using WAIT_GetContext.
pDeviceRef	- Pointer to initialised ca821x_dev struct

Returns

Status

Return values

CA_ERROR_SUCCESS	Success
CA_ERROR_INVALID_STATE	System in invalid state - did you try and use from a callback?
CA_ERROR_SPI_WAIT_TIMEOUT	Timed out waiting for message

WAIT_GetContext()

void* WAIT_GetContext

(

void

)

Get the callback context from within a callback being waited for.

This is a helper function for WAIT_Callback, which allows the callback function being waited for to retrieve a single pointer. It is only valid for use inside the relevent callback function, and will otherwise return NULL.

Returns

Pointer to context or NULL

WAIT_ms()

void WAIT_ms

(

uint32_t

ticks

)

Wait for a given number of milliseconds.

Parameters

ticks

The number of milliseconds to wait.