pub/scm/utils/cpu/mce/mcelog.git  about / heads / tags
Linux x86 machine check user space processing utility
$ git log --pretty=format:'%h %s (%cs)%d'
c17897d server: Correct prameter type for connect() API (2024-05-16)
	(HEAD -> master, tag: v199)
23c2487 Remove obsolete on disk dimm database code (2024-03-28)
ab58f07 page.c: Disable gcc warnings (2024-03-27)
	(tag: v198)
d94de7f page.c: Remove obsolete comment (2024-03-27)
569b3ce mcelog: Fix clang warnings (2024-03-27)
c0f843b mcelog: mempage_replace missing initialization of mempage fields (2024-03-27)
2e7e64d mcelog: Add third model number for Arrowlake (2024-03-24)
f5615e9 mcelog: Add kernel CONFIG message if /dev/mcelog isn't found (2024-01-18)
a325ae1 Merge pull request #120 from meow-watermelon/add_ping_option (2024-01-06)
320a128 address comments (2024-01-06)
...

$ git cat-file blob HEAD:README.md
# mcelog

mcelog is the user space backend for logging machine check errors reported
by the hardware to the kernel. The kernel does the immediate actions
(like killing processes etc.) and mcelog decodes the errors and manages
various other advanced error responses like offlining memory, CPUs or triggering
events. In addition mcelog also handles corrected errors, by logging and
accounting them.
It primarily handles machine checks and thermal events, which are reported
for errors detected by the CPU.

