From 87d1d08196ed2c69d4736a2815135bb69d996d11 Mon Sep 17 00:00:00 2001 From: Francis Rowe Date: Mon, 22 Dec 2014 05:58:57 -0500 Subject: ich9deblob: add more commenting --- (limited to 'resources/utilities/ich9deblob') diff --git a/resources/utilities/ich9deblob/ich9deblob.c b/resources/utilities/ich9deblob/ich9deblob.c index 0d1768d..a2819bf 100644 --- a/resources/utilities/ich9deblob/ich9deblob.c +++ b/resources/utilities/ich9deblob/ich9deblob.c @@ -1,5 +1,8 @@ /* - * ich9deblob.c + * main.c + * This file is part of the ich9deblob utility from the libreboot project + * + * Purpose: disable and remove the ME from ich9m/gm45 machines in coreboot. * * Copyright (C) 2014 Steve Shenton * Francis Rowe @@ -17,6 +20,25 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ + +/* + * Read a factory.rom dump (ich9m/gm45 machines) and + * modify the flash descriptor to remove all regions except descriptor, + * Gbe and BIOS. Set BIOS region to full size of the ROM image (after + * the flash descriptor and gbe). Basically, deblob the descriptor. + * + * This will will generate a concatenated descriptor+gbe dump suitable + * for use in libreboot. Currently tested: ThinkPad X200 (coreboot/libreboot) + */ + +// See docs/hcl/x200_remove_me.html for info plus links to datasheet (also linked below) + +// Info about flash descriptor (read page 850 onwards): +// * http://www.intel.co.uk/content/dam/doc/datasheet/io-controller-hub-9-datasheet.pdf + +// Info about Gbe region (read whole datasheet): +// * http://www.intel.co.uk/content/dam/doc/application-note/i-o-controller-hub-9m-82567lf-lm-v-nvm-map-appl-note.pdf +// * https://communities.intel.com/community/wired/blog/2010/10/14/how-to-basic-eeprom-checksums #include #include @@ -25,16 +47,22 @@ #define DESCRIPTORREGIONSIZE 0x1000 // 4096 bytes / 4KiB #define GBEREGIONSIZE 0x2000 // 8192 bytes / 8KiB +// These will have a modified descriptor+gbe based on what's in the factory.rom +// These will be joined into a single 12KiB buffer (descriptor, then gbe) and saved to a file +// NOTE: The GBE region of 8K is actually 2x 4K regions in a single region; both 4K blocks can be identical (and by default, are) +// The 2nd one is a "backup", but we don't know when it's used. perhaps it's used when the checksum on the first one does not match? +// gbe checksum related functions unsigned short GetChecksum(char* buffer, unsigned short desiredValue); // for GBe region (checksum calculation) unsigned short GetRegionWord(int i, char* buffer); // used for getting each word needed to calculate said checksum int main(int argc, char *argv[]) { - // check compiler bit-packs in a compatible way + + // descriptor region. Will have actual descriptor mapped to it (from the factory.rom dump) struct DESCRIPTORREGIONRECORD descriptorRegion; unsigned int descriptorRegionStructSize = sizeof(descriptorRegion); - // basically, it is expected that this code will be used on x86 + // check compiler bit-packs in a compatible way basically, it is expected that this code will be used on x86 if (DESCRIPTORREGIONSIZE != descriptorRegionStructSize){ printf("\nerror: compiler incompatibility: descriptor struct length is %i bytes (should be %i)\n", descriptorRegionStructSize, DESCRIPTORREGIONSIZE); return 1; @@ -56,10 +84,11 @@ int main(int argc, char *argv[]) } printf("\nfactory.rom opened successfully\n"); // ----------------------------------------------- + + // Get the descriptor region dump from the factory.rom // Create empty descriptor buffer (populated below) char descriptorBuffer[DESCRIPTORREGIONSIZE]; - // Extract the descriptor region from the factory.rom dump // (goes in descriptorBuffer variable) unsigned int readLen; @@ -70,7 +99,6 @@ int main(int argc, char *argv[]) return 1; } printf("\ndescriptor region read successfully\n"); - // copy descriptor buffer into descriptor struct memory // descriptorRegion is an instance of a struct that actually // defines the locations of all these variables in the descriptor, @@ -78,16 +106,24 @@ int main(int argc, char *argv[]) // descriptor over the struct so that it can then be modified // for libreboot's purpose memcpy(&descriptorRegion, &descriptorBuffer, DESCRIPTORREGIONSIZE); + + // ----------------------------------------------------------------------------------------------- + + // Get the gbe region dump from the factory.rom // get original GBe region location // (it will be moved to the beginning of the flash, after the descriptor region) - unsigned int flRegionBitShift = 12; + unsigned int flRegionBitShift = 12;// bits 12-24 are represented. + // note for example, gbeRegionLocation is set to <<12 of actual address (in C). this is how the addresses + // are stored in the descriptor. unsigned int gbeRegionLocation = descriptorRegion.regionSection.flReg3.BASE << flRegionBitShift; + // Set offset so that we can read the data from + // the gbe region fseek(fp, gbeRegionLocation, SEEK_SET); - + // data will go in here char gbeBuffer[GBEREGIONSIZE]; - + // Read the gbe data from the factory.rom and put it in gbeBuffer readLen = fread(gbeBuffer, sizeof(char), GBEREGIONSIZE, fp); if (GBEREGIONSIZE != readLen) { @@ -95,6 +131,8 @@ int main(int argc, char *argv[]) return 1; } + // ----------------------------------------------------------------------------------------------- + // Get size of ROM image // This is needed for relocating the BIOS region (per descriptor) fseek(fp, 0L, SEEK_END); @@ -103,43 +141,69 @@ int main(int argc, char *argv[]) printf("\nfactory.rom size: [%i] bytes\n", romSize); fclose(fp); + + // ----------------------------------------------------------------------------------------------- + // debugging printf("\nOriginal Descriptor start block: %08x ; Descriptor end block: %08x\n", descriptorRegion.regionSection.flReg0.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg0.LIMIT << flRegionBitShift); printf("Original BIOS start block: %08x ; BIOS end block: %08x\n", descriptorRegion.regionSection.flReg1.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg1.LIMIT << flRegionBitShift); printf("Original ME start block: %08x ; ME end block: %08x\n", descriptorRegion.regionSection.flReg2.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg2.LIMIT << flRegionBitShift); printf("Original GBe start block: %08x ; GBe end block: %08x\n", gbeRegionLocation, descriptorRegion.regionSection.flReg3.LIMIT << flRegionBitShift); - // set number of regions from 4 -> 2 (0 based) + // Now we need to modify the descriptor so that the ME can be excluded + // from the final ROM image (libreboot one) after adding the modified + // descriptor+gbe. Refer to libreboot docs for details: docs/hcl/x200_remove_me.html + + // set number of regions from 4 -> 2 (0 based, so 4 means 5 and 2 + // means 3. We want 3 regions: descriptor, gbe and bios, in that order) descriptorRegion.flMaps.flMap0.NR = 2; - // make descriptor writable from OS. + // make descriptor writable from OS. This is that the user can run: + // sudo ./flashrom -p internal:laptop=force_I_want_a_brick + // from the OS, without relying an an external SPI flasher, while + // being able to write to the descriptor region (locked by default, + // until making the change below): descriptorRegion.masterAccessSection.flMstr1.fdRegionWriteAccess = 1; // relocate BIOS region and increase size to fill image - descriptorRegion.regionSection.flReg1.BASE = 3; - descriptorRegion.regionSection.flReg1.LIMIT = ((romSize / 0x1000) - 1); - - // set ME region size to 0 - descriptorRegion.regionSection.flReg2.BASE = 0xFFF; + descriptorRegion.regionSection.flReg1.BASE = 3; // 3<<12 is 12KiB, which is where BIOS region is to begin (after descriptor and gbe) + descriptorRegion.regionSection.flReg1.LIMIT = ((romSize >> flRegionBitShift) - 1); + // ^ for example, 8MB ROM, that's 8388608 bytes. + // ^ 8388608>>12 (or 8388608/4096) = 2048 bytes + // 2048 - 1 = 2047 bytes. + // This defines where the final 0x1000 (4KiB) page starts in the flash chip, because the hardware does: + // 2047<<12 (or 2047*4096) = 8384512 bytes, or 7FF000 bytes + // (it can't be 0x7FFFFF because of limited number of bits) + + // set ME region size to 0 - the ME is a blob, we don't want it in libreboot + descriptorRegion.regionSection.flReg2.BASE = 0x1FFF; // setting 1FFF means setting size to 0. 1FFF<<12 is outside of the ROM image (8MB) size? + // ^ datasheet says to set this to 1FFF, but FFF was previously used and also worked. descriptorRegion.regionSection.flReg2.LIMIT = 0; - - // relocate Gbe region - descriptorRegion.regionSection.flReg3.BASE = 1; + // ^ 0<<12=0, so basically, the size is 0, and the base (1FFF>>12) is well outside the higher 8MB range. + + // relocate Gbe region to begin at 4KiB (immediately after the flash descriptor) + descriptorRegion.regionSection.flReg3.BASE = 1; // 1<<12 is 4096, which is where the Gbe region is to begin (after the descriptor) descriptorRegion.regionSection.flReg3.LIMIT = 2; + // ^ 2<<12=8192 bytes. So we are set it to size 8KiB after the first 4KiB in the flash chip. - // set Platform region size to 0 - descriptorRegion.regionSection.flReg4.BASE = 0xFFF; + // set Platform region size to 0 - another blob that we don't want + descriptorRegion.regionSection.flReg4.BASE = 0x1FFF; // setting 1FFF means setting size to 0. 1FFF<<12 is outside of the ROM image (8MB) size? + // ^ datasheet says to set this to 1FFF, but FFF was previously used and also worked. descriptorRegion.regionSection.flReg4.LIMIT = 0; + // ^ 0<<12=0, so basically, the size is 0, and the base (1FFF>>12) is well outside the higher 8MB range. - // disable ME in ICHSTRAP0 + // disable ME in ICHSTRAP0 - the ME is a blob, we don't want it in libreboot descriptorRegion.ichStraps.ichStrap0.meDisable = 1; // disable ME and TPM in MCHSTRAP0 - descriptorRegion.mchStraps.mchStrap0.meDisable = 1; - descriptorRegion.mchStraps.mchStrap0.tpmDisable = 1; + descriptorRegion.mchStraps.mchStrap0.meDisable = 1; // ME is a blob. not wanted in libreboot. + descriptorRegion.mchStraps.mchStrap0.tpmDisable = 1; // not wanted in libreboot - // disable ME, apart from chipset bugfixes (ME region still required) - //descriptorRegion.mchStraps.mchStrap0.meAlternateDisable = 1; + // disable ME, apart from chipset bugfixes (ME region should first be re-enabled above) + // This is sort of like the CPU microcode updates, but for the chipset + // (commented out below here, since blobs go against libreboot's purpose, + // but may be interesting for others) + // descriptorRegion.mchStraps.mchStrap0.meAlternateDisable = 1; // debugging printf("\nRelocated Descriptor start block: %08x ; Descriptor end block: %08x\n", descriptorRegion.regionSection.flReg0.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg0.LIMIT << flRegionBitShift); @@ -147,19 +211,27 @@ int main(int argc, char *argv[]) printf("Relocated ME start block: %08x ; ME end block: %08x\n", descriptorRegion.regionSection.flReg2.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg2.LIMIT << flRegionBitShift); printf("Relocated GBe start block: %08x ; GBe end block: %08x\n", descriptorRegion.regionSection.flReg3.BASE << flRegionBitShift, descriptorRegion.regionSection.flReg3.LIMIT << flRegionBitShift); + // ---------------------------------------------------------------------------------------------------------------- + // Convert the descriptor and gbe back to byte arrays, so that they + // can more easily be written to files: + // deblobbed descriptor region char deblobbedDescriptorBuffer[DESCRIPTORREGIONSIZE]; memcpy(&deblobbedDescriptorBuffer, &descriptorRegion, DESCRIPTORREGIONSIZE); + // delete old file before continuing remove(deblobbedDescriptorFilename); + // open new file for writing the deblobbed descriptor+gbe fp = fopen(deblobbedDescriptorFilename, "ab"); + // write the descriptor region into the first part if (DESCRIPTORREGIONSIZE != fwrite(deblobbedDescriptorBuffer, sizeof(char), DESCRIPTORREGIONSIZE, fp)) { printf("\nerror: writing descriptor region failed\n"); return 1; } + // add gbe to the end of the file if (GBEREGIONSIZE != fwrite(gbeBuffer, sizeof(char), GBEREGIONSIZE, fp)) { printf("\nerror: writing GBe region failed\n"); @@ -173,17 +245,20 @@ int main(int argc, char *argv[]) // calculate the 0x3F'th 16-bit uint to make the desired final checksum for GBe // observed values (from actual factory.rom dumps) 0xBABA 0x3ABA 0x34BA. spec defined as 0xBABA. // theoretically, this could be any l33t speak variation of BABA, eg 3434 or BA34, and so on, but this is untested. so far. - // 40BA was also observed in another factory dump for another X200 - this is not l33t speak. + // 40BA was also observed in another factory dump for another X200 - this is l33t speak for aoba, not baba.... // maybe only the 8 least significant bits are checked? or something deeper than that + // it will need to be tested if those gbe regions that use something other than baba + // will also work with the checksum changed to match baba (per datasheets) unsigned short gbeCalculatedChecksum = GetChecksum(gbeBuffer, 0xBABA); // get the actual 0x3F'th 16-bit uint that was already in the supplied (pre-compiled) region data - unsigned short gbeChecksum = GetRegionWord(0x3F, gbeBuffer); + unsigned short gbeChecksum = GetRegionWord(0x3F, gbeBuffer); // from the original factory.rom printf("\ncalculated Gbe checksum: 0x%hx actual GBe checksum: 0x%hx\n", gbeCalculatedChecksum, gbeChecksum); return 0; } +// checksum calculation for gbe region (algorithm based on datasheet) unsigned short GetChecksum(char* regionData, unsigned short desiredValue) { unsigned short regionWord; @@ -197,7 +272,6 @@ unsigned short GetChecksum(char* regionData, unsigned short desiredValue) checksum = desiredValue - checksum; return checksum; } - // Read a 16-bit unsigned int from a supplied region buffer unsigned short GetRegionWord(int index, char* regionData) { diff --git a/resources/utilities/ich9deblob/ich9desc.c b/resources/utilities/ich9deblob/ich9desc.c index c3e1edf..b852497 100644 --- a/resources/utilities/ich9deblob/ich9desc.c +++ b/resources/utilities/ich9deblob/ich9desc.c @@ -1,5 +1,6 @@ /* * ich9desc.c + * This file is part of the ich9deblob utility from the libreboot project * * Copyright (C) 2014 Steve Shenton * Francis Rowe @@ -17,18 +18,37 @@ * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ + +// Purpose: provide struct representing descriptor region. +// Map actual buffers of this regions, directly to instances of these +// structs. This makes working with descriptor really easy. + +// bit fields used, corresponding to datasheet. See links to datasheets +// and documentation in ich9deblob.c struct FLVALSIG{ unsigned int signature; }; struct FLMAP0 { + // least signicant bits unsigned char FCBA : 8; unsigned char NC : 2; unsigned char : 6; + // ^^^^ unnamed members like these represent unused bits (per datasheet). + // the same applies for all structs in this file. unsigned char FRBA : 8; unsigned char NR : 3; unsigned char : 5; + // most significant bits. + + // the datasheet lists msb's first and lsb's last, in each table. + // meanwhile, x86 gcc treats the members at the top of the struct as lsb's + // and at the bottom of the struct, the members there are msb's. The same + // fact applies to all the other structs below. + + // non-x86 (and/or non-gcc) is untested + // little endian assumed }; struct FLMAP1 { diff --git a/resources/utilities/ich9deblob/ich9gbe.c b/resources/utilities/ich9deblob/ich9gbe.c index 69eb9ca..b6d279b 100644 --- a/resources/utilities/ich9deblob/ich9gbe.c +++ b/resources/utilities/ich9deblob/ich9gbe.c @@ -18,12 +18,16 @@ */ struct GBEREGIONRECORD { - unsigned char macAddress[6]; - unsigned char otherStuff[120]; - unsigned short checkSum; + unsigned char macAddress[6]; // 0x03 words, or 0x06 bytes + unsigned char otherStuff[120]; // 0x3c words, or 0x7E bytes + unsigned short checkSum; // when added to the sum of all words above, this should be 0xBABA unsigned char padding1[3968]; - unsigned char macAddress2[6]; - unsigned char otherStuff2[120]; - unsigned short checkSum2; + // Backup region: + // This is actually "main" on X200, since the real main has a bad checksum + // and other errors. You should do what you need on this one (if modifying + // lenovobios's gbe region) and then copy to main + unsigned char macAddress2[6]; // ditto + unsigned char otherStuff2[120]; // ditto + unsigned short checkSum2; // ditto unsigned char padding2[3968]; }; -- cgit v0.9.1