| /* |
| * Copyright (c) 2020 Raspberry Pi (Trading) Ltd. |
| * |
| * SPDX-License-Identifier: BSD-3-Clause |
| */ |
| |
| #ifndef _PICO_MULTICORE_H |
| #define _PICO_MULTICORE_H |
| |
| #include "pico/types.h" |
| #include "pico/sync.h" |
| #include "hardware/structs/sio.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** \file multicore.h |
| * \defgroup pico_multicore pico_multicore |
| * Adds support for running code on the second processor core (core 1) |
| * |
| * \subsection multicore_example Example |
| * \addtogroup pico_multicore |
| * \include multicore.c |
| */ |
| |
| // PICO_CONFIG: PICO_CORE1_STACK_SIZE, Stack size for core 1, min=0x100, max=0x10000, default=PICO_STACK_SIZE (0x800), group=pico_multicore |
| #ifndef PICO_CORE1_STACK_SIZE |
| #ifdef PICO_STACK_SIZE |
| #define PICO_CORE1_STACK_SIZE PICO_STACK_SIZE |
| #else |
| #define PICO_CORE1_STACK_SIZE 0x800 |
| #endif |
| #endif |
| |
| /*! \brief Reset core 1 |
| * \ingroup pico_multicore |
| * |
| * This function can be used to reset core 1 into its initial state (ready for launching code against via \ref multicore_launch_core1 and similar methods) |
| * |
| * \note this function should only be called from core 0 |
| */ |
| void multicore_reset_core1(void); |
| |
| /*! \brief Run code on core 1 |
| * \ingroup pico_multicore |
| * |
| * Wake up (a previously reset) core 1 and enter the given function on core 1 using the default core 1 stack (below core 0 stack). |
| * |
| * core 1 must previously have been reset either as a result of a system reset or by calling \ref multicore_reset_core1 |
| * |
| * core 1 will use the same vector table as core 0 |
| * |
| * \param entry Function entry point |
| * \see multicore_reset_core1 |
| */ |
| void multicore_launch_core1(void (*entry)(void)); |
| |
| /*! \brief Launch code on core 1 with stack |
| * \ingroup pico_multicore |
| * |
| * Wake up (a previously reset) core 1 and enter the given function on core 1 using the passed stack for core 1 |
| * |
| * core 1 must previously have been reset either as a result of a system reset or by calling \ref multicore_reset_core1 |
| * |
| * core 1 will use the same vector table as core 0 |
| * |
| * \param entry Function entry point |
| * \param stack_bottom The bottom (lowest address) of the stack |
| * \param stack_size_bytes The size of the stack in bytes (must be a multiple of 4) |
| * \see multicore_reset_core1 |
| */ |
| void multicore_launch_core1_with_stack(void (*entry)(void), uint32_t *stack_bottom, size_t stack_size_bytes); |
| |
| /*! \brief Launch code on core 1 with no stack protection |
| * \ingroup pico_multicore |
| * |
| * Wake up (a previously reset) core 1 and start it executing with a specific entry point, stack pointer |
| * and vector table. |
| * |
| * This is a low level function that does not provide a stack guard even if USE_STACK_GUARDS is defined |
| * |
| * core 1 must previously have been reset either as a result of a system reset or by calling \ref multicore_reset_core1 |
| * |
| * \param entry Function entry point |
| * \param sp Pointer to the top of the core 1 stack |
| * \param vector_table address of the vector table to use for core 1 |
| * \see multicore_reset_core1 |
| */ |
| void multicore_launch_core1_raw(void (*entry)(void), uint32_t *sp, uint32_t vector_table); |
| |
| /*! |
| * \defgroup multicore_fifo fifo |
| * \ingroup pico_multicore |
| * \brief Functions for the inter-core FIFOs |
| * |
| * The RP2040 contains two FIFOs for passing data, messages or ordered events between the two cores. Each FIFO is 32 bits |
| * wide, and 8 entries deep. One of the FIFOs can only be written by core 0, and read by core 1. The other can only be written |
| * by core 1, and read by core 0. |
| * |
| * \note The inter-core FIFOs are a very precious resource and are frequently used for SDK functionality (e.g. during |
| * core 1 launch or by the \ref multicore_lockout functions). Additionally they are often required for the exclusive use |
| * of an RTOS (e.g. FreeRTOS SMP). For these reasons it is suggested that you do not use the FIFO for your own purposes |
| * unless none of the above concerns apply; the majority of cases for transferring data between cores can be eqaully |
| * well handled by using a \ref queue |
| */ |
| |
| /*! \brief Check the read FIFO to see if there is data available (sent by the other core) |
| * \ingroup multicore_fifo |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * \return true if the FIFO has data in it, false otherwise |
| */ |
| static inline bool multicore_fifo_rvalid(void) { |
| return !!(sio_hw->fifo_st & SIO_FIFO_ST_VLD_BITS); |
| } |
| |
| /*! \brief Check the write FIFO to see if it has space for more data |
| * \ingroup multicore_fifo |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * @return true if the FIFO has room for more data, false otherwise |
| */ |
| static inline bool multicore_fifo_wready(void) { |
| return !!(sio_hw->fifo_st & SIO_FIFO_ST_RDY_BITS); |
| } |
| |
| /*! \brief Push data on to the write FIFO (data to the other core). |
| * \ingroup multicore_fifo |
| * |
| * This function will block until there is space for the data to be sent. |
| * Use multicore_fifo_wready() to check if it is possible to write to the |
| * FIFO if you don't want to block. |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * \param data A 32 bit value to push on to the FIFO |
| */ |
| void multicore_fifo_push_blocking(uint32_t data); |
| |
| /*! \brief Push data on to the write FIFO (data to the other core) with timeout. |
| * \ingroup multicore_fifo |
| * |
| * This function will block until there is space for the data to be sent |
| * or the timeout is reached |
| * |
| * \param data A 32 bit value to push on to the FIFO |
| * \param timeout_us the timeout in microseconds |
| * \return true if the data was pushed, false if the timeout occurred before data could be pushed |
| */ |
| bool multicore_fifo_push_timeout_us(uint32_t data, uint64_t timeout_us); |
| |
| /*! \brief Pop data from the read FIFO (data from the other core). |
| * \ingroup multicore_fifo |
| * |
| * This function will block until there is data ready to be read |
| * Use multicore_fifo_rvalid() to check if data is ready to be read if you don't |
| * want to block. |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * \return 32 bit data from the read FIFO. |
| */ |
| uint32_t multicore_fifo_pop_blocking(void); |
| |
| /*! \brief Pop data from the read FIFO (data from the other core) with timeout. |
| * \ingroup multicore_fifo |
| * |
| * This function will block until there is data ready to be read or the timeout is reached |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * \param timeout_us the timeout in microseconds |
| * \param out the location to store the popped data if available |
| * \return true if the data was popped and a value copied into `out`, false if the timeout occurred before data could be popped |
| */ |
| bool multicore_fifo_pop_timeout_us(uint64_t timeout_us, uint32_t *out); |
| |
| /*! \brief Discard any data in the read FIFO |
| * \ingroup multicore_fifo |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| */ |
| static inline void multicore_fifo_drain(void) { |
| while (multicore_fifo_rvalid()) |
| (void) sio_hw->fifo_rd; |
| } |
| |
| /*! \brief Clear FIFO interrupt |
| * \ingroup multicore_fifo |
| * |
| * Note that this only clears an interrupt that was caused by the ROE or WOF flags. |
| * To clear the VLD flag you need to use one of the 'pop' or 'drain' functions. |
| * |
| * See the note in the \ref multicore_fifo section for considerations regarding use of the inter-core FIFOs |
| * |
| * \see multicore_fifo_get_status |
| */ |
| static inline void multicore_fifo_clear_irq(void) { |
| // 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 |
| */ |
| |
| /*! \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() |
| * |
| * \note multicore_lockout_start_ functions are not nestable, and must be paired with a call to a corresponding |
| * \ref multicore_lockout_end_blocking |
| */ |
| void multicore_lockout_start_blocking(void); |
| |
| /*! \brief Request the other core to pause in a known state and wait up to a time limit for it to do so |
| * \ingroup multicore_lockout |
| * |
| * The other core must have previously executed \ref multicore_lockout_victim_init() |
| * |
| * \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 |