Repository: raspberrypi/pico-sdk
File: src/rp2_common/pico_multicore/include/pico/multicore.h (C/C++)

Code before:
/*! \brief Get FIFO statuses
 *  \ingroup multicore_fifo
 *
 * \return The statuses as a bitfield
 *
 * Bit | Description
 * ----|------------
 * 3 | Sticky flag indicating the RX FIFO was read when empty. This read was ignored by the FIFO.
 * 2 | Sticky flag indicating the TX FIFO was written when full. This write was ignored by the FIFO.
 * 1 | Value is 1 if this core’s TX FIFO is not full (i.e. if FIFO_WR is ready for more data)
 * 0 | Value is 1 if this core’s RX FIFO is not empty (i.e. if FIFO_RD is valid)
 *
 * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs
 *
*/
static inline uint32_t multicore_fifo_get_status(void) {
    return sio_hw->fifo_st;
}

/*!
 * \defgroup multicore_lockout lockout
 * \ingroup pico_multicore
 * \brief 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, this can easily be done by simply disabling interrupts, however on a multi-core
 * system that is not sufficient, and unless the other core is polling, then it will need to be interrupted
 * in order to cooperatively enter a blocked state.
 *
 * These "lockout" functions use the inter process 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 cna be "locked out" by the other core calls
 * /ref 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 executing code from RAM and has interrupts disabled. This allows
 * the lockout functions to be used by code that wants to write to flash (at which point no code must be executing
 * from flash)
 *
 * The core which wishes to lockout the other core calls \ref multicore_lockout_start_blocking or
 * \ref 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 \ref multicore_lockout_end_blocking or
 * \ref multicore_lockout_end_timeout_us to release the lockout and wait for confirmation.
 *
 * \note Because multicore lockout uses the intercore FIFOs, the FIFOs <b>cannot</b> be used for any other purpose
 */

/*! \brief Initialize the current core such that it can be a "victim" of lockout (i.e. force to pause in a known state by the other core)
 *  \ingroup multicore_lockout
 *
 * This code hooks the multicore FIFO IRQ, and the FIFO may not be used for any other purpose after this.

Review comment (suggestion):
This "Sometimes it is useful to enter a critical section on both cores at once. On a single core system, this can easily be done..." seems like a bit of a logical tautology? :wink:  I think I get the intention though.

Code after:
    // Write any value to clear the error flags
    sio_hw->fifo_st = 0xff;
}

/*! \brief Get FIFO statuses
 *  \ingroup multicore_fifo
 *
 * \return The statuses as a bitfield
 *
 * Bit | Description
 * ----|------------
 * 3 | Sticky flag indicating the RX FIFO was read when empty (ROE). This read was ignored by the FIFO.
 * 2 | Sticky flag indicating the TX FIFO was written when full (WOF). This write was ignored by the FIFO.
 * 1 | Value is 1 if this core’s TX FIFO is not full (i.e. if FIFO_WR is ready for more data)
 * 0 | Value is 1 if this core’s RX FIFO is not empty (i.e. if FIFO_RD is valid)
 *
 * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs
 *
*/
static inline uint32_t multicore_fifo_get_status(void) {
    return sio_hw->fifo_st;
}

/*!
 * \defgroup multicore_lockout lockout
 * \ingroup pico_multicore
 * \brief 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
 * \ref 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 \ref multicore_lockout_start_blocking or
 * \ref 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 \ref multicore_lockout_end_blocking or
 * \ref multicore_lockout_end_timeout_us to release the lockout and wait for confirmation.
 *
 * \note Because multicore lockout uses the intercore FIFOs, the FIFOs <b>cannot</b> be used for any other purpose
 */