IUCODE_TOOL(8)                iucode_tool manual                IUCODE_TOOL(8)

       iucode_tool  -  Tool to manipulate Intel(R) IA-32/X86-64 microcode bun-

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

       iucode_tool is an utility that can load  Intel(R)  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  pro-
       cessor  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  direc-
       tories  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

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

       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

       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.

              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 ker-
                     nel driver and the BIOS/EFI, which is described in detail
                     by  the  Intel 64 and IA-32 Architectures Software Devel-
                     oper'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

              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.

              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.

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

              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.

              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.

              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  cor-
              rupted,  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.

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

       -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 num-
              bers must not have leading zeros, otherwise they would be inter-
              preted as octal numbers.

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

              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 sys-
              tem for their signatures.

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

              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  con-
              dition 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 dig-
              its for the month and day and "-" (minus sign) for  the  separa-
              tor.    Dates   are   not   range-checked,   so   you   can  use
              --date-after=2000-00-00 to select  all  microcodes  dated  since
              January 1st, 2000.

              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.

              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/intel-ucode).

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

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

              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  per-
              missions, ACLs and other extended attributes of the old destina-
              tion file will be lost.

              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.

       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 deter-
       ministic, 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  subsys-

       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 fea-
       tures (such as the microcode updates that disabled Intel  TSX  instruc-
       tions  on  Intel  Haswell  cores).   It needs an uncompressed initramfs
       image with the  microcode  update  data  in  /kernel/x86/microcode/Gen-
       uineIntel.bin.   This uncompressed initramfs image must come before any
       compressed initramfs image(s),  and  it  has  an  special  name:  early

       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

       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 num-
       ber 1 is written to /sys/devices/system/cpu/microcode/reload.

   Updating files in /lib/firmware/intel-ucode:
       iucode_tool -K/lib/firmware/intel-ucode \
                   /lib/firmware/intel-ucode \

   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 \

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

   Using  the  recovery  loader  to  load  and to update microcode in an early
       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

       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.

       The Intel 64 and IA-32 Architectures Software Developer's Manual,  Vol-
       ume 3A: System Programming Guide, Part 1 (order number 253668), section

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

IUCODE_TOOL 1.5.1                 2016-02-13                    IUCODE_TOOL(8)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2021 Hurricane Electric. All Rights Reserved.