{"componentChunkName":"component---src-templates-post-template-js","path":"/unix-xv6-007-kernel-main-04-en","result":{"data":{"markdownRemark":{"id":"b0f87460-0d5b-5467-9bba-bcfb12604d0b","html":"
\n

This page has been machine-translated from the original page.

\n
\n

Inspired by An Introduction to OS Code Reading: Learning Kernel Internals with UNIX V6, I’m reading xv6 OS.

\n

Because UNIX V6 itself does not run on x86 CPUs, I decided to read the source of kash1064/xv6-public: xv6 OS, a fork of the xv6 OS repository that makes UNIX V6 run on the x86 architecture.

\n

In the previous article, I looked at how the mpinit function retrieves CPU information in a multiprocessor configuration.

\n

This time, I will trace the behavior of the lapicinit function.

\n\n

Table of Contents

\n\n

The lapicinit function

\n

This time I will start from lapicinit, the first function called in main.

\n

This function initializes the interrupt controller.

\n
lapicinit();     // interrupt controller
\n

The lapicinit function is defined in lapic.c as follows.

\n
void lapicinit(void)\n{\n  if(!lapic) return;\n\n  // Enable local APIC; set spurious interrupt vector.\n  lapicw(SVR, ENABLE | (T_IRQ0 + IRQ_SPURIOUS));\n\n  // The timer repeatedly counts down at bus frequency\n  // from lapic[TICR] and then issues an interrupt.\n  // If xv6 cared more about precise timekeeping,\n  // TICR would be calibrated using an external time source.\n  lapicw(TDCR, X1);\n  lapicw(TIMER, PERIODIC | (T_IRQ0 + IRQ_TIMER));\n  lapicw(TICR, 10000000);\n\n  // Disable logical interrupt lines.\n  lapicw(LINT0, MASKED);\n  lapicw(LINT1, MASKED);\n\n  // Disable performance counter overflow interrupts\n  // on machines that provide that interrupt entry.\n  if(((lapic[VER]>>16) & 0xFF) >= 4) lapicw(PCINT, MASKED);\n\n  // Map error interrupt to IRQ_ERROR.\n  lapicw(ERROR, T_IRQ0 + IRQ_ERROR);\n\n  // Clear error status register (requires back-to-back writes).\n  lapicw(ESR, 0);\n  lapicw(ESR, 0);\n\n  // Ack any outstanding interrupts.\n  lapicw(EOI, 0);\n\n  // Send an Init Level De-Assert to synchronise arbitration ID's.\n  lapicw(ICRHI, 0);\n  lapicw(ICRLO, BCAST | INIT | LEVEL);\n  while(lapic[ICRLO] & DELIVS)\n    ;\n\n  // Enable interrupts on the APIC (but not on the processor).\n  lapicw(TPR, 0);\n}
\n

The line if(!lapic) return; checks whether the global variable lapic holds a value.

\n

Local APIC registers

\n

The variable lapic had the address from lapicaddr inside the MP Floating Pointer Structure stored into it during the MP table retrieval covered in the previous article.

\n

Let’s confirm the actual value stored in this global variable using a debugger.

\n
$ b *0x801027a0\n$ continue
\n

After inspecting the contents of lapic, the address 0xfee00000 was stored there.

\n
$ info variables lapic\nFile lapic.c:\n44:volatile uint *lapic;\n\n$ p lapic\n$1 = (volatile uint *) 0xfee00000
\n

This lapic is the memory-mapped Local APIC register.

\n

The Local APIC register is 32-bit data that is memory-mapped at the address pointed to by the MP Configuration Table.

\n

Each 32-bit element at an offset aligned to a 16-byte boundary is set as a Local APIC register.

\n

The following page is helpful for further details.

\n

Reference: APIC - OSDev Wiki

\n

From here, we will configure the Local APIC registers.

\n

The following values defined in lapic.c are used for this purpose.

\n
// Local APIC registers, divided by 4 for use as uint[] indices.\n#define ID      (0x0020/4)   // ID\n#define VER     (0x0030/4)   // Version\n#define TPR     (0x0080/4)   // Task Priority\n#define EOI     (0x00B0/4)   // EOI\n#define SVR     (0x00F0/4)   // Spurious Interrupt Vector\n  #define ENABLE     0x00000100   // Unit Enable\n#define ESR     (0x0280/4)   // Error Status\n#define ICRLO   (0x0300/4)   // Interrupt Command\n  #define INIT       0x00000500   // INIT/RESET\n  #define STARTUP    0x00000600   // Startup IPI\n  #define DELIVS     0x00001000   // Delivery status\n  #define ASSERT     0x00004000   // Assert interrupt (vs deassert)\n  #define DEASSERT   0x00000000\n  #define LEVEL      0x00008000   // Level triggered\n  #define BCAST      0x00080000   // Send to all APICs, including self.\n  #define BUSY       0x00001000\n  #define FIXED      0x00000000\n#define ICRHI   (0x0310/4)   // Interrupt Command [63:32]\n#define TIMER   (0x0320/4)   // Local Vector Table 0 (TIMER)\n  #define X1         0x0000000B   // divide counts by 1\n  #define PERIODIC   0x00020000   // Periodic\n#define PCINT   (0x0340/4)   // Performance Counter LVT\n#define LINT0   (0x0350/4)   // Local Vector Table 1 (LINT0)\n#define LINT1   (0x0360/4)   // Local Vector Table 2 (LINT1)\n#define ERROR   (0x0370/4)   // Local Vector Table 3 (ERROR)\n  #define MASKED     0x00010000   // Interrupt masked\n#define TICR    (0x0380/4)   // Timer Initial Count\n#define TCCR    (0x0390/4)   // Timer Current Count\n#define TDCR    (0x03E0/4)   // Timer Divide Configuration
\n

Setting the Spurious Interrupt Vector and enabling the Local APIC

\n

Moving on.

\n

This line uses the lapicw function to set the Spurious Interrupt Vector and enable the Local APIC.

\n
// Enable local APIC; set spurious interrupt vector.\nlapicw(SVR, ENABLE | (T_IRQ0 + IRQ_SPURIOUS));
\n

The lapicw function, used frequently from here on, is defined as follows.

\n
static void\nlapicw(int index, int value)\n{\n  lapic[index] = value;\n  lapic[ID];  // wait for write to finish, by reading\n}
\n

It takes index and value as arguments and overwrites the corresponding lapic value.

\n

ID in lapic[ID] is defined as (0x0020/4) in lapic.c.

\n

lapic[ID]; does not change any settings; its purpose is to wait for the preceding lapic write to complete by reading this value.

\n

Let’s look at the line lapicw(SVR, ENABLE | (T_IRQ0 + IRQ_SPURIOUS));.

\n

The index is SVR.

\n

This refers to the offset (0x00F0/4) of the Spurious Interrupt Vector Register.

\n

As described in the following article, setting bit 8 (0x100) of the Spurious Interrupt Vector Register enables the APIC.

\n

Reference: APIC - OSDev Wiki

\n

Also, in order for the Local APIC to be able to receive interrupts, the Spurious Interrupt Vector must be set.

\n

The lower 8 bits of the Spurious Interrupt Vector Register are mapped to the IRQ number of the Spurious Interrupt Vector.

\n

Therefore, 0x13f, the OR of 0x100 and 0x3f, is set in the Spurious Interrupt Vector Register.

\n

This lower value 0x3f comes from the expression T_IRQ0 + IRQ_SPURIOUS.

\n

The values such as T_IRQ0 are defined in traps.h.

\n
// These are arbitrarily chosen, but with care not to overlap\n// processor defined exceptions or interrupt vectors.\n#define T_SYSCALL       64      // system call\n#define T_DEFAULT      500      // catchall\n\n#define T_IRQ0          32      // IRQ 0 corresponds to int T_IRQ\n\n#define IRQ_TIMER        0\n#define IRQ_KBD          1\n#define IRQ_COM1         4\n#define IRQ_IDE         14\n#define IRQ_ERROR       19\n#define IRQ_SPURIOUS    31
\n

According to the OSDev Wiki, the simplest value to set for the Spurious Interrupt Vector is 0xff, but xv6OS uses 0x1f.

\n

(I don’t really understand the reason for this…)

\n

Timer configuration

\n

Next are the following lines.

\n
// The timer repeatedly counts down at bus frequency\n// from lapic[TICR] and then issues an interrupt.\n// If xv6 cared more about precise timekeeping,\n// TICR would be calibrated using an external time source.\nlapicw(TDCR, X1);\nlapicw(TIMER, PERIODIC | (T_IRQ0 + IRQ_TIMER));\nlapicw(TICR, 10000000);
\n

TDCR is (0x03E0/4), which is the offset of the Divide Configuration Register (for Timer).

\n

This setting is used when configuring the Local APIC timer period.

\n

The Local APIC timer is a timer built into each processor’s Local APIC, and it generates interrupts only for that processor.

\n

The Local APIC timer starts from a value set by the kernel as the Timer Initial Count, decrements at a fixed interval, and fires an interrupt when it reaches 0.

\n

The decrement speed depends on the CPU’s bus frequency divided by the Timer Divide Configuration value.

\n

The Local APIC timer supports two modes: Periodic mode and One-shot mode.

\n

In Periodic mode, when the count reaches 0, it automatically resets to the initial value and begins counting down again.

\n

In One-shot mode, when the count reaches 0 and fires an interrupt, the count stays at 0 until the program explicitly sets a new initial value.

\n

Reference: APIC timer - OSDev Wiki

\n

Reference: Timer interrupt selected as Local APIC timer interrupt - ZDNet Japan

\n

In xv6OS, the Timer Divide Configuration value is set to 0x0000000B.

\n

\n \n \n \n \n \n \n \n \n

\n

Reference image: Intel SDM vol3

\n

Also, the Timer Initial Count is set to 10000000 by lapicw(TICR, 10000000);.

\n

Incidentally, the following line configures Local Vector Table 0 (TIMER).

\n
lapicw(TIMER, PERIODIC | (T_IRQ0 + IRQ_TIMER));
\n

The Local Vector Table (LVT) itself is a table in the Local APIC that maps events to interrupt vectors.

\n

Through the LVT, software can specify how local interrupts are sent to the CPU.

\n

\n \n \nlapicw(ICRHI, 0);\nlapicw(ICRLO, BCAST | INIT | LEVEL);\nwhile(lapic[ICRLO] & DELIVS);\n

Here, an INIT Level De-assert message is sent to all Local APICs in the system to synchronize and set their arbitration IDs.

\n

\n \n \n \n \n \n \n \n \n

\n

Reference image: Intel SDM vol3

\n

Finally, setting the TPR (Task Priority Register) to 0 allows the CPU to handle all interrupts, enabling the interrupt functionality.

\n
// Enable interrupts on the APIC (but not on the processor).\nlapicw(TPR, 0);
\n

Incidentally, setting the TPR to 15 disables all interrupts.

\n

Summary

\n

With this, all processing inside the lapicinit function called from main is complete.

\n

There were many parts I didn’t fully understand this time, so I plan to add notes as I figure things out.

\n

Next time: segment descriptors at last.

\n

It’s becoming more and more interesting as the inner workings of the kernel start to come into focus.

\n

Reference Books

\n","fields":{"slug":"/unix-xv6-007-kernel-main-04-en","tagSlugs":["/tag/unix-en/","/tag/xv-6-en/","/tag/kernel-en/","/tag/os-en/","/tag/english/"]},"frontmatter":{"date":"2022-02-02","description":"I am learning about kernels by reading the source code of the educational OS xv6OS. In this article, I walk through the behavior of the xv6OS kernel's main function.","tags":["Unix (en)","xv6 (en)","Kernel (en)","OS (en)","English"],"title":"Reading xv6OS Thoroughly to Fully Understand the Kernel - Local APIC Edition -","socialImage":{"publicURL":"/static/1333b4e4c7eb212c2c577464f891366f/unix-xv6-007-kernel-main-04.png"}}}},"pageContext":{"slug":"/unix-xv6-007-kernel-main-04-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}