summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorFrancis Rowe <info@gluglug.org.uk>2014-12-22 05:58:57 (EST)
committer Francis Rowe <info@gluglug.org.uk>2014-12-22 05:58:57 (EST)
commit87d1d08196ed2c69d4736a2815135bb69d996d11 (patch)
tree8e061f7d66fc3fa56744d56e9ea1428d00640653
parentb9bcb5c141131e955e18b67d1107db8f3a13aebf (diff)
downloadlibreboot-87d1d08196ed2c69d4736a2815135bb69d996d11.zip
libreboot-87d1d08196ed2c69d4736a2815135bb69d996d11.tar.gz
libreboot-87d1d08196ed2c69d4736a2815135bb69d996d11.tar.bz2
ich9deblob: add more commenting
-rw-r--r--resources/utilities/ich9deblob/ich9deblob.c130
-rw-r--r--resources/utilities/ich9deblob/ich9desc.c20
-rw-r--r--resources/utilities/ich9deblob/ich9gbe.c16
3 files changed, 132 insertions, 34 deletions
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 <sgsit@libreboot.org>
* Francis Rowe <info@gluglug.org.uk>
@@ -17,6 +20,25 @@
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
+
+/*
+ * 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 <stdio.h>
#include <string.h>
@@ -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 <sgsit@libreboot.org>
* Francis Rowe <info@gluglug.org.uk>
@@ -17,18 +18,37 @@
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
+
+// 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];
};