For more details on what mcelog can do and the underlying theory
see [mcelog.org](https://www.mcelog.org).

It is recommended that mcelog runs on all x86 machines, both 64bit
(since early 2.6) and 32bit (since 2.6.32).

mcelog can run in several modes:

- cronjob
- trigger
- daemon

**cronjob** is the old method. mcelog runs every 5 minutes from cron and checks
for errors. Disadvantage of this is that it can delay error reporting
significantly (upto 10 minutes) and does not allow mcelog to keep extended state.

**trigger** is a newer method where the kernel runs mcelog on a error.

This is configured with:
```sh
echo /usr/sbin/mcelog > /sys/devices/system/machinecheck/machinecheck0/trigger
```
This is faster, but still doesn't allow mcelog to keep state,
and has relatively high overhead for each error because a program has
to be initialized from scratch.

In **daemon** mode mcelog runs continuously as a daemon in the background and
wait for errors. It is enabled by running `mcelog --daemon &`
from a init script. This is the fastest and most feature-ful.

The recommended mode is **daemon**, because several new functions (like page
error predictive failure analysis) require a continuously running daemon.

## Documentation

- The primary reference documentation are the man pages.
- [lk10-mcelog.pdf](lk10-mcelog.pdf)
  has a overview over the errors mcelog handles (originally from Linux Kongress 2010).
- [mce.pdf](mce.pdf)
  is a very old paper describing the first releases of mcelog (some parts are obsolete).

## For distributors

You can run mcelog from systemd or similar daemons. An example systemd unit
file is in `mcelog.service`.

By default mcelog reports its version as the git tag. This can be overridden
by setting up a `.os_version` file in the source directory. A build system
could write the OS version to this file to mark the binary.

### For older distributions using init scripts

Please install an init script by default that runs mcelog in daemon mode.
The `mcelog.init` script is a good starting point. Also install a
logrotated file (mcelog.logrotate) or equivalent when mcelog is running
in daemon mode.
These two are not in make install.

The installation also requires a config file `/etc/mcelog.conf` and the default
triggers. These are all installed by `make install`

`/dev/mcelog` is needed for mcelog operation. If it's not there it can be
created with:
```sh
mknod /dev/mcelog c 10 227
```

Normally it should be created automatically in udev.

## Security

mcelog needs to run as root because it might trigger actions like
page-offlining, which require `CAP_SYS_ADMIN`. Also it opens `/dev/mcelog`
and an UNIX socket for client support.

It also opens `/dev/mem` to parse the BIOS DMI tables. It is careful to close
the file descriptor and unmap any mappings after using them.

There is support for changing the user in daemon mode after opening the device
and the sockets, but that would stop triggers from doing corrective action
that require `root`.

In principle it would be possible to only keep `CAP_SYS_ADMIN` for page-offling,
but that would prevent triggers from doing root-only actions not covered by
it (and `CAP_SYS_ADMIN` is not that different from full root)

In `daemon` mode mcelog listens to a UNIX socket and processes requests from
`sh mcelog --client`. This can be disabled in the configuration file.
The uid/gid of the requestor is checked on access and is configurable
(default 0/0 only). The command parsing code is very straight forward
(server.c). The client parsing/reply is currently done with full privileges
of the `daemon`.

## Testing

There is a simple test suite in `sh tests/`. The test suite requires root to
run and access to mce-inject and a kernel with MCE injection support
`CONFIG_X86_MCE_INJECT`.  It will kill any running mcelog daemon.

Run it with `sh make test`.

The test suite requires the
[mce-inject](git://git.kernel.org/pub/utils/cpu/mce/mce-inject.git) tool.
The `mce-inject` executable must be either in `$PATH` or in the
`../mce-inject` directory.

You can also test under **valgrind** with `sh make valgrind-test`. For this
valgrind needs to be installed of course. Advanced valgrind options can be
specified with:
```sh
make VALGRIND="valgrind --option" valgrind-test
```

### Other checks

`make iccverify` and `make clangverify` run the static verifiers in *clang*
and *icc* respectively.

## License

This program is licensed under the subject of the GNU Public General
License, v.2

# heads (aka `branches'):
$ git for-each-ref --sort=-creatordate refs/heads \
	--format='%(HEAD) %(refname:short) %(subject) (%(creatordate:short))'
* master       server: Correct prameter type for connect() API (2024-05-16)

# tags:
$ git for-each-ref --sort=-creatordate refs/tags \
	--format='%(refname:short) %(subject) (%(creatordate:short))'
v199         server: Correct prameter type for connect() API (2024-05-16) tar.gz
v198         page.c: Disable gcc warnings (2024-03-27) tar.gz
v197         Merge pull request #119 from meow-watermelon/point_freed_ptr_null (2024-01-02) tar.gz
v196         mcelog: Add second model number for Arrowlake (2023-10-31) tar.gz
v195         mcelog: Wire up model-specific decoding for Sierra Forest (2023-09-06) tar.gz
v194         mcelog: New model number for Arrowlake (2023-04-05) tar.gz
v193         mcelog: Don't overwrite model number when lookup fails (2023-04-03) tar.gz
v192         mcelog: Add Graniterapids, Grandridge and Sierraforest (2023-03-10) tar.gz
v191         Merge branch 'master' of ssh://github.com/andikleen/mcelog (2023-01-12) tar.gz
v190         mcelog: Add support for Meteor Lake (2022-11-01) tar.gz
...

# associated public inboxes:
# (number on the left is used for dev purposes)
         10 lkml
          6 u-boot
          4 qemu-devel
          3 linux-nfs
          3 netfilter-devel
          3 linux-edac
          3 linux-devicetree
          3 linux-arm-kernel
          3 linux-iio
          3 linux-gpio
          3 dpdk-dev
          3 git
          3 buildroot
          2 linux-wireless
          2 linux-mtd
          2 linux-arm-msm
          2 linux-mm
          2 netdev
          2 linux-media
          2 xen-devel
          2 stable
          2 linux-mips
          2 linux-pm
          2 linux-hwmon
          2 alsa-devel
          2 linux-scsi
          2 linux-rdma
          2 linux-next
          2 linuxppc-dev
          2 linux-watchdog
          2 linux-i3c
          2 util-linux
          2 linux-wpan
          2 linux-mmc
          2 dri-devel
          2 linux-i2c
          2 linux-kbuild
          2 linux-rockchip
          2 dm-devel
          2 fio
          2 openembedded-core
          2 linux-patches
          2 xenomai
          2 poky
          2 qemu-riscv
          2 grub-devel
          1 linux-samsung-soc
          1 linux-fscrypt
          1 cocci
          1 linux-block
          1 linux-riscv
          1 linux-nvme
          1 linux-xfs
          1 live-patching
          1 bpf
          1 linux-mediatek
          1 linux-crypto
          1 linux-efi
          1 linux-acpi
          1 linux-integrity
          1 linux-fsdevel
          1 linux-cifs
          1 linux-amlogic
          1 linux-erofs
          1 linux-nvdimm
          1 linux-iommu
          1 linux-snps-arc
          1 fstests
          1 linux-rtc
          1 linux-input
          1 linux-btrfs
          1 kvmarm
          1 driverdev-devel
          1 linux-usb
          1 linux-renesas-soc
          1 linux-kselftest
          1 selinux
          1 kernel-hardening
          1 linux-clk
          1 dmaengine
          1 linux-parisc
          1 linux-ext4
          1 linux-leds
          1 linux-security-module
          1 linux-pci
          1 linux-f2fs-devel
          1 kvm
          1 linux-modules
          1 kernelnewbies
          1 linux-rt-users
          1 linux-bluetooth
          1 linux-sgx
          1 linux-ide
          1 linux-serial
          1 linux-trace-devel
          1 linux-hyperv
          1 workflows
          1 rcu
          1 linux-m68k
          1 linux-spdx
          1 ksummit-discuss
          1 wireguard
          1 backports
          1 io-uring
          1 linux-kernel-mentees
          1 linux-doc
          1 linux-csky
          1 linux-man
          1 amd-gfx
          1 intel-gfx
          1 tpmdd-devel
          1 linux-unionfs
          1 linux-firmware
          1 linux-api
          1 cip-dev
          1 linux-omap
          1 linux-audit
          1 linux-spi
          1 linux-remoteproc
          1 linux-dash
          1 linux-bcache
          1 linux-sparse
          1 mm-commits
          1 linux-pwm
          1 linux-tegra
          1 lttng-dev
          1 virtualization
          1 linux-fpga
          1 ceph-devel
          1 linux-arch
          1 linux-can
          1 containers
          1 linux-raid
          1 xdp-newbies
          1 platform-driver-x86
          1 phone-devel
          1 openbmc
          1 linux-hardening
          1 dash
          1 keyrings
          1 linux-fbdev
          1 linux-sctp
          1 linux-cxl
          1 linux-perf-users
          1 target-devel
          1 lustre-devel
          1 linux-sh
          1 soc
          1 ocfs2-devel
          1 rust-for-linux
          1 ath10k
          1 ath11k
          1 nouveau
          1 linux-phy
          1 linux-s390
          1 kernel-janitors
          1 sparclinux
          1 linux-staging
          1 linux-sunxi
          1 mptcp
          1 linux-coco
          1 regressions
          1 ksummit
          1 b43-dev
          1 nvdimm
          1 linux-nfc
          1 linux-bcachefs
          1 ath9k-devel
          1 ntfs3
          1 llvm
          1 iwd
          1 ell
          1 ofono
          1 ltp
          1 yocto
          1 yocto-meta-freescale
          1 yocto-toaster
          1 yocto-meta-arm
          1 yocto-docs
          1 openembedded-devel
          1 bitbake-devel
          1 yocto-meta-virtualization
          1 chrome-platform
          1 ntb
          1 yocto-meta-ti
          1 yocto-meta-arago
          1 outreachy
          1 damon
          1 asahi
          1 openrisc
          1 intel-wired-lan
          1 kexec
          1 loongarch
          1 imx
          1 ath12k
          1 b4-sent
          1 linux-trace-kernel
          1 oe-linux-nfc
          1 oe-kbuild-all
          1 oe-chipsec
          1 batman
          1 intel-xe
          1 linux-um
          1 virtio-dev
          1 virtio-comment
          1 v9fs
          1 ecryptfs
          1 linux-ia64
          1 cluster-devel
          1 kbd
          1 autofs
          1 cpufreq
          1 dccp
          1 cgroups
          1 devicetree-spec
          1 devicetree-compiler
          1 initramfs
          1 kvm-ppc
          1 hail-devel
          1 kvm-ia64
          1 linux-8086
          1 kernel-testers
          1 linux-alpha
          1 linux-btrace
          1 linux-embedded
          1 linux-hams
          1 linux-hexagon
          1 linux-hotplug
          1 linux-laptop
          1 linux-sound
          1 trinity
          1 reiserfs-devel
          1 linux-metag
          1 linux-x25
          1 linux-nilfs
          1 lvs-devel
          1 netfilter
          1 linux-oxnas
          1 u-boot-amlogic
          1 lm-sensors
          1 lvm-devel
          1 acpica-devel
          1 perfbook
          1 virtio-fs
          1 smatch
          1 ../../../../../../fuego
          1 ../../../../../../wireless-regdb
          1 ../../../../../../igt-dev
          1 ../../../../../../powertop

git clone https://yhbt.net/lore/pub/scm/utils/cpu/mce/mcelog.git