Fix spelling mistake, add documentation (#1444)

* USB descriptor string length.

Implement a mechanism to set the maximum string length used in
tud_descriptor_string_cb() by defining USBD_DESC_STR_MAX. If
USBD_DESC_STR_MAX is not defined, the behavior remains unchanged and the
previous default value of 20 is used. A compile time error is produced
if USBD_DESC_STR_MAX is higher than 127 since the length of the string
plus header is returned in a single byte as (2 * len + 2). Similarly, a
compile time error is generated if the length is defined as less than 17
in order to ensure that there is enough room for the 16-character serial
number plus header.

* Fix spelling mistake.

Renamed irq_hander_chain_free_slot_head to irq_handler_chain_free_slot_head
(added missing l).

* Add documentation for gpio_add_raw_irq_handler functions.

Added a note that irq_add_shared_handler() is used internally and that
the function will assert if the maximum number of shared handlers would
be exceeded.

src/rp2_common/hardware_gpio/include/hardware/gpio.h

@@ -493,6 +493,8 @@ void gpio_acknowledge_irq(uint gpio, uint32_t event_mask);
  * This method adds such an explicit GPIO IRQ handler, and disables the "default" callback for the specified GPIOs.
  *
  * \note Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.
+ * Internally, this function calls \ref irq_add_shared_handler, which will assert if the maximum number of shared handlers
+ * (configurable via PICO_MAX_IRQ_SHARED_HANDLERS) would be exceeded.
  *
  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
  *
@@ -526,6 +528,8 @@ void gpio_add_raw_irq_handler_with_order_priority_masked(uint gpio_mask, irq_han
  * This method adds such a callback, and disables the "default" callback for the specified GPIO.
  *
  * \note Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.
+ * Internally, this function calls \ref irq_add_shared_handler, which will assert if the maximum number of shared handlers
+ * (configurable via PICO_MAX_IRQ_SHARED_HANDLERS) would be exceeded.
  *
  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
  *
@@ -556,6 +560,8 @@ static inline void gpio_add_raw_irq_handler_with_order_priority(uint gpio, irq_h
  * This method adds such a callback, and disables the "default" callback for the specified GPIOs.
  *
  * \note Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.
+ * Internally, this function calls \ref irq_add_shared_handler, which will assert if the maximum number of shared handlers
+ * (configurable via PICO_MAX_IRQ_SHARED_HANDLERS) would be exceeded.
  *
  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
  *
@@ -586,6 +592,8 @@ void gpio_add_raw_irq_handler_masked(uint gpio_mask, irq_handler_t handler);
  * This method adds such a callback, and disables the "default" callback for the specified GPIO.
  *
  * \note Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.
+ * Internally, this function calls \ref irq_add_shared_handler, which will assert if the maximum number of shared handlers
+ * (configurable via PICO_MAX_IRQ_SHARED_HANDLERS) would be exceeded.
  *
  * A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:
  *

src/rp2_common/hardware_irq/irq.c

@@ -100,7 +100,7 @@ extern struct irq_handler_chain_slot {
     irq_handler_t handler;
 } irq_handler_chain_slots[PICO_MAX_SHARED_IRQ_HANDLERS];
 
-static int8_t irq_hander_chain_free_slot_head;
+static int8_t irq_handler_chain_free_slot_head;
 
 static inline bool is_shared_irq_raw_handler(irq_handler_t raw_handler) {
     return (uintptr_t)raw_handler - (uintptr_t)irq_handler_chain_slots < sizeof(irq_handler_chain_slots);
@@ -212,10 +212,10 @@ void irq_add_shared_handler(uint num, irq_handler_t handler, uint8_t order_prior
 #else
     spin_lock_t *lock = spin_lock_instance(PICO_SPINLOCK_ID_IRQ);
     uint32_t save = spin_lock_blocking(lock);
-    hard_assert(irq_hander_chain_free_slot_head >= 0); // we must have a slot
-    struct irq_handler_chain_slot *slot = &irq_handler_chain_slots[irq_hander_chain_free_slot_head];
-    int8_t slot_index = irq_hander_chain_free_slot_head;
-    irq_hander_chain_free_slot_head = slot->link;
+    hard_assert(irq_handler_chain_free_slot_head >= 0); // we must have a slot
+    struct irq_handler_chain_slot *slot = &irq_handler_chain_slots[irq_handler_chain_free_slot_head];
+    int8_t slot_index = irq_handler_chain_free_slot_head;
+    irq_handler_chain_free_slot_head = slot->link;
     irq_handler_t vtable_handler = get_vtable()[16 + num];
     if (!is_shared_irq_raw_handler(vtable_handler)) {
         // start new chain
@@ -332,8 +332,8 @@ void irq_remove_handler(uint num, irq_handler_t handler) {
                             0xbd01;                                                                // pop {r0, pc}
 
                     // add old next slot back to free list
-                    next_slot->link = irq_hander_chain_free_slot_head;
-                    irq_hander_chain_free_slot_head = next_slot_index;
+                    next_slot->link = irq_handler_chain_free_slot_head;
+                    irq_handler_chain_free_slot_head = next_slot_index;
                 } else {
                     // Slot being removed is at the end of the chain
                     if (!exception) {
@@ -347,8 +347,8 @@ void irq_remove_handler(uint num, irq_handler_t handler) {
                             vtable_handler = __unhandled_user_irq;
                         }
                         // add slot back to free list
-                        to_free_slot->link = irq_hander_chain_free_slot_head;
-                        irq_hander_chain_free_slot_head = get_slot_index(to_free_slot);
+                        to_free_slot->link = irq_handler_chain_free_slot_head;
+                        irq_handler_chain_free_slot_head = get_slot_index(to_free_slot);
                     } else {
                         // since we are the last slot we know that our inst3 hasn't executed yet, so we change
                         // it to bl to irq_handler_chain_remove_tail which will remove the slot.
@@ -418,8 +418,8 @@ void irq_add_tail_to_free_list(struct irq_handler_chain_slot *slot) {
         assert(found);
     }
     // add slot to free list
-    slot->link = irq_hander_chain_free_slot_head;
-    irq_hander_chain_free_slot_head = slot_index;
+    slot->link = irq_handler_chain_free_slot_head;
+    irq_handler_chain_free_slot_head = slot_index;
     spin_unlock(lock, save);
 }
 #endif