#include <oskit/machine/page.h>

This file provides of following symbols, which define the architectural page size of the architecture for which the OSKit is configured:

PAGE_SIZE:

The number of bytes on each page. It can always be assumed to be a power of two.

PAGE_SHIFT:

The number of low address bits not translated by the MMU hardware. PAGE_SIZE is always 2^PAGE_SHIFT.

PAGE_MASK:

A bit mask with the low-order PAGE_SHIFT address bits set. Always equal to PAGE_SIZE - 1. WARNING: Some systems (like linux) define this to be  ~ (PAGE_SIZE - 1), be careful that the definitions match what the code expects!

In addition, the following macros are provided for convenience in performing page-related manipulations of addresses:

atop(addr ):

Converts a byte address into a page frame number, by dividing by PAGE_SIZE.

ptoa(page ):

Converts a page frame number into an integer (oskit_addr_t) byte address, by multiplying by PAGE_SIZE.

round_page(addr ):

Returns addr rounded up to the next higher page boundary. If addr is already on a page boundary, it is returned unchanged.

trunc_page(addr ):

Returns addr rounded down to the next lower page boundary. If addr is already on a page boundary, it is returned unchanged.

page_aligned(addr ):

Evaluates to true (nonzero) if addr is page aligned, or false (zero) if it isn’t.

Note that many modern architectures support multiple page sizes. On such architectures, the page size defined in this file is the minimum architectural page size, i.e., the finest granularity over which the MMU has control. Since there seems to be no sufficiently generic and useful way that this header file could provide symbols indicating which “other” page sizes the architecture supports, making good use of larger pages probably must be done in machine-dependent code.

Some operating systems on some architectures do not actually support the minimum architectural page size in software; instead, they aggregate multiple architectural pages together into larger “logical pages” managed by the OS software. On such operating systems, it would be inappropriate for general OS or application code to use the PAGE_SIZE value provided by oskit/page.h, since this value would be smaller (more fine-grained) than the OS software actually supports, and therefore inappropriate. However, this is purely a high-level OS issue; like other parts of the toolkit, no one is required to use this header file if it is inappropriate in a particular situation.

This file was originally derived from Mach’s vm_param.h.

#include <oskit/machine/spin_lock.h>

This file provides the architecture-dependent definition of the spin_lock_t “spin lock” data type and associated manipulation macros. This facility provides a basic locking mechanism which can be used with preemptive threading or on a multi-processor.

spin_lock_t:

Typedef for the spin lock data type.

spin_lock_init(s ):

Initialize a spin lock.

spin_lock_locked(s ):

Check if a spin lock is locked.

spin_unlock(s ):

Unlock a spin lock.

spin_try_lock(s ):

Attempt to lock a spin lock. Returns 0 if successful, nonzero if unsuccessful.

spin_lock(s ):

Busy wait until the lock is free. On return the lock has been acquired.

This header file is taken from CMU’s Mach kernel.

#include <oskit/queue.h>

