NAME
mca – Machine Check Architecture
DESCRIPTION
The mca subsystem provides support for the x86 Machine Check Architecture. The CPU uses this architecture to report various hardware problems, ranging from correctible errors to uncorrectible fatal errors. The mca subsystem processes the errors reported by the CPU and logs them according to the user-supplied configuration.
The mca subsystem is automatically compiled into every x86 kernel.
LOGGING
By default, every message is logged to four locations:
-
The console
-
The system log (using the LOG_KERN syslog(3) facility)
-
An in-kernel cache of event records
-
A statistics array
An administrator can disable console logging of non-fatal errors using the hw.mca.uselog sysctl(8) or tunable setting. Fatal errors are always logged to the console.
The in-kernel cache of event records can be accessed from userspace using the hw.mca.records sysctl(8) node. By default, the in-kernel cache of event records grows without bound and contains records for all mca events received since system boot. The cache can be limited (in which case it turns into a ring buffer) or disabled altogether using the hw.mca.maxcount sysctl(8) or tunable setting.
The statistics array can be retrieved using the hw.mca.stats sysctl(8) node.
SYSCTL VARIABLES
The subsystem has a number of configuration options to control the way events are processed and logged. These options are configured via sysctl(8) variables or tunables. These settings control things such as log destination, event limiting, and sampling. These settings directly impact both the completeness of logs and the performance impact of processing mca events. A system administrator may want to review these and modify them to obtain the appropriate behavior in their environment.
- hw.mca.enabled
-
(Only settable as a tunable.)
If set to 0, the CPU is not configured to send mca messages to the kernel.
Default is 1 (enabled).
- hw.mca.log_corrected
-
(Settable as a tunable or sysctl.)
If enabled, corrected messages are logged to console, syslog, the in-kernel event cache, and the statistics array (subject to separate configuration controlling those facilities). If disabled, corrected messages are only logged to the in-kernel event cache (subject to separate configuration controlling that facility).
Default is 1 (enabled).
- hw.mca.intel6h_HSD131
-
(Only settable as a tunable.)
This setting enables a workaround for benign corrected parity errors which may be reported by certain Intel desktop Haswell CPUs. (The name "HSD131" comes from the name of the Intel erratum report about this issue.)
Default is 0 (disabled).
- hw.mca.amd10h_L1TP
-
(Only settable as a tunable.)
Enable logging of level one TLB parity errors on certain AMD CPUs. This option has no impact on other CPUs.
Default is 1 (enabled).
- hw.mca.erratum383
-
(Only settable as a tunable.)
This setting enables a workaround for Erratum 383 on AMD Family 10h CPUs. The erratum changes the way pages are promoted to or demoted from being super-pages. On affected AMD CPUs, either hw.mca.amd10h_L1TP or hw.mca.erratum383 must be on. If both are off, the system will dynamically enable hw.mca.erratum383 at boot time.
Default is 0 (disabled).
- hw.mca.uselog
-
(Settable as a tunable or sysctl.)
If enabled, the system will send messages about non-fatal mca events to syslog and not to the console. If disabled, the system will send messages about non-fatal mca events to both syslog and the console. Fatal events are always logged to the console.
Default is false (disabled).
- hw.mca.stats
-
(Read-only sysctl.)
This returns an array of MCA_T_COUNT uint64_t values. The enum mca_stat_types definition in ⟨x86/mca.h⟩ provides the value of MCA_T_COUNT and the index values for various event types.
- hw.mca.log_interval
-
(Settable as a tunable or sysctl.)
This sets the minimum time (in seconds) between logging correctible errors. The rate limit is only applied after the system records a reasonable number of errors of the same type. The goal is to reduce the impact of the system seeing and attempting to log a burst of similar errors, which can be expensive (especially when printed to the console). If this setting is 0, no rate limit is applied.
Default is 0 (no rate limit).
- hw.mca.cmc_throttle
-
(Settable as a tunable or sysctl. Only available if apic(4) support is enabled and the hardware supports CMC interrupt throttling.)
This sets the maximum time (in seconds) to throttle CMC interrupts. In normal operation, the system attempts to receive CMC interrupts as soon as an event occurs. However, if a high rate of events occurs in a short time, the system will begin throttling the CMC interrupts. While the events continue to occur at a high rate, the system will gradually increase the throttling interval until it reaches the hw.mca.cmc_throttle setting.
Default is 60 seconds.
- hw.mca.count
-
(Read-only sysctl.)
This returns the current number of mca records in the in-kernel cache. This can be used to determine how many records are available to read with the hw.mca.records sysctl(8) interface. It can also be used to monitor the amount of memory used by the in-kernel record cache.
- hw.mca.maxcount
-
(Settable as a tunable or sysctl.)
This setting controls the size and behavior of the in-kernel cache of mca records. If the setting is -1, the in-kernel cache grows without bounds and contains a complete record events since boot or the last time the hw.mca.maxcount setting was changed. If the setting is 0, the in-kernel cache is disabled. If the setting is a positive integer, the in-kernel cache functions as a ring buffer with the number of entries defined by the setting.
Default is -1 (unlimited).
- hw.mca.interval
-
(Settable as a tunable or sysctl.)
This setting controls how often (in seconds) the kernel should proactively scan for new mca events. In many circumstances, the CPU will send an interrupt to signal new events. However, there are cases where the periodic scan for events will discover new events.
Default is 300 seconds.
- hw.mca.force_scan
-
(Settable only as a sysctl.)
Setting this to any non-zero value will force an immediate scan for mca events. Setting this to zero has no effect. This is functionally a write-only setting. The current value is always 0, even when a scan is running.
Default is 0 (no scan requested).
- hw.mca.records.n
-
(Read-only sysctl.)
This is used to copy mca records from the in-kernel cache to a user space process. The n value in the sysctl(8) node is an integer index into the in-kernel cache. (Or, put differently, the "new" value describes how many records the kernel should skip to find the desired record.) The return value is a struct mca_record, which is defined in ⟨x86/mca.h⟩.
LOADER TUNABLES
Tunables can be set at the loader(8) prompt before booting the kernel or stored in /boot/loader.conf. The tunables all have corresponding sysctl(8) entries. The tunables are listed above in the SYSCTL VARIABLES section.
COMPATIBILITY
mca is only available on x86 systems.
SEE ALSO
AUTHORS
The mca subsystem was originally written by John Baldwin ⟨[email protected]⟩.
This manual page was written by Jonathan Looney ⟨[email protected]⟩.