FuriHal: interrupt priorities and documentation (#3366)

* FuriHal: interrupt priorities and documentation
* FuriHal: wording
* FuriHal: update interrupt docs
* FuriHal: add more interrupt priority levels
* FuriHal: proper furi_check in interrupts, shift default level to 10

---------

Co-authored-by: hedger <hedger@users.noreply.github.com>

lib/signal_reader/signal_reader.c

@@ -278,7 +278,10 @@ void signal_reader_start(SignalReader* instance, SignalReaderCallback callback,
 
     // Start DMA irq, higher priority than normal
     furi_hal_interrupt_set_isr_ex(
-        SIGNAL_READER_DMA_GPIO_IRQ, 14, furi_hal_sw_digital_pin_dma_rx_isr, instance);
+        SIGNAL_READER_DMA_GPIO_IRQ,
+        FuriHalInterruptPriorityHighest,
+        furi_hal_sw_digital_pin_dma_rx_isr,
+        instance);
 
     // Start DMA Sync timer
     LL_DMA_EnableChannel(SIGNAL_READER_DMA_CNT_SYNC_DEF);

targets/f18/api_symbols.csv

@@ -1149,7 +1149,7 @@ Function,-,furi_hal_init,void,
 Function,-,furi_hal_init_early,void,
 Function,-,furi_hal_interrupt_init,void,
 Function,+,furi_hal_interrupt_set_isr,void,"FuriHalInterruptId, FuriHalInterruptISR, void*"
-Function,+,furi_hal_interrupt_set_isr_ex,void,"FuriHalInterruptId, uint16_t, FuriHalInterruptISR, void*"
+Function,+,furi_hal_interrupt_set_isr_ex,void,"FuriHalInterruptId, FuriHalInterruptPriority, FuriHalInterruptISR, void*"
 Function,+,furi_hal_light_blink_set_color,void,Light
 Function,+,furi_hal_light_blink_start,void,"Light, uint8_t, uint16_t, uint16_t"
 Function,+,furi_hal_light_blink_stop,void,

targets/f7/api_symbols.csv

@@ -1256,7 +1256,7 @@ Function,-,furi_hal_init,void,
 Function,-,furi_hal_init_early,void,
 Function,-,furi_hal_interrupt_init,void,
 Function,+,furi_hal_interrupt_set_isr,void,"FuriHalInterruptId, FuriHalInterruptISR, void*"
-Function,+,furi_hal_interrupt_set_isr_ex,void,"FuriHalInterruptId, uint16_t, FuriHalInterruptISR, void*"
+Function,+,furi_hal_interrupt_set_isr_ex,void,"FuriHalInterruptId, FuriHalInterruptPriority, FuriHalInterruptISR, void*"
 Function,+,furi_hal_light_blink_set_color,void,Light
 Function,+,furi_hal_light_blink_start,void,"Light, uint8_t, uint16_t, uint16_t"
 Function,+,furi_hal_light_blink_stop,void,

targets/f7/furi_hal/furi_hal_infrared.c

@@ -406,7 +406,10 @@ static void furi_hal_infrared_configure_tim_cmgr2_dma_tx(void) {
     LL_DMA_EnableIT_TC(INFRARED_DMA_CH1_DEF);
 
     furi_hal_interrupt_set_isr_ex(
-        INFRARED_DMA_CH1_IRQ, 4, furi_hal_infrared_tx_dma_polarity_isr, NULL);
+        INFRARED_DMA_CH1_IRQ,
+        FuriHalInterruptPriorityKamiSama,
+        furi_hal_infrared_tx_dma_polarity_isr,
+        NULL);
 }
 
 static void furi_hal_infrared_configure_tim_rcr_dma_tx(void) {
@@ -436,7 +439,7 @@ static void furi_hal_infrared_configure_tim_rcr_dma_tx(void) {
     LL_DMA_EnableIT_HT(INFRARED_DMA_CH2_DEF);
     LL_DMA_EnableIT_TE(INFRARED_DMA_CH2_DEF);
 
-    furi_hal_interrupt_set_isr_ex(INFRARED_DMA_CH2_IRQ, 5, furi_hal_infrared_tx_dma_isr, NULL);
+    furi_hal_interrupt_set_isr(INFRARED_DMA_CH2_IRQ, furi_hal_infrared_tx_dma_isr, NULL);
 }
 
 static void furi_hal_infrared_tx_fill_buffer_last(uint8_t buf_num) {

targets/f7/furi_hal/furi_hal_interrupt.c

@@ -11,7 +11,7 @@
 
 #define TAG "FuriHalInterrupt"
 
-#define FURI_HAL_INTERRUPT_DEFAULT_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY)
+#define FURI_HAL_INTERRUPT_DEFAULT_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY + 5)
 
 typedef struct {
     FuriHalInterruptISR isr;
@@ -126,16 +126,21 @@ void furi_hal_interrupt_init() {
 }
 
 void furi_hal_interrupt_set_isr(FuriHalInterruptId index, FuriHalInterruptISR isr, void* context) {
-    furi_hal_interrupt_set_isr_ex(index, FURI_HAL_INTERRUPT_DEFAULT_PRIORITY, isr, context);
+    furi_hal_interrupt_set_isr_ex(index, FuriHalInterruptPriorityNormal, isr, context);
 }
 
 void furi_hal_interrupt_set_isr_ex(
     FuriHalInterruptId index,
-    uint16_t priority,
+    FuriHalInterruptPriority priority,
     FuriHalInterruptISR isr,
     void* context) {
     furi_check(index < FuriHalInterruptIdMax);
-    furi_check(priority <= 15);
+    furi_check(
+        (priority >= FuriHalInterruptPriorityLowest &&
+         priority <= FuriHalInterruptPriorityHighest) ||
+        priority == FuriHalInterruptPriorityKamiSama);
+
+    uint16_t real_priority = FURI_HAL_INTERRUPT_DEFAULT_PRIORITY - priority;
 
     if(isr) {
         // Pre ISR set
@@ -153,7 +158,7 @@ void furi_hal_interrupt_set_isr_ex(
     if(isr) {
         // Post ISR set
         furi_hal_interrupt_clear_pending(index);
-        furi_hal_interrupt_enable(index, priority);
+        furi_hal_interrupt_enable(index, real_priority);
     } else {
         // Post ISR clear
     }

targets/f7/furi_hal/furi_hal_interrupt.h

@@ -59,27 +59,54 @@ typedef enum {
     FuriHalInterruptIdMax,
 } FuriHalInterruptId;
 
+typedef enum {
+    FuriHalInterruptPriorityLowest =
+        -3, /**< Lowest priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityLower =
+        -2, /**< Lower priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityLow =
+        -1, /**< Low priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityNormal =
+        0, /**< Normal(default) priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityHigh =
+        1, /**< High priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityHigher =
+        2, /**< Higher priority level, you can use ISR-safe OS primitives */
+    FuriHalInterruptPriorityHighest =
+        3, /**< Highest priority level, you can use ISR-safe OS primitives */
+
+    /* Special group, read docs first(ALL OF THEM: especially FreeRTOS configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) */
+    FuriHalInterruptPriorityKamiSama =
+        6, /**< Forget about thread safety, you are god now. No one can prevent you from messing with OS critical section. You are not allowed to use any OS primitives, but who can stop you? Use this priority only for direct hardware interaction with LL HAL. */
+} FuriHalInterruptPriority;
+
 /** Initialize interrupt subsystem */
 void furi_hal_interrupt_init();
 
 /** Set ISR and enable interrupt with default priority
- * We don't clear interrupt flags for you, do it by your self.
- * @param index - interrupt ID
- * @param isr - your interrupt service routine or use NULL to clear
- * @param context - isr context
+ *
+ * @warning    Interrupt flags are not cleared automatically. You may want to
+ *             ensure that your peripheral status flags are cleared.
+ *
+ * @param      index    - interrupt ID
+ * @param      isr      - your interrupt service routine or use NULL to clear
+ * @param      context  - isr context
  */
 void furi_hal_interrupt_set_isr(FuriHalInterruptId index, FuriHalInterruptISR isr, void* context);
 
 /** Set ISR and enable interrupt with custom priority
- * We don't clear interrupt flags for you, do it by your self.
- * @param index - interrupt ID
- * @param priority - 0 to 15, 0 highest
- * @param isr - your interrupt service routine or use NULL to clear
- * @param context - isr context
+ *
+ * @warning    Interrupt flags are not cleared automatically. You may want to
+ *             ensure that your peripheral status flags are cleared.
+ *
+ * @param      index     - interrupt ID
+ * @param      priority  - One of FuriHalInterruptPriority
+ * @param      isr       - your interrupt service routine or use NULL to clear
+ * @param      context   - isr context
  */
 void furi_hal_interrupt_set_isr_ex(
     FuriHalInterruptId index,
-    uint16_t priority,
+    FuriHalInterruptPriority priority,
     FuriHalInterruptISR isr,
     void* context);