v2.0.0
Functions
lockout
High Level APIs » pico_multicore

Functions to enable one core to force the other core to pause execution in a known state. More...

## Functions
void | multicore_lockout_victim_init (void)
| Initialize the current core such that it can be a "victim" of lockout (i.e. forced to pause in a known state by the other core) More...
bool | multicore_lockout_victim_is_initialized (uint core_num)
| Determine if multicore_victim_init() has been called on the specified core. More...
void | multicore_lockout_start_blocking (void)
| Request the other core to pause in a known state and wait for it to do so. More...
bool | multicore_lockout_start_timeout_us (uint64_t timeout_us)
| Request the other core to pause in a known state and wait up to a time limit for it to do so. More...
void | multicore_lockout_end_blocking (void)
| Release the other core from a locked out state amd wait for it to acknowledge. More...
bool | multicore_lockout_end_timeout_us (uint64_t timeout_us)
| Release the other core from a locked out state amd wait up to a time limit for it to acknowledge. More...

## Detailed Description

Functions to enable one core to force the other core to pause execution in a known state.

Sometimes it is useful to enter a critical section on both cores at once. On a single core system a critical section can trivially be entered by disabling interrupts, however on a multi-core system that is not sufficient, and unless the other core is polling in some way, then it will need to be interrupted in order to cooperatively enter a blocked state.

These "lockout" functions use the inter core FIFOs to cause an interrupt on one core from the other, and manage waiting for the other core to enter the "locked out" state.

The usage is that the "victim" core ... i.e the core that can be "locked out" by the other core calls multicore_lockout_victim_init to hook the FIFO interrupt. Note that either or both cores may do this.

Note
  When "locked out" the victim core is paused (it is actually executing a tight loop with code in RAM) and has interrupts disabled. This makes the lockout functions suitable for use by code that wants to write to flash (at which point no code may be executing from flash)

The core which wishes to lockout the other core calls multicore_lockout_start_blocking or multicore_lockout_start_timeout_us to interrupt the other "victim" core and wait for it to be in a "locked out" state. Once the lockout is no longer needed it calls multicore_lockout_end_blocking or multicore_lockout_end_timeout_us to release the lockout and wait for confirmation.

Note
  Because multicore lockout uses the intercore FIFOs, the FIFOs cannot be used for any other purpose

## Function Documentation

## ◆ multicore_lockout_end_blocking()

void multicore_lockout_end_blocking | ( | void |  | ) |

Release the other core from a locked out state amd wait for it to acknowledge.

Note
  The other core must previously have been "locked out" by calling a `multicore_lockout_start_` function from this core

## ◆ multicore_lockout_end_timeout_us()

bool multicore_lockout_end_timeout_us | ( | uint64_t | timeout_us | ) |

Release the other core from a locked out state amd wait up to a time limit for it to acknowledge.

The other core must previously have been "locked out" by calling a `multicore_lockout_start_` function from this core

Note
  be very careful using small timeout values, as a timeout here will leave the "lockout" functionality in a bad state. It is probably preferable to use multicore_lockout_end_blocking anyway as if you have already waited for the victim core to enter the lockout state, then the victim core will be ready to exit the lockout state very quickly.

Parameters

  timeout_us | the timeout in microseconds

Returns
  true if the other core successfully exited locked out state within the timeout, false otherwise

## ◆ multicore_lockout_start_blocking()

void multicore_lockout_start_blocking | ( | void |  | ) |

Request the other core to pause in a known state and wait for it to do so.

The other (victim) core must have previously executed multicore_lockout_victim_init()

Note
  multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding multicore_lockout_end_blocking

## ◆ multicore_lockout_start_timeout_us()

bool multicore_lockout_start_timeout_us | ( | uint64_t | timeout_us | ) |

Request the other core to pause in a known state and wait up to a time limit for it to do so.

The other core must have previously executed multicore_lockout_victim_init()

Note
  multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding multicore_lockout_end_blocking

Parameters

  timeout_us | the timeout in microseconds

Returns
  true if the other core entered the locked out state within the timeout, false otherwise

## ◆ multicore_lockout_victim_init()

void multicore_lockout_victim_init | ( | void |  | ) |

Initialize the current core such that it can be a "victim" of lockout (i.e. forced to pause in a known state by the other core)

This code hooks the intercore FIFO IRQ, and the FIFO may not be used for any other purpose after this.

## ◆ multicore_lockout_victim_is_initialized()

bool multicore_lockout_victim_is_initialized | ( | uint | core_num | ) |

Determine if multicore_victim_init() has been called on the specified core.

Note
  this state persists even if the core is subsequently reset; therefore you are advised to always call multicore_lockout_victim_init() again after resetting a core, which had previously been initialized.

Parameters

  core_num | the core number (0 or 1)

Returns
  true if multicore_victim_init() has been called on the specified core, false otherwise.