[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Xen-devel] [PATCH] docs, amd_ucode: Add AMD container file format notes



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@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                
  |
+Length       | 8                                             | 4               
  | equiv_table_len1 | Length of equivalence table(1) bytes                     
  |
+                                                                               
                     | Includes a terminating entry with all                    
  |
+                                                                               
                     | zeroes (1 entry = 16 bytes)                              
  |
+Equiv_table  | 12                                            | 
equiv_table_len1  | -                | Equivalence table                        
                  |
+Type         | 12 + equiv_table_len1                         | 4               
  | 1                | 0 - Equivalence table, 1- Microcode patch                
  |
+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                                          
  |
+                                                                          .    
                                                                                
  /
+                                                                          .    
                                                                                
  \
+                                                                          .    
                                                                                
  /
+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  
  |
+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
+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
-- 
1.7.9.5


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel


 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.