1.\" 2.\" Copyright (c) 2026 The FreeBSD Project 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd January 14, 2026 7.Dt MCA 4 amd64 8.Os 9.Sh NAME 10.Nm mca 11.Nd Machine Check Architecture 12.Sh DESCRIPTION 13The 14.Nm 15subsystem provides support for the x86 Machine Check Architecture. 16The CPU uses this architecture to report various hardware problems, 17ranging from correctible errors to uncorrectible fatal errors. 18The 19.Nm 20subsystem processes the errors reported by the CPU and logs them 21according to the user-supplied configuration. 22.Pp 23The 24.Nm 25subsystem is automatically compiled into every x86 kernel. 26.Sh LOGGING 27By default, every message is logged to four locations: 28.Bl -bullet 29.It 30The console 31.It 32The system log (using the 33.Dv LOG_KERN 34.Xr syslog 3 35facility) 36.It 37An in-kernel cache of event records 38.It 39A statistics array 40.El 41.Pp 42An administrator can disable console logging of non-fatal errors using the 43.Va hw.mca.uselog 44.Xr sysctl 8 45or tunable setting. 46Fatal errors are always logged to the console. 47.Pp 48The in-kernel cache of event records can be accessed from userspace using the 49.Va hw.mca.records 50.Xr sysctl 8 51node. 52By default, the in-kernel cache of event records grows without bound and 53contains records for all 54.Nm 55events received since system boot. 56The cache can be limited (in which case it turns into a ring buffer) or 57disabled altogether using the 58.Va hw.mca.maxcount 59.Xr sysctl 8 60or tunable setting. 61.Pp 62The statistics array can be retrieved using the 63.Va hw.mca.stats 64.Xr sysctl 8 65node. 66.Sh SYSCTL VARIABLES 67The subsystem has a number of configuration options to control the 68way events are processed and logged. 69These options are configured via 70.Xr sysctl 8 71variables or tunables. 72These settings control things such as log destination, event limiting, 73and sampling. 74These settings directly impact both the completeness of logs and the performance 75impact of processing 76.Nm 77events. 78A system administrator may want to review these and modify them to obtain 79the appropriate behavior in their environment. 80.Bl -tag -width indent 81.It Va hw.mca.enabled 82(Only settable as a tunable.) 83.Pp 84If set to 0, the CPU is not configured to send 85.Nm 86messages to the kernel. 87.Pp 88Default is 1 (enabled). 89.It Va hw.mca.log_corrected 90(Settable as a tunable or sysctl.) 91.Pp 92If enabled, corrected messages are logged to console, syslog, the in-kernel 93event cache, and the statistics array (subject to separate configuration 94controlling those facilities). 95If disabled, corrected messages are only logged to the in-kernel event 96cache (subject to separate configuration controlling that facility). 97.Pp 98Default is 1 (enabled). 99.It Va hw.mca.intel6h_HSD131 100(Only settable as a tunable.) 101.Pp 102This setting enables a workaround for benign corrected parity errors which 103may be reported by certain Intel desktop Haswell CPUs. 104(The name "HSD131" comes from the name of the Intel erratum report about this 105issue.) 106.Pp 107Default is 0 (disabled). 108.It Va hw.mca.amd10h_L1TP 109(Only settable as a tunable.) 110.Pp 111Enable logging of level one TLB parity errors on certain AMD CPUs. 112This option has no impact on other CPUs. 113.Pp 114Default is 1 (enabled). 115.It Va hw.mca.erratum383 116(Only settable as a tunable.) 117.Pp 118This setting enables a workaround for Erratum 383 on AMD Family 10h CPUs. 119The erratum changes the way pages are promoted to or demoted from being 120super-pages. 121On affected AMD CPUs, either 122.Va hw.mca.amd10h_L1TP 123or 124.Va hw.mca.erratum383 125must be on. 126If both are off, the system will dynamically enable 127.Va hw.mca.erratum383 128at boot time. 129.Pp 130Default is 0 (disabled). 131.It Va hw.mca.uselog 132(Settable as a tunable or sysctl.) 133.Pp 134If enabled, the system will send messages about non-fatal 135.Nm 136events to syslog and not to the console. 137If disabled, the system will send messages about non-fatal 138.Nm 139events to both syslog and the console. 140Fatal events are always logged to the console. 141.Pp 142Default is false (disabled). 143.It Va hw.mca.stats 144(Read-only sysctl.) 145.Pp 146This returns an array of 147.Va MCA_T_COUNT 148uint64_t values. 149The 150.Vt "enum mca_stat_types" 151definition in 152.In x86/mca.h 153provides the value of 154.Va MCA_T_COUNT 155and the index values for various event types. 156.It Va hw.mca.log_interval 157(Settable as a tunable or sysctl.) 158.Pp 159This sets the minimum time (in seconds) between logging correctible errors. 160The rate limit is only applied after the system records a reasonable 161number of errors of the same type. 162The goal is to reduce the impact of the system seeing and attempting to log 163a burst of similar errors, which can be expensive (especially when printed 164to the console). 165If this setting is 0, no rate limit is applied. 166.Pp 167Default is 0 (no rate limit). 168.It Va hw.mca.cmc_throttle 169(Settable as a tunable or sysctl. Only available if 170.Xr apic 4 171support is enabled and the hardware supports CMC interrupt throttling.) 172.Pp 173This sets the maximum time (in seconds) to throttle CMC interrupts. 174In normal operation, the system attempts to receive CMC interrupts as soon as 175an event occurs. 176However, if a high rate of events occurs in a short time, the system will 177begin throttling the CMC interrupts. 178While the events continue to occur at a high rate, the system will gradually 179increase the throttling interval until it reaches the 180.Va hw.mca.cmc_throttle 181setting. 182.Pp 183Default is 60 seconds. 184.It Va hw.mca.count 185(Read-only sysctl.) 186.Pp 187This returns the current number of 188.Nm 189records in the in-kernel cache. 190This can be used to determine how many records are available to read with the 191.Va hw.mca.records 192.Xr sysctl 8 193interface. 194It can also be used to monitor the amount of memory used by the in-kernel 195record cache. 196.It Va hw.mca.maxcount 197(Settable as a tunable or sysctl.) 198.Pp 199This setting controls the size and behavior of the in-kernel cache of 200.Nm 201records. 202If the setting is -1, the in-kernel cache grows without bounds and contains a 203complete record events since boot or the last time the 204.Va hw.mca.maxcount 205setting was changed. 206If the setting is 0, the in-kernel cache is disabled. 207If the setting is a positive integer, the in-kernel cache functions as a ring 208buffer with the number of entries defined by the setting. 209.Pp 210Default is -1 (unlimited). 211.It Va hw.mca.interval 212(Settable as a tunable or sysctl.) 213.Pp 214This setting controls how often (in seconds) the kernel should proactively 215scan for new 216.Nm 217events. 218In many circumstances, the CPU will send an interrupt to signal new events. 219However, there are cases where the periodic scan for events will discover 220new events. 221.Pp 222Default is 300 seconds. 223.It Va hw.mca.force_scan 224(Settable only as a sysctl.) 225.Pp 226Setting this to any non-zero value will force an immediate scan for 227.Nm 228events. 229Setting this to zero has no effect. 230This is functionally a write-only setting. 231The current value is always 0, even when a scan is running. 232.Pp 233Default is 0 (no scan requested). 234.It Va hw.mca.records.n 235(Read-only sysctl.) 236.Pp 237This is used to copy 238.Nm 239records from the in-kernel cache to a user space process. 240The 241.Va n 242value in the 243.Xr sysctl 8 244node is an integer index into the in-kernel cache. 245(Or, put differently, the "new" value describes how many records the kernel 246should skip to find the desired record.) 247The return value is a 248.Vt "struct mca_record" , 249which is defined in 250.In x86/mca.h . 251.El 252.Sh LOADER TUNABLES 253Tunables can be set at the 254.Xr loader 8 255prompt before booting the kernel or stored in 256.Pa /boot/loader.conf . 257The tunables all have corresponding 258.Xr sysctl 8 259entries. 260The tunables are listed above in the 261.Sx SYSCTL VARIABLES 262section. 263.Sh COMPATIBILITY 264.Nm 265is only available on x86 systems. 266.Sh SEE ALSO 267.Xr loader.conf 5 , 268.Xr sysctl 8 , 269.Xr syslogd 8 270.Sh AUTHORS 271The 272.Nm 273subsystem was originally written by 274.An John Baldwin Aq Mt jhb@FreeBSD.org . 275.Pp 276This manual page was written by 277.An Jonathan Looney Aq Mt jtl@FreeBSD.org . 278