struct queue_entry {

typedef struct queue_entry *queue_t;
typedef struct queue_entry queue_head_t;
typedef struct queue_entry queue_chain_t;
typedef struct queue_entry *queue_entry_t;

Macros and structures for implementation of a “queue” data type. The implementation uses a doubly-linked list and supports operations to insert and delete anywhere in the list.

queue_init(q ):

Initialize the given queue.

queue_first(q ):

Returns the first entry in the queue.

queue_next(q ):

Returns the entry after an item in the queue.

queue_last(q ):

Returns the last entry in the queue.

queue_prev(q ):

Returns the entry before an item in the queue.

queue_end(q, qe ):

Tests whether a new entry is really the end of the queue.

queue_empty(q ):

Tests whether a queue is empty.

queue_enter(q, elt, type, field ):

Insert a new element at the tail of the queue.

queue_enter_first(head, elt, type, field ):

Insert a new element at the head of the queue.

queue_enter_before(head, nelt, elt, type, field ):

Insert a new element before the indicated element.

queue_enter_after(head, pelt, elt, type, field ):

Insert a new element after the indicated element.

queue_remove(head, elt, type, field ):

Remove an arbitrary item from the queue.

queue_remove_first(head, entry, type, field ):

Remove and return the entry at the head of the queue.

queue_remove_last(head, entry, type, field ):

Remove and return the entry at the tail of the queue.

queue_assign(to, from, type, field ):

Move an element in a queue to a new piece of memory.

queue_iterate(head, elt, type, field ):

Iterate over each item in the queue. Generates a ‘for’ loop, setting elt to each item in turn (by reference).

This header file is taken from CMU’s Mach kernel.

#include <oskit/debug.h>

This file contains simple macros and functions to assist in debugging. Many of these facilities are intended to be used to “annotate” programs permanently or semi-permanently in ways that reflect the code’s proper or desired behavior. These facilities typically change their behavior depending on whether the preprocessor symbol DEBUG is defined: if it is defined, then extra code is introduced to check invariants and such; when DEBUG is not defined, all of this debugging code is “compiled out” so that it does not result in any size increase or efficiency loss in the resulting compiled code.

The following macros and functions are intended to be used as permanent- or semi-permanent annotations to be sprinkled throughout ordinary code to increase its robustness and clarify its invariants and assumptions to human readers:

assert(cond ):

This is a standard assert macro, like (and compatible with) the one provided in oskit/c/assert.h. If DEBUG is defined, this macro produces code that evaluates cond and calls panic (see Section 14.8.3) if the result is false (zero). When an assertion fails and causes a panic, the resulting message includes the source file name and line number of the assertion that failed, as well as the text of the cond expression used in the assertion. If DEBUG is not defined, this macro evaluates to nothing (an empty statement), generating no code.

Assertions are typically used to codify assumptions made by a code sequence, e.g., about the parameters to a function or the conditions on entry to or exit from a loop. By placing explicit assert statements in well-chosen locations to verify that the code’s invariants indeed hold, a thicker “safety net” is woven into the code, which tends to make bugs manifest themselves earlier and in much more obvious ways, rather than allowing incorrect results to “trickle” through the program’s execution for a long time, sometimes resulting in completely baffling behavior. Assertions can also act as a form of documentation, clearly describing to human readers the exact requirements and assumptions in a piece of code.

otsan():

If DEBUG is defined, this macro unconditionally causes a panic with the message “off the straight and narrow!,” along with the source file name and line number, if it is ever executed. It is intended to be placed at code locations that should never be reached if the code is functioning properly; e.g., as the default case of a switch statement for which the result of the conditional expression should always match one of the explicit case values. If DEBUG is not defined, this macro evaluates to nothing.

do_debug(stmt ):

If DEBUG is defined, this macro evaluates to stmt; otherwise it evaluates to nothing. This macro is useful in situations where an #ifdef DEBUG ... #endif block would otherwise be used over just a few lines of code or a single statement: it produces the same effect, but is smaller and less visually intrusive.

The following macros and functions are primarily intended to be used as temporary scaffolding during debugging, and removed from production code:

void dump_stack_trace(void):

This function dumps a human-readable backtrace of the current function call stack to the console, using printf. The exact content and format of the printed data is architecture-specific; however, the output is typically a list of instruction pointer or program counter values, each pointing into a function on the call stack, presumably to the return point after the function call to the next level. You can find out what function these addresses reside in by running the Unix nm utility on the appropriate executable file image, sorting the resulting symbol list if necessary, and looking up the address in the sorted list. Alternatively, for more precise details, you can look up the exact instruction addresses in a disassembly of the executable file, e.g., by using GNU objdump with the ‘-d’ option.

here():

This macro generates code that simply prints the source file name and line number at which the macro was used. This macro can be extremely useful when trying to nail down the precise time or code location at which a particular bug manifests itself, or to determine the sequence of events leading up to it. By sprinkling around calls to the here macro in appropriate places, the program will dump regular status reports of its location every time it hits one of these macros, effectively producing a log of “interesting” events (“interesting” being defined according to the placement of the here macro invocations). Using the here macro this way is equivalent to the common practice of sprinkling printf’s around and watching the output, except it is easier because the here invocation in each place does not have to be “tailored” to make it distinguishable from the other locations: each use of the here macro is self-identifying.

If DEBUG is not defined, the here macro is not defined at all; this makes it obvious when you’ve accidentally left invocations of this macro in a piece of code after it has been debugged.

debugmsg(printfargs ):

This macro is similar to here, except it allows a formatted message to be printed along with the source file name and line number. printfargs is a complete set of arguments to be passed to the printf function, including parentheses: for example, ‘debugmsg(("foo is %d", foo));’. A newline is automatically appended to the end of the message. This macro is generally useful as a wrapper for printf for printing temporary run-time status messages during execution of a program being debugged.

As with here, if DEBUG is not defined, the debugmsg macro is not defined at all, in order to make it obvious if any invocations are accidentally left in production code.

Note that only panic and dump_stack_trace are real functions; the others are simply macros.

#include <oskit/base_critical.h>

void base_critical_enter(void);

void base_critical_leave(void);

Functions to implements a simple “global critical region.” These functions are used throughout the OSKit to ensure proper serialization for various “touchy” but non-performance critical activities such as panicing, rebooting, debugging, etc. This critical region can safely be entered recursively; the only requirement is that enters match exactly with leaves.

The implementation of this module is machine-dependent, and generally disables interrupts and, on multiprocessors, grabs a recursive spin lock.

#include <oskit/x86/asm.h>

This file contains convenience macros useful when writing x86 assembly language code in AT&T/GAS syntax. This header file is directly derived from Mach, and similar headers are used in various BSD kernels.

Symbol name extension: The following macros allow assembly language code to be written that coexists with C code compiled for either ELF or a.out format. In a.out format, by convention an underscore (_) is prefixed to each public symbol referenced or defined by the C compiler; however, the underscore prefix is not used in ELF format.

EXT(name ):

Evaluates to _name in a.out format, or just name in ELF. This macro is typically used when referring to public symbols defined in C code.

LEXT(name ):

Evaluates to _name : in a.out format, or name : in ELF. This macro is generally used when defining labels to be exported to C code.

SEXT(name ):

Evaluates to the string literal "_name " in a.out format, or "name " in ELF. This macro can be used in GCC inline assembly code, where the code is contained in a string constant; for example: asm("...; call "SEXT(foo)"; ...");

Alignment: The following macros relate to alignment of code and data:

TEXT_ALIGN:

Evaluates to the preferred alignment of instruction entrypoints (e.g., functions or branch targets), as a power of two. Currently evaluates to 4 (16-byte alignment) if the symbol i486 is defined, or 2 (4-byte alignment) otherwise.

ALIGN:

A synonym for TEXT_ALIGN.

DATA_ALIGN:

Evaluates to the preferred minimum alignment of data structures. Currently it is always defined as 2, although in some cases a larger value may be preferable, such as the processor’s cache line size.

P2ALIGN(alignment ):

Assembly language code can use this macro to work around the fact that the .align directive works differently in different x86 environments: sometimes .align takes a byte count, whereas other times it takes a power of two (bit count). The P2ALIGN macro always takes a power of two: for example, P2ALIGN(2) means 4-byte alignment. By default, the P2ALIGN macro uses the .p2align directive supported by GAS; if a different assembler is being used, then P2ALIGN should be redefined as either .align alignment or .align 1<<(alignment ), depending on the assembler’s interpretation of .align.

XXX S_ARG, B_ARG, frame stuff, . . .

XXX need to make the macros more easily overridable, using ifdefs.

XXX need to clean out old trash still in the header file

XXX IODELAY macro

#include <oskit/x86/eflags.h>

XXX

This header file can be used in assembly language code as well as C. The flags defined here correspond the the ones in the processor databooks.

EFL_CF:

carry

EFL_PF:

parity of low 8 bits

EFL_AF:

carry out of bit 3

EFL_ZF:

zero

EFL_SF:

sign

EFL_TF:

trace trap

EFL_IF:

interrupt enable

EFL_DF:

direction

EFL_OF:

overflow

EFL_IOPL:

IO privilege level mask. All 0’s is the same as EFL_IOPL_KERNEL, while all 1’s (or just EFL_IOPL) is the same as EFL_IOPL_USER.

EFL_NT:

nested task

EFL_RF:

resume without tracing

EFL_VM:

virtual 8086 mode

EFL_AC:

alignment check

EFL_VIF:

virtual interrupt flag

EFL_VIP:

virtual interrupt pending

EFL_ID:

CPUID instruction support

#include <oskit/x86/proc_reg.h>

XXX

This header file contains the definitions for the processor’s control registers (CR0, CR4). It also contains macros for getting and setting the processor registers and flags. There is also a macro for reading the processor’s cycle counter (on Pentium and above processors).

This header file is taken from CMU’s Mach kernel.

#include <oskit/x86/debug_reg.h>

This provides the definitions for the processor’s built-in debug registers. There are also inline functions that allow the hardware-assisted breakpoints to be set.

DR0 through DR3 are the breakpoint address registers; DR6 is the status register, and DR7 is the control register.

get_dr0():

Returns the value in breakpoint address register 0.

get_dr1():

Returns the value in breakpoint address register 1.

get_dr2():

Returns the value in breakpoint address register 2.

get_dr3():

Returns the value in breakpoint address register 3.

get_dr6():

Returns the value in the debug status register.

get_dr7():

Returns the value in the debug control register.

set_dr0(val ):

Sets the value in breakpoint address register 0 to val.

set_dr1(val ):

Sets the value in breakpoint address register 1 to val.

set_dr2(val ):

Sets the value in breakpoint address register 2 to val.

set_dr3(val ):

Sets the value in breakpoint address register 3 to val.

set_dr6(val ):

Sets the value in the debug status register to val.

set_dr7(val ):

Sets the value in the debug control register to val.

set_b0(unsigned addr, unsigned len, unsigned rw ):

Enables breakpoint register 0. Sets dr0 to LINEAR address addr and updates dr7 to enable it. rw must be DR7_RW_INST, DR7_RW_WRITE, DR7_RW_IO, or DR7_RW_DATA indicating the condition to break on. len must be DR7_LEN_1, DR7_LEN_2, or DR7_LEN_4, indicating how many bytes are covered by the register.

set_b1(unsigned addr, unsigned len, unsigned rw ):

Enables breakpoint register 1.

set_b2(unsigned addr, unsigned len, unsigned rw ):

Enables breakpoint register 2.

set_b3(unsigned addr, unsigned len, unsigned rw ):

Enables breakpoint register 3.

#include <oskit/x86/fp_reg.h>

XXX

This file contains the structure definition for saving the floating-point state and then restoring it. It also contains definitions for the x87 control and status registers.

This header file is taken from CMU’s Mach kernel.

#include <oskit/x86/far_ptr.h>

This contains struct definitions for creating “far pointers.” Far pointers on the x86 are those that take an explicit segment in addition to the offset value.

struct far_pointer_16:

16-bit pointer structure which contains a 16-bit segment and a 16-bit offset. The address is computed as segment ¡¡ 4 + offset.

struct far_pointer_32:

48-bit pointer which contains a 32-bit offset and a 16-bit segment descriptor. Segmentation is used to determine what linear address is generated by these pointers.

#include <oskit/x86/pio.h>

These are macros for accessing IO-space directly on the x86. These instructions will generate traps if executed in user-mode without permissions (either IOPL in the eflags register or access via the io-bitmap in the tss).

iodelay():

A macro used to delay the processor for a short period of time, generally to wait until programmed io can complete. The actual amount of time is indeterminate, since the delay is accomplished by doing an inb from a nonexistent port, which depends on the processor and chipset.¹ The nominal delay value is 1uS for most machines.

inl(port ):

Returns 32-bit value from port

inw(port ):

Returns 16-bit value from port

inb(port ):

Returns 8-bit value from port

inl_p(port ):

inl followed immediately by iodelay

inw_p(port ):

inw followed immediately by iodelay

inb_p(port ):

inb followed immediately by iodelay

outl(port, val ):

Send 32-bit val out port.

outw(port, val ):

Send 16-bit val out port.

outb(port, val ):

Send 8-bit val out port.

outl_p(port ):

outl followed immediately by iodelay

outw_p(port ):

outw followed immediately by iodelay

outb_p(port ):

outb followed immediately by iodelay

The above macros have versions that begin with i16_, which are defined to be the same. It may be desirable to use the i16_ versions in 16-bit code in place of the normal macros for clarity.

This header file is taken from CMU’s Mach kernel.

#include <oskit/x86/seg.h>

XXX

struct x86_desc:

Normal segment descriptors.

struct x86_gate:

Trap, interrupt, and call gates.

struct pseudo_descriptor:

Used to load the IDT and GDT (and LDT).

sel_idx(sel):

Converts the selector into an index in the descriptor table.

ISPL(s):

Returns the selector’s privilege level.

USERMODE(s, f):

KERNELMODE(s, f):

fill_descriptor(struct x86_desc *desc, unsigned base, unsigned limit, unsigned char access, unsigned char sizebits):

Fill a segment descriptor.

fill_descriptor_base(struct x86_desc *desc, unsigned base):

Set the base address in a segment descriptor.

fill_descriptor_limit(struct x86_desc *desc, unsigned limit):

Set the limit in a segment descriptor.

fill_gate(struct x86_gate *gate, unsigned offset, unsigned short selector, unsigned char access, unsigned char word_count):

Fill an x86 gate descriptor.

This header file is based on a file in CMU’s Mach kernel.

#include <oskit/x86/gate_init.h>

This file contains the C structures and assembly-language macro definitions used to build x86 gate descriptor tables suitable for use by gate_init (see Section 15.5.10).

struct gate_init_entry:

C structure describing a gate descriptor.

GATE_INITTAB_BEGIN(name):

Starts assembly-language definition of a gate descriptor table.

GATE_ENTRY(n, entry, type):

Initializes an element of a gate descriptor table.

GATE_INITTAB_END:

Defines the end of a gate descriptor table.

The assembly-language macros are designed to be used while writing trap entrypoint routines. See oskit/libkern/x86/base_trap_inittab.S for example code that uses this facility.

#include <oskit/x86/trap.h>

XXX

This contains the definitions for the trap numbers returned by the processor when something goes ‘wrong’. These can be used to determine the cause of the trap.

T_DIVIDE_ERROR:

T_DEBUG:

T_NMI:

non-maskable interrupt

T_INT3:

T_OVERFLOW:

overflow test

T_OUT_OF_BOUNDS:

bounds check

T_INVALID_OPCODE:

T_NO_FPU:

T_DOUBLE_FAULT:

T_FPU_FAULT:

T_INVALID_TSS:

T_SEGMENT_NOT_PRESENT:

T_STACK_FAULT:

T_GENERAL_PROTECTION:

T_PAGE_FAULT:

T_PF_PROT: protection violation; T_PF_WRITE: write access; T_PF_USER: from user state

T_FLOATING_POINT_ERROR:

T_ALIGNMENT_CHECK:

T_MACHINE_CHECK:

This header file is taken from CMU’s Mach kernel.

XXX

This header file is derived from Mach’s intel/pmap.h.

#include <oskit/x86/tss.h>

