cpupdate manpage draft

     cpupdate - cpu microcode analysis and updating tool

     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]]

     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 
     naming convention.
     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
     microcodes reside.
     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


     to /etc/rc.conf.

     -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
     -U updatefile 
          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
     -p primary-repo-path
          Use this base directory for primary update repo, instead
          of default /usr/local/share/cpupdate/CPUMicrocodes/primary
     -s secondary-repo-path
          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.
     -f filepath
           Get internal stats of the microcode file specified
     -d dirpath 
           Get internal stats of the microcode file
           contained in the directory specified  
     -c repo-path
          Verify the integrity of the microcode files in the repo path
     -S source-path
          Specify source directory for combine or extraction function.
     -T target-path
   Specify 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-blobbed 
microcode files (new Intel format)  
     -X   Extract multi-blobbed microcode files to single-blobbed ones.
     (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.

     None yet. Probably should be some settings for paths or the like.
     (Suggestions needed) 
     Use the -vv option to find out what is happening in more detail.
     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 to
     the 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... 

     Stefan Blachmann <sblachmann at gmail dot com>, Stanislav Sedov,
     Eugene Grosbein <... at ... dot ...>, Olivier Cochard, ... 
     (to be completed)
     lscpu(1), cpucontrol(8)


Beliebte Posts aus diesem Blog

Notes for making the sysutils/cpupdate port, testing, review etc

Exposed: The missing Meltdown/Spectre microcode updates - is Intel lying to the public?