[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Xen-devel] [PATCH] docs, amd_ucode: Add AMD container file format notes
On 07/16/2014 03:30 PM, Aravind Gopalakrishnan wrote:
This patch introduces documentation notes about AMD container
file formats and where to obtain latest container files from.
I wonder whether this description should be part of the firmware tree as
opposed to the Xen tree. At least the format part.
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@xxxxxxx>
---
docs/misc/amd-ucode-container.txt | 123 +++++++++++++++++++++++++++++++++++++
1 file changed, 123 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..975c02b
--- /dev/null
+++ b/docs/misc/amd-ucode-container.txt
@@ -0,0 +1,123 @@
+-------------------------------------------------
+AMD Microcode Container File format
+-------------------------------------------------
+Author:
+ Aravind [dot] Gopalakrishnan [at] amd [dot] com
+Created:
+ July 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 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 [2], [3]
+
+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
+
+The microcode container file format is as follows-
+-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
+Name | Byte Offset | Length
| Value | Description
|
+-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
+UCODE_MAGIC | 0 | 4
| MAGIC VAL | AMD UCODE MAGIC ID
|
+Type | 4 | 4
| 0 | 0 - Equivalence table, 1- Microcode patch
|
Description should say something like "Equivalence Table Type" (i.e.
since value is zero, this is not a patch)
+Length | 8 | 4
| equiv_table_len1 | Length of equivalence table(1) bytes
|
+
| Includes a terminating entry with all
|
+
| zeroes (1 entry = 16 bytes)
|
Please describe somewhere equivalence table entry's format.
+Equiv_table | 12 |
equiv_table_len1 | - | Equivalence table
|
+Type | 12 + equiv_table_len1 | 4
| 1 | 0 - Equivalence table, 1- Microcode patch
|
"Microcode Patch Type" for description?
+Length | 16 + equiv_table_len1 | 4
| m(1) | Length of 1st ucode patch in bytes
|
+Patch | 20 + equiv_table_len1 | m(1)
| - | 1st ucode patch
|
Maybe mention somewhere patch's header format (i.e. struct
microcode_header_amd)?
+ .
/
+ .
\
+ .
/
+Type | 20 + equiv_table_len1 + m(1) + ... + m(x-1) | 4
| 1 | 0 - Equivalence table, 1- Microcode patch
|
+Length | 24 + equiv_table_len1 + m(1) + ... + m(x-1) | 4
| m(x) | Length of last ucode patch of this container#1 in bytes
|
"last ucode patch" -> "Xth ucode patch".
+Patch | 28 + equiv_table_len1 + m(1) + ... + m(x-1) | m(x)
| - | last ucode patch of container#1
|
+-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
+UCODE_MAGIC | 28 + equiv_table_len1 + m(1) + ... + m(x) | 4
| MAGIC VAL | AMD UCODE MAGIC ID (container#2 starts here)
|
+Type | 32 + equiv_table_len1 + m(1) + ... + m(x) | 4
| 0 | 0 - Equivalence table, 1- Microcode patch
|
+Length | 36 + equiv_table_len1 + m(1) + ... + m(x) | 4
| equiv_table_len2 | Length of equivalence table(2) in bytes
|
+
| Includes a terminating entry with all
|
+
| zeroes (1 entry = 16 bytes)
|
+Equiv_table | 40 + equiv_table_len1 + m(1) + ... + m(x) |
equiv_table_len2 | - | Equivalence table
|
+Type | 40 + equiv_table_len1 + m(1) + ... + m(x) | 4
| 1 | 0 - Equivalence table, 1- Microcode patch
|
+ + equiv_table_len2
|
+Length | 44 + equiv_table_len1 + m(1) + ... + m(x) | 4
| n(1) | Length of 1st ucode patch in bytes
|
+ + equiv_table_len2
|
+Patch | 48 + equiv_table_len1 + m(1) + ... + m(x) | n(1)
| - | 1st ucode patch
|
+ + equiv_table_len2
|
+ .
/
+ .
\
+ .
/
+Type | 48 + equiv_table_len1 + m(1) + ... + m(x) | 4
| 1 | 0 - Equivalence table, 1- Microcode patch
|
+ + equiv_table_len2 + ... + n(y-1)
|
+Length | 52 + equiv_table_len1 + m(1) + ... + m(x) | 4
| n(y) | Length of last ucode patch of this container in bytes
|
+ + equiv_table_len2 + ... + n(y-1)
|
+Patch | 56 + equiv_table_len1 + m(1) + ... + m(x) | n(y)
| - | last ucode patch of container#2
|
+ + equiv_table_len2 + ... + n(y)
|
+-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
+ .
/
+ .
\
+ .
/
+-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
+
+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. cp /lib/firmware/amd-ucode/microcode_amd.bin .
+5. cp /lib/firmware/amd-ucode/microcode_amd_fam15h.bin .
+6. cat microcode_amd.bin microcode_amd_fam15h.bin > microcode_concatenated.bin
+7. mv microcode_concatenated.bin kernel/x86/microcode/AuthenticAMD.bin
+8. rm microcode_amd.bin microcode_amd_fam15h.bin
+9. find . | cpio -o -H newc > ucode.cpio
+10. cp /boot/initrd.img-3.8.0-30-generic .
+11. cat ucode.cpio initrd.img-3.8.0-30-generic > initrd_for_xen_with_ucode
+12. cp initrd_for_xen_with_ucode /boot/
+13. On grub.cfg, provide the above initrd name as module.
+14. 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. (two microcode_amd_fam15h.bin for example)
+This is because:
+There is no check in Xen currently to verify this.
+Now, given a situation where
+1. An earlier container has a patch that 'fits' the processor you are
+ currently on,
+2. There is a subsequent container that *also* has a patch that 'fits',
+3. The second patch happens to be an update over the patch found on the
+ first container file.
+
+In such a case, only the patch from the first container is applied.
+This is because Xen assumes that the the containers (if concatenated
+together) are different kinds AND the 'Mutual Exclusivity' rule is
+always true.
+
+On such cases of deadlock, it is preferable to update the microcode container
"Deadlock" doesn't sound like the best term here. You probably meant
that in cases where users are not sure about provenance of containers
they should obtain a "good" set since it's not guaranteed that the
latest patch will be applied?
-boris
+files first using distro specific methods or downloading them from [2], [3].
+
+Reference(s):
+-------------
+[1] http://lxr.free-electrons.com/source/Documentation/x86/early-microcode.txt
+[2] http://www.amd64.org/microcode.html
+[3]
https://git.kernel.org/cgit/linux/kernel/git/firmware/linux-firmware.git/tree/amd-ucode
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
