v2.0.0
Functions
hardware_claim
Hardware APIs

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. 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 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