michaelh/zephyr
1
0
Fork 0
Code Releases Activity

ioapic: cleanup code comments and doxygenize the file description

Browse source 
Use doxygen format for file documentation and move 
parameters to be part of the function comments.

Change-Id: I01c0614e7cd3ef4c689d2aec3aa3e52e0d21ffcd
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
Anas Nashif 2015-08-11 09:22:05 -04:00
commit 45a387fc46
1 changed files with 86 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

186
drivers/interrupt_controller/ioapic_intr.c
View file

@ -1,5 +1,3 @@
/* ioApicIntr.c - Intel IO APIC/xAPIC driver */
/* /*
* Copyright (c) 1997-1998, 2000-2002, 2004, 2006-2008, 2011-2015 Wind River * Copyright (c) 1997-1998, 2000-2002, 2004, 2006-2008, 2011-2015 Wind River
*Systems, Inc. *Systems, Inc.
@ -31,48 +29,49 @@
* POSSIBILITY OF SUCH DAMAGE. * POSSIBILITY OF SUCH DAMAGE.
*/ */
/* /**
DESCRIPTION * @file
This module is a driver for the IO APIC/xAPIC (Advanced Programmable * @brief Intel IO APIC/xAPIC driver
Interrupt Controller) for P6 (PentiumPro, II, III) family processors *
and P7 (Pentium4) family processors. The IO APIC/xAPIC is included * This module is a driver for the IO APIC/xAPIC (Advanced Programmable
in the Intel's system chip set, such as ICH2. Software intervention * Interrupt Controller) for P6 (PentiumPro, II, III) family processors
may be required to enable the IO APIC/xAPIC in some chip sets. * and P7 (Pentium4) family processors. The IO APIC/xAPIC is included
The 8259A interrupt controller is intended for use in a uni-processor * in the Intel's system chip set, such as ICH2. Software intervention
system, IO APIC can be used in either a uni-processor or multi-processor * may be required to enable the IO APIC/xAPIC in some chip sets.
system. The IO APIC handles interrupts very differently than the 8259A. * The 8259A interrupt controller is intended for use in a uni-processor
Briefly, these differences are: * system, IO APIC can be used in either a uni-processor or multi-processor
- Method of Interrupt Transmission. The IO APIC transmits interrupts * system. The IO APIC handles interrupts very differently than the 8259A.
through a 3-wire bus and interrupts are handled without the need for * Briefly, these differences are:
the processor to run an interrupt acknowledge cycle. * - Method of Interrupt Transmission. The IO APIC transmits interrupts
- Interrupt Priority. The priority of interrupts in the IO APIC is * through a 3-wire bus and interrupts are handled without the need for
independent of the interrupt number. For example, interrupt 10 can * the processor to run an interrupt acknowledge cycle.
be given a higher priority than interrupt 3. * - Interrupt Priority. The priority of interrupts in the IO APIC is
- More Interrupts. The IO APIC supports a total of 24 interrupts. * independent of the interrupt number. For example, interrupt 10 can
* be given a higher priority than interrupt 3.
The IO APIC unit consists of a set of interrupt input signals, a 24-entry * - More Interrupts. The IO APIC supports a total of 24 interrupts.
by 64-bit Interrupt Redirection Table, programmable registers, and a message *
unit for sending and receiving APIC messages over the APIC bus or the * The IO APIC unit consists of a set of interrupt input signals, a 24-entry
Front-Side (system) bus. IO devices inject interrupts into the system by * by 64-bit Interrupt Redirection Table, programmable registers, and a message
asserting one of the interrupt lines to the IO APIC. The IO APIC selects the * unit for sending and receiving APIC messages over the APIC bus or the
corresponding entry in the Redirection Table and uses the information in that * Front-Side (system) bus. IO devices inject interrupts into the system by
entry to format an interrupt request message. Each entry in the Redirection * asserting one of the interrupt lines to the IO APIC. The IO APIC selects the
Table can be individually programmed to indicate edge/level sensitive interrupt * corresponding entry in the Redirection Table and uses the information in that
signals, the interrupt vector and priority, the destination processor, and how * entry to format an interrupt request message. Each entry in the Redirection
the processor is selected (statically and dynamically). The information in * Table can be individually programmed to indicate edge/level sensitive interrupt
the table is used to transmit a message to other APIC units (via the APIC bus * signals, the interrupt vector and priority, the destination processor, and how
or the Front-Side (system) bus). IO APIC is used in the Symmetric IO Mode. * the processor is selected (statically and dynamically). The information in
The base address of IO APIC is determined in loapic_init() and stored in the * the table is used to transmit a message to other APIC units (via the APIC bus
global variable ioApicBase and ioApicData. * or the Front-Side (system) bus). IO APIC is used in the Symmetric IO Mode.
The lower 32 bit value of the redirection table entries for IRQ 0 * The base address of IO APIC is determined in loapic_init() and stored in the
to 15 are edge triggered positive high, and for IRQ 16 to 23 are level * global variable ioApicBase and ioApicData.
triggered positive low. * The lower 32 bit value of the redirection table entries for IRQ 0
* to 15 are edge triggered positive high, and for IRQ 16 to 23 are level
This implementation doesn't support multiple IO APICs. * triggered positive low.
*
INCLUDE FILES: ioapic.h loapic.h * This implementation doesn't support multiple IO APICs.
*
SEE ALSO: loApicIntr.c * INCLUDE FILES: ioapic.h loapic.h
*
*/ */
#include <nanokernel.h> #include <nanokernel.h>
@ -217,7 +216,6 @@ static void _IoApicRedUpdateLo(unsigned int irq, uint32_t value,
* *
* @return N/A * @return N/A
*/ */
void _ioapic_init(void) void _ioapic_init(void)
{ {
int32_t ix; /* redirection table index */ int32_t ix; /* redirection table index */
@ -259,12 +257,11 @@ void _ioapic_init(void)
* @brief Send EOI (End Of Interrupt) signal to IO APIC * @brief Send EOI (End Of Interrupt) signal to IO APIC
* *
* This routine sends an EOI signal to the IO APIC's interrupting source. * This routine sends an EOI signal to the IO APIC's interrupting source.
* @param irq Interrupt number to send EOI
* *
* @return N/A * @return N/A
*/ */
void _ioapic_eoi(unsigned int irq)
void _ioapic_eoi(unsigned int irq /* INT number to send EOI */
)
{ {
*(volatile unsigned int *)(CONFIG_IOAPIC_BASE_ADDRESS + IOAPIC_EOI) = irq; *(volatile unsigned int *)(CONFIG_IOAPIC_BASE_ADDRESS + IOAPIC_EOI) = irq;
*(volatile unsigned int *)(CONFIG_LOAPIC_BASE_ADDRESS + LOAPIC_EOI) = 0; *(volatile unsigned int *)(CONFIG_LOAPIC_BASE_ADDRESS + LOAPIC_EOI) = 0;
@ -276,16 +273,14 @@ void _ioapic_eoi(unsigned int irq /* INT number to send EOI */
* *
* This routine returns EOI signalling information for a specific IRQ. * This routine returns EOI signalling information for a specific IRQ.
* *
* @param irq IRQ number of interest
* @param argRequired Pointer to "argument required" result area
* @param arg Pointer to "argument value" result area
* @return address of routine to be called to signal EOI; * @return address of routine to be called to signal EOI;
* as a side effect, also passes back indication if routine requires * as a side effect, also passes back indication if routine requires
* an interrupt vector argument and what the argument value should be * an interrupt vector argument and what the argument value should be
*/ */
void *_ioapic_eoi_get(unsigned int irq, char *argRequired, void **arg)
void *_ioapic_eoi_get(unsigned int irq, /* INTIN number of interest */
char *argRequired, /* ptr to "argument required" result
area */
void **arg /* ptr to "argument value" result area */
)
{ {
#ifndef XIOAPIC_DIRECT_ADDRESSING #ifndef XIOAPIC_DIRECT_ADDRESSING
if (!(__IoApicGet(IOAPIC_VERS) & IOAPIC_PRQ)) { if (!(__IoApicGet(IOAPIC_VERS) & IOAPIC_PRQ)) {
@ -316,12 +311,11 @@ void *_ioapic_eoi_get(unsigned int irq, /* INTIN number of interest */
* @brief Enable a specified APIC interrupt input line * @brief Enable a specified APIC interrupt input line
* *
* This routine enables a specified APIC interrupt input line. * This routine enables a specified APIC interrupt input line.
* @param irq IRQ number to enable
* *
* @return N/A * @return N/A
*/ */
void _ioapic_irq_enable(unsigned int irq)
void _ioapic_irq_enable(unsigned int irq /* INTIN number to enable */
)
{ {
_IoApicRedUpdateLo(irq, 0, IOAPIC_INT_MASK); _IoApicRedUpdateLo(irq, 0, IOAPIC_INT_MASK);
} }
@ -331,12 +325,11 @@ void _ioapic_irq_enable(unsigned int irq /* INTIN number to enable */
* @brief Disable a specified APIC interrupt input line * @brief Disable a specified APIC interrupt input line
* *
* This routine disables a specified APIC interrupt input line. * This routine disables a specified APIC interrupt input line.
* @param irq IRQ number to disable
* *
* @return N/A * @return N/A
*/ */
void _ioapic_irq_disable(unsigned int irq)
void _ioapic_irq_disable(unsigned int irq /* INTIN number to disable */
)
{ {
_IoApicRedUpdateLo(irq, IOAPIC_INT_MASK, IOAPIC_INT_MASK); _IoApicRedUpdateLo(irq, IOAPIC_INT_MASK, IOAPIC_INT_MASK);
} }
@ -346,13 +339,13 @@ void _ioapic_irq_disable(unsigned int irq /* INTIN number to disable */
* @brief Programs the interrupt redirection table * @brief Programs the interrupt redirection table
* *
* This routine sets up the redirection table entry for the specified IRQ * 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 * @return N/A
*/ */
void _ioapic_irq_set(unsigned int irq, /* virtualized IRQ */ void _ioapic_irq_set(unsigned int irq, unsigned int vector, uint32_t flags)
unsigned int vector, /* vector number */
uint32_t flags /* interrupt flags */
)
{ {
uint32_t rteValue; /* value to copy into redirection table entry */ uint32_t rteValue; /* value to copy into redirection table entry */
@ -369,11 +362,11 @@ void _ioapic_irq_set(unsigned int irq, /* virtualized IRQ */
* The routine writes the interrupt vector in the Interrupt Redirection * The routine writes the interrupt vector in the Interrupt Redirection
* Table for specified irq number * Table for specified irq number
* *
* @param irq Interrupt number
* @param vector Vector number
* @return N/A * @return N/A
*/ */
void _ioapic_int_vec_set(unsigned int irq, /* INT number */ void _ioapic_int_vec_set(unsigned int irq, unsigned int vector)
unsigned int vector /* vector number */
)
{ {
_IoApicRedUpdateLo(irq, vector, IOAPIC_VEC_MASK); _IoApicRedUpdateLo(irq, vector, IOAPIC_VEC_MASK);
} }
@ -385,13 +378,11 @@ void _ioapic_int_vec_set(unsigned int irq, /* INT number */
* @brief Read a 32 bit IO APIC register * @brief Read a 32 bit IO APIC register
* *
* This routine reads the specified IO APIC register using indirect addressing. * This routine reads the specified IO APIC register using indirect addressing.
* @param offset Register offset (8 bits)
* *
* @return register value * @return register value
*/ */
static uint32_t __IoApicGet(int32_t offset)
static uint32_t __IoApicGet(
int32_t offset /* register offset (8 bits) */
)
{ {
uint32_t value; /* value */ uint32_t value; /* value */
int key; /* interrupt lock level */ int key; /* interrupt lock level */
@ -415,13 +406,11 @@ static uint32_t __IoApicGet(
* *
* This routine writes the specified IO APIC register using indirect addressing. * 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 * @return N/A
*/ */
static void __IoApicSet(int32_t offset, uint32_t value)
static void __IoApicSet(
int32_t offset, /* register offset (8 bits) */
uint32_t value /* value to set the register */
)
{ {
int key; /* interrupt lock level */ int key; /* interrupt lock level */
@ -443,11 +432,10 @@ static void __IoApicSet(
* *
* This routine reads the low-order 32 bits of a Redirection Table entry. * This routine reads the low-order 32 bits of a Redirection Table entry.
* *
* @param irq INTIN number
* @return 32 low-order bits * @return 32 low-order bits
*/ */
static uint32_t ioApicRedGetLo(unsigned int irq)
static uint32_t ioApicRedGetLo(unsigned int irq /* INTIN number */
)
{ {
#ifdef XIOAPIC_DIRECT_ADDRESSING #ifdef XIOAPIC_DIRECT_ADDRESSING
volatile uint32_t *pEntry; /* pointer to redirection table entry */ volatile uint32_t *pEntry; /* pointer to redirection table entry */
@ -469,12 +457,11 @@ static uint32_t ioApicRedGetLo(unsigned int irq /* INTIN number */
* *
* This routine writes the low-order 32 bits of a 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 * @return N/A
*/ */
static void ioApicRedSetLo(unsigned int irq, uint32_t lower32)
static void ioApicRedSetLo(unsigned int irq, /* INTIN number */
uint32_t lower32 /* value to be written */
)
{ {
#ifdef XIOAPIC_DIRECT_ADDRESSING #ifdef XIOAPIC_DIRECT_ADDRESSING
volatile uint32_t *pEntry; /* pointer to redirection table entry */ volatile uint32_t *pEntry; /* pointer to redirection table entry */
@ -496,12 +483,11 @@ static void ioApicRedSetLo(unsigned int irq, /* INTIN number */
* *
* This routine writes the high-order 32 bits of a 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 * @return N/A
*/ */
static void ioApicRedSetHi(unsigned int irq, uint32_t upper32)
static void ioApicRedSetHi(unsigned int irq, /* INTIN number */
uint32_t upper32 /* value to be written */
)
{ {
#ifdef XIOAPIC_DIRECT_ADDRESSING #ifdef XIOAPIC_DIRECT_ADDRESSING
volatile uint32_t *pEntry; /* pointer to redirection table entry */ volatile uint32_t *pEntry; /* pointer to redirection table entry */
@ -524,14 +510,14 @@ static void ioApicRedSetHi(unsigned int irq, /* INTIN number */
* This routine modifies selected portions of the low-order 32 bits of a * This routine modifies selected portions of the low-order 32 bits of a
* Redirection Table entry, as indicated by the associate bit mask. * Redirection Table entry, as indicated by the associate bit mask.
* *
* @param irq INTIN number
* @param value Value to be written
* @param mask Mask of bits to be modified
* @return N/A * @return N/A
*/ */
static void _IoApicRedUpdateLo(unsigned int irq,
static void _IoApicRedUpdateLo( uint32_t value,
unsigned int irq, /* INTIN number */ uint32_t mask)
uint32_t value, /* value to be written */
uint32_t mask /* mask of bits to be modified */
)
{ {
ioApicRedSetLo(irq, (ioApicRedGetLo(irq) & ~mask) | (value & mask)); ioApicRedSetLo(irq, (ioApicRedGetLo(irq) & ~mask) | (value & mask));
} }
@ -550,12 +536,11 @@ static void _IoApicRedUpdateLo(
* This routine writes the specified 32-bit <value> into the RTE configuration * This routine writes the specified 32-bit <value> into the RTE configuration
* register for the specified <irq> (0 to (CONFIG_IOAPIC_NUM_RTES - 1)) * register for the specified <irq> (0 to (CONFIG_IOAPIC_NUM_RTES - 1))
* *
* @return void * @param irq INTIN number
* @param value Value to be written
* @return N/A
*/ */
static void _IoApicRteConfigSet(unsigned int irq, uint32_t value)
static void _IoApicRteConfigSet(unsigned int irq, /* INTIN number */
uint32_t value /* value to be written */
)
{ {
unsigned int offset; /* register offset */ unsigned int offset; /* register offset */
@ -577,10 +562,11 @@ static void _IoApicRteConfigSet(unsigned int irq, /* INTIN number */
* *
* This routine writes the 32-bit <value> into the redirection register * This routine writes the 32-bit <value> into the redirection register
* specified by <reg>. * specified by <reg>.
* @param reg Register
* @param value Value to be written
* *
* @return void * @return N/A
*/ */
static void _IoApicRedirRegSet(unsigned int reg, uint32_t value) static void _IoApicRedirRegSet(unsigned int reg, uint32_t value)
{ {
unsigned int offset; /* register offset */ unsigned int offset; /* register offset */