IOAPIC: Difference between revisions

The Intel I/O Advanced Programmable Interrupt Controller is used to distribute external interrupts in a more advanced manner than that of the standard 8259 PIC. With the I/O APIC, interrupts can be distributed to physical or logical (clusters of) processors and can be prioritized. Each I/O APIC typically handles 24 external interrupts.

Detecting I/O APIC

In order to detect the existence of an I/O APIC (or multiple ones), the Intel Multi-Processor or ACPI tables (specifically, the MADT) must be parsed. In the MP tables, configuration tables with the entry identification of 0x02 are for I/O APICs. Parsing will tell how many (if any) I/O APICs exist, what are their APIC ID, base MMIO address and first IRQ (or GSI - Global System Interrupt). For more information on parsing the MP tables, see the External MP Tables Links section below. So you can have, say, 2 I/O APICs, the first handling IRQs 0 - 23 and the second 24 - 47.

Programming the I/O APIC

Each I/O APIC has a set of 2 or 3 (depending on version) 32-bit registers and up to many 64-bit registers (one per IRQ). The 64-bit registers have to be accessed as two 32-bit reads/writes. All registers are memory indexed. It means that you actually have only two 32-bit registers in memory, called IOREGSEL and IOREGWIN. You put the register index in IOREGSEL, and then you can read/write in IOREGWIN. The first three registers contain general information about this I/O APIC, while the remaining registers contain the specific configuration for each IRQ.

IOAPICID

This register has index 0 (you write 0 to IOREGSEL and then read from IOREGWIN). It's a Read-Only register with almost all bits reserved. The only interesting field is in bits 24 - 27: the APIC ID for this device (each peripheral which is interfaced with the APIC Bus needs an APIC ID, not only CPUs). You shall find this ID in ACPI/MP Tables as well.

IOAPICVER

This register (index 1) contains the I/O APIC Version in bits 0 - 7, and the Max Redirection Entry which is "how many IRQs can this I/O APIC handle - 1". It is encoded in bits 16 - 23.

IOAPICARB

This register (index 2) contains in bits 24 - 27 the APIC Arbitration ID. TODO

IOREDTBL

Following there are two 32-bit register for each IRQ. The first IRQ has indexes 0x10 and 0x11, the second 0x12 and 0x13, the third 0x14 and 0x15, and so on. So the Redirection Entry register for IRQ n is 0x10 + n * 2 (+ 1). In the first of the two registers you access to the LOW uint32_t / bits 31:0, and the second for the high uint32_t / 63:32. Each redirection entry is made of the following fields:

IOREGSEL and IOWIN

The register IOREGSEL is an MMIO register select register that is used to access all the other I/O APIC registers. The IOWIN register is the 'data' register. Once the IOREGSEL register has been set, the IOWIN register can be used to write or read the register in the IOREGSEL. The actual position in memory of the two registers is specified in the ACPI MADT Table and/or in the MP table. The IOREGSEL is at the address specified, and IOREGWIN is at the same address + 0x10.

#define IOAPICID 0x00
#define IOAPICVER 0x01
#define IOAPICARB 0x02
#define IOAPICREDTBL(n) (0x10 + 2 * n) // lower-32bits (add +1 for upper 32-bits)
voidwrite_ioapic_register(constuintptr_tapic_base,constuint8_toffset,constuint32_tval)
{
/* tell IOREGSEL where we want to write to */
*(volatileuint32_t*)(apic_base)=offset;
/* write the value to IOWIN */
*(volatileuint32_t*)(apic_base+0x10)=val;
}

uint32_tread_ioapic_register(constuintptr_tapic_base,constuint8_toffset)
{
/* tell IOREGSEL where we want to read from */
*(volatileuint32_t*)(apic_base)=offset;
/* return the data from IOWIN */
return*(volatileuint32_t*)(apic_base+0x10);
}
/* @class IOAPIC
 *
 * A sample driver code which control an IOAPIC. It handles one IOAPIC and exposes
 * some functions. It is totally representational, .i.e you should add locking support
 * link all IOAPIC classes in a data structure and much more. Here we are just showing
 * what & how your'e gonna handle this in C++.
 *
 * You could also note that IOAPIC registers "may" cross a page boundary. So maybe you
 * may need to map the physical-base to a double-page (means allocate twice the amount
 * of memory from vmm).
 */
