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 

     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

          cpupdate_enable="YES"

     to /etc/rc.conf.

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

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

           contained in the directory specified  

     -c repo-path

          Verify the integrity of the microcode files in the repo path

          given.

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


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

FILES
     

         /usr/local/share/cpupdate/CPUMicrocodes/primary

     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.

         /usr/local/share/cpupdate/CPUMicrocodes/secondary

     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.

     (Suggestions needed) 

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

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)