Provided by: iucode-tool_1.5.1-1_i386 bug

NAME

       iucode_tool - Tool to manipulate Intel® IA‐32/X86‐64 microcode bundles

SYNOPSIS

       iucode_tool [options] [[-ttype] filename|dirname] ...

DESCRIPTION

       iucode_tool is an utility that can load Intel® processor microcode data
       from files in both text and binary microcode bundle formats.

       It can output a list of the microcodes  in  these  files,  merge  them,
       upload  them  to  the  kernel  (to  upgrade the microcode in the system
       processor cores) or write some of them out to a file in  binary  format
       for later use.

       iucode_tool  will  load  all  microcodes  in  the  specified  files and
       directories to memory,  in  order  to  process  them.   Duplicated  and
       outdated microcodes will be discarded.  It can read microcode data from
       standard input (stdin), by specifying a file name of “-” (minus sign).

       Microcode data files are assumed to be in .dat text format if they have
       a  .dat  suffix,  and to be in binary format otherwise.  Standard input
       (stdin) is assumed to be in .dat text format.  The  -t  option  can  be
       used  to change the type of the files specified after it, including for
       stdin.

       If a directory is specified, all files whose names do not begin with  a
       dot  will  be  loaded,  in  unspecified  order.  Nested directories are
       skipped.

       Empty files and directories are ignored, and will be skipped.

       You can select which  microcodes  should  be  written  out,  listed  or
       uploaded to the kernel using the -S, -s, --date-before and --date-after
       options.  Should none of those options  be  specified,  all  microcodes
       will be selected.

       You can upload the selected microcodes to the kernel, write them out to
       a file (in binary format), to a Linux early initramfs archive, to  per‐
       processor‐signature  files in a directory, or to per‐microcode files in
       a directory using the -w, --write-earlyfw, -k, -K, and -W options.

       For more information about Intel processor microcodes, please read  the
       included  documentation  and  the  Intel manuals listed in the SEE ALSO
       section.

