-------------------------------------------------
AMD Microcode Container File format
-------------------------------------------------
Author:
  Aravind [dot] Gopalakrishnan [at] amd [dot] com
Initial version:
  July 2014
Updated:
  October 2014
-------------------------------------------------

Intro to AMD Container Files:
-----------------------------

* AMD provides microcode patch support for processors belonging to AMD
  processor families 10h, 11h, 12h, 14h, and 15h.
* There is one single file (container file) containing all microcode patches
  for AMD families 10h - 14h processors. [microcode_amd.bin]
* For AMD processor families 15h and later, there is a separate container file
  for each family. (e.g. microcode_amd_fam15h.bin)
* Microcode patches are not incremental, therefore you only need to make
  sure you have the latest container file for your AMD processor family.
* One can find the latest AMD microcode containers from [1], [2]

Mutual Exclusivity Rule of AMD containers:
* The patches for families 10h - 14h are guaranteed to be only on
  microcode_amd.bin
* Similarly, patches for family 15h and later will only be on their respective
  family specific container file. (e.g. microcode_amd_fam15h.bin)
* This is because, the processes and scripts used to create container files
  ensure that there is no mix-up

Microcode patch header structure:
---------------------------------
struct __packed microcode_header_amd {
    uint32_t data_code;
    uint32_t patch_id;
    uint8_t  mc_patch_data_id[2];
    uint8_t  mc_patch_data_len;
    uint8_t  init_flag;
    uint32_t mc_patch_data_checksum;
    uint32_t nb_dev_id;
    uint32_t sb_dev_id;
    uint16_t processor_rev_id;
    uint8_t  nb_rev_id;
    uint8_t  sb_rev_id;
    uint8_t  bios_api_rev;
    uint8_t  reserved1[3];
    uint32_t match_reg[8];
}
More details about microcode patch header are typically not exposed to public.

Apply microcode updates using initrd:
-------------------------------------
Initrd images can be modified to contain AMD microcode containers in cpio
format at the start of the image.

Following example shows how to generate a combined initrd
Note: initrd-<val> could be different on your machine. Substitute accordingly
Example System base: Ubuntu 13.04 with 3.8.0-30-generic kernel

1.  mkdir initrd-for-xen-with_append
2.  cd initrd-for-xen-with_append
3.  mkdir -p kernel/x86/microcode
4.  cat /lib/firmware/amd-ucode/microcode_amd.bin \
        /lib/firmware/amd-ucode/microcode_amd_fam15h.bin > \
	kernel/x86/microcode/AuthenticAMD.bin 
5.  find . | cpio -o -H newc > ucode.cpio
6.  cat ucode.cpio /boot/initrd.img-3.8.0-30-generic > /boot/initrd_for_xen_with_ucode
7. On grub.cfg, provide the above initrd name as module.
8. Use 'ucode=scan' option as Xen boot parameter.

Misc Notes:
-----------
It is not recommended to concatenate two(or more) container files of
the same kind. (e.g. two microcode_amd_fam15h.bin) since the hypervisor
will apply a patch as and when it determines that it is a 'good fit'.
Once the patch is applied, further parsing of the file is skipped.
Therefore, if a subsequent container file has a newer/updated patch, that 
patch will be ignored.

In cases where users are not sure about provenance of containers 
they should obtain a "good" set  by downloading them from source links
[1], [2] since it's not guaranteed that the latest patch will be applied.

Reference(s):
-------------
[1] http://www.amd64.org/microcode.html 
[2] https://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/amd-ucode 
[3] http://lxr.free-electrons.com/source/Documentation/x86/early-microcode.txt