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

Code before:
 *
 * 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.
 */
void multicore_lockout_victim_init(void);

/*! \brief Request the other core to paused in a known state and wait for it to do so
 *  \ingroup multicore_lockout
 *
 * The other (victim) core must have previously executed \ref multicore_lockout_victim_init()
 */
void multicore_lockout_start_blocking(void);

/*! \brief Request the other core to paused in a known state and wait up to a time limit for it to do so

Review comment (suggestion):
After reading this a couple of times, perhaps "This makes the lockout functions suitable for code that wants to write to flash..." makes more sense than "This allows the lockout functions to be used by code that wants to write to flash..." ? :man_shrugging: (I was confused by the "allows")

Code after:
 * 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
 */

/*! \brief 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)
 *  \ingroup multicore_lockout
 *
 * This code hooks the intercore FIFO IRQ, and the FIFO may not be used for any other purpose after this.
 */
void multicore_lockout_victim_init(void);

/*! \brief Request the other core to pause in a known state and wait for it to do so
 *  \ingroup multicore_lockout
 *
 * The other (victim) core must have previously executed \ref multicore_lockout_victim_init()