OPTIONS

       iucode_tool accepts the following options:

       -q, --quiet
              Inhibit usual output.

       -v, --verbose
              Print more information.  Use more than once for added verbosity.

       -h, -?, --help
              List all available options and their meanings.

       --usage
              Show summary of options.

       -V, --version
              Show version of program.

       -t type
              Sets the file type of the following files. type can be:

              b      binary format.  This is  the  same  format  used  by  the
                     kernel  driver  and  the  BIOS/EFI, which is described in
                     detail by the Intel 64 and IA32  Architectures  Software
                     Developer's Manual, Volume 3A, section 9.11.

              d      Intel  microcode  .dat  text  format.  This is the format
                     normally used  by  Intel  to  distribute  microcode  data
                     files.

              r      recover  microcode in binary format.  Search uncompressed
                     generic binary files for microcodes  in  Intel  microcode
                     binary  format  to  recover.  Note: It can find microcode
                     that  will  not  pass  strict  checks,  and  thus   cause
                     iucode_tool   to   exit   if  the  --no-strict-checks  or
                     --ignore-broken options are not in effect.

              a      (default) iucode_tool will use the  suffix  of  the  file
                     name  to select the file type: .dat text format for files
                     that have a .dat suffix, and binary type otherwise.  Note
                     that for stdin, .dat text format is assumed.

       --downgrade
              When multiple versions of the microcode for a specific processor
              are available from different files, keep the one from  the  file
              loaded  last,  regardless  of revision levels.  Files are always
              loaded in the order they were specified  in  the  command  line.
              This option has no effect when just one file has been loaded.

       --no-downgrade
              When multiple versions of the microcode for a specific processor
              are available from  different  files,  keep  the  one  with  the
              highest revision level.  This is the default mode of operation.

       --strict-checks
              Perform  strict checks on the microcode data.  It will refuse to
              load microcodes and microcode data files  with  unexpected  size
              and  metadata.   It  will  also refuse to load microcode entries
              that have the same metadata, but different payload.  This is the
              default mode of operation.

       --no-strict-checks
              Perform  less  strict checks on the microcode data.  Use only if
              you happen to  come  across  a  microcode  data  file  that  has
              microcodes  with  weird sizes or incorrect non‐critical metadata
              (such as invalid dates), which you want to retain.  If you  just
              want to skip those, use the --ignore-broken option.

       --ignore-broken
              Skip  broken  microcode  entries  when  loading a microcode data
              file, instead of aborting program execution.  If  the  microcode
              entry  has  an  unsupported  format  or  had its header severely
              corrupted, all remaining data  in  the  file  will  have  to  be
              ignored.   In  that case, using a file type of recover microcode
              in binary format (-tr option) is recommended,  as  it  can  skip
              over badly mangled microcode data.

       --no-ignore-broken
              Abort  program  execution  if  a broken microcode is found while
              loading a microcode data file.  This  is  the  default  mode  of
              operation.

       -s ! | [!]signature[,pf_mask]
              Select microcodes by the specified signature and processor flags
              mask (pf_mask).  If pf_mask is specified, it  will  select  only
              microcodes  that  are suitable for at least one of the processor
              flag combinations present in the mask.

              Specify more than once to select more microcodes.   This  option
              can  be  combined  with  the --scan-system option to select more
              microcodes.  If signature is prefixed with  a  “!”  (exclamation
              mark),  it  will deselect microcodes instead.  Ordering matters,
              with later -s options overriding earlier ones.

              When specifying signature and pf_mask, hexadecimal numbers  must
              be  prefixed  with  “0x”,  and  octal numbers with “0”.  Decimal
              numbers must not have leading zeros,  otherwise  they  would  be
              interpreted as octal numbers.

              The special notation -s! (with no signature parameter) instructs
              iucode_tool  to  require   explicit   inclusion   of   microcode
              signatures   (using   the  non-negated  form  of  -s,  or  using
              --scan-system).

              The  --scan-system  option   has   precedence,   therefore   the
              microcodes it selects cannot be deselected.

       -S, --scan-system
              Select  microcodes  by  scanning  all  online processors on this
              system for their signatures.

              This option can be combined with the -s option  to  select  more
              microcodes.

              Should  the  signature  scan  fail on all online processors, the
              program will print a warning to the  user  and  continue  as  if
              --scan-system  had  not  been  specified.   This  is a fail‐safe
              condition when iucode_tool is used to install microcode  updates
              for the next boot.

       --date-before=YYYY-MM-DD and --date-after=YYYY-MM-DD
              Limit the selected microcodes by a date range.  The date must be
              given in ISO format, with four  digits  for  the  year  and  two
              digits  for  the  month  and  day  and  “-” (minus sign) for the
              separator.   Dates  are  not  range‐checked,  so  you  can   use
              --date-after=2000-00-00  to  select  all  microcodes dated since
              January 1st, 2000.

       --loose-date-filtering
              When a date range is specified, all revisions of  the  microcode
              will  be considered for selection (ignoring just the date range,
              all other filters still apply) should  any  of  the  microcode's
              revisions be within the date range.

       --strict-date-filtering
              When a date range is specified, select only microcodes which are
              within the date range.  This is the default mode of operation.

       -l, --list
              List selected microcode signatures to standard output (stdout).

       -L, --list-all
              List all microcode signatures while they're being  processed  to
              standard output (stdout).

       -k[device], --kernel[=device]
              Upload  selected  microcodes  to  the  kernel.   Optionally, the
              device path  can  be  specified  (default:  /dev/cpu/microcode).
              This  update method is deprecated: it will be removed eventually
              from the kernel and from iucode_tool.

       -K[directory], --write-firmware[=directory]
              Write selected microcodes with the file names  expected  by  the
              Linux  kernel  firmware  loader.   Optionally,  the  destination
              directory can be specified (default: /lib/firmware/intelucode).

       -wfile, --write-to=file
              Write selected microcodes to a file in binary format.

       --write-earlyfw=file
              Write selected microcodes to an early initramfs  archive,  which
              should be prepended to the regular initramfs to allow the kernel
              to update processor microcode very early during system boot.

       -Wdirectory, --write-named-to=directory
              Write  selected  microcodes  to  the  specified  directory,  one
              microcode  per  file,  in binary format.  The file names reflect
              the microcode signature, mask and revision.

       --write-all-named-to=directory
              Write every microcode to the specified directory, one  microcode
              per  file,  in  binary  format.   The  file  names  reflect  the
              microcode signature, mask and revision.  This is the only way to
              write out every revision of the same microcode.

       --overwrite
              Remove  the destination file before writing, if it exists and is
              not a directory.  The destination file is  not  overwritten  in‐
              place.   Hardlinks  will  be  severed,  and  any existing access
              permissions, ACLs and  other  extended  attributes  of  the  old
              destination file will be lost.

       --no-overwrite
              Abort  if  the  destination  file  already  exists.  This is the
              default mode of operation.  Do note that  iucode_tool  does  not
              follow non‐directory symlinks when writing files.

