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

[Aravind Gopalakrishnan <aravind.gopalakrishnan@amd.com>]

On 7/17/2014 5:39 AM, Andrew Cooper wrote:
> +
> +The microcode container file format is as follows-
> +-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
> +Name         | Byte Offset                                   | Length            |  Value           | Description                                                |
> +-------------+-----------------------------------------------+-------------------+------------------+------------------------------------------------------------+
> +UCODE_MAGIC  | 0                                             | 4                 | MAGIC VAL        | AMD UCODE MAGIC ID                                         |
> What is MAGIC VAL ?

(from microcode_amd) #define UCODE_MAGIC                0x00414d44

>> +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)                                |
> Does this mean that equiv_table_len1 is in units of 16 bytes, or that it
> is guaranteed to be a multiple of 16?

I am not able to find any documentation that attests to this.
But, looking at struct __packed equiv_cpu_entry, it seems so..

In any case, I just wanted to convey here that the equiv_table indicates 
it's end using such a 'terminating entry'.
Not to mean the table itself should be seen as being divided into '16 
byte entries'

>> +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                            |
> So judging from the above, an individual container is made up of a magic
> value followed by a number of type/length/data blobs.
>
> Type can be one of equivalence table or microcode patch, and there are
> multiple microcode patches per equivalence table?

Hmm..I think instead of saying there are multiple patches per 
equiv_table, a better way to put it would be:
there is one equiv_table per container and there are multiple patches 
per container. (as patches are encapsulated within the container, not 
the equiv_table)

The equiv_table is basically a list of patches available in the container,
and provides a mapping of equiv_cpu_id to current_cpu_id (current_cpu_id 
= cpuid_eax(0x00000001))

Thanks,
-Aravind.