====== Microcode update image support ======

===== Name =====

    IMAGE_UCODE

===== Header file =====

Configured via ''[[http://git.ipxe.org/ipxe.git/blob/HEAD:/src/config/general.h|config/general.h]]''.

===== Examples =====

=== Enable support for microcode update images ===

    #define IMAGE_UCODE          /* Microcode update images */

=== Download and apply microcode updates ===

    chain --autofree http://192.168.0.1/ucode.bin

=== Download and apply microcode updates, and report status ===

    chain --autofree http://192.168.0.1/ucode.bin --verbose

===== Description =====

This build option enables support for Intel and AMD microcode update images.

===== See also =====

  * ''[[:cmd:chain]]'' command
  * ''[[:buildcfg:CPUID_SETTINGS]]''
  * [[:buildcfg|List of all iPXE build options]]

===== Notes =====

You can apply microcode updates before booting an operating system, to ensure that the latest microcode is in use even if the operating system itself has not yet been updated.

Intel microcode updates are published to the [[https://github.com/intel/Intel-Linux-Processor-Microcode-Data-Files|Intel Processor Microcode Update]] repository, and AMD microcode updates are published as part of the ''[[https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git|linux-firmware]]'' repository.  Both are included within most Linux distributions, and can usually be found in the ''/lib/firmware/intel-ucode'' and ''/lib/firmware/amd-ucode'' directories.

iPXE will automatically identify the appropriate update to use for your processor within the update file.  You can concatenate any number of microcode updates into a single file for ease of use.  For example:

    cat /lib/firmware/intel-ucode/*-*-* /lib/firmware/amd-ucode/*.bin > ucode.bin

To reduce download size, you can also create separate files for each CPU vendor.  For example:

    cat /lib/firmware/intel-ucode/*-*-* > GenuineIntel.bin
    cat /lib/firmware/amd-ucode/*.bin > AuthenticAMD.bin

You can then use the ''[[:cfg:cpuvendor]]'' setting in iPXE to download the appropriate per-vendor file:

    chain --autofree http://192.168.0.1/${cpuvendor}.bin

By default, executing a microcode update image will produce no output unless an error occurs.  You can obtain a brief summary status report by using the ''%%--verbose%%'' option.  For example:

    iPXE> chain --autofree http://192.168.0.1/ucode.bin --verbose
    Microcode: updated version 0x4114->0x411c (x12)

This one-line status report shows the old and new microcode versions and the number of CPU cores updated.

In almost all cases, you will want to free the download microcode image after applying it.  You can either use the ''%%--autofree%%'' option as shown above, or use the ''[[:cmd:imgfree]]'' command to explicitly free the microcode image.