cpupdate manpage draft
NAME cpupdate - cpu microcode analysis and updating tool SYNOPSIS cpupdate -i [-v[v]] cpupdate -u [-w] [-p primary-path] [-p secondary-path] [-v[v] | -q] cpupdate -U microcode-file [-w] [-v[v] | -q] cpupdate -V cpupdate -h cpupdate -f -I microcode-file [-v[v]] cpupdate -c -I microcode-dir [-v[v]] cpupdate -C -I -S source-dir -T target-dir [-v[v]] cpupdate -X -I -S source-dir -T target-dir [-v[v]] DESCRIPTION cpupdate is a tool for tasks related to microcode updating.
Display the CPU family, model, stepping and microcode version.
Show the internal characteristics of microcode update files.
Convert back and forth microcode files between the legacy and
the new multi-blobbed Intel format.
Verify integrity of microcode files.
Update the processor's microcode and register the processor
features added by the microcode update (if any).
Intel in 2015 introduced the new multi-blobbed microcode file
format, recognizable by the FF-MM-SS family-model-stepping
Using the new format allows cpupdate to directly pick the
correct microcode file.
It does not need to walk through thousands of files, as legacy
microcode updaters often do.
When you download updated Intel microcodes, place the contents
of the archive's intel-ucode subdirectory into the microcode
primary repo directory (see -p option below).
If only legacy format files are available, cpupdate can
convert them to the modern format. It also can convert modern
format files to legacy format.
By changing the default directory paths, the microcode update
files could be loaded from a centralized repository server
instead from the default directories where the OS-supplied
In these repository directories there are vendor-specific
subdirectories, namely 'Intel', 'AMD' and 'VIA', which contain
the microcodes for the respective makes.
(NOTE: Only Intel support implemented atm)
All options except iuU can be run as regular user.
To enable updating microcode at boot time, add a line
OPTIONS-q quiet mode. Does not output to screen unless errors happen.-v verbose mode. For debugging use twice (-vv).-i Displays the microprocessor core family-model-stepping
and installed microcode version.
-u update microcode, searching the default (or overridden)
library directories for applicable microcodes
update microcode using specified file name.
This overrides automatic file detection and path searching.
-w write actually. Without this option the update process is
only dry-run simulation
-V print version
-h print short help
Use this base directory for primary update repo, instead
of default /usr/local/share/cpupdate/CPUMicrocodes/primary
Use this base directory for primary update repo, instead
of default /usr/local/share/cpupdate/CPUMicrocodes/secondary
-I | -A | -V
sets vendor mode for the integrity checking, combine and
extraction functions described below.
Get internal stats of the microcode file specified
Get internal stats of the microcode files
contained in the directory specified
Verify the integrity of the microcode files in the repo path
Specify source directory for combine or extraction function.
-T target-pathSpecify target directory for combine or extraction function.
In most cases you'll want to make sure it is empty beforehand.-C Combine single-blobbed microcode files to multi-blobbedmicrocode files (new Intel format)-X Extract multi-blobbed microcode files to single-blobbed ones.EXAMPLES
(Note: Use the -v or -vv options to get more detailed output)
Shows the cpu info:
# cpupdate -i
Found CPU(s) from Intel Core 0 to 11: CPUID: 206c2 Fam 06 Mod 2c ...
... Step 02 Flag 01 uCode 0000001d
Updates the processor microcode (assuming the microcode files
are in their default locations (see -p and -s option description):
# cpupdate -u
Shows microcode file stats:
% cpupdate -I -f mypath/cpu206C2_plat03
Verifies integrity of microcode files in a given directory:
% cpupdate -I -c somedir
Converts single-blobbed microcode files contained in <somedir>
to new Intel format multi-blobbed files being placed in <targetdir>:
% cpupdate -I -S somedir -T targetdir -C
Extracts multi-blobbed microcode files contained in <somedir>
to single-blobbed files being placed in <targetdir>:
% cpupdate -I -S somedir -T targetdir -X
This directory gets searched first for microcode files (unless
overridden by the -p option). Intended usage is to place newest
manufacturer's microcode files there.
If no matching update found in the primary directory, this
directory gets searched (unless overridden by the -s option).
Usually there a larger, potentially less recent microcode
collection should be placed.
ENVIRONMENT None yet. Probably should be some settings for paths or the like.
DIAGNOSTICS Use the -vv option to find out what is happening in more detail.
NOTES / BUGS Registering the new processor functions/flags after microcode
updating requires the CPUCTL_EVAL_CPU_FEATURES feature, which
is not available on FreeBSD prior to 11.1.1.
cpupdate can be compiled on older FreeBSD versions down to 7.2,
on these will be a notice that new processor flags are not being
used by the kernel.
Originally it was planned to support extended headers for
Intel microcode files.
However it turned out that extended headers were apparently used
only once. And furthermore it was used in a manner incompatible tothe new filename convention.
The microcode files for 06-4A-08 and -09 of Aug 12, 2014 contain
the same microcode and refer to the other processor respective
in the extended header. Look yourself using the -f option.
So the (still incomplete) code for supporting the extended headers
has partly been disabled by "#if 0", so they are being displayed,
but are not considered when updating processors.
It can be re-enabled, should ever the need arise.
The author guesses that Intel itself decided to drop
extended headers in favor of a new file format because of the
complications they would cause.
The file owners and permissions in the -C and -X options possibly
should be set to root after generation, if not created by root.
When updating cpus with hyperthreading activated, it will look like
cpupdate only updates cores with even numbers, because every core
with odd number will look "is up-to-date".
The reason for this is that hyperthreading fakes the number of
cores to be double the real number of cores.
So actually core #1 is a "mirrored" copy of core #0 and so on.
Thus, when core #0 gets updated, core #1 gets updated, too.
This is harmless, but might be confusing.
Probably some actual bugs wait to be discovered yet, too...
AUTHORS AND CONTRIBUTORS Stefan Blachmann <sblachmann at gmail dot com>, Stanislav Sedov,
Eugene Grosbein <... at ... dot ...>, Olivier Cochard, ...
(to be completed)
SEE ALSO lscpu(1), cpucontrol(8)