CPU(8) BSD System Manager's Manual CPU(8)NAMEcpu - control multiprocessor aspects of system
SYNOPSIScpu [-dOv] [-i savefile] [-f cpudev] [-o override-file] command [args]
[overrides]
DESCRIPTION
The cpu program is used to control multiprocessor aspects of BSD/OS .
The primary function of cpu is the transition of the system from unipro-
cessor mode (also referred to as PIC mode, the state the system is in af-
ter boot) to symmetric I/O mode with (possibly) multiple processors run-
ning.
The bulk of the functionality available to the user via this program is
used for debugging and/or dealing with motherboards and BIOS that do not
fully live up to the Intel Multiprocessor Specification (1.4) standard.
In normal use, a cpu mp command is run by '/etc/rc' during the boot pro-
cess if /etc/mp.config is present (it may be empty); this takes care of
all the details of starting any additional CPUs. Much of the information
and functionality described below is targeted at engineers attempting to
bring up a new motherboard.
The cpu program also performs numerous debugging and status functions
that do not affect the state of the system.
The flags are
-d Enable debug mode. In this mode operations which would change the
state of a running system are not issued. This mode also enables
verbose mode.
-f cpudev
Give a different name for the special device file used to control
the system. If not given /dev/cpu is used.
-i savefile
This specifies a file with saved system state from a previous invo-
cation of cpu. When this option is used information about the system
(BIOS SMP information, interrupt status, cpu status) that is used in
the operation of the program is read from the file instead of from
the currently running kernel (via /dev/cpu ). Note: if -d is not
also specified and changes requested are still issued to the kernel
via /dev/cpu. Thus, this option is most useful in conjunction with
-d to display debugging information about another machine (ie: to
see how cpu is routing interrupts on a different machine).
-o override-file
This specifies the pathname to a file which may contain configura-
tion overrides. See OVERRIDES below.
-O This specifies that no overrides will be read from an external file;
overrides on the command line are still recognized.
-v Turns on verbose mode, in this mode additional warnings and debug
information is printed as cpu performs its duties.
Some definitions will aid in understanding the commands and overrides:
PIC (8259)
Programmable interrupt controller. Two of these devices are built
into all PC chipsets, these are based on the original 8259 interrupt
controllers used on the PC/AT in 1983. Pre-MP capable systems use
these parts to handle device interrupts.
When using the PIC's to handle interrupts the interrupt lines from
the card slots (ISA, PCI) and internal peripherals (clock, keyboard,
etc.) are connected to one of the two 8259 PIC's; these are in turn
connected to the CPU and deliver interrupts directly via special bus
cycles.
APIC
Advanced programmable interrupt controller. This device replaces the
functionality of the PIC in a system that is running more than one
CPU. Systems with APIC's must also have PIC hardware to allow them
to boot and run older software that does not support the APIC sys-
tem.
In an APIC based system each CPU has an APIC built into it (referred
to as the local APIC) and the motherboard has one or more I/O APIC's
to which the interrupt signals are connected. All the APIC's in the
system are connected to a common bus. When an interrupt is signalled
to an I/O APIC, it picks a CPU on the APIC bus that can service the
interrupt and exchanges message packets with that CPU's local APIC
(which in turn causes the CPU to enter an interrupt service rou-
tine). With the APIC system interrupts can be distributed amongst
all the CPU's instead of just one CPU (as with the PIC system).
In general, once the APIC system has been enabled the PIC's are no
longer used to distribute interrupts (they are disabled).
Apic-ID (Cpu-ID)
Each APIC on the APIC bus (either cpu local or I/O) is assigned a
unique 4 bit identifier (by the hardware designer). On typical two
processor systems with one I/O apic the CPU's are at ID 0 and ID 1,
and the I/O APIC is at ID 2. ID 0xf is not available, allowing up to
14 APIC's total (counting CPU's and I/O APIC's) per system. A mode
is available where several APIC busses can be cascaded, however is
this not supported by BSD/OS (or the Intel MPS 1.4 spec). Cpu-ID is
synonymous with Apic-ID (a number from 0 to 0xe).
Mixed mode
Some (arguably broken) motherboard chip sets do not externalize all
their interrupt sources (specifically the clock signal) so there is
no way to connect the interrupt source directly to an I/O APIC. On
these systems a mixed interrupt delivery mode is used; interrupts
that are not connected to the APIC system are handled by the old PIC
system (and routed to the boot processor), interrupts that are con-
nected to the APIC's are delivered using the APIC system. This is
not a desirable mode to run in.
Symmetric I/O mode
When a system is first booted it is in PIC mode (using the 8259 in-
terrupt controllers); the first step in starting additional proces-
sors is to turn off the PIC's and enable interrupt distribution via
the APIC bus. When interrupts are routed via the APIC bus the system
is said to be running in symmetric I/O mode.
It is possible to run the system in symmetric I/O mode without
starting additional CPU's (or even on a system with only one CPU, as
long as it has an APIC bus and an I/O APIC). This is typically used
to check out the I/O hardware on a new motherboard before adding the
additional load (and possible complication) of a second CPU.
UP Uniprocessor mode; the state the system is in after booting (using
PIC's for interrupt distribution and only the boot processor is run-
ning).
MP (or SMP)
Multiprocessor mode; this is the state the system is in after it has
been switched into symmetric I/O mode and additional CPU's have been
started.
COMMANDScpu has multiple functions, selected via the command argument.
The CPU number and APIC-ID values are in the same name space, they are a
number from 0 to 14. A given address may be an I/O apic or a CPU, but not
both. All numeric input to cpu may be in hex (leading 0x), octal (leading
0), of decimal (no prefix).
Many dual processor systems use Cpu-0 and Cpu-1, and have an I/O APIC at
address 2. The BIOS is the final source of information on CPU and APIC
id's, use the bootparam command to display the BIOS data regarding the
machine.
check
This determines if the CPU on which it is running is capable of
serving as a processor in an SMP system. If verbose mode is set, de-
tailed information regarding the stepping and other features of the
CPU is printed.
This may be run on a machine without an SMP capable kernel (even an
older release). This does not require superuser privileges, nor ac-
cess to /dev/cpu.
cpu This is similar to the
check
command, but displays info based on the Intel MPS data provided in
the system bootparam info.
mp [overrides]
This attempts to switch the system into symmetric I/O mode (a pre-
requisite for running multiple CPUs) and then starts all additional
processors.
See OVERRIDES below for information on when and how overrides are
used.
siomode [overrides]
This switches the system into symmetric I/O mode but does not start
any additional CPUs. It is sometimes necessary to test a system un-
der symmetric I/O mode before starting additional processors. See
OVERRIDES below for information on when and how overrides are used.
stat
Displays the status of the I/O system (PIC mode or symmetric I/O
mode), the state of each known CPU, and the current interrupt coun-
ters for each interrupt source. Note that in PIC mode any additional
processors will not be shown in this display (since their presence
has not yet been determined).
start cpuno
Start a CPU and set it up for scheduling user mode processes.
The following commands are generally only used for debugging.
bootparam
Decode and display all system boot parameters, for SMP systems the
section with the Intel MPS data is of most interest (it shows how
the motherboard routes interrupt sources when in symmetric I/O
mode).
dumplapic
This dumps the register set of the local APIC on the CPU which is
running the cpu program. Since there is (currently) no way to force
a program to run on a particular CPU this is of limited used once
multiple processors have been started.
dumpiapic apic-id
This dumps the register set of the I/O apic apic-id.
intr
This summarizes the interrupt sources from the bootparam data. It is
simply an easier to digest version of the data displayed by
bootparam.
mpinfo
This summarizes the Intel MPS data from the bootparam data. It is
simply an easier to digest version of the data displayed by
bootparam.
pci Display PCI device information; this is simply the results of a bus
walk looking for any valid PCI devices (using the same criteria the
kernel uses when it boots; non-zero functions will not be displayed
for instance). This information is used when determining interrupt
routing for PCI devices.
save savefile
This reads all the kernel information needed by cpu to switch into
symmetric I/O mode and start processors, and then saves the data in-
to savefile. This file (which is uuencoded) may then be sent to a
support engineer to aid in the debugging of interrupt routing is-
sues. This is the file that the -i flag expects.
OVERRIDES
Overrides may be given on the command line or in a file. The subcommands
that accept overrides will first attempt to read overrides from a file,
then will add the overrides specified on the command line.
The override file is /etc/mp.config by default. If the MPINFO environment
variable is set, it specifies an alternate filename to use. If the -o
flag is given, the file specified will be used as the override file. If
-O is supplied then overrides will not be read from any file (command
line overrides will still be applied).
Overrides on the command line must not have spaces within them (white
space delimits the overrides). When putting overrides in a file, the for-
mat is one override per line, whitespace may be used within the override,
and any characters following a '#' on the line are ignored as a comment.
In normal operation these overrides should not be needed. The overrides
are fully explained here, however use of them is not directly supported.
Generally they should only be used at the request of a BSDI support or
engineering. Any options may be changed or removed at any time. Improper
use can cause a system to hang or corrupt data.
These overrides are intended for use debugging problems with new chip
sets and motherboards or to work BIOS revisions that do not properly re-
port multiprocessor information.
nopci
Prevent the routing of any interrupts described by the BIOS as PCI
interrupts. Typically this is used when the BIOS PCI routing infor-
mation is incorrect and irqN=apic,pin statements are used to manual-
ly route the PCI interrupt pins to the appropriate IRQs instead.
noisa
Prevent the routing of any interrupts described by the BIOS as ISA
or EISA. Typically this is used when the BIOS PCI routing informa-
tion is incorrect and irqN=apic,pin statements are used to manually
route the PCI interrupt pins to the appropriate IRQs instead.
isashare
Allows an ISA interrupt source to route to an IRQ that is already in
use by another interrupt type. Some machines disconnect PCI inter-
rupts from the ISA interrupt set (they are routed as 'pci' inter-
rupts, separate from all of the ISA interrupts); setting this option
allows the interrupt that was previously overridden by a PCI inter-
rupt to be delivered to its IRQ (along with the PCI interrupt). All
interrupts routed in this manner are assumed to be edge sensitive.
This option may also be used when it is unknown which interrupts
will be delivered via ExtINT and which via the BIOS interrupt rout-
ing. In this case all the ExtINT sources plus all the BIOS defined
ISA pins can simultaneously route to their respective IRQs.
noautoeoi
If the extclk override is used this option will run the 8259 PIC in
normal (non auto-eoi) mode. This forces a different interrupt han-
dler to be used for clock interrupts, not only must it EOI the APIC
but it must EOI the 8259. Use this only if the default (auto-eoi
mode) doesn't work (it is a little less efficient than the default).
ignore_defcfg
Some older BIOS'es report that the operating system should supply
the configuration details based on one of a number of predefined (by
the Intel MPS 1.4) configurations. It is possible for the BIOS to
request a default MPS configuration and then also supply details
(which possibly conflict the MPS version of the configuration). The
default behavior is to ignore the BIOS details if it calls for an
MPS default configuration, however, if ignore_defcfg is specified
then the BIOS supplied configuration will be used instead. This
override has no effect unless the BIOS supplies its own configura-
tion and simultaneously calls for an MPS default configuration.
irqN=apic,pin[,level][,edge][,high][,low][,excl]
This manually routes a given interrupt source (as described by apic
and pin ) to a given IRQ. The source must on an I/O APIC (single in-
terrupts cannot be delivered via CPU local APIC pins).
The level option indicates the pin should be programmed (and
blocked) as a level triggered source (ie: PCI). The edge option
forces edge trigger mode to be used on the interrupt pin. Edge or
level mode is normally automatically selected based on the source of
the interrupt. The high option forces triggering based on an active
high signal. The low option forces triggering based on an active low
signal. Normally the polarity is automatically selected based on the
source of the interrupt.
The excl flag indicates that no other interrupt sources may share
this IRQ (an error is generated if an other override specifies this
IRQ as a target. BIOS supplied routings are considered 'soft' for
this purpose, if any are mapped to an exclusive use IRQ they are in-
stead redirected to a handler that simply counts them. An example of
this case is one where an exclusive route is assigned from a PCI in-
terrupt source and yet the BIOS still defines an ISA interrupt
source for the same IRQ; in this case the isa IRQ will be redirected
to the stray interrupt catcher.
irqN=ext
This indicates that the named IRQ is to be handled via the 8259 PICs
(AT compatible mode) on an ExtINT pin (either connected directly to
a CPU or connected to an I/O apic).
noext
Disable all ExtINT inputs.
extclk
This forces a special mode where the external PIC is assumed to have
only one active interrupt (the clock, IRQ0) and the ExtINT pin is on
an I/O APIC. In this mode the APIC pin is programmed as a normal
interrupt (instead of an ExtINT input). This implies some additional
work in the interrupt handler to manage the 8259 as well as the APIC
when an interrupt is received (which is why there is a special mode
and a normal irq override isn't sufficient).
Normally a determination of the need to use this workaround is made
based on the identification of the chipset (the problem occurs in
chipsets which use the Intel 82371 PIIX3). If the device ID changes
in a newer version of the chip this keyword may be used as a
workaround until an update has been posted. A symptom of not using
this workaround when needed are that the counts for IRQ0 do not sow
up in the output of cpu stat.
noextclk
This forces the extclk workaround to not be used.
extint=apic,pin
This selects a particular source for the ExtINT input (this is the
chaining interrupt from the AT compatible 8259 interrupt con-
trollers). There may only be one ExtINT source active on a system.
The BIOS boot data normally supplies this routing, this override may
be needed if multiple ExtINT sources are defined by the BIOS. Rout-
ing ExtINT to the non-boot processor may cause the system to hang
before the target processor is started (or if the target processor
is stopped).
extdest=cpu
If the ExtINT source is on an I/O APIC this determines which CPU the
8259 interrupts will be routed to. Interrupts delivered via the Ex-
tINT mechanism can only be routed to one CPU (there is no mode to
automatically route them to the best processor as there is with APIC
interrupts). Routing interrupts to a processor other than the boot
processor may cause the system to hang before the target processor
is started (or if it is stopped).
nmi=apic,pin
This sets up the listed interrupt source as an NMI input (apic may
be a CPU or an I/O apic). Unless 'nmidest' is specified the NMI is
programmed in broadcast mode. If not given NMI routing is determined
by BIOS info.
nmidest=cpu
Sets the destination for all NMI sources, if not specified the des-
tination is the broadcast address (all CPUs). This only has meaning
on I/O APIC sources that receive NMIs (the destination is always the
local CPU for CPU LINTn connections). There is no shorthand to
specify that NMI is wired to the same pin on each CPU, use multiple
nmi overrides.
nonmi
Do not route any NMI sources.
smi=apic,pin
This sets up the listed interrupt source as a system management
(SMI) input (apic may be a CPU or an I/O apic). Unless 'smidest' is
specified the SMI is programmed in broadcast mode. If not given SMI
routing is determined by BIOS info.
smidest=cpu
Sets the destination for all SMI sources, if not specified the des-
tination is the broadcast address (all CPUs). This only has meaning
on I/O APIC sources that receive SMIs (the destination is always the
local CPU for CPU LINTn connections). There is no shorthand to
specify that SMI is wired to the same pin on each CPU, multiple smi
overrides.
nosmi
Do not route any SMI sources.
unk=apic,pin
Routes the interrupt source given by apic and pin to an unknown in-
terrupt handler (this will keep count of any interrupts received on
the pin and print a message). This is valid only for I/O APIC based
interrupts.
apicN=physaddr
Indicates than an I/O APIC with ID N exists at the physical address
physaddr.
apicN=down
Indicates that I/O APIC N is not available (even if the BIOS says it
is).
cpuN=up|down
Indicate that a given CPU (APIC ID) exists or does not exist. This
overrides any data supplied by the BIOS.
FILES
/dev/cpu special file used to access MP kernel functions
/etc/mp.config default file to read override information from
ENVIRONMENT VARIABLES
MPINFO If set, overrides the default configuration file path (
/etc/mp.config ). Overridden by the -o command line option.
SEE ALSOcpu(4)BUGS
The mechanisms used to override various aspects of the interrupt routing
algorithm are flexible but much too complex.
HISTORY
The cpu first appeared in BSD/OS 4.0.
BSDI BSD/OS October 15, 1997 8
