Struct LocalApic

pub struct LocalApic { /* private fields */ }

Local APIC state.

Notes on Mutability

In a multi-core x86_64 system, each CPU core has its own local APIC. Therefore, the Mycelium HAL’s interrupt::Controller type uses core-local storage to store a reference to each CPU core’s local APIC that can be accessed only by that core. The value in core-local storage is a RefCell<Option<LocalApic>>, as the local APIC must be initialized on a per-core basis before it can be used.

Note that the RefCell must only be borrowed mutably in order to initialize the LocalApic value. Once the local APIC has been initialized, it may receive interrupts, and may also be accessed by interrupt handlers in order to send an end-of-interrupt. This means that mutably borrowing the RefCell once interrupts are enabled may result in a panic if an ISR attempts to borrow the local APIC immutably to send an EOI while the local APIC is borrowed mutably.

Therefore, all local APIC operations that mutate state, such as setting the timer calibration, must use interior mutability, so that an interrupt handler may access the local APIC’s state. Interior mutability need not be thread-safe, however, as the local APIC state is only accessed from the core that owns it.

Implementations

impl LocalApic

pub fn try_new<A>( pagectrl: &mut impl Map<Size4Kb, A>, frame_alloc: &A, ) -> Result<LocalApic, FeatureNotSupported>

where A: Alloc<Size4Kb>,

Try to construct a LocalApic.

Arguments

• pagectrl: a page mapper used to ensure that the local APIC’s memory-mapped register page is mapped and writable.
• frame_alloc: a frame allocator used to allocate page frame(s) while mapping the MMIO register page.

Returns

• Ok(LocalApic) if this CPU supports the APIC interrupt model.
• Err(FeatureNotSupported) if this CPU does not support APIC interrupt handling.

pub fn new<A>(pagectrl: &mut impl Map<Size4Kb, A>, frame_alloc: &A) -> LocalApic

where A: Alloc<Size4Kb>,

pub fn enable(&self, spurious_vector: u8)

pub fn calibrate_timer(&self, divisor: TimerDivisor)

pub fn version(&self) -> Version

Reads the local APIC’s version register.

The returned Version struct indicates the version of the local APIC, the maximum LVT entry index, and whether or not EOI suppression is supported.

pub fn interrupt_in( &self, duration: Duration, vector: u8, ) -> Result<(), TimerError>

pub fn start_periodic_timer( &self, interval: Duration, vector: u8, ) -> Result<(), TimerError>

pub unsafe fn end_interrupt(&self)

Sends an End of Interrupt (EOI) to the local APIC.

This should be called by an interrupt handler after handling a local APIC interrupt.

Safety

This should only be called when an interrupt has been triggered by this local APIC.

pub fn check_error(&self) -> Result<(), ErrorStatus>

Reads the error stauts register (ESR) of the local APIC.

Calling this method resets the value of the error status register. Any currently set error bits are cleared. If the same error bits are present in a subsequent call to LocalApic::check_error, they represent new instances of the same error.

Returns

If any error bits are set, this method returns Err(ErrorStatus). Otherwise, if no error bits are present, this method returns Ok().

Trait Implementations

impl Debug for LocalApic

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.