         struct x86_tss {
                 int     back_link;      /* previous task's segment, if nested */
                 int     esp0;           /* initial stack pointer ... */
                 int     ss0;            /* and segment for ring 0 */
                 int     esp1;           /* initial stack pointer ... */
                 int     ss1;            /* and segment for ring 1 */
                 int     esp2;           /* initial stack pointer ... */
                 int     ss2;            /* and segment for ring 2 */
                 int     cr3;            /* CR3 - page table physical address */
                 int     eip;            /* eip */
                 int     eflags;         /* eflags */
                 int     eax;            /* eax */
                 int     ecx;            /* ecx */
                 int     edx;            /* edx */
                 int     ebx;            /* ebx */
                 int     esp;            /* current stack pointer (ring 3) */
                 int     ebp;            /* ebp */
                 int     esi;            /* esi */
                 int     edi;            /* edi */
                 int     es;             /* es */
                 int     cs;             /* cs */
                 int     ss;             /* current stack segment (ring 3) */
                 int     ds;             /* ds */
                 int     fs;             /* fs */
                 int     gs;             /* gs */
                 int     ldt;            /* local descriptor table segment */
                 unsigned short  trace_trap;     /* trap on switch to task */
                 unsigned short  io_bit_map_offset; /* offset to IO perm bitmap */
         };
         

XXX

XXX only the 32-bit version

This contains the definition of a 32-bit tss. The tss used by the 80286 is incompatible with this.

This header file is taken from CMU’s Mach kernel.

#include <oskit/x86/pc/irq_list.h>

XXX

Many of the interrupt vectors have pre-defined uses. The rest of them can be assigned to ISA, PCI, or other devices. This file contains the ‘defined’ interrupt usages.

#include <oskit/x86/pc/pic.h>

XXX

This contains definitions for the 8259(A) Programmable Interrupt Controller (PIC). In addition to numerous constants, it also contains the prototypes for several functions and macros.

pic_init(unsigned char master_base, unsigned char slave_base):

MASTER_PIC_BASE and SLAVES_PIC_BASE are also defined, and may be passed in as parameters.

pic_disable_irq(unsigned char irq):

pic_enable_irq(unsigned char irq):

pic_test_irq(unsigned char irq):

pic_enable_all:

pic_disable_all:

pic_ack(irq):

#include <oskit/x86/pc/keyboard.h>

XXX

This header file contains the register definitions for the PC keyboard. The port addresses are defined, along with the status and control bits. This would be used by a keyboard device driver, or someone manipulating they keyboard directly. (ie, to turn on and off the keyboard LEDs).

This header file is taken from CMU’s Mach kernel.

#include <oskit/x86/pc/rtc.h>

This file is taken from FreeBSD (XXX cite?) and contains definitions for the standard NVRAM, or Real Time Clock, register locations.

rtcin(unsigned char addr):

Returns the 8-bit value from location addr.

rtcout(unsigned char addr, unsigned char val):

Writes val to location addr.

#include <oskit/x86/cpuid.h>

struct cpu_info {

This structure is used to hold identification information about x86 processors, such as information returned by the CPUID instruction. The cpuid toolkit function, described below, fills in an instance of this structure with information about the current processor.

Note that it is expected that the cpu_info structure will continue to grow in the future as new x86-architecture processors are released, so client code should not depend on this structure in ways that will break if the structure’s size changes.

The family field describes the processor family:

CPU_FAMILY_386:

A 386-class processor.

CPU_FAMILY_486:

A 486-class processor.

CPU_FAMILY_PENTIUM:

A Pentium-class (“586”) processor.

CPU_FAMILY_PENTIUM_PRO:

A Pentium Pro-class (“686”) processor.

The type field is one of the following:

CPU_TYPE_ORIGINAL:

Original OEM processor.

CPU_TYPE_OVERDRIVE:

OverDrive upgrade processor.

CPU_TYPE_DUAL:

Dual processor.

The feature_flags field is a bit field containing the following bits:

CPUF_ON_CHIP_FPU:

Set if the CPU has a built-in floating point unit.

CPUF_VM86_EXT:

Set if the virtual 8086 mode extensions are supported, i.e., the VIF and VIP flags register bits, and the VME and PVI bits in CR4.

CPUF_IO_BKPTS:

Set if I/O breakpoints are supported, i.e., the DR7_RW_IO mode defined in x86/debug_reg.h.

CPUF_4MB_PAGES:

Set if 4MB superpages are supported, i.e., the INTEL_PDE_SUPERPAGE page directory entry bit defined in x86/paging.h.

CPUF_TS_COUNTER:

Set if the on-chip timestamp counter and the RDTSC instruction are available.

CPUF_PENTIUM_MSR:

Set if the Pentium model specific registers are available.

CPUF_PAGE_ADDR_EXT:

Set if the Pentium Pro’s page addressing extensions (36-bit physical addresses and 2MB pages) are available.

CPUF_MACHINE_CHECK_EXCP:

Set if the processor supports the Machine Check exception (vector 18, or T_MACHINE_CHECK in x86/trap.h).

CPUF_CMPXCHG8B:

Set if the processor supports the CMPXCHG8B instruction (also known as “double-compare-and-swap”).

CPUF_LOCAL_APIC:

Set if the processor has a built-in local APIC (Advanced Programmable Interrupt Controller), for symmetric multiprocessor support.

CPUF_MEM_RANGE_REGS:

Set if the processor supports the memory type range registers.

CPUF_PAGE_GLOBAL_EXT:

Set if the processor supports the global global paging extensions, i.e., the INTEL_PDE_GLOBAL page table entry bit defined in x86/paging.h.

CPUF_MACHINE_CHECK_ARCH:

Set if the processor supports Intel’s machine check architecture and the MCG_CAP model-specific register.

CPUF_CMOVCC:

Set if the processor supports the CMOVcc instructions.

The cpuid.h header file also contains symbolic definitions for other constants such as the cache configuration descriptor values; see the header file and the Intel documentation for details on these.

#include <oskit/x86/cpuid.h>

void cpuid([out] struct cpu_info *out_info);

This function identifies the CPU on which it is running using Intel’s recommended CPU identification procedure, and fills in the supplied structure with the information found.

Note that since the cpuid function is 32-bit code, it wouldn’t run on anything less than an 80386 in the first place; therefore it doesn’t bother to check for earlier processors.

out_info:

The CPU information structure to fill in.

#include <oskit/x86/cpuid.h>

void cpu_info_format(struct cpu_info *info, void (*formatter)(void *data, const char *fmt, ...), void *data);

This function takes the information in a cpu_info structure and formats it as human-readable text. The formatter should be a pointer to a printf-like function to be called to format the output data. The formatter function may be called multiple times to output all the relevant information.

info:

The filled-in CPU information structure to output.

formatter:

The printf-style formatted output function to call. It will be called with the opaque data pointer provided, a standard C format string (fmt), and optionally a set of data items to format.

data:

An opaque pointer which is simply passed on to the formatter function.

#include <oskit/x86/cpuid.h>

void cpu_info_min(struct cpu_info *id1, struct cpu_info *id2);

Determine the minimum (least-common-denominator) feature set of the two provided structures and return that. The new feature set is returned in id1.

Typically used on SMP systems to determine the basic feature set common across all processors in the system regardless of type.

id1, id2:

The CPU information structures to compare.

#include <oskit/x86/cpuid.h>

void cpu_info_dump(struct cpu_info *info);

This function is merely a convenient front-end to cpu_info_format; it simply formats the CPU information and outputs it to the console using printf.

#include <oskit/x86/pmode.h>

void i16_enter_pmode(int prot_cs);

This 16-bit function switches the processor into protected mode by turning on the Protection Enable (PE) bit in CR0. The instruction that sets the PE bit is followed immediately by a jump instruction to flush the prefetch buffer, as recommended by Intel documentation.

The function also initializes the CS register with the appropriate new protected-mode code segment, whose selector is specified in the prot_cs parameter. The prot_cs must evaluate to a constant, as it is used as an immediate operand in an inline assembly language code fragment.

This routine does not perform any of the other steps in Intel’s recommended mode switching procedure, such as setting up the GDT or reinitializing the data segment registers; these steps must be performed separately. The overall mode switching sequence is necessarily much more dependent on various OS-specific factors such as the layout of the GDT; therefore the OSKit does not attempt to provide a “generic” function to perform the entire switch. Instead, the full switching sequence is provided as part of the base environment setup code; see Section 15.10 for more details.

#include <oskit/x86/pmode.h>

void i16_leave_pmode(int real_cs);

This 16-bit function switches the processor out of protected mode and back into real mode by turning off the Protection Enable (PE) bit in CR0. The instruction that clears the PE bit is followed immediately by a jump instruction to flush the prefetch buffer, as recommended by Intel documentation. At the same time, this function also initializes the CS register with the appropriate real-mode code segment, specified by the real_cs parameter.

This routine does not perform any of the other steps in Intel’s recommended mode switching procedure, such as reinitializing the data segment registers; these steps must be performed separately. See Section 15.10 for information on the full mode switch implementation provided by the base environment.

#include <oskit/x86/paging.h>

void paging_enable(oskit_addr_t pdir);

Loads the processor page directory using pdir and turns on paging.

The caller must already have created and initialized an appropriate initial page directory as described in Intel documentation. The OSKit provides convenient facilities that can be used to create x86 page directories and page tables; for more information, see Section 15.9.

This function assumes that pdir equivalently maps the physical memory that contains the currently executing code, the currently loaded GDT and IDT.

#include <oskit/x86/paging.h>

void paging_disable(void);

Turns paging off and flushes the TLB.

This function assumes that the currently loaded page directory equivalently maps the physical memory that contains the currently executing code, the currently loaded GDT and IDT.

#include <oskit/x86/gate_init.h>

void gate_init(struct x86_gate *dest, const struct gate_init_entry *src, unsigned entry_cs);

Install entries in a processor descriptor table from the specified array of gate descriptors (see Section 15.3.9). Typically used to initialize the processor IDT with trap and interrupt vectors (see Section 15.7.4).

dest:

Pointer to the x86 descriptor table to fill in.

src:

Pointer to the gate_init_entry array to copy from.

entry_cs:

Code segment selector to associate with all entries.

fill_gate:

§ 15.3.8

#include <oskit/machine/base_vm.h>

This header file provides generic virtual memory-related definitions commonly used throughout the base environment, which apply to both segmentation and paging. In particular, this file defines a set of macros and global variables which allow the rest of the base environment code in the toolkit (and the client OS, if it chooses) to maintain independence from the memory model in effect. These facilities allow code to avoid various assumptions about the relationships between kernel virtual addresses, linear addresses, and physical addresses.

The following variable and associated macros are provided to convert between linear and kernel virtual addresses.

linear_base_va:

This global variable defines the address in kernel virtual memory that corresponds to address 0 in linear memory. It is used by the following conversion macros; therefore, changing this variable changes the behavior of the associated macros.

lintokv(la ):

This macro converts linear address la into a kernel virtual address and returns the result as an oskit_addr_t.

kvtolin(va ):

For example, the segmentation initialization code uses kvtolin() to calculate the linear addresses of segmentation structures to be used in segment descriptor or pseudo-descriptor structures provided to the processor.

Similarly, the following variable and associated macros convert between physical and kernel virtual addresses. (Conversions between linear and physical addresses can be done by combining the two sets of macros.)

phys_mem_va:

This global variable defines the address in kernel virtual memory that corresponds to address 0 in physical memory. It is used by the following conversion macros; therefore, changing this variable changes the behavior of the associated macros.

phystokv(pa ):

This macro converts physical address pa into a kernel virtual address and returns the result as an oskit_addr_t. The macro makes the assumption that the specified physical address can be converted to a kernel virtual address this way: in OS kernels that do not direct-map all physical memory into the kernel’s virtual address space, the caller must ensure that the supplied pa refers to a physical address that is mapped. For example, the primitive page table management code provided by the OSKit’s base environment uses this macro to access page table entries given the physical address of the page table; therefore, these functions can only be used if page tables are allocated from physical pages that are direct-mapped into the kernel’s address space.

kvtophys(va ):

This macro converts kernel virtual address va into a physical address and returns the result as an oskit_addr_t. The macro assumes that the virtual address can be converted directly to a physical address this way; the caller must ensure that this is the case. For example, some operating systems only direct-map the kernel’s code and statically allocated data; in such kernels, va should only refer to statically-allocated variables or data structures. This is generally sufficient for the OSKit’s base environment code, which mostly operates on statically-allocated data structures; however, the OS must of course take its chosen memory model into consideration if it uses these macros as well.

XXX real_cs

Note that there is nothing in this header file that defines or relates to “user-mode” address spaces. This is because the base environment code in the OSKit is not concerned with user mode in any way; in fact, it doesn’t even care whether or not the OS kernel implements user address spaces at all. For example, boot loaders or unprotected real-time kernels built using the OSKit probably do not need any notion of user mode at all.

#include <oskit/machine/base_cpu.h>

void base_cpu_setup(void);

This function provides a single entrypoint to initialize and activate all of the processor structures necessary for ordinary execution. This includes identifying the CPU, and initializing and activating the base GDT, IDT, and TSS, and reloading all segment registers as recommended by Intel. The call returns with the CS segment set to KERNEL_CS (the default kernel code segment; see 15.7.1 for details), DS, ES, and SS set to KERNEL_DS (the default kernel data segment), and FS and GS set to 0. After the base_cpu_setup call completes, a full working kernel environment is in place: segment registers can be loaded, interrupts and traps can be fielded by the OS, privilege level changes can occur, etc.

This function does not initialize or activate the processor’s paging mechanism, since unlike the other mechanisms, paging is optional on the x86 and not needed in some environments (e.g., boot loaders or embedded kernels).

The base_cpu_setup function is actually just a simple wrapper that calls base_cpu_init followed by base_cpu_load.

Note that it is permissible to call this function (and/or the more primitive functions it is built on) more than once. This is particularly useful when reconfiguring the kernel memory map. For example, a typical MultiBoot (or other 32-bit) kernel generally starts out with paging disabled, so it must run in the low range of linear/physical memory. However, after enabling page translation, the OS may later want to relocate itself to run at a higher address in linear memory so that application programs can use the low part (e.g., v86-mode programs). An easy way to do this with the OSKit is to call base_cpu_setup once at the very beginning, to initialize the basic unpaged kernel environment, and then later, after paging is enabled and appropriate mappings have been established in high linear address space, modify the linear_base_va variable (Section 15.6.2) to reflect the kernel’s new linear address base, and finally call base_cpu_setup again to reinitialize and reload the processor tables according to the new memory map.

base_cpu_init:

§ 15.6.4

base_cpu_load:

§ 15.6.5

#include <oskit/machine/base_cpu.h>

void base_cpu_init(void);

This function initializes all of the critical data structures used by the base environment, including base_cpuid, base_idt, base_gdt, and base_tss, but does not actually activate them or otherwise modify the processor’s execution state. The base_cpu_load function must be called later to initialize the processor with these structures. Separate initialization and activation functions are provided to allow the OS to customize the processor data structures if necessary before activating them.

cpuid:

§ 15.5.2

base_trap_init:

§ 15.8.2

base_gdt_init:

§ 15.7.2

base_tss_init:

§ 15.7.7

#include <oskit/machine/base_cpu.h>

void base_cpu_load(void);

This function loads the critical base environment data structures (in particular, the GDT, IDT, and TSS) into the processor, and reinitializes all segment registers from the new GDT as recommended in Intel processor documentation. The structures must already have been set up by a call to base_cpu_init and/or custom initialization code in the client OS.

This function returns with the CS segment set to KERNEL_CS (the default kernel code segment; see Section 15.7.1 for details), DS, ES, and SS set to KERNEL_DS (the default kernel data segment), and FS and GS set to 0. After the base_cpu_load call completes, a full working kernel environment is in place: segment registers can be loaded, interrupts and traps can be fielded by the OS, privilege level changes can occur, etc.

base_gdt_load:

§ 15.7.3

base_idt_load:

§ 15.7.5

base_tss_load:

§ 15.7.8

#include <oskit/machine/base_cpu.h>

extern struct cpu_info base_cpuid;

This is a global variable that is filled in by base_cpu_init with information about the processor on which base_cpu_init was called. (Alternatively, it can also be initialized manually by the OS simply by calling cpuid(&base_cpuid)). This structure is used by other parts of the kernel support library to determine whether or not certain processor features are available, such as 4MB superpages. See 15.5.1 for details on the contents of this structure.

Note that in a multiprocessor system, this variable will reflect the boot processor. This is generally not a problem, since most SMPs use identical processors, or at least processors in the same generation, so that they appear equivalent to OS software. (For example, it is very unlikely that you’d find an SMP that mixes 486 and Pentium processors), However, if this ever turns out to be a problem, the OS can always override the cpuid or base_cpu_init function, or just modify the contents of the base_cpuid variable after calling base_cpu_init so that it reflects the least common denominator of all the processors.

#include <oskit/machine/base_stack.h>

Definitions related to the default kernel stack.

BASE_STACK_SIZE:

Preprocessor constant defining the size in bytes of the default kernel stack.

base_stack_start:

C external variable declaration for the low-address end of the stack. On the x86, this is the end toward which the stack grows.

base_stack_end:

C external variable declaration for the high-address end of the stack (base_stack_start + BASE_STACK_SIZE). On the x86, this is the end where the stack begins.

This header file can be used in assembly language code as well as C.

#include <oskit/x86/base_gdt.h>

extern struct x86_desc base_gdt[GDTSZ];

This variable is used in the base environment as the default global descriptor table. The default base_gdt definition contains GDTSZ selector slots, including the Intel-reserved, permanently unused slot 0.

The following symbols are defined in base_gdt.h to be segment selectors for the descriptors in the base GDT. These selectors can be converted to indices into the GDT descriptor array base_gdt by dividing by 8 (the processor reserves the low three bits of all selectors for other information).

BASE_TSS:

A selector for the base task state segment (base_tss). The BASE_TSS segment descriptor is initialized by base_gdt_init, but the base_tss structure itself is initialized by base_tss_init and loaded into the processor by base_tss_load; see Section 15.7.6 for more details.

KERNEL_CS:

This is the default kernel code segment selector. It is initialized by base_gdt_init to be a flat-model, 4GB, readable, ring 0 code segment; base_gdt_load loads this segment into the CS register while reinitializing the processor’s segment registers.

KERNEL_DS:

This is the default kernel data segment selector. It is initialized by base_gdt_init to be a flat-model, 4GB, writable, ring 0 data segment; base_gdt_load loads this segment into the DS, ES, and SS registers while reinitializing the processor’s segment registers.

KERNEL_16_CS:

This selector is identical to KERNEL_CS except that it is a 16-bit code segment (the processor defaults to 16-bit operand and addressing modes rather than 32-bit while running code in this segment), and it has a 64KB limit rather than 4GB. This selector is used when switching between real and protected mode, to provide an intermediate 16-bit protected mode execution context. It is unused in kernels that never execute in real mode (e.g., typical MultiBoot kernels).

KERNEL_16_DS:

This selector is a data segment synonym for KERNEL_16_CS; it is generally only used when switching from protected mode back to real mode. It is used to ensure that the segment registers contain sensible real-mode values before performing the switch, as recommended in Intel literature.

LINEAR_CS:

This selector is set up to be a ring 0 code segment that directly maps the entire linear address space: in other words, it has an offset of zero and a 4GB limit. In some environments, where kernel virtual addresses are the same as linear addresses, this selector is a synonym for KERNEL_CS.

LINEAR_DS:

This is a data segment otherwise identical to LINEAR_CS.

USER_CS:

This selector is left unused and uninitialized by the OSKit; nominally, it is intended to be used as a code segment for unprivileged user-level code.

USER_DS:

This selector is left unused and uninitialized by the OSKit; nominally, it is intended to be used as a data segment for unprivileged user-level code.

If the client OS wants to make use of the base GDT but needs more selector slots for its own purposes, it can define its own instance of the base_gdt variable so that it has room for more than GDTSZ elements; base_gdt_init will initialize only the first “standard” segment descriptors, leaving the rest for the client OS’s use.

On multiprocessor systems, the client OS may want each processor to have its own GDT. In this case, the OS can create a separate clone of the base GDT for each additional processor besides the boot processor, and leave the boot processor using the base GDT. Alternatively, the OS could use the base GDT only during initialization, and switch all processors to custom GDTs later; this approach provides the most flexibility to the OS, since the custom GDTs can be arranged in whatever way is most convenient.

#include <oskit/x86/base_gdt.h>

void base_gdt_init(void); void i16_base_gdt_init(void);

This function initializes the standard descriptors in the base GDT as described in Section 15.7.1.

For all of the standard descriptors except LINEAR_CS and LINEAR_DS, the kvtolin macro is used to compute the linear address to plug into the offset field of the descriptor: for BASE_TSS, this is kvtolin(&base_tss); for the kernel code and data segments, it is kvtolin(0) (i.e., the linear address corresponding to the beginning of kernel virtual address space). LINEAR_CS and LINEAR_DS are always given an offset of 0.

A 16-bit version of this function, i16_base_gdt_init, is also provided so that the GDT can be initialized properly before the processor has been switched to protected mode. (Switching to protected mode on the x86 according to Intel’s recommended procedure requires a functional GDT to be already initialized and activated.)

fill_descriptor:

§ 15.3.8

kvtolin:

§ 15.6.2

base_gdt:

§ 15.7.1

base_tss:

§ 15.7.6

void base_gdt_load(void); void i16_base_gdt_load(void);

This function loads the base GDT into the processor’s GDTR, and then reinitializes all segment registers from the descriptors in the newly loaded GDT. It returns with the CS segment set to KERNEL_CS (the default kernel code segment; see Section 15.7.1 for details), DS, ES, and SS set to KERNEL_DS (the default kernel data segment), and FS and GS set to 0.

kvtolin:

§ 15.6.2

base_gdt:

§ 15.7.1

#include <oskit/x86/base_idt.h>

extern struct x86_desc base_idt[IDTSZ];

This global variable is used in the base environment as the default interrupt descriptor table. The default definition of base_idt in the library contains the architecturally-defined maximum of 256 interrupt vectors (IDTSZ).²

The base_idt.h header file does not define any symbols representing interrupt vector numbers. The lowest 32 vectors are the processor trap vectors defined by Intel; since these are not specific to the base environment, they are defined in the generic header file x86/trap.h (see Section 15.3.10). Standard hardware interrupt vectors are PC-specific, and therefore are defined separately in x86/pc/irq_list.h (see Section 15.4.1). For the same reason, there is no base_idt_init function, only separate functions to initialize the trap vectors in the base IDT (base_trap_init, Section 15.8.2), and hardware interrupt vectors in the IDT (base_irq_init, Section 15.12.3).

#include <oskit/x86/base_idt.h>

void base_idt_load(void);

This function loads the base_idt into the processor, so that subsequent traps and hardware interrupts will vector through it. It uses the kvtolin macro to compute the proper linear address of the IDT to be loaded into the processor.

kvtolin:

§ 15.6.2

base_idt:

§ 15.7.4

#include <oskit/x86/base_tss.h>

extern struct x86_tss base_tss;

The base_tss variable provides a default task state segment that the OS can use for privilege level switching if it does not otherwise use the x86’s task switching mechanisms. The x86 architecture requires every protected-mode OS to have at least one TSS even if no task switching is done; however, many x86 kernels do not use the processor’s task switching features because it is faster to context switch manually. Even if special TSS segments are used sometimes (e.g., to take advantage of the I/O bitmap feature when running MS-DOS programs), the OS can still use a common TSS for all tasks that do not need to use these special features; this is the strategy taken by the Mach kernel, for example. The base_tss provided by the toolkit serves in this role as a generic “default” TSS.

The base_tss is a minimal TSS, in that it contains no I/O bitmap or interrupt redirection map. XXX The toolkit also supports an alternate default TSS with a full I/O permission bitmap, but it isn’t fully integrated or documented yet.

#include <oskit/x86/base_tss.h>

void base_tss_init(void);

The base_tss_init function initializes the base_tss to a valid minimal state. It sets the I/O permission bitmap offset to point past the end of the TSS, so that it will be interpreted by the processor as empty (no permissions for any I/O ports). It also initializes the ring 0 stack segment selector (ss0) to KERNEL_DS, and the ring 0 stack pointer (esp0) to the current stack pointer value at the time of the function call, to provide a minimal working context for trap handling. Once the OS kernel sets up a “real” kernel stack, it should reinitialize base_tss.esp0 to point to that.

base_tss:

§ 15.7.6

#include <oskit/x86/base_tss.h>

void base_tss_load(void);

This function activates the base_tss in the processor using the LTR instruction, after clear the busy bit in the BASE_TSS segment descriptor to ensure that a spurious trap isn’t generated.

base_gdt:

§ 15.7.1

#include <oskit/x86/base_trap.h>

