diff options
Diffstat (limited to '')
| -rw-r--r-- | debian/README.source | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source new file mode 100644 index 0000000..adad784 --- /dev/null +++ b/debian/README.source @@ -0,0 +1,218 @@ +intel-microcode for Debian +-------------------------- + +Adding new microcodes to the package: + +* Regular microcode bundles (upstream releases): + + Add them to the top-level dir, names must match the patterns: + + * microcode-<id>.dat for Intel text format bundles; + * microcode-<id>.bin for Intel binary bundles. + * microcode-<id>.d/ for directories with split binary microcode. + + <id> should be the upstream release date in YYYYMMDD format. + If it is not, you must make sure microcode files that have + been released later also come later in C collating order. + + Some upstream releases contain the microcode update data twice: + in .dat, and as a directory with several binary files. In that + case, you must compare the contents (e.g. using iucode_tool -L) + to ensure that they match. Don't add both copies of the update + data to the package: it is a waste of mirror space, and only one + copy (the one that sorts last) would be used to generate the + final microcode pack (so you would still have to ensure both + formats had the same contents anyway). + + Hint: iucode_tool will compare two "supposedly identical" + microcodes to ensure they are just that: identical. So, it is + enough to do something like this: + + iucode_tool --write-all-named-to=/tmp/dir1 file1.dat ; + iucode_tool --write-all-named-to=/tmp/dir2 intel-ucode/ ; + diff -R /tmp/dir1 /tmp/dir2 && echo ok ; + iucode_tool -v /tmp/dir1 /tmp/dir2 + + Later regular microcode bundles have precedence over older regular + microcode bundles, and may downgrade microcode revisions. This + implements the automatic "revision rollback" mechanism. + + The "oldies" and the IUC_INCLUDE mechanisms of the main Makefile may + select microcodes from any of the regular microcode bundles. + Otherwise, only microcodes in the latest regular microcode bundle will + be selected. This logic implements the "automatic removal" mechanism + to handle microcode recalls. + + Directories of microcodes must not have nested subdirectories. The + contents of the directory will be processed into a temporary ".dbin" + binary microcode file, to allow the automatic "revision rollback" + mechanism to work in a predictable way. Due to sorting order, + ".dbin" files are preferred over ".dat" files when deciding which + would be used to generate the final microcode pack. + + Supplementary microcode bundles and microcode overrides can select + additional microcode (see below). + +* Latest available version of a microcode that is not being shipped + anymore, but which is present in an older microcode bundle: + + Add "-s <signature>" to IUC_INCLUDE in the Makefile. + +* Supplementary microcode bundles: + + The intended usage for this feature is to ship microcode updates that + fix important errata before they are available through a regular Intel + microcode bundle release. + + Add them to the top-level dir, names must match the pattern: + + * supplementary-ucode-<id>.bin + * supplementary-ucode-<id>.d/ + + <id> should be a descriptive name, sorting order does not + matter. It must not have spaces or tabs. + + These bundles have the same precedence as the newest regular microcode + bundle: microcodes with the highest revision among the newest regular + microcode bundle and every supplementary microcode bundles will be + selected. + + Supplementary microcode bundles must be in binary format. + + Use "iucode_tool -w" to create supplementary microcode bundles. + The bundles may have any number of microcodes inside, and should be + described in the "upstream" changelog. + + Directories of supplementary microcode updates must not have nested + subdirectories. The data files inside the directory should be in + binary format, and may contain more than one microcode update. They + should be descriptively named, and should be described in the + "upstream" changelog. + + WARNING: microcodes added through supplementary bundles cannot be + "recalled" (excluded or downgraded) automatically by the latest + regular microcode bundle, only by overrides and IUC_EXCLUDE. + +* Individual microcode overrides (at a specific revision): + + The intended usage for this feature is to ship microcode at a specific + revision. For microcode that should be superseded by a newer version + when available, use a supplementary bundle (see above), instead. + + These overrides have the highest precedence, and will override + (possibly downgrading) microcodes in the other bundles, regular or + supplementary. + + Add them to the top-level dir, names should be in the format: + + * s<sig>_m<pfmask>_r<revision>.fw + + <sig> is the CPU signature, <pfmask> is the processor flags + mask, and revision is the microcode revision level. All + values in hexadecimal using uppercase letters, no leading + prefixes, with left padding with zeroes, field length 8, as + in the printf mask: s%08X_m%08X_r%08X.fw + + The files must be in binary format, and should contain only a single + microcode (to ensure maintainer sanity). + + "iucode_tool -s <signature> -W" can be used to easily extract + microcodes and create (and name) .fw override files. + +* Excluding microcodes, no matter where they were sourced from: + + Add "-s !<signature>" to IUC_EXCLUDE in the Makefile. + + This will remove from the final microcode distribution even microcodes + that were sourced from override files. + + + +When you add a new microcode (bundle or otherwise): + +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +!!! Always verify if you do not have to remove microcodes from the !!! +!!! exclusion list in the top Makefile. !!! +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Please avoid shipping microcodes "recalled" by Intel, unless you DO know +better (i.e. you know the reason why it was "recalled", and you consider +that Debian users would be best served by its inclusion). Always +document why you're doing this as much as you are allowed to in the +package changelog. Microcode override files (.fw files) can be used to +make sure a specific microcode is shipped, however, should you want to +ship the latest available version of a microcode from older bundles, you +must use IUC_INCLUDE. + +If you are adding a microcode bundle made available directly by Intel in +their public site, please update the "upstream changelog". There is no +fully automated way to do it yet, but you can use "iucode_tool -l" to +list the contents of the bundles, and apply some sed magic, sort, and +"diff -u" to find out which microcodes were added, deleted, updated, or +downgraded. The debian/diff-latest-pack.sh script should be of help. + +Please check all additions against the changelog, and annotate them as +appropriate when the microcode was present in a previous release. Intel +has done a "delete in one release, add back with a downgraded revision +in the next release" once in the past. Annotations should say when the +microcode was updated or downgraded, or just re-added with the same +revision. + +Please check all deletions. When very recent microcode is deleted, it +could well mean an unfriendly "microcode revision recall" is happening +(someone at Intel decided to remove it instead of directly marking it a +downgrade by publishing the previously known-good revision). When +microcodes for older processors are deleted, it is probably safe to +assume it is just the regular housekeeping cleanups, and the microcode +should still be shipped by distros that have users running 10-15 +year-old boxes, like Debian. + +If you know that a microcode signature belongs to alpha or beta hardware +(engineering samples), you may remove the microcodes for that signature +by adding them to IUC_EXCLUDE in the Makefile, on the grounds that such +microcodes just waste space on everyone's system. Unfortunately, a list +of the CPU signatures of such unsupported processors is hard to come by. + + +Keeping useless microcode out of amd64 and x32 binary packages: + +It is useless to ship microcode that targets processors not capable of +Intel64 (X86-64) on the amd64 and x32 arch-specific binary packages. + +The top-level Makefile tries to avoid this by parsing cpu-signatures.txt +and ignoring anything listed as i?86 when building intel-microcode-64.bin, +which debian/rules will use instead of intel-microcode.bin for non-i386. + +Failure to update cpu-signatures.txt should be mostly harmless (it is +engineered to fail safe, and distribute unlisted microcode so that at +most it will waste some space). It is unlikely that new i686 microcode +signatures will show up, but it may be useful to know to which +processors a microcode update apply even for newer processors, just in +case we have to issue a critical update and warn users. + + +Where to find processor signature information: + +They appear to be listed only in the Specification Updates for each +processor, you'll have to locate and download them all from Intel's site +(this is _not_ easy to do, some of these documents are hard to track +down). Better information is likely to available (possibly under NDA) +on the Intel developer channels. + +As for non-canonical sources, there is a CPUID database in the Internet +and a memory/latency timings database used by HPC people which are of +some help. Search engines will often find a BIOS/UEFI firmware upgrade +changelog that names the particular core of a microcode update +signature. + +Cross-check by searching the S-SPEC numbers in the Intel ARK directory +(e.g. to verify whether it supports X86-64 or not). + + +Backport notes: + +1. Only kernels 3.10 and above are supported in the 3.x branch of + intel-microcode. To support older kernels, you will have to backport + the 2.x or 1.x branches of intel-microcode, instead. + +-- Henrique de Moraes Holschuh <hmh@debian.org> |