APIC(3)                                                   APIC(3)

     NAME
          apic - Intel 32 and 64-bit Advanced Programmable Interrupt
          Controller

     SYNOPSIS
          bind -a #P /dev

          /dev/mpapic
          /dev/mpirq
          /dev/mptable
          /dev/mpvec
          *apicmode={flat, cluster, phys}
          *nomsi={0, 1}

     DESCRIPTION
          The APIC code implements the (x)APIC specification and
          message-signaled interrupts (MSI) for multiprocessor inter-
          rupt delivery.  They are supported by almost all 386 and
          amd64 machines.  APIC IDs less than 64 (or 256 by changing
          constants) are supported.  APIC code configures this hard-
          ware, picks a delivery mode, and assigns vectors in a
          round-robin fashon to interrupt targets.  In flat or cluster
          delivery mode, the target is hardware's choice from a set of
          processors; in physical mode, a specific processor is tar-
          geted.  Flat mode may be used with 8 or fewer processors.
          Clusters are defined by hardware, and must have 4 or fewer
          processors. Delivery mode is overridden with *apicmode; phys
          is always a safe choice.

          The APIC infrastructure supports two types of APICs.  The
          local APIC (LAPIC) is APIC target and initiator attached to
          each core.  I/O APICs route bus interrupts to LAPICs.  Three
          types of interrupts are supported: self (such as a clock
          interrupt), inter-processor interrupts (IPIs) or bus inter-
          rupts.  Bus interrupts are are routed from devices through
          I/O APICs to a set of LAPICs.

          The routing mechanism is a 64-bit vector stored in an I/O
          APIC that translates an input bus interrupt to a set of pro-
          cessors and a processor interrupt.  The set of processors
          may be specified (by order of preference) as a "flat" set of
          logical processors, a cluster of processors or a single
          physical processor.  The physical vectors select a target
          based on the LAPICs APIC ID, while logical vectors target
          the APIC DEST register.  Clusters are exactly matched, cores
          are matched as a bit vector.  A flat logical vector target-
          ing the first four processors would use a mask of 0x0f.

          For PCI devices with MSI capability, the vector is pro-
          grammed directly into the PCI device.  This allows the I/O

     Page 1                       Plan 9             (printed 3/28/24)

     APIC(3)                                                   APIC(3)

          APIC to be bypassed.  The interrupt targets LAPICs directly.
          Thus MSI interrupts can function without knowing anything
          more than the LAPIC ids of the processors.

          The available busses, interrupt routings and APICs are spec-
          ified in the MP table.  A digested version of the MP table
          is available in /dev/mptable if a table is found.  The for-
          mat is ad-hoc.

          When the machine is in multiprocessor mode, *nomp=0, addi-
          tional tables are available.

          A description of the available APICs and their configuration
          is available in /dev/mpapic.  This file contains 7 fields:
          type (proc or ioapic), APIC number, APIC ID, APIC DEST,
          mask, flags (b bsp, e enabled), and processor number.  Since
          the vector targeting code picks processors in round robin
          fashion regardless of mode, the mask will be the same for
          every processor in logical flat mode, the same for every
          processor in a cluster in logical cluster mode, and unique
          for every processor in physical mode.

          The /dev/mpirq file contains a list of vector mappings by
          bus as reported by the MP structure.  This file is self-
          explanatory, and not intended to be parsed.

          The /dev/mpvec file lists the configured I/O APIC vectors in
          the running system.  There are three fields: the I/O APIC
          number, the vector number, and the 64-bit vector.  a vector
          of 0x10000 is an unset, masked vector.

     SOURCE
          /sys/src/9/pc/apic.c
          /sys/src/9/pc/mp.c
          /sys/src/9/pc/mp.h

     SEE ALSO
          plan9.ini(8)
          Intel 5500 Chipset and Intel 5520 Chipset Datasheet,
          Intel 64 Architecture x2APIC Specification
          Intel 64 and IA-32 Architectures Software Developer's Manual
          Volume 3A
          Intel Multiprocessor Specification, version 1.4

     BUGS
          You are not expected to understand this.

          No support for x2APIC.

     Page 2                       Plan 9             (printed 3/28/24)