 struct trap_state
 {
         /* Saved segment registers */
         unsigned int    gs;
         unsigned int    fs;
         unsigned int    es;
         unsigned int    ds;
 
         /* PUSHA register state frame */
         unsigned int    edi;
         unsigned int    esi;
         unsigned int    ebp;
         unsigned int    cr2;    /* we save cr2 over esp for page faults */
         unsigned int    ebx;
         unsigned int    edx;
         unsigned int    ecx;
         unsigned int    eax;
 
         /* Processor trap number, 0-31.  */
         unsigned int    trapno;
 
         /* Error code pushed by the processor, 0 if none.  */
         unsigned int    err;
 
         /* Processor state frame */
         unsigned int    eip;
         unsigned int    cs;
         unsigned int    eflags;
         unsigned int    esp;
         unsigned int    ss;
 
         /* Virtual 8086 segment registers */
         unsigned int    v86_es;
         unsigned int    v86_ds;
         unsigned int    v86_fs;
         unsigned int    v86_gs;
 };

This structure defines the saved state frame pushed on the stack by the default trap entrypoints provided by the base environment (see Section 15.8.3). It is also used by the trap_dump routine, which is used in the default environment to dump the saved register state and panic if an unexpected trap occurs; and by gdb_trap, the default trap handler for remote GDB debugging.

This client OS is not obligated to use this structure as the saved state frame for traps it handles; if this structure is not used, then the OS must also override (or not use) the dependent routines mentioned above.

The structure elements from err down corresponds to the basic trap frames pushed on the stack by the x86 processor. (For traps in which the processor does not push an error code, the default trap entrypoint code sets err to zero.) The structure elements from esp down are only pushed by traps from lower privilege (rings 1-3), and the structure elements from v86_es down are only pushed by traps from v86 mode.

The rest of the state frame is pushed manually by the default trap entrypoint code. The saved integer register state is organized in a format compatible with the processor’s PUSHA instruction. However, in the slot that would otherwise hold the pushed ESP (which is useless since it is the trap handler’s stack pointer rather than the trapping code’s stack pointer), the default trap handler saves the CR2 register (page fault linear address) during page faults.

This trap state structure is borrowed from Mach.

#include <oskit/x86/base_trap.h>

void base_trap_init(void);

This function initializes the processor trap vectors in the base IDT to the default trap entrypoints defined in base_trap_inittab.

gate_init:

§ 15.5.10

base_idt:

§ 15.7.4

base_trap_inittab:

§ 15.8.3

#include <oskit/x86/base_trap.h>

extern struct gate_init_entry base_trap_inittab[];

This gate initialization table (see Section 15.3.9) encapsulates the base environment’s default trap entrypoint code. This module provides IDT entrypoints for all of the processor-defined trap vectors; each entrypoint pushes a standard state frame on the stack (see Section 15.8.1), and then calls the C function pointed to by the corresponding entry in base_trap_handlers array (see Section 15.8.4). Through these entrypoints, the OSKit provides the client OS with a convenient, uniform method of handling all processor traps in ordinary high-level C code.

If a trap occurs and the trap entrypoint code finds that the corresponding entry in base_trap_handlers is null, or if it points to a handler routine but the handler returns a nonzero value indicating failure, the entrypoint code calls trap_dump_panic (see Section 15.8.7) to dump the register state to the console and panic the kernel. This behavior is typically appropriate in kernels that do not expect traps to occur during proper operation (e.g., boot loaders or embedded operating systems), where a trap probably indicates a serious software bug.

On the other hand, if a trap handler is present and returns success (zero), the entrypoint code restores the saved state and resumes execution of the trapping code. The trap handler may change the contents of the trap_state structure passed by the entrypoint code; in this case, final contents of the structure on return from the trap handler will be the state restored.

All of the IDT entries initialized by the base_trap_inittab are trap gates rather than interrupt gates; therefore, if hardware interrupts are enabled when a trap occurs, then interrupts will still be enabled during the trap handler unless the trap handler explicitly disables them. If the OS wants interrupts to be disabled during trap handling, it can change the processor trap vectors in the IDT (vectors 0-31) into interrupt gates, or it can simply use its own trap entrypoint code instead.

struct trap_state:

§ 15.8.1

base_trap_handlers:

§ 15.8.4

trap_dump_panic:

§ 15.8.7

#include <oskit/x86/base_trap.h>

void (*base_trap_handlers[BASE_TRAP_COUNT]) (struct trap_state *ts );

Contains a function pointer for every hardware trap vector. By default, all entries in this table point to base_trap_default_handler, which will simply dump the register state to the console and panic. The client OS can set entries in this table to point to its own trap handler function(s), or to alternative trap handlers supplied by the OSKit, such as the remote GDB debugging trap handler, gdb_trap (see Section 15.17.5).

state:

A pointer to the trap state structure to dump.

The trap handler returns zero (success) to resume execution, or nonzero (failure) to cause the entrypoint code to dump the register state and panic the kernel.

#include <oskit/x86/pc/base_trap.h>

void base_trap_default_handler(struct trap_state *state);

This routine is the default handler for all traps in the base environment. It simply displays displays the trap state information and then calls panic.

It is expected that the client OS will override entries in the base_trap_handlers array for traps it cares about. Alternatively, the client OS may override the base_trap_default_handler entrypoint entirely.

state:

A pointer to the processor state at the time of the interrupt.

struct trap_state:

§ 15.8.1

#include <oskit/x86/base_trap.h>

void trap_dump(const struct trap_state *state);

This function dumps the contents of the specified trap state frame to the console using the printf function, in a simple human-readable form. The function is smart enough to determine whether the trap occurred from supervisor mode, user mode, or v86 mode, and interpret the saved state accordingly. For example, for traps from rings 1-3 or from v86 mode, the the original stack pointer is part of the saved state frame; however, for traps from ring 0, the original stack pointer is simply the end of the stack frame pushed by the processor, since no stack switch occurs in this case.

In addition, for traps from ring 0, this routine also provides a hex dump of the top of the kernel stack as it appeared when the trap occurred; this stack dump can aid in tracking down the cause of a kernel bug. trap_dump does not attempt to dump the stack for traps from user or v86 mode, because there seems to be no sufficiently generic way for it to access the appropriate user stack; in addition, in this case the trap might have been caused by a user-stack-related exception, in which case attempting to dump the user stack could lead to a recursive trap.

state:

A pointer to the trap state structure to dump.

struct trap_state:

§ 15.8.1

printf:

§ 14.6

#include <oskit/x86/base_trap.h>

void trap_dump_panic(const struct trap_state *state);

This function simply calls trap_dump (Section 15.8.6) to dump the specified trap state frame, and then calls panic (Section 14.8.3). It is invoked by the default trap entrypoint code (Section 15.8.3) if a trap occurs when there is no interrupt handler, or if there is an interrupt handler but it returns a failure indication.

state:

A pointer to the trap state structure to dump.

trap_dump:

§ 15.8.6

panic:

§ 14.8.3

#include <oskit/x86/base_paging.h>

void base_paging_init(void);

This function can be used to set up a minimal paging environment. It first allocates and clears an initial page directory using ptab_alloc (see Section 15.9.7), sets base_pdir_pa to point to it (see Section 15.9.2), then direct-maps all known physical memory into this address space starting at linear address 0, allocating additional page tables as needed. Finally, this function enables the processor’s paging mechanism, using the base page directory as the initial page directory.

The global variable phys_mem_max (see Section 15.11.2) is assumed to indicate the top of physical memory; all memory from 0 up to at least this address is mapped. The function actually rounds phys_mem_max up to the next 4MB superpage boundary, so that on Pentium and higher processors, all physical memory can be mapped using 4MB superpages even if known physical memory does not end exactly on a 4MB boundary. Note that phys_mem_max does not necessarily need to reflect all physical memory in the machine; for example, it is perfectly reasonable for the client OS to set it to some artificially lower value so that only that part of physical memory is direct-mapped.

On Pentium and higher processors, this function sets the PSE (page size extensions) bit in CR4 in addition to the PG (paging) bit, so that the 4MB page mappings used to map physical memory will work properly.

base_pdir_pa:

§ 15.9.2

ptab_alloc:

§ 15.9.7

pdir_map_range:

§ 15.9.11

base_cpuid:

§ 15.6.6

paging_enable:

§ 15.5.8

#include <oskit/x86/base_paging.h>

extern oskit_addr_t base_pdir_pa;

This variable is initialized by base_paging_init (see Section 15.9.1) to contain the physical address of the base page directory. This is the value that should be loaded into the processor’s page directory base register (CR3) in order to run in the linear address space defined by this page directory. (The base page directory is automatically activated in this way during initialization; the client OS only needs to load the CR3 register itself if it wants to switch among multiple linear address spaces.) The pdir_find_pde function (Section 15.9.3) and other related functions can be used to manipulate the page directory and its associated page tables.

Initially, the base page directory and its page tables directly map physical memory starting at linear address 0. The client OS is free to change the mappings after initialization, for example by adding new mappings outside of the physical address range, or by relocating the physical memory mappings to a different location in the linear address space as described in Section 15.6.3.

Most “real” operating systems will need to create other, separate page directories and associated page tables to represent different address spaces or protection domains. However, the base page directory may still be useful, e.g., as a template for initializing the common kernel portion of other page directories, or as a “kernel-only” address space for use by kernel tasks, etc.

#include <oskit/x86/base_paging.h>

pd_entry_t *pdir_find_pde(oskit_addr_t pdir_pa, oskit_addr_t la);

This primitive macro uses the appropriate bits in linear address la (bits 22-31) to look up a particular entry in the specified page directory. Note that this function takes the physical address of a page directory, but returns a kernel virtual address (i.e., an ordinary pointer to the selected page directory entry).

pdir_pa:

Physical address of the page directory.

la:

Linear address to be used to select a page directory entry.

Returns a pointer to the selected page directory entry.

phystokv:

§ 15.6.2

#include <oskit/x86/base_paging.h>

pd_entry_t *ptab_find_pte(oskit_addr_t ptab_pa, oskit_addr_t la);

This macro uses the appropriate bits in la (bits 12-21) to look up a particular entry in the specified page table. This macro is just like pdir_find_pde, except that it selects an entry based on the page table index bits in the linear address rather than the page directory index bits (bits 22-31). Note that this function takes the physical address of a page table, but returns a kernel virtual address (an ordinary pointer).

ptab_pa:

Physical address of the page table.

la:

Linear address to be used to select a page table entry.

Returns a pointer to the selected page table entry.

phystokv:

§ 15.6.2

#include <oskit/x86/base_paging.h>

pt_entry_t *pdir_find_pte(oskit_addr_t pdir_pa, oskit_addr_t la);

This function is a combination of pdir_find_pde and ptab_find_pte: it descends through both levels of the x86 page table hierarchy and finds the page table entry for the specified linear address.

This function assumes that if the page directory entry selected by bits 22-31 of la is valid (the INTEL_PDE_VALID bit is set), then that entry actually refers to a page table, and is not a 4MB page mapping. The caller must ensure that this is the case.

pdir_pa:

Physical address of the page directory.

la:

Linear address to use to select the appropriate page directory and page table entries.

Returns a pointer to the selected page table entry, or NULL if there is no page table for this linear address.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

#include <oskit/x86/base_paging.h>

pt_entry_t pdir_get_pte(oskit_addr_t pdir_pa, oskit_addr_t la);

This function is a simple extension of pdir_find_pte: instead of returning the address of the selected page table entry, it returns the contents of the page table entry: i.e., the physical page frame in bits 12-31 and the associated INTEL_PTE_* flags in bits 0-11. If there is no page table in the page directory for the specified linear address, then this function returns 0, the same as if there was a page table but the selected page table entry was zero (invalid).

As with pdir_find_pte, this function assumes that if the page directory entry selected by bits 22-31 of la is valid (the INTEL_PDE_VALID bit is set), then that entry actually refers to a page table, and is not a 4MB page mapping.

pdir_pa:

Physical address of the page directory.

la:

Linear address to use to select the appropriate page directory and page table entries.

Returns the selected page table entry, or zero if there is no page table for this linear address. Also returns zero if the selected page table entry exists but is zero.

pdir_find_pte:

§ 15.9.5

#include <oskit/x86/base_paging.h>

int ptab_alloc([out] oskit_addr_t *out_ptab_pa);

All of the following page mapping routines call this function to allocate new page tables as needed to create page mappings. It attempts to allocate a single page of physical memory, and if successful, returns 0 with the physical address of that page in *out_ptab_pa. The newly allocated page is cleared to all zeros by this function. If this function is unsuccessful, it returns nonzero.

The default implementation of this function assumes that the OSKit’s minimal C library (libc) and list-based memory manager (liblmm) are being used to manage physical memory, and allocates page table pages from the malloc_lmm memory pool (see Section 14.5.1). However, in more complete OS environments, e.g., in which low physical memory conditions should trigger a page-out rather than failing immediately, this routine can be overridden to provide the desired behavior.

out_ptab_pa:

The address of a variable of type oskit_addr_t into which this function will deposit the physical address of the allocated page, if the allocation was successful.

Returns zero if the allocation was successful, or nonzero on failure.

lmm_alloc_page:

§ 25.6.8

malloc_lmm:

§ 14.5.1

memset:

§ 14.4.18

kvtophys:

§ 15.6.2

#include <oskit/x86/base_paging.h>

void ptab_free(oskit_addr_t ptab_pa);

The page mapping and unmapping functions described in the following sections call this routine to free a page table that is no longer needed; thus, this function is the partner of ptab_alloc (see Section 15.9.7). The default implementation again assumes that the malloc_lmm memory pool is being used to manage physical memory. If the client OS overrides ptab_alloc to use a different allocation mechanism, it should also override ptab_free correspondingly.

ptab_pa:

The physical address of the page table page to free.

lmm_free_page:

§ 25.6.10

#include <oskit/x86/base_paging.h>

int pdir_map_page(oskit_addr_t pdir_pa, oskit_addr_t la, pt_entry_t mapping);

This function creates a single 4KB page mapping in the linear address space represented by the specified page directory. If the page table covering the specified linear address does not exist (i.e., the selected page directory entry is invalid), then a new page table is allocated using ptab_alloc and inserted into the page directory before the actual page mapping is inserted into the page table. Any new page tables created by this function are mapped into the page directory with permissions INTEL_PTE_USER | INTEL_PTE_WRITE: full permissions are granted at the page directory level, although the specified mapping value, which is inserted into the selected page table entry, may restrict permissions at the individual page granularity.

This function assumes that if the page directory entry selected by bits 22-31 of la is valid (the INTEL_PDE_VALID bit is set), then that entry actually refers to a page table, and is not a 4MB page mapping. In other words, the caller should not attempt to create a 4KB page mapping in a part of the linear address space already covered by a valid 4MB superpage mapping. The caller must first unmap the 4MB superpage mapping, then map the 4KB page (which will cause a page table to be allocated). If the caller follows the guidelines described in Section 15.9, then this requirement should not be a problem.

pdir_pa:

Physical address of the page directory acting as the root of the linear address space in which to make the requested page mapping.

la:

Linear address at which to make the mapping. Only bits 12-31 are relevant to this function; bits 0-11 are ignored.

mapping:

Contains the page table entry value to insert into the appropriate page table entry: the page frame number is in bits 12-31, and the INTEL_PTE_* flags are in bits 0-11. XXX The caller must include INTEL_PTE_VALID; other flags may be set according to the desired behavior. (To unmap pages, use pdir_unmap_page instead; see Section 15.9.10)

If all goes well and the mapping is successful, this function returns zero. If this function needed to allocate a new page table but the ptab_alloc function failed (returned nonzero), then this function passes back the return value from ptab_alloc.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

ptab_alloc:

§ 15.9.7

#include <oskit/x86/base_paging.h>

void pdir_unmap_page(oskit_addr_t pdir_pa, oskit_addr_t la);

This function invalidates a single 4KB page mapping in the linear address space represented by the specified page directory. The la parameter should fall in a page previous mapped with pdir_map_page, otherwise the result of the call is undefined. XXX Is this overly restrictive?

This function assumes that if the page directory entry selected by bits 22-31 of la is valid (the INTEL_PDE_VALID bit is set), then that entry actually refers to a page table, and is not a 4MB page mapping. In other words, the caller should not attempt to destroy a 4KB page mapping in a part of the linear address space covered by a valid 4MB superpage mapping. Use pmap_unmap_range to remove a 4MB superpage mapping.

pdir_pa:

Physical address of the page directory acting as the root of the linear address space from which the requested page mapping is to be removed.

la:

Linear address contained in the page to be removed. Only bits 12-31 are relevant to this function; bits 0-11 are ignored.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

ptab_free:

§ 15.9.8

#include <oskit/x86/base_paging.h>

int pdir_map_range(oskit_addr_t pdir_pa, oskit_addr_t la, oskit_addr_t pa, oskit_size_t size, pt_entry_t mapping_bits);

This function maps a range of linear addresses in the linear address space represented by the specified page directory onto a contiguous range of physical addresses. The linear (source) address, physical (destination) address, and mapping size must be multiples of the 4KB architectural page size, but other than that no restrictions are imposed on the location or size of the mapping range. If the processor description in the global base_cpuid variable (see Section 15.6.6) indicates that page size extensions are available, and the physical and linear addresses are properly aligned, then this function maps as much of the range as possible using 4MB superpage mappings instead of 4KB page mappings. Where 4KB page mappings are needed, this function allocates new page tables as necessary using ptab_alloc. Any new page tables created by this function are mapped into the page directory with permissions INTEL_PTE_USER | INTEL_PTE_WRITE: full permissions are granted at the page directory level, although the mapping_bits may specify more restricted permissions for the actual page mappings.

This function assumes that no valid mappings already exist in the specified linear address range; if any mappings do exist, this function may not work properly. If the caller follows the guidelines described in Section 15.9, always unmapping previous mappings before creating new ones, then this requirement should not be a problem.

pdir_pa:

Physical address of the page directory acting as the root of the linear address space in which to make the requested mapping.

la:

Starting linear address at which to make the mapping. Must be page-aligned.

pa:

Starting physical address to map to. Must be page-aligned.

size:

Size of the linear-to-physical mapping to create. Must be page-aligned.

mapping_bits:

Permission bits to OR into each page or superpage mapping entry. The caller must include INTEL_PTE_VALID; other flags may be set according to the desired behavior. (To unmap ranges, use pdir_unmap_range instead; see Section 15.9.13)

If all goes well and the mapping is successful, this function returns zero. If this function needed to allocate a new page table but the ptab_alloc function failed (returned nonzero), then this function passes back the return value from ptab_alloc.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

ptab_alloc:

§ 15.9.7

base_cpuid:

§ 15.6.6

#include <oskit/x86/base_paging.h>

void pdir_prot_range(oskit_addr_t pdir_pa, oskit_addr_t la, oskit_size_t size, pt_entry_t new_mapping_bits);

This function can be used to modify the permissions and other attribute bits associated with a mapping range previously created with pdir_map_range. The la and size parameters must be exactly the same as those passed to the pdir_map_range used to create the mapping.

pdir_pa:

Physical address of the page directory acting as the root of the linear address space containing the mapping to modify.

la:

Starting linear address of the mapping to modify. Must be exactly the same as the address specified to the pdir_map_range call used to create this mapping.

size:

Size of the mapping to modify. Must be exactly the same as the size specified to the pdir_map_range call used to create this mapping.

new_mapping_bits:

New permission flags to insert into each page or superpage mapping entry. The caller must include INTEL_PTE_VALID; other flags may be set according to the desired behavior. (To unmap ranges, use pdir_unmap_range; see Section 15.9.13)

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

#include <oskit/x86/base_paging.h>

void pdir_unmap_range(oskit_addr_t pdir_pa, oskit_addr_t la, oskit_size_t size);

This function removes a mapping range previously created using pdir_map_range. The la and size parameters must be exactly the same as those passed to the pdir_map_range used to create the mapping.

pdir_pa:

Physical address of the page directory acting as the root of the linear address space containing the mapping to destroy.

la:

Starting linear address of the mapping to destroy. Must be exactly the same as the address specified to the pdir_map_range call used to create this mapping.

size:

Size of the mapping to destroy. Must be exactly the same as the size specified to the pdir_map_range call used to create this mapping.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

#include <oskit/x86/base_paging.h>

void pdir_clean_range(oskit_addr_t pdir_pa, oskit_addr_t la, oskit_size_t size);

This function scans the portion of the given page directory covering the given address range, looking for associated page table pages that are unnecessary and frees them. “Unnecessary” page table pages are those which contain only entries for which INTEL_PTE_VALID is not set. These pages are freed with ptab_free and the corresponding page directory entries marked as invalid.

pdir_pa:

Physical address of the page directory.

la:

Starting linear address of the region to clean. Must be page-aligned.

size:

Size (in bytes) of the region to clean. The value passed is rounded up to whole pages. Use “0” for la and “ (oskit_addr_t)0” for size to clean the entire page directory.

pdir_find_pde:

§ 15.9.3

ptab_find_pte:

§ 15.9.4

ptab_free:

§ 15.9.8

#include <oskit/x86/base_paging.h>

void pdir_dump(oskit_addr_t pdir_pa);

This function is primarily intended for debugging purposes: it dumps the mappings described by the specified page directory and all associated page tables in a reasonably compact, human-readable form, using printf. 4MB superpage as well as 4KB page mappings are handled properly, and contiguous ranges of identical mappings referring to successive physical pages or superpages are collapsed into a single line for display purposes. The permissions and other page directory/page table entry flags are expanded out as human-readable flag names.

pdir_pa:

Physical address of the page directory describing the linear address space to dump.

ptab_dump:

§ 15.9.16

printf:

§ 14.6

phystokv:

§ 15.6.2

#include <oskit/x86/base_paging.h>

void ptab_dump(oskit_addr_t ptab_pa, oskit_addr_t base_la);

This is primarily a helper function for pdir_dump, but it can also be used independently, to dump the contents of an individual page table. For output purposes, the page table is assumed to reside at base_la in “some” linear address space: in other words, this parameter provides the topmost ten bits in the linear addresses dumped by this routine. Contiguous ranges of identical mappings referring to successive physical pages are collapsed into a single line for display purposes. The permissions and other page directory/page table entry flags are expanded out as human-readable flag names.

pdir_pa:

Physical address of the page table to dump.

base_la:

Linear address at which this page table resides, for purposes of displaying linear source addresses. Must be 4MB aligned.

printf:

§ 14.6

phystokv:

§ 15.6.2

#include <oskit/x86/pc/phys_lmm.h>

There are three priority values assigned to regions of physical memory as they are made available at boot time (via lmm_add_region). In increasing order of priority (i.e., increasing preference for allocation):

LMM_PRI_1MB:

For physical memory below 1MB.

LMM_PRI_16MB:

For physical memory below 16MB.

LMM_PRI_HIGH:

For physical memory above 16MB.

These priorities prevent the simple memory allocation interfaces from handing out the more precious low-address memory. To enable savvy applications to explicitly allocate memory of a given type, the following flag values are assigned at boot time and can be passed to LMM allocation routines:

LMMF_1MB:

Set on memory below 1MB; i.e., the LMM_PRI_1MB region.

LMMF_16MB:

Set on memory below 16MB; i.e., the LMM_PRI_1MB and LMM_PRI_16MB regions.

Thus, if neither flag is set, memory can be allocated from any of the three regions with preference given to LMM_PRI_HIGH, followed by LMM_PRI_16MB and LMM_PRI_1MB. If just LMMF_16MB is set, memory can be allocated from either LMM_PRI_16MB or LMM_PRI_1MB in that order. If both flags are set, memory can only be allocated from the LMM_PRI_1MB region.

#include <oskit/x86/pc/phys_lmm.h>

extern oskit_addr_t phys_mem_max;

This variable records the highest physical memory address; i.e., the end address of the highest free block added to malloc_lmm. This is the highest address that the kernel should ever have to deal with.

Not all addresses between 0 and phys_mem_max are necessarily available for allocation, there may be holes in the available physical memory space.

#include <oskit/x86/pc/phys_lmm.h>

void phys_lmm_init(void);

This routine sets up malloc_lmm with three physical memory regions, one for each of the memory types described in phys_lmm.h. No actual memory is added to those regions. You can then call phys_lmm_add() to add memory to those regions. In the base environment, base_multiboot_init_mem handles this chore.

malloc_lmm:

§ 14.5.1

lmm_add_region:

§ 25.6.2

phystokv:

§ 15.6.2

#include <oskit/x86/pc/phys_lmm.h>

void phys_lmm_add(oskit_addr_t min_pa, oskit_size_t size);

Add a chunk of physical memory to the appropriate region(s) on the malloc_lmm. The provided memory block may be arbitrarily aligned and may cross region boundaries (e.g., the 16MB boundary); it will be shrunken and split apart as necessary. If the address of the end of the block is greater than the current value in phys_max_mem, this address is recorded.

Note that phys_lmm_add takes a physical address, not a virtual address as the underlying LMM routines do. This routine will perform the conversion as needed with phystokv.

min_pa:

Physical address of the start of the chunk being added.

size:

Size in bytes of the chunk being added.

malloc_lmm:

§ 14.5.1

lmm_add_free:

§ 25.6.3

phystokv:

§ 15.6.2

phys_mem_max:

§ 15.11.2

#include <oskit/x86/pc/base_irq.h>

BASE_IRQ_COUNT:

Number of interrupt request lines.

BASE_IRQ_MASTER_BASE:

Default location in the IDT for programming the PIC.

BASE_IRQ_SLAVE_BASE:

Default location in the IDT for programming the PIC.

irq_master_base:

Variable storing the current master PIC interrupt vector base.

irq_slave_base:

Variable storing the current slave PIC interrupt vector base.

fill_irq_gate(irq_num, entry, selector, access):

Fill the base_idt descriptor for the indicated IRQ with an interrupt gate containing the given entry, selector and access information.

#include <oskit/x86/pc/base_irq.h>

void (*base_irq_handlers[BASE_IRQ_COUNT]) (struct trap_state *ts );

Contains a function pointer for every hardware interrupt vector. By default, all entries in this table point to base_irq_default_handler. Custom interrupt handlers can be installed by changing the appropriate table entry.

Interrupt handlers can freely examine and modify the processor state (15.8.1) of the interrupted activity, e.g., to implement threads and preemption. On entry, the processor’s IDT interrupt vector number is in ts->trapno and the hardware IRQ number that caused the interrupt is in ts->err.

base_irq_default_handler:

§ 15.12.5

#include <oskit/x86/pc/base_irq.h>

void base_irq_init(void);

Initializes the system to properly handle hardware interrupts. It loads the appropriate entries in the base IDT (15.7.4) with the gate descriptor information from base_irq_inittab, programs the PICs to the standard vector base addresses (see Section 15.12.1), and disables all interrupt request lines.

Processor interrupts must be disabled when this routine is called.

NOTE: This routine no longer enables interrupts!

base_idt:

§ 15.7.4

base_irq_inittab:

§ 15.12.4

gate_init:

§ 15.5.10

pic_init:

§ 15.4.2

pic_disable_all:

§ 15.4.2

irq_master_base:

§ 15.12.1

irq_slave_base:

§ 15.12.1

#include <oskit/x86/pc/base_irq.h>

extern struct gate_init_entry base_irq_inittab[];

This gate initialization table (15.3.9) encapsulates the base environment’s default interrupt entrypoint code. This module provides IDT entrypoints for all the standard PC hardware interrupt vectors; each entrypoint pushes a standard state frame on the stack (15.8.1), disables and acknowledges the hardware interrupt, and then calls the C handler function pointed to by the appropriate entry of the base_irq_handlers array (15.12.2). Upon return from the handler, the interrupt code checks for a pending software interrupt and dispatches to function pointer contained in base_irq_softint_handler.

base_irq_handlers:

§ 15.12.2

base_irq_nest:

§ 15.12.6

base_irq_softint_handler:

§ 15.12.8

#include <oskit/x86/pc/base_irq.h>

void base_irq_default_handler(struct trap_state *state);

This routine is the default handler for all interrupts in the base environment. It simply displays a warning message and returns.

It is expected that the client OS will override this default behavior for all interrupts it cares about, leaving this routine to be called only for unexpected interrupts.

state:

A pointer to the processor state at the time of the interrupt.

struct trap_state:

§ 15.8.1

printf:

§ 14.6

#include <oskit/x86/pc/base_irq.h>

extern unsigned char base_irq_nest;

Hardware interrupt nesting counter, used to ensure that the software interrupt handler isn’t called until all outstanding hardware interrupts have been processed. In addition, this variable also acts as the software interrupt pending flag: if the high bit is clear, a software interrupt is pending.

#include <oskit/x86/pc/base_irq.h>

void base_irq_softint_request(void);

This routine requests a software interrupt and is typically called from a hardware interrupt handler to schedule lower priority processing.

After requesting a software interrupt, the function pointed to by base_irq_softint_handler will be called when all hardware interrupt handlers have completed processing and base_irq_nest is zero. If an interrupt is scheduled from a non-interrupt context, the handler will not be called until the next hardware interrupt occurs and has been processed.

Only a single software interrupt may be pending at a time.

base_irq_nest:

§ 15.12.6

#include <oskit/x86/pc/base_irq.h>

void (*base_irq_softint_handler) (struct trap_state *ts );

Pointer to a software interrupt handler called by the interrupt entry/exit stub code when a software interrupt has been requested and needs to be run. The default value of this pointer is the function base_irq_softint_default_handler, which simply returns; to use software interrupts, the kernel must override it.

The handler is free to examine and modify the processor state in state.

state:

A pointer to the processor state at the time of the interrupt.

struct trap_state:

§ 15.8.1

#include <oskit/x86/pc/base_console.h>

The following variable are used in the base_console code:

serial_console:

Set non-zero if a serial port is being used as the console. Default value is zero, but may be turned on by either a command line option or the CONS_COM environment variable.

cons_com_port:

If serial_console is non-zero, this variable indicates the COM port to use for console input and output. Default value is 1, but may be changed by setting the CONS_COM environment variable. Possible values are 1, 2, 3 or 4.

enable_gdb:

If non-zero, enables the GDB trap handler; i.e., makes remote debugging possible. The default value is zero.

gdb_com_port:

If enable_gdb is non-zero, this variable indicates the COM port to use for remote GDB interaction. The default value is 1 (the console and remote GDB can share the same serial port, but do not have to). Possible values are 1, 2, 3 or 4.

Refer to Section 15.13.2 for more information on command line options and environment variables. See Section 15.17 for more on remote GDB.

#include <oskit/x86/base_console.h>

void base_console_init(int argc, char **argv);