@web-font-path: "roboto-debian.css";
v2.2.0 (RP2040)
Loading...
Searching...
No Matches
hardware_claim

Lightweight hardware resource management API. More...

## 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.
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.
bool | hw_is_claimed (const uint8_t *bits, uint bit_index)
| Determine if a resource is claimed at the time of the call.
void | hw_claim_clear (uint8_t *bits, uint bit_index)
| Atomically unclaim a resource.
uint32_t | hw_claim_lock (void)
| Acquire the runtime mutual exclusion lock provided by the hardware_claim library.
void | hw_claim_unlock (uint32_t token)
| Release the runtime mutual exclusion lock provided by the hardware_claim library.

## Detailed Description

Lightweight hardware resource management API.

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