v2.0.0
multicore.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7#ifndef _PICO_MULTICORE_H
8#define _PICO_MULTICORE_H
9
10#include "pico/types.h"
11#include "pico/sync.h"
12#include "hardware/structs/sio.h"
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_PICO_MULTICORE, Enable/disable assertions in the pico_multicore module, type=bool, default=0, group=pico_multicore
19#ifndef PARAM_ASSERTIONS_ENABLED_PICO_MULTICORE
20#define PARAM_ASSERTIONS_ENABLED_PICO_MULTICORE 0
21#endif
22
32// PICO_CONFIG: PICO_CORE1_STACK_SIZE, Minimum amount of stack space reserved in the linker script for core 1, min=0x100, max=0x10000, default=PICO_STACK_SIZE (0x800), group=pico_multicore
33#ifndef PICO_CORE1_STACK_SIZE
34#ifdef PICO_STACK_SIZE
35#define PICO_CORE1_STACK_SIZE PICO_STACK_SIZE
36#else
37#define PICO_CORE1_STACK_SIZE 0x800
38#endif
39#endif
40
57#ifndef SIO_FIFO_IRQ_NUM
58#if !PICO_RP2040
59#define SIO_FIFO_IRQ_NUM(core) SIO_IRQ_FIFO
60#else
61static_assert(SIO_IRQ_PROC1 == SIO_IRQ_PROC0 + 1, "");
62#define SIO_FIFO_IRQ_NUM(core) (SIO_IRQ_PROC0 + (core))
63#endif
64#endif
65
73void multicore_reset_core1(void);
74
87void multicore_launch_core1(void (*entry)(void));
88
103void multicore_launch_core1_with_stack(void (*entry)(void), uint32_t *stack_bottom, size_t stack_size_bytes);
104
120void multicore_launch_core1_raw(void (*entry)(void), uint32_t *sp, uint32_t vector_table);
121
145 static inline bool multicore_fifo_rvalid(void) {
146 return sio_hw->fifo_st & SIO_FIFO_ST_VLD_BITS;
147}
148
156 static inline bool multicore_fifo_wready(void) {
157 return sio_hw->fifo_st & SIO_FIFO_ST_RDY_BITS;
158}
159
171void multicore_fifo_push_blocking(uint32_t data);
172
184 static inline void multicore_fifo_push_blocking_inline(uint32_t data) {
185 // We wait for the fifo to have some space
186 while (!multicore_fifo_wready())
187 tight_loop_contents();
188
189 sio_hw->fifo_wr = data;
190
191 // Fire off an event to the other core
192 __sev();
193}
194
205bool multicore_fifo_push_timeout_us(uint32_t data, uint64_t timeout_us);
206
218uint32_t multicore_fifo_pop_blocking(void);
219
231 static inline uint32_t multicore_fifo_pop_blocking_inline(void) {
232 // If nothing there yet, we wait for an event first,
233 // to try and avoid too much busy waiting
234 while (!multicore_fifo_rvalid())
235 __wfe();
236
237 return sio_hw->fifo_rd;
238}
239
251bool multicore_fifo_pop_timeout_us(uint64_t timeout_us, uint32_t *out);
252
258 static inline void multicore_fifo_drain(void) {
259 while (multicore_fifo_rvalid())
260 (void) sio_hw->fifo_rd;
261}
262
273 static inline void multicore_fifo_clear_irq(void) {
274 // Write any value to clear the error flags
275 sio_hw->fifo_st = 0xff;
276}
277
293 static inline uint32_t multicore_fifo_get_status(void) {
294 return sio_hw->fifo_st;
295}
296
307#if NUM_DOORBELLS
308static inline void check_doorbell_num_param(__unused uint doorbell_num) {
309 invalid_params_if(PICO_MULTICORE, doorbell_num >= NUM_DOORBELLS);
310}
311
321void multicore_doorbell_claim(uint doorbell_num, uint core_mask);
322
333int multicore_doorbell_claim_unused(uint core_mask, bool required);
334
342void multicore_doorbell_unclaim(uint doorbell_num, uint core_mask);
343
348 static inline void multicore_doorbell_set_other_core(uint doorbell_num) {
349 check_doorbell_num_param(doorbell_num);
350 sio_hw->doorbell_out_set = 1u << doorbell_num;
351}
352
357 static inline void multicore_doorbell_clear_other_core(uint doorbell_num) {
358 check_doorbell_num_param(doorbell_num);
359 sio_hw->doorbell_out_clr = 1u << doorbell_num;
360}
361
366 static inline void multicore_doorbell_set_current_core(uint doorbell_num) {
367 check_doorbell_num_param(doorbell_num);
368 sio_hw->doorbell_in_set = 1u << doorbell_num;
369}
370
375 static inline void multicore_doorbell_clear_current_core(uint doorbell_num) {
376 check_doorbell_num_param(doorbell_num);
377 sio_hw->doorbell_in_clr = 1u << doorbell_num;
378}
379
384 static inline bool multicore_doorbell_is_set_current_core(uint doorbell_num) {
385 check_doorbell_num_param(doorbell_num);
386 return sio_hw->doorbell_in_set & (1u << doorbell_num);
387}
388
393 static inline bool multicore_doorbell_is_set_other_core(uint doorbell_num) {
394 check_doorbell_num_param(doorbell_num);
395 return sio_hw->doorbell_out_set & (1u << doorbell_num);
396}
397
406#ifndef DOORBELL_IRQ_NUM
407#define DOORBELL_IRQ_NUM(doorbell_num) SIO_IRQ_BELL
408#endif
409
410static inline uint multicore_doorbell_irq_num(uint doorbell_num) {
411 check_doorbell_num_param(doorbell_num);
412 return DOORBELL_IRQ_NUM(doorbell_num);
413}
414
415#endif
416
450void multicore_lockout_victim_init(void);
451
462bool multicore_lockout_victim_is_initialized(uint core_num);
463
472void multicore_lockout_start_blocking(void);
473
485bool multicore_lockout_start_timeout_us(uint64_t timeout_us);
486
493void multicore_lockout_end_blocking(void);
494
509bool multicore_lockout_end_timeout_us(uint64_t timeout_us);
510
511#ifdef __cplusplus
512}
513#endif
514#endif
sync.h
SIO_IRQ_PROC0
@ SIO_IRQ_PROC0
Select SIO_PROC0's IRQ output.
Definition: intctrl_rp2040.h:63
SIO_IRQ_PROC1
@ SIO_IRQ_PROC1
Select SIO_PROC1's IRQ output.
Definition: intctrl_rp2040.h:64
__sev
static __force_inline void __sev(void)
Insert a SEV instruction in to the code path.
Definition: sync.h:90
__wfe
static __force_inline void __wfe(void)
Insert a WFE instruction in to the code path.
Definition: sync.h:106
multicore_doorbell_is_set_other_core
static bool multicore_doorbell_is_set_other_core(uint doorbell_num)
Determine if the given doorbell is active on the this core.
Definition: multicore.h:393
multicore_doorbell_clear_current_core
static void multicore_doorbell_clear_current_core(uint doorbell_num)
Deactivate the given doorbell on this core.
Definition: multicore.h:375
multicore_doorbell_claim
void multicore_doorbell_claim(uint doorbell_num, uint core_mask)
Cooperatively claim the use of this hardware alarm_num.
Definition: multicore.c:349
multicore_doorbell_clear_other_core
static void multicore_doorbell_clear_other_core(uint doorbell_num)
Deactivate the given doorbell on the other core.
Definition: multicore.h:357
DOORBELL_IRQ_NUM
#define DOORBELL_IRQ_NUM(doorbell_num)
Returns the irq_num_t for processor interrupts for the given doorbell number.
Definition: multicore.h:407
multicore_doorbell_claim_unused
int multicore_doorbell_claim_unused(uint core_mask, bool required)
Cooperatively claim the use of this hardware alarm_num.
Definition: multicore.c:356
multicore_doorbell_set_other_core
static void multicore_doorbell_set_other_core(uint doorbell_num)
Activate the given doorbell on the other core.
Definition: multicore.h:348
multicore_doorbell_set_current_core
static void multicore_doorbell_set_current_core(uint doorbell_num)
Activate the given doorbell on this core.
Definition: multicore.h:366
multicore_doorbell_unclaim
void multicore_doorbell_unclaim(uint doorbell_num, uint core_mask)
Cooperatively release the claim on use of this hardware alarm_num.
Definition: multicore.c:372
multicore_doorbell_is_set_current_core
static bool multicore_doorbell_is_set_current_core(uint doorbell_num)
Determine if the given doorbell is active on the other core.
Definition: multicore.h:384
multicore_fifo_push_timeout_us
bool multicore_fifo_push_timeout_us(uint32_t data, uint64_t timeout_us)
Push data on to the write FIFO (data to the other core) with timeout.
Definition: multicore.c:38
multicore_fifo_push_blocking
void multicore_fifo_push_blocking(uint32_t data)
Push data on to the write FIFO (data to the other core).
Definition: multicore.c:34
multicore_fifo_pop_timeout_us
bool multicore_fifo_pop_timeout_us(uint64_t timeout_us, uint32_t *out)
Pop data from the read FIFO (data from the other core) with timeout.
Definition: multicore.c:57
multicore_fifo_pop_blocking_inline
static uint32_t multicore_fifo_pop_blocking_inline(void)
Pop data from the read FIFO (data from the other core).
Definition: multicore.h:231
multicore_fifo_drain
static void multicore_fifo_drain(void)
Discard any data in the read FIFO.
Definition: multicore.h:258
multicore_fifo_push_blocking_inline
static void multicore_fifo_push_blocking_inline(uint32_t data)
Push data on to the write FIFO (data to the other core).
Definition: multicore.h:184
multicore_fifo_wready
static bool multicore_fifo_wready(void)
Check the write FIFO to see if it has space for more data.
Definition: multicore.h:156
multicore_fifo_get_status
static uint32_t multicore_fifo_get_status(void)
Get FIFO statuses.
Definition: multicore.h:293
multicore_fifo_pop_blocking
uint32_t multicore_fifo_pop_blocking(void)
Pop data from the read FIFO (data from the other core).
Definition: multicore.c:53
multicore_fifo_clear_irq
static void multicore_fifo_clear_irq(void)
Clear FIFO interrupt.
Definition: multicore.h:273
multicore_fifo_rvalid
static bool multicore_fifo_rvalid(void)
Check the read FIFO to see if there is data available (sent by the other core)
Definition: multicore.h:145
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.
Definition: multicore.c:309
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 know...
Definition: multicore.c:229
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.
Definition: multicore.c:283
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.
Definition: multicore.c:279
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.
Definition: multicore.c:305
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.
Definition: multicore.c:301
multicore_launch_core1
void multicore_launch_core1(void(*entry)(void))
Run code on core 1.
Definition: multicore.c:155
multicore_launch_core1_with_stack
void multicore_launch_core1_with_stack(void(*entry)(void), uint32_t *stack_bottom, size_t stack_size_bytes)
Launch code on core 1 with stack.
Definition: multicore.c:132
multicore_launch_core1_raw
void multicore_launch_core1_raw(void(*entry)(void), uint32_t *sp, uint32_t vector_table)
Launch code on core 1 with no stack protection.
Definition: multicore.c:163
multicore_reset_core1
void multicore_reset_core1(void)
Reset core 1.
Definition: multicore.c:100
tight_loop_contents
static __force_inline void tight_loop_contents(void)
No-op function for the body of tight loops.
Definition: platform.h:67