classIOAPIC
{
public:
enumDeliveryMode
{
EDGE=0,
LEVEL=1,
};
enumDestinationMode
{
PHYSICAL=0,
LOGICAL=1
};
unionRedirectionEntry
{
struct
{
uint64_tvector:8;
uint64_tdelvMode:3;
uint64_tdestMode:1;
uint64_tdelvStatus:1;
uint64_tpinPolarity:1;
uint64_tremoteIRR:1;
uint64_ttriggerMode:1;
uint64_tmask:1;
uint64_treserved:39;
uint64_tdestination:8;
};
struct
{
uint32_tlowerDword;
uint32_tupperDword;
};
};
unsignedcharid(){return(apicId);}
unsignedcharver(){return(apicVer);}
unsignedcharredirectionEntries(){return(redirEntryCnt);}
unsignedlongglobalInterruptBase(){return(globalIntrBase);}
IOAPIC::IOAPIC(unsignedlongphysRegs,unsignedlongapicId,unsignedlonggsib)
{
this->virtAddr=KernelMemory::allocatePage(PAGE_SIZE);
/* map virtAddr to physical-regs. Note that your paging code may not support 
 automatically aligning physRegs to page-boundaries. Be sure to check! */
EnsureMapping(virtAddr,physRegs,PagePresent|PageReadWrite|PageCacheDisable);

virtAddr+=physRegs%PAGE_SIZE;
apicId=(read(IOAPICID)>>24)&0xF0;
apicVer=read(IOAPICVER);// cast to uint8_t (unsigned char) hides upper bits
//< max. redir entry is given IOAPICVER[16:24]
redirEntryCnt=(read(IOAPICVER)>>16)+1;// cast to uint8_t occuring ok!
globalIntrBase=gsib;
}
/*
 * Bit of assignment here - implement this on your own. Use the lowerDword & upperDword
 * fields of RedirectionEntry using
 * ent.lowerDword = read(entNo);
 * ent.upperDword = read(entNo);
 * return (ent);
 *
 * Be sure to check that entNo < redirectionEntries()
 *
 * @param entNo - entry no. for which redir-entry is required
 * @return entry associated with entry no.
 */
RedirectionEntrygetRedirEntry(unsignedcharentNo);
/*
 * Bit of assignment here - implement this on your own. Use the lowerDword & upperDword
 * fields of RedirectionEntry using
 * write(entNo, ent->lowerDword);
 * write(entNo, ent->upperDword);
 *
 * Be sure to check that entNo < redirectionEntries()
 *
 * @param entNo - entry no. for which redir-entry is required
 * @param entry - ptr to entry to write
 */
voidwriteRedirEntry(unsignedcharentNo,RedirectionEntry*entry);
private:
/*
 * This field contains the physical-base address for the IOAPIC
 * can be found using an IOAPIC-entry in the ACPI 2.0 MADT.
 */
unsignedlongphysRegs;
/*
 * Holds the base address of the registers in virtual memory. This
 * address is non-cacheable (see paging).
 */
unsignedlongvirtAddr;
/*
 * Software has complete control over the apic-id. Also, hardware
 * won't automatically change its apic-id so we could cache it here.
 */
unsignedcharapicId;
/*
 * Hardware-version of the apic, mainly for display purpose. ToDo: specify
 * more purposes.
 */
unsignedcharapicVer;
/*
 * Although entries for current IOAPIC is 24, it may change. To retain
 * compatibility make sure you use this.
 */
unsignedcharredirEntryCnt;
/*
 * The first IRQ which this IOAPIC handles. This is only found in the
 * IOAPIC entry of the ACPI 2.0 MADT. It isn't found in the IOAPIC
 * registers.
 */
unsignedlongglobalIntrBase;
/*
 * Reads the data present in the register at offset regOff.
 *
 * @param regOff - the register's offset which is being read
 * @return the data present in the register associated with that offset
 */
uint32_tread(unsignedcharregOff)
{
*(uint32_tvolatile*)virtAddr=regOff;
return*(uint32_tvolatile*)(virtAddr+0x10);
}
/*
 * Writes the data into the register associated. 
 *
 * @param regOff - the register's offset which is being written
 * @param data - dword to write to the register
 */
voidwrite(unsignedcharregOff,uint32_tdata)
{
*(uint32_tvolatile*)virtAddr=regOff;
*(uint32_tvolatile*)(virtAddr+0x10)=data;
}
};

'apic_base' is the memory base address for a selected IOAPIC, these can be found by enumerating them from the MP or ACPI Tables.

IO APIC Inputs

How other hardware (devices, etc) use IO APIC inputs is completely arbitrary - the motherboard/chipset designer can hard-wire anything they like to any IO APIC input. For the motherboard designer's convenience, most but not all legacy IRQs are often (but not always) connected "1:1" to IO APIC inputs (e.g. IO APIC input #1 may be the same as PIC chip input #1) as this makes firmware a little easier (e.g. no need for "interrupt redirection entries" in ACPI's MADT/APIC table), but this is not a requirement of any standard and not something that useful operating system software can rely on.

To correctly determine what how IO APIC inputs are used (and how they must be configured - as active high or active low, and as edge triggered or level triggered) operating system software must either:

1) Use APIC's MADT/APIC table to determine how legacy IRQs are mapped to IO APIC inputs; then use ACPI's AML (with a suitable interpreter) to determine how PCI devices are connected to IO APIC inputs

2) Use Intel's "MultiProcessor Specification" tables to determine how both legacy IRQs and PCI IRQs are mapped to IO APIC inputs. Note that Intel's "MultiProcessor Specification" is deprecated (an operating system should use ACPI where possible, and fall back to MultiProcessor Specification tables if ACPI doesn't exist or can't be used)

3) Provide (many) motherboard specific drivers, where each driver is able to use motherboard specific information to determine how IO inputs are used

4) Use an excessively "clever" auto-detection scheme (with a high risk of misconfiguration and race conditions). These schemes typically begin with whatever information can be obtained easily (e.g. determining legacy IRQs from ACPI's MADT/APIC table), assuming everything else can be configured as "level triggered active low" (to suit PCI), and then asking device drivers to repeatedly forcing their device to generate an IRQ (while ruling out IO APIC inputs that weren't triggered within a certain period of time after the IRQ was caused) until the specific IO APIC that the device uses can be determined.

External Links

MP Tables

• Intel MultiProcessor Specification

I/O APIC

• Intel 82093AA I/O APIC
• Intel SDM 3A (see chapter 9.9)

• Pages with ignored display titles
• Pages using deprecated source tags
• Interrupts
• Multiprocessing