From 95e7b9efe9b9989028940aa655d113965165ce85 Mon Sep 17 00:00:00 2001 From: graham sanderson Date: Mon, 3 Feb 2025 12:42:12 -0600 Subject: [PATCH 1/2] add a bunch of verbosity around shared vtables --- .../hardware_irq/include/hardware/irq.h | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/rp2_common/hardware_irq/include/hardware/irq.h b/src/rp2_common/hardware_irq/include/hardware/irq.h index 78548ad9b..b9c90df97 100644 --- a/src/rp2_common/hardware_irq/include/hardware/irq.h +++ b/src/rp2_common/hardware_irq/include/hardware/irq.h @@ -286,6 +286,33 @@ void irq_set_mask_n_enabled(uint n, uint32_t mask, bool enabled); * This method will assert if there is already any sort of interrupt handler installed * for the specified irq number. * + * NOTE: By default, the SDK uses a single shared vector table per core, and the current installed + * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ numbers. + * Therefore, this method (when using the same vector table for both cores) sets the same interrupt handler + * for both cores. + * + * On RP2040 this was never really a cause of any confusion, because it rarely made sense to enable + * the same interrupt number in the NVIC on both cores (see \ref irq_set_enabled()), because the interrupt + * would then fire on both cores, and the interrupt handlers would race. + * + * The problem *does* exist however when dealing with interrupts which are independent on the two cores. + * + * This includes: + * + * * the core local "spare" IRQs + * * on RP2350 the SIO FIFO IRQ which is now the same irq number for both cores (vs RP2040 where it was two) + * + * In the cases where you want to enable the same IRQ on both cores, and both cores are sharing the same vector + * table, you should install the IRQ handler once - it will be used on both cores - and check the core + * number (via \ref get_core_num()) on each core. + * + * NOTE: It is not thread safe to add/remove/handle IRQs for the same irq number in the same vector table + * from both cores concurrently. + * + * NOTE: The SDK defines a PICO_VTABLE_PER_CORE variable indicating whether the two vector tables are separate, + * however as of version 2.1.1 the user cannot set this value, and expect the vector table duplication to be handled + * for them. This functionality will be added in a future SDK version + * * \param num Interrupt number \ref interrupt_nums * \param handler The handler to set. See \ref irq_handler_t * \see irq_add_shared_handler() @@ -316,6 +343,33 @@ irq_handler_t irq_get_exclusive_handler(uint num); * the (total across all IRQs on both cores) maximum (configurable via PICO_MAX_SHARED_IRQ_HANDLERS) number of shared handlers * would be exceeded. * + * NOTE: By default, the SDK uses a single shared vector table per core, and the current installed + * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ numbers. + * Therefore, this method (when using the same vector table for both cores) add the same interrupt handler + * for both cores. + * + * On RP2040 this was never really a cause of any confusion, because it rarely made sense to enable + * the same interrupt number in the NVIC on both cores (see \ref irq_set_enabled()), because the interrupt + * would then fire on both cores, and the interrupt handlers would race. + * + * The problem *does* exist however when dealing with interrupts which are independent on the two cores. + * + * This includes: + * + * * the core local "spare" IRQs + * * on RP2350 the SIO FIFO IRQ which is now the same irq number for both cores (vs RP2040 where it was two) + * + * In the cases where you want to enable the same IRQ on both cores, and both cores are sharing the same vector + * table, you should install the IRQ handler once - it will be used on both cores - and check the core + * number (via \ref get_core_num()) on each core. + * + * NOTE: It is not thread safe to add/remove/handle IRQs for the same irq number in the same vector table + * from both cores concurrently. + * + * NOTE: The SDK defines a PICO_VTABLE_PER_CORE variable indicating whether the two vector tables are separate, + * however as of version 2.1.1 the user cannot set this value, and expect the vector table duplication to be handled + * for them. This functionality will be added in a future SDK version + * * \param num Interrupt number \ref interrupt_nums * \param handler The handler to set. See \ref irq_handler_t * \param order_priority The order priority controls the order that handlers for the same IRQ number on the core are called. From 3feee49da9e28ccd1a0c3a11e71e49a44c648021 Mon Sep 17 00:00:00 2001 From: Graham Sanderson Date: Tue, 4 Feb 2025 16:04:23 -0600 Subject: [PATCH 2/2] fix typos --- src/rp2_common/hardware_irq/include/hardware/irq.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rp2_common/hardware_irq/include/hardware/irq.h b/src/rp2_common/hardware_irq/include/hardware/irq.h index b9c90df97..1ef382d5b 100644 --- a/src/rp2_common/hardware_irq/include/hardware/irq.h +++ b/src/rp2_common/hardware_irq/include/hardware/irq.h @@ -287,7 +287,7 @@ void irq_set_mask_n_enabled(uint n, uint32_t mask, bool enabled); * for the specified irq number. * * NOTE: By default, the SDK uses a single shared vector table per core, and the current installed - * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ numbers. + * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ number. * Therefore, this method (when using the same vector table for both cores) sets the same interrupt handler * for both cores. * @@ -344,7 +344,7 @@ irq_handler_t irq_get_exclusive_handler(uint num); * would be exceeded. * * NOTE: By default, the SDK uses a single shared vector table per core, and the current installed - * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ numbers. + * IRQ handlers are effectively a linked list starting a vector table entry for a particular IRQ number. * Therefore, this method (when using the same vector table for both cores) add the same interrupt handler * for both cores. *