drivers: interrupt_controller: remove @return doc for void funcs

For functions returning nothing, there is no need to document
with @return, as Doxgen complains about "documented empty
return type of ...".

Signed-off-by: Daniel Leung <daniel.leung@intel.com>

drivers/interrupt_controller/intc_gic.c

@@ -219,16 +219,13 @@ static void gic_cpu_init(void)
 	sys_write32(val, GICC_CTLR);
 }
 
-/**
- *
- * @brief Initialize the GIC device driver
- *
- *
- * @return N/A
- */
 #define GIC_PARENT_IRQ 0
 #define GIC_PARENT_IRQ_PRI 0
 #define GIC_PARENT_IRQ_FLAGS 0
+
+/**
+ * @brief Initialize the GIC device driver
+ */
 int arm_gic_init(const struct device *unused)
 {
 	ARG_UNUSED(unused);

drivers/interrupt_controller/intc_ioapic.c

@@ -153,12 +153,11 @@ static bool get_vtd(void)
  */
 
 /**
- *
  * @brief Initialize the IO APIC or xAPIC
  *
  * This routine initializes the IO APIC or xAPIC.
  *
- * @return N/A
+ * @retval 0 on success.
  */
 __boot_func
 int ioapic_init(const struct device *unused)
@@ -193,13 +192,11 @@ uint32_t z_ioapic_num_rtes(void)
 }
 
 /**
- *
  * @brief Enable a specified APIC interrupt input line
  *
  * This routine enables a specified APIC interrupt input line.
- * @param irq IRQ number to enable
  *
- * @return N/A
+ * @param irq IRQ number to enable
  */
 __pinned_func
 void z_ioapic_irq_enable(unsigned int irq)
@@ -208,13 +205,10 @@ void z_ioapic_irq_enable(unsigned int irq)
 }
 
 /**
- *
  * @brief Disable a specified APIC interrupt input line
  *
  * This routine disables a specified APIC interrupt input line.
  * @param irq IRQ number to disable
- *
- * @return N/A
  */
 __pinned_func
 void z_ioapic_irq_disable(unsigned int irq)
@@ -362,15 +356,12 @@ static int ioapic_pm_action(const struct device *dev,
 #endif  /*CONFIG_PM_DEVICE*/
 
 /**
- *
  * @brief Programs the interrupt redirection table
  *
  * This routine sets up the redirection table entry for the specified IRQ
  * @param irq Virtualized IRQ
  * @param vector Vector number
  * @param flags Interrupt flags
- *
- * @return N/A
  */
 __boot_func
 void z_ioapic_irq_set(unsigned int irq, unsigned int vector, uint32_t flags)
@@ -422,7 +413,6 @@ no_vtd:
 }
 
 /**
- *
  * @brief Program interrupt vector for specified irq
  *
  * The routine writes the interrupt vector in the Interrupt Redirection
@@ -430,7 +420,6 @@ no_vtd:
  *
  * @param irq Interrupt number
  * @param vector Vector number
- * @return N/A
  */
 __boot_func
 void z_ioapic_int_vec_set(unsigned int irq, unsigned int vector)
@@ -439,7 +428,6 @@ void z_ioapic_int_vec_set(unsigned int irq, unsigned int vector)
 }
 
 /**
- *
  * @brief Read a 32 bit IO APIC register
  *
  * This routine reads the specified IO APIC register using indirect addressing.
@@ -466,14 +454,12 @@ static uint32_t __IoApicGet(int32_t offset)
 }
 
 /**
- *
  * @brief Write a 32 bit IO APIC register
  *
  * This routine writes the specified IO APIC register using indirect addressing.
  *
  * @param offset Register offset (8 bits)
  * @param value Value to set the register
- * @return N/A
  */
 __pinned_func
 static void __IoApicSet(int32_t offset, uint32_t value)
@@ -491,7 +477,6 @@ static void __IoApicSet(int32_t offset, uint32_t value)
 }
 
 /**
- *
  * @brief Get low 32 bits of Redirection Table entry
  *
  * This routine reads the low-order 32 bits of a Redirection Table entry.
@@ -508,14 +493,12 @@ static uint32_t ioApicRedGetLo(unsigned int irq)
 }
 
 /**
- *
  * @brief Set low 32 bits of Redirection Table entry
  *
  * This routine writes the low-order 32 bits of a Redirection Table entry.
  *
  * @param irq INTIN number
  * @param lower32 Value to be written
- * @return N/A
  */
 __pinned_func
 static void ioApicRedSetLo(unsigned int irq, uint32_t lower32)