NOTES

       iucode_tool  reads  all data to memory before doing any processing.  It
       enforces a sanity limit of a maximum of 1GiB worth of binary  microcode
       data per microcode data file.

       All  informational  and  error  messages  are  sent  to  standard error
       (stderr), while user‐requested output (such as output generated by  the
       list options) is sent to standard output (stdout).

       iucode_tool  creates  files with permissions 0644 (rw-r--r--), modified
       by the current umask.

       iucode_tool's selected microcode listing and microcode output files are
       sorted  by  cpu  signature,  however  the  ordering  inside  a group of
       microcodes that share the  same  cpu  signature  is  undefined:  it  is
       deterministic, but it is sensitive to command line parameters and their
       ordering, and also depends on the ordering of the individual microcodes
       inside each loaded data file.

       When  multiple  revisions  of  a microcode are selected, the older ones
       will be skipped.  Only the newest selected revision of a microcode  (or
       the  last one in load order when the --downgrade option is active) will
       be written to a file or uploaded to the kernel.

       Intel microcode data files, both in binary and  text  formats,  can  be
       concatenated to generate a bigger and still valid microcode data file.

       iucode_tool does not follow symlinks when writing microcode data files.
       It will either refuse to write the file  and  abort  (default  mode  of
       operation),  or  (when the --overwrite option is active) it will remove
       the target symlink or file (and therefore  breaking  hardlinks)  before
       writing the new file.

       iucode_tool  does  follow directory symlinks to locate the directory to
       write files into.

   Linux Notes
       There are two microcode update  kernel  drivers  in  Linux:  the  early
       microcode  update  driver  (which gets the microcode update data from a
       special uncompressed initramfs image) and  the  late  microcode  update
       driver,   which   gets  microcode  update  data  through  the  firmware
       subsystem.

       The late microcode update driver should be present in the system at all
       times  to ensure microcode updates are reapplied on resume from suspend
       and cpu hotplug, even when the early microcode update driver  is  used.
       Do not unload it, unless you really know better.

       Updating  microcode  through the early driver is safer, but can only be
       done at boot.  Using the early driver to update microcode  is  strongly
       recommended.   The late microcode update driver can apply new microcode
       updates at any time, but it  cannot  safely  apply  any  new  microcode
       updates that would change visible processor features.

       The early microcode kernel driver is available since Linux v3.9, and it
       can safely  apply  microcode  updates  that  change  visible  processor
       features  (such  as  the  microcode  updates  that  disabled  Intel TSX
       instructions  on  Intel  Haswell  cores).   It  needs  an  uncompressed
       initramfs     image    with    the    microcode    update    data    in
       /kernel/x86/microcode/GenuineIntel.bin.   This  uncompressed  initramfs
       image must come before any compressed initramfs image(s), and it has an
       special name: early initramfs.

       The microcode update data inside the  early  initramfs  image  must  be
       aligned  to  a 16‐byte boundary due to a bug in several versions of the
       Linux kernel early microcode  update  driver.   This  requires  special
       steps  when creating the initramfs archive with the microcode data, and
       will  be  handled  automatically  by  the  iucode_tool  --write-earlyfw
       option.

       The  /dev/cpu/microcode  update  interface of the late microcode update
       driver has been deprecated and made optional, and should not  be  used.
       It  has  one special requirement: each write syscall must contain whole
       microcode(s).  It can be accessed through iucode_tool --kernel.

       Up to Linux v3.5, the late microcode update driver  required  microcode
       updates   to  be  triggered  per‐core,  by  writing  the  number  1  to
       /sys/devices/system/cpu/*/microcode/reload for every cpu.  Depending on
       kernel  version,  you  must  either trigger it on every core to avoid a
       dangerous situation where some cores are using outdated  microcode,  or
       the  kernel will accept the request only for the boot processor and use
       it to trigger an update on all system processor cores.

       Since Linux v3.6, the late microcode update driver has a new  interface
       that  explicitly  triggers  an  update  for every core at once when the
       number 1 is written to /sys/devices/system/cpu/microcode/reload.

EXAMPLES

   Updating files in /lib/firmware/intelucode:
       iucode_tool -K/lib/firmware/intel‐ucode \
                   /lib/firmware/intel‐ucode \
                   /tmp/file-with-new-microcodes.bin

   Processing several compressed files at once:
       zcat intel-microcode*.dat.gz | iucode_tool -l -

       zcat intel-microcode*.bin.gz | iucode_tool -l -tb -

   Selecting microcodes and creating an early initramfs:
       iucode_tool --scan-system \
                   --write-earlyfw=/tmp/early.cpio \
                   /lib/firmware/intel-ucode

       iucode_tool -s 0x106a5 -s 0x106a4 -l /lib/firmware/intel-ucode

   Using the recovery loader to load and  to  update  microcode  in  an  early
       initramfs:
       iucode_tool -L -tr /boot/intel-ucode.img

       iucode_tool -Ll -S --write-earlyfw=/boot/intel-ucode.img.new \
                   -tr  /boot/intel-ucode.img -tb /lib/firmware/intel-ucode &&
              \
              mv /boot/intel-ucode.img.new /boot/intel-ucode.img

BUGS

       Microcode with negative revision numbers is not special‐cased, and will
       not be preferred over regular microcode.

       The  downgrade  mode  should  be used only for microcodes with the same
       pf_mask.  It cannot handle the corner cases where modifying  a  pf_mask
       would  be  required  to  force the kernel to load a lower revision of a
       microcode.  So far, this has not proved to be a relevant limitation  as
       changes to the pf_mask of post‐launch, production microcode updates are
       very rare.

       The loader version microcode metadata field is ignored by  iucode_tool.
       This shouldn't cause problems as long as the same signature never needs
       more than a single type of loader.

       Files are not replaced atomically: if iucode_tool is interrupted  while
       writing to a file, that file will be corrupted.

SEE ALSO

       The  Intel  64  and  IA32  Architectures  Software Developer's Manual,
       Volume 3A: System Programming Guide,  Part  1  (order  number  253668),
       section 9.11.

AUTHOR

       Henrique de Moraes Holschuh <hmh@hmh.eng.br>