[PATCH V3] docs, amd_ucode: Add AMD container file format notes

[PATCH V3] docs, amd_ucode: Add AMD container file format notes

[Aravind Gopalakrishnan]

This patch introduces documentation notes about AMD container
file formats and where to obtain latest container files from.

Also, We provide a how-to for updating patch level by
concatenating container files along with initrd images.
Misc notes about how Xen handles two containers of same
kind (if/when) they are concatenated together are also included.

Signed-off-by: Aravind Gopalakrishnan <aravind.gopalakrishnan@amd.com>
---
Changes in V3: (inputs from Boris)
 - condense steps listed to apply ucode using initrd
 - condense 'Misc notes' section

Changes in V2:
 - Boris suggested the format part itself is probably better suited
   in linux-firmware tree. There was also another idea about getting
   it out as a separate vendor doc rather than hanging it off of a
   repository. Since this is still WIP, I have removed the ascii art
   about the container file format itself here.
   - I shall update docs with links to relevant documentation as and
     when it is available.
 - Including patch header format (as suggested by Boris)
 - Provide more accurate description of what was meant by "deadlock"
   (as suggested by Boris)

 docs/misc/amd-ucode-container.txt | 88 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docs/misc/amd-ucode-container.txt

diff --git a/docs/misc/amd-ucode-container.txt b/docs/misc/amd-ucode-container.txt
new file mode 100644
index 0000000..f275252
--- /dev/null
+++ b/docs/misc/amd-ucode-container.txt
@@ -0,0 +1,88 @@
+-------------------------------------------------
+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:
+-----------------------------
+
+* Beginning with processor family 10h, AMD provides microcode patch support.
+* There is one single file (container file) containing all microcode patches
+  for AMD families 10h - 14h processors. [microcode_amd.bin]
+* For AMD family 15h processors there is a separate container file. [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 will only be on 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.
+   i.e 'module /boot/initrd_for_xen_with_ucode'
+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
-- 
2.1.0

Re: [PATCH V3] docs, amd_ucode: Add AMD container file format notes

[Ian Campbell]

On Mon, 2014-10-06 at 13:57 -0500, Aravind Gopalakrishnan wrote:
> This patch introduces documentation notes about AMD container
> file formats and where to obtain latest container files from.

I think this has already been committed and is currently sitting in
staging waiting for a test pass.

Re: [PATCH V3] docs, amd_ucode: Add AMD container file format notes

[Boris Ostrovsky]

On 10/06/2014 02:57 PM, Aravind Gopalakrishnan wrote:
> +-------------------------------------------------
> +
> +Intro to AMD Container Files:
> +-----------------------------
> +
> +* Beginning with processor family 10h, AMD provides microcode patch support.
> +* There is one single file (container file) containing all microcode patches
> +  for AMD families 10h - 14h processors. [microcode_amd.bin]
> +* For AMD family 15h processors there is a separate container file. [microcode_amd_fam15h.bin]

I think this would need to be updated to 15h+ as well (i.e. new file 
name for all 15h and later processors). Here and in a couple of places 
below.

Since it's apparently already in the staging tree perhaps you can wait 
until it shows up in the mainline and then send a patch?

-boris

Re: [PATCH V3] docs, amd_ucode: Add AMD container file format notes

[Ian Campbell]

On Tue, 2014-10-07 at 09:48 -0400, Boris Ostrovsky wrote:
> On 10/06/2014 02:57 PM, Aravind Gopalakrishnan wrote:
> > +-------------------------------------------------
> > +
> > +Intro to AMD Container Files:
> > +-----------------------------
> > +
> > +* Beginning with processor family 10h, AMD provides microcode patch support.
> > +* There is one single file (container file) containing all microcode patches
> > +  for AMD families 10h - 14h processors. [microcode_amd.bin]
> > +* For AMD family 15h processors there is a separate container file. [microcode_amd_fam15h.bin]
> 
> I think this would need to be updated to 15h+ as well (i.e. new file 
> name for all 15h and later processors). Here and in a couple of places 
> below.
> 
> Since it's apparently already in the staging tree perhaps you can wait 
> until it shows up in the mainline and then send a patch?

It's completely fine to send patches against staging if the baseline you
need is in there...

Ian.

Re: [PATCH V3] docs, amd_ucode: Add AMD container file format notes

[Aravind Gopalakrishnan]

On 10/7/2014 8:49 AM, Ian Campbell wrote:
> On Tue, 2014-10-07 at 09:48 -0400, Boris Ostrovsky wrote:
>> On 10/06/2014 02:57 PM, Aravind Gopalakrishnan wrote:
>>> +-------------------------------------------------
>>> +
>>> +Intro to AMD Container Files:
>>> +-----------------------------
>>> +
>>> +* Beginning with processor family 10h, AMD provides microcode patch support.
>>> +* There is one single file (container file) containing all microcode patches
>>> +  for AMD families 10h - 14h processors. [microcode_amd.bin]
>>> +* For AMD family 15h processors there is a separate container file. [microcode_amd_fam15h.bin]
>> I think this would need to be updated to 15h+ as well (i.e. new file
>> name for all 15h and later processors). Here and in a couple of places
>> below.

Ok. There's one other instance where I will update this.
I shall leave the instances that are used for exemplification purposes 
untouched.

>> Since it's apparently already in the staging tree perhaps you can wait
>> until it shows up in the mainline and then send a patch?
> It's completely fine to send patches against staging if the baseline you
> need is in there...
>
>

Ok, I shall base V3 patch off staging and send it as a separate patch.

Thanks,
-Aravind.