@@ -526,14 +509,12 @@ static void ioApicRedSetLo(unsigned int irq, uint32_t lower32)
 }
 
 /**
- *
  * @brief Set high 32 bits of Redirection Table entry
  *
  * This routine writes the high-order 32 bits of a Redirection Table entry.
  *
  * @param irq INTIN number
  * @param upper32 Value to be written
- * @return N/A
  */
 __pinned_func
 static void ioApicRedSetHi(unsigned int irq, uint32_t upper32)
@@ -544,7 +525,6 @@ static void ioApicRedSetHi(unsigned int irq, uint32_t upper32)
 }
 
 /**
- *
  * @brief Modify low 32 bits of Redirection Table entry
  *
  * This routine modifies selected portions of the low-order 32 bits of a
@@ -553,7 +533,6 @@ static void ioApicRedSetHi(unsigned int irq, uint32_t upper32)
  * @param irq INTIN number
  * @param value Value to be written
  * @param mask  Mask of bits to be modified
- * @return N/A
  */
 __pinned_func
 static void IoApicRedUpdateLo(unsigned int irq,

drivers/interrupt_controller/intc_loapic.c

@@ -183,7 +183,6 @@ void z_loapic_enable(unsigned char cpu_number)
 }
 
 /**
- *
  * @brief Dummy initialization function.
  *
  * The local APIC is initialized via z_loapic_enable() long before the
@@ -204,12 +203,9 @@ uint32_t z_loapic_irq_base(void)
 }
 
 /**
- *
  * @brief Set the vector field in the specified RTE
  *
  * This associates an IRQ with the desired vector in the IDT.
- *
- * @return N/A
  */
 __boot_func
 void z_loapic_int_vec_set(unsigned int irq, /* IRQ number of the interrupt */
@@ -241,14 +237,11 @@ void z_loapic_int_vec_set(unsigned int irq, /* IRQ number of the interrupt */
 }
 
 /**
- *
  * @brief Enable an individual LOAPIC interrupt (IRQ)
  *
  * @param irq the IRQ number of the interrupt
  *
  * This routine clears the interrupt mask bit in the LVT for the specified IRQ
- *
- * @return N/A
  */
 __pinned_func
 void z_loapic_irq_enable(unsigned int irq)
@@ -270,14 +263,11 @@ void z_loapic_irq_enable(unsigned int irq)
 }
 
 /**
- *
  * @brief Disable an individual LOAPIC interrupt (IRQ)
  *
  * @param irq the IRQ number of the interrupt
  *
  * This routine clears the interrupt mask bit in the LVT for the specified IRQ
- *
- * @return N/A
  */
 __pinned_func
 void z_loapic_irq_disable(unsigned int irq)

drivers/interrupt_controller/intc_plic.c

