1-------------------------------------------------
2AMD Microcode Container File format
3-------------------------------------------------
4Author:
5  Aravind [dot] Gopalakrishnan [at] amd [dot] com
6Initial version:
7  July 2014
8Updated:
9  October 2014
10-------------------------------------------------
11
12Intro to AMD Container Files:
13-----------------------------
14
15* AMD provides microcode patch support for processors belonging to AMD
16  processor families 10h, 11h, 12h, 14h, and 15h.
17* There is one single file (container file) containing all microcode patches
18  for AMD families 10h - 14h processors. [microcode_amd.bin]
19* For AMD processor families 15h and later, there is a separate container file
20  for each family. (e.g. microcode_amd_fam15h.bin)
21* Microcode patches are not incremental, therefore you only need to make
22  sure you have the latest container file for your AMD processor family.
23* One can find the latest AMD microcode containers from [1], [2]
24
25Mutual Exclusivity Rule of AMD containers:
26* The patches for families 10h - 14h are guaranteed to be only on
27  microcode_amd.bin
28* Similarly, patches for family 15h and later will only be on their respective
29  family specific container file. (e.g. microcode_amd_fam15h.bin)
30* This is because, the processes and scripts used to create container files
31  ensure that there is no mix-up
32
33Microcode patch header structure:
34---------------------------------
35struct __packed microcode_header_amd {
36    uint32_t data_code;
37    uint32_t patch_id;
38    uint8_t  mc_patch_data_id[2];
39    uint8_t  mc_patch_data_len;
40    uint8_t  init_flag;
41    uint32_t mc_patch_data_checksum;
42    uint32_t nb_dev_id;
43    uint32_t sb_dev_id;
44    uint16_t processor_rev_id;
45    uint8_t  nb_rev_id;
46    uint8_t  sb_rev_id;
47    uint8_t  bios_api_rev;
48    uint8_t  reserved1[3];
49    uint32_t match_reg[8];
50}
51More details about microcode patch header are typically not exposed to public.
52
53Apply microcode updates using initrd:
54-------------------------------------
55Initrd images can be modified to contain AMD microcode containers in cpio
56format at the start of the image.
57
58Following example shows how to generate a combined initrd
59Note: initrd-<val> could be different on your machine. Substitute accordingly
60Example System base: Ubuntu 13.04 with 3.8.0-30-generic kernel
61
621.  mkdir initrd-for-xen-with_append
632.  cd initrd-for-xen-with_append
643.  mkdir -p kernel/x86/microcode
654.  cat /lib/firmware/amd-ucode/microcode_amd.bin \
66        /lib/firmware/amd-ucode/microcode_amd_fam15h.bin > \
67	kernel/x86/microcode/AuthenticAMD.bin
685.  find . | cpio -o -H newc > ucode.cpio
696.  cat ucode.cpio /boot/initrd.img-3.8.0-30-generic > /boot/initrd_for_xen_with_ucode
707. On grub.cfg, provide the above initrd name as module.
718. Use 'ucode=scan' option as Xen boot parameter.
72
73Misc Notes:
74-----------
75It is not recommended to concatenate two(or more) container files of
76the same kind. (e.g. two microcode_amd_fam15h.bin) since the hypervisor
77will apply a patch as and when it determines that it is a 'good fit'.
78Once the patch is applied, further parsing of the file is skipped.
79Therefore, if a subsequent container file has a newer/updated patch, that
80patch will be ignored.
81
82In cases where users are not sure about provenance of containers
83they should obtain a "good" set  by downloading them from source links
84[1], [2] since it's not guaranteed that the latest patch will be applied.
85
86Reference(s):
87-------------
88[1] http://www.amd64.org/microcode.html
89[2] https://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/amd-ucode
90[3] http://lxr.free-electrons.com/source/Documentation/x86/early-microcode.txt
91