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

Code before:
 *
 * \note The other core must previously have been "locked out" by calling a `multicore_lockout_start_` function
 * from this core
 */
void multicore_lockout_end_blocking(void);

/*! \brief Release the other core from a locked out state amd wait up to a time limit for it to acknowledge
 *  \ingroup multicore_lockout
 *
 * 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 timout here will leave these "lockout" functionality
 * in a bad state. It is probably preferable to use \ref 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.
 *
 * \param timeout_us the timeout in microseconds
 * \return true if the other core successfully exited locked out state within the timeout, false otherwise
 */
bool multicore_lockout_end_timeout_us(uint64_t timeout_us);

#ifdef __cplusplus
}
#endif
#endif


Review comment (suggestion):
Given that you can only call `multicore_lockout_end_` after `multicore_lockout_start_`, what's the use-case for ever needing/wanting to use `multicore_lockout_end_timeout_us` ?  "if you have already waited for the victim core to enter the lockout state" - there doesn't seem to be any way to **not** wait for the victim core to enter the lockout state? :thinking: 
EDIT: Oh, or will the victim core "eventually" enter the lockout state, if you called `multicore_lockout_start_timeout_us` with a small timeout value and it returned false? (If so, perhaps that's worth clarifying in the `multicore_lockout_start_timeout_us` doxygen comments?)

Code after:
 * \note multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding
 * \ref multicore_lockout_end_blocking
 *
 * \param timeout_us the timeout in microseconds
 * \return true if the other core entered the locked out state within the timeout, false otherwise
 */
bool multicore_lockout_start_timeout_us(uint64_t timeout_us);

/*! \brief Release the other core from a locked out state amd wait for it to acknowledge
 *  \ingroup multicore_lockout
 *
 * \note The other core must previously have been "locked out" by calling a `multicore_lockout_start_` function
 * from this core
 */
void multicore_lockout_end_blocking(void);

/*! \brief Release the other core from a locked out state amd wait up to a time limit for it to acknowledge
 *  \ingroup multicore_lockout
 *
 * 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 \ref 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.
 *
 * \param timeout_us the timeout in microseconds
 * \return true if the other core successfully exited locked out state within the timeout, false otherwise
 */
bool multicore_lockout_end_timeout_us(uint64_t timeout_us);

#ifdef __cplusplus
}
#endif
#endif