@@ -35,16 +35,14 @@ struct plic_regs_t {
 static int save_irq;
 
 /**
- *
  * @brief Enable a riscv PLIC-specific interrupt line
  *
  * This routine enables a RISCV PLIC-specific interrupt line.
  * riscv_plic_irq_enable is called by SOC_FAMILY_RISCV_PRIVILEGE
  * arch_irq_enable function to enable external interrupts for
  * IRQS level == 2, whenever CONFIG_RISCV_HAS_PLIC variable is set.
- * @param irq IRQ number to enable
  *
- * @return N/A
+ * @param irq IRQ number to enable
  */
 void riscv_plic_irq_enable(uint32_t irq)
 {
@@ -58,16 +56,14 @@ void riscv_plic_irq_enable(uint32_t irq)
 }
 
 /**
- *
  * @brief Disable a riscv PLIC-specific interrupt line
  *
  * This routine disables a RISCV PLIC-specific interrupt line.
  * riscv_plic_irq_disable is called by SOC_FAMILY_RISCV_PRIVILEGE
  * arch_irq_disable function to disable external interrupts, for
  * IRQS level == 2, whenever CONFIG_RISCV_HAS_PLIC variable is set.
- * @param irq IRQ number to disable
  *
- * @return N/A
+ * @param irq IRQ number to disable
  */
 void riscv_plic_irq_disable(uint32_t irq)
 {
@@ -81,7 +77,6 @@ void riscv_plic_irq_disable(uint32_t irq)
 }
 
 /**
- *
  * @brief Check if a riscv PLIC-specific interrupt line is enabled
  *
  * This routine checks if a RISCV PLIC-specific interrupt line is enabled.
@@ -98,15 +93,14 @@ int riscv_plic_irq_is_enabled(uint32_t irq)
 }
 
 /**
- *
  * @brief Set priority of a riscv PLIC-specific interrupt line
  *
  * This routine set the priority of a RISCV PLIC-specific interrupt line.
  * riscv_plic_irq_set_prio is called by riscv arch_irq_priority_set to set
  * the priority of an interrupt whenever CONFIG_RISCV_HAS_PLIC variable is set.
- * @param irq IRQ number for which to set priority
  *
- * @return N/A
+ * @param irq IRQ number for which to set priority
+ * @param priority Priority of IRQ to set to
  */
 void riscv_plic_set_priority(uint32_t irq, uint32_t priority)
 {
@@ -120,14 +114,12 @@ void riscv_plic_set_priority(uint32_t irq, uint32_t priority)
 }
 
 /**
- *
  * @brief Get riscv PLIC-specific interrupt line causing an interrupt
  *
  * This routine returns the RISCV PLIC-specific interrupt line causing an
  * interrupt.
- * @param irq IRQ number for which to set priority
  *
- * @return N/A
+ * @return PLIC-specific interrupt line causing an interrupt.
  */
 int riscv_plic_get_irq(void)
 {
@@ -174,9 +166,9 @@ static void plic_irq_handler(const void *arg)
 }
 
 /**
- *
  * @brief Initialize the Platform Level Interrupt Controller
- * @return N/A
+ *
+ * @retval 0 on success.
  */
 static int plic_init(const struct device *dev)
 {

drivers/interrupt_controller/intc_system_apic.c

@@ -23,7 +23,6 @@
 #define HARDWARE_IRQ_LIMIT ((z_loapic_irq_base() + LOAPIC_IRQ_COUNT) - 1)
 
 /**
- *
  * @brief Program interrupt controller
  *
  * This routine programs the interrupt controller with the given vector
@@ -42,7 +41,6 @@
  * @param vector the vector number
  * @param irq the virtualized IRQ
  * @param flags interrupt flags
- *
  */
 __boot_func
 void z_irq_controller_irq_config(unsigned int vector, unsigned int irq,
@@ -58,7 +56,6 @@ void z_irq_controller_irq_config(unsigned int vector, unsigned int irq,
 }
 
 /**
- *
  * @brief Enable an individual interrupt (IRQ)
  *
  * The public interface for enabling/disabling a specific IRQ for the IA-32
@@ -71,8 +68,6 @@ void z_irq_controller_irq_config(unsigned int vector, unsigned int irq,
  * to the IRQ virtualization that is performed by this platform.  See the
  * comments in _interrupt_vector_allocate() for more information regarding IRQ
  * virtualization.
- *
- * @return N/A
  */
 __pinned_func
 void arch_irq_enable(unsigned int irq)
@@ -85,15 +80,12 @@ void arch_irq_enable(unsigned int irq)
 }
 
 /**
- *
  * @brief Disable an individual interrupt (IRQ)
  *
  * The irq_disable() routine is provided by the interrupt controller driver due
  * to the IRQ virtualization that is performed by this platform.  See the
  * comments in _interrupt_vector_allocate() for more information regarding IRQ
  * virtualization.
- *
- * @return N/A
  */
 __pinned_func
 void arch_irq_disable(unsigned int irq)

include/irq.h

@@ -247,8 +247,6 @@ unsigned int z_smp_global_lock(void);
  * @note Can be called by ISRs.
  *
  * @param key Lock-out key generated by irq_lock().
- *
- * @return N/A
  */
 #ifdef CONFIG_SMP
 void z_smp_global_unlock(unsigned int key);
@@ -391,8 +389,6 @@ static inline unsigned int irq_parent_level_3(unsigned int irq)
  * This routine enables interrupts from source @a irq.
  *
  * @param irq IRQ line.
- *
- * @return N/A
  */
 #define irq_enable(irq) arch_irq_enable(irq)
 
@@ -402,8 +398,6 @@ static inline unsigned int irq_parent_level_3(unsigned int irq)
  * This routine disables interrupts from source @a irq.
  *
  * @param irq IRQ line.
- *
- * @return N/A
  */
 #define irq_disable(irq) arch_irq_disable(irq)
 

include/irq_nextlevel.h

@@ -48,8 +48,6 @@ struct irq_next_level_api {
  *
  * @param dev Pointer to the device structure for the driver instance.
  * @param irq IRQ to be enabled.
- *
- * @return N/A
  */
 static inline void irq_enable_next_level(const struct device *dev,
 					 uint32_t irq)
@@ -67,8 +65,6 @@ static inline void irq_enable_next_level(const struct device *dev,
  *
  * @param dev Pointer to the device structure for the driver instance.
  * @param irq IRQ to be disabled.
- *
- * @return N/A
  */
 static inline void irq_disable_next_level(const struct device *dev,
 					  uint32_t irq)
@@ -107,8 +103,6 @@ static inline unsigned int irq_is_enabled_next_level(const struct device *dev)
  * @param irq IRQ to be disabled.
  * @param prio priority for irq in the interrupt controller.
  * @param flags controller specific flags.
- *
- * @return N/A
  */
 static inline void irq_set_priority_next_level(const struct device *dev,
 				               uint32_t irq,