From 975e257f2ce9daadcbe26d50df88158dc626e9e9 Mon Sep 17 00:00:00 2001 From: Daniel Leung Date: Thu, 6 Jan 2022 16:35:43 -0800 Subject: [PATCH] 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 --- drivers/interrupt_controller/intc_gic.c | 11 +++----- drivers/interrupt_controller/intc_ioapic.c | 25 ++----------------- drivers/interrupt_controller/intc_loapic.c | 10 -------- drivers/interrupt_controller/intc_plic.c | 22 ++++++---------- .../interrupt_controller/intc_system_apic.c | 8 ------ include/irq.h | 6 ----- include/irq_nextlevel.h | 6 ----- 7 files changed, 13 insertions(+), 75 deletions(-) diff --git a/drivers/interrupt_controller/intc_gic.c b/drivers/interrupt_controller/intc_gic.c index 17d0a55ec18..4650fcdf87e 100644 --- a/drivers/interrupt_controller/intc_gic.c +++ b/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); diff --git a/drivers/interrupt_controller/intc_ioapic.c b/drivers/interrupt_controller/intc_ioapic.c index 6c8be2695c9..81202f38a18 100644 --- a/drivers/interrupt_controller/intc_ioapic.c +++ b/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, diff --git a/drivers/interrupt_controller/intc_loapic.c b/drivers/interrupt_controller/intc_loapic.c index ed0a8ef387e..44f61c11ab3 100644 --- a/drivers/interrupt_controller/intc_loapic.c +++ b/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) diff --git a/drivers/interrupt_controller/intc_plic.c b/drivers/interrupt_controller/intc_plic.c index 9ce948c79f3..3c16e5ebf99 100644 --- a/drivers/interrupt_controller/intc_plic.c +++ b/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) { diff --git a/drivers/interrupt_controller/intc_system_apic.c b/drivers/interrupt_controller/intc_system_apic.c index 14933c181ea..3f85b832c21 100644 --- a/drivers/interrupt_controller/intc_system_apic.c +++ b/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) diff --git a/include/irq.h b/include/irq.h index 44dc9075aea..6e285d10778 100644 --- a/include/irq.h +++ b/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) diff --git a/include/irq_nextlevel.h b/include/irq_nextlevel.h index b7660e8a73c..20533cdf6e0 100644 --- a/include/irq_nextlevel.h +++ b/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,