hardware_claim

Functions
void	hw_claim_or_assert (uint8_t *bits, uint bit_index, const char *message)
	Atomically claim a resource, panicking if it is already in use. More...
int	hw_claim_unused_from_range (uint8_t *bits, bool required, uint bit_lsb, uint bit_msb, const char *message)
	Atomically claim one resource out of a range of resources, optionally asserting if none are free. More...
bool	hw_is_claimed (const uint8_t *bits, uint bit_index)
	Determine if a resource is claimed at the time of the call. More...
void	hw_claim_clear (uint8_t *bits, uint bit_index)
	Atomically unclaim a resource. More...
uint32_t	hw_claim_lock (void)
	Acquire the runtime mutual exclusion lock provided by the hardware_claim library. More...
void	hw_claim_unlock (uint32_t token)
	Release the runtime mutual exclusion lock provided by the hardware_claim library. More...

Detailed Description

Lightweight hardware resource management

hardware_claim provides a simple API for management of hardware resources at runtime.

This API is usually called by other hardware specific claiming APIs and provides simple multi-core safe methods to manipulate compact bit-sets representing hardware resources.

This API allows any other library to cooperatively participate in a scheme by which both compile time and runtime allocation of resources can co-exist, and conflicts can be avoided or detected (depending on the use case) without the libraries having any other knowledge of each other.

Facilities are providing for:

1. Claiming resources (and asserting if they are already claimed)
2. Freeing (unclaiming) resources
3. Finding unused resources

Function Documentation

hw_claim_clear()

void hw_claim_clear	(	uint8_t *	bits,
		uint	bit_index
	)

Atomically unclaim a resource.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits	pointer to an array of bits (8 bits per byte)
bit_index	resource to unclaim (bit index into array of bits)

hw_claim_lock()

uint32_t hw_claim_lock

(

void

)

Acquire the runtime mutual exclusion lock provided by the hardware_claim library.

This method is called automatically by the other hw_claim_ methods, however it is provided as a convenience to code that might want to protect other hardware initialization code from concurrent use.

Note

hw_claim_lock() uses a spin lock internally, so disables interrupts on the calling core, and will deadlock if the calling core already owns the lock.

Returns

a token to pass to hw_claim_unlock()

hw_claim_or_assert()

void hw_claim_or_assert	(	uint8_t *	bits,
		uint	bit_index,
		const char *	message
	)

Atomically claim a resource, panicking if it is already in use.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits	pointer to an array of bits (8 bits per byte)
bit_index	resource to claim (bit index into array of bits)
message	string to display if the bit cannot be claimed; note this may have a single printf format "%d" for the bit

hw_claim_unlock()

void hw_claim_unlock

(

uint32_t

token

)

Release the runtime mutual exclusion lock provided by the hardware_claim library.

Note

This method MUST be called from the same core that call hw_claim_lock()

Parameters

token

the token returned by the corresponding call to hw_claim_lock()

hw_claim_unused_from_range()

int hw_claim_unused_from_range	(	uint8_t *	bits,
		bool	required,
		uint	bit_lsb,
		uint	bit_msb,
		const char *	message
	)

Atomically claim one resource out of a range of resources, optionally asserting if none are free.

Parameters

bits	pointer to an array of bits (8 bits per byte)
required	true if this method should panic if the resource is not free
bit_lsb	the lower bound (inclusive) of the resource range to claim from
bit_msb	the upper bound (inclusive) of the resource range to claim from
message	string to display if the bit cannot be claimed

Returns

the bit index representing the claimed or -1 if none are available in the range, and required = false

hw_is_claimed()

bool hw_is_claimed ( const uint8_t *  bits, uint  bit_index  )

inline

Determine if a resource is claimed at the time of the call.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits	pointer to an array of bits (8 bits per byte)
bit_index	resource to check (bit index into array of bits)

Returns

true if the resource is claimed