Date: Wed, 04 Feb 2015 04:14:49 -0500 Subject: Documentation: implement theme, drastically improve readability --- (limited to 'docs/hcl/x200_remove_me.html') diff --git a/docs/hcl/x200_remove_me.html b/docs/hcl/x200_remove_me.html index 48468c6..ae0a83f 100644 --- a/docs/hcl/x200_remove_me.html +++ b/docs/hcl/x200_remove_me.html @@ -13,181 +13,189 @@ -

ThinkPad X200: remove the ME (manageability engine)

- This sections relates to disabling and removing the ME (Intel Management Engine) - on the ThinkPad X200. -

- The ME is a blob that typically must be left inside the flash chip (in the ME region, as outlined - by the default descriptor). On the X200, it is possible to remove it without any ill effects. All - other parts of coreboot on the X200 can be blob-free, so removing the ME was the last obstacle to - get X200 support in libreboot (the machine can also work without the microcode blobs). -

- The ME is removed and disabled in libreboot by modifying the descriptor. More info about - this can be found in the ich9deblob/ich9gen source code in resources/utilities/ich9deblob/ - in libreboot, or more generally on this page. -

- Or back to main X200 compatibility page (x200.html). -

+ +

ThinkPad X200: remove the ME (manageability engine)

+ This sections relates to disabling and removing the ME (Intel Management Engine) + on the ThinkPad X200. +

+ The ME is a blob that typically must be left inside the flash chip (in the ME region, as outlined + by the default descriptor). On the X200, it is possible to remove it without any ill effects. All + other parts of coreboot on the X200 can be blob-free, so removing the ME was the last obstacle to + get X200 support in libreboot (the machine can also work without the microcode blobs). +

+ The ME is removed and disabled in libreboot by modifying the descriptor. More info about + this can be found in the ich9deblob/ich9gen source code in resources/utilities/ich9deblob/ + in libreboot, or more generally on this page. +

+ Back to main X200 compatibility page (x200.html). +

+ +

ICH9 gen utility

- -

- This is no longer strictly necessary. Libreboot ROM images for X200 now - contain the 12KiB descriptor+gbe generated from ich9gen, by default. -

- -

- It is no longer necessary to use ich9deblob to generate - a deblobbed descriptor+gbe image for the X200. ich9gen is a small utility within - ich9deblob that can generate them from scratch, without a factory.bin dump. -

- -

- Run:
- $ ./ich9gen -

- -

- It is also possible to generate a descriptor+gbe image with your own MAC address - inside (with the Gbe checksum updated to match). Run:
- $ ./ich9gen --macaddress XX:XX:XX:XX:XX:XX
- (replace the XX chars with the hexadecimal chars in the MAC address that you want) -

- -

- You can find out your MAC address from ip addr or ifconfig in GNU/Linux. - Alternatively, if you are running libreboot already (with the correct MAC address in your - ROM), dump it (flashrom -r) and read the first 6 bytes from position 0x1000 (or 0x2000) in a hex editor - (or, rename it to factory.rom and run it in ich9deblob: in the newly created mkgbe.c - will be the individual bytes of your MAC address). If you are currently running the stock firmware - and haven't installed libreboot yet, you can also run that through ich9deblob to get the mac address. -

- -

- An even simpler way to get the MAC address would be to read what's on the little sticker on - the underside. (on the X200, this would be near the VGA port). -

ICH9 gen utility

- A bash script is also included in libreboot which will change the mac address (using ich9gen) - on all X200 ROM images. For instance:
- $ ./ich9macchange XX:XX:XX:XX:XX:XX -

+ This is no longer strictly necessary. Libreboot ROM images for X200 now + contain the 12KiB descriptor+gbe generated from ich9gen, by default. +

- Two new files will be created: -

ich9fdgbe_4m.bin: this is for X200 laptops with the 4MB flash chip.
ich9fdgbe_8m.bin: this is for X200 laptops with the 8MB flash chip.

+ It is no longer necessary to use ich9deblob to generate + a deblobbed descriptor+gbe image for the X200. ich9gen is a small utility within + ich9deblob that can generate them from scratch, without a factory.bin dump. +

- ich9gen executables can be found under ./ich9deblob/ statically compiled in - libreboot_bin. If you are using src or git, build ich9gen from source with:
- $ ./builddeps-ich9deblob
- The executable will appear under resources/utilities/ich9deblob/ -

- -

- Assuming that your X200 libreboot image is named libreboot.rom, copy - the file to where libreboot.rom is located - and then run, for instance:
- $ dd if=ich9fdgbe_8m.bin of=libreboot.rom bs=1 count=12k conv=notrunc
- or:
- $ dd if=ich9fdgbe_4m.bin of=libreboot.rom bs=1 count=12k conv=notrunc -

- -

- Your X200 libreboot.rom image is now ready to be flashed on the machine. Refer back to - ../install/index.html#flashrom - for how to flash it. -

+ Run:
+ $ ./ich9gen +

+ +

+ It is also possible to generate a descriptor+gbe image with your own MAC address + inside (with the Gbe checksum updated to match). Run:
+ $ ./ich9gen --macaddress XX:XX:XX:XX:XX:XX
+ (replace the XX chars with the hexadecimal chars in the MAC address that you want) +

+ +

+ You can find out your MAC address from ip addr or ifconfig in GNU/Linux. + Alternatively, if you are running libreboot already (with the correct MAC address in your + ROM), dump it (flashrom -r) and read the first 6 bytes from position 0x1000 (or 0x2000) in a hex editor + (or, rename it to factory.rom and run it in ich9deblob: in the newly created mkgbe.c + will be the individual bytes of your MAC address). If you are currently running the stock firmware + and haven't installed libreboot yet, you can also run that through ich9deblob to get the mac address. +

+ +

+ An even simpler way to get the MAC address would be to read what's on the little sticker on + the underside. (on the X200, this would be near the VGA port). +

+ +

+ A bash script is also included in libreboot which will change the mac address (using ich9gen) + on all X200 ROM images. For instance:
+ $ ./ich9macchange XX:XX:XX:XX:XX:XX +

+ +

+ Two new files will be created: +

ich9fdgbe_4m.bin: this is for X200 laptops with the 4MB flash chip.
ich9fdgbe_8m.bin: this is for X200 laptops with the 8MB flash chip.

+ +

+ ich9gen executables can be found under ./ich9deblob/ statically compiled in + libreboot_bin. If you are using src or git, build ich9gen from source with:
+ $ ./builddeps-ich9deblob
+ The executable will appear under resources/utilities/ich9deblob/ +

+ +

+ Assuming that your X200 libreboot image is named libreboot.rom, copy + the file to where libreboot.rom is located + and then run, for instance:
+ $ dd if=ich9fdgbe_8m.bin of=libreboot.rom bs=1 count=12k conv=notrunc
+ or:
+ $ dd if=ich9fdgbe_4m.bin of=libreboot.rom bs=1 count=12k conv=notrunc +

+ +

+ Your X200 libreboot.rom image is now ready to be flashed on the machine. Refer back to + ../install/index.html#flashrom + for how to flash it. +

+ +

ICH9 deblob utility

- -

- This is no longer strictly necessary. Libreboot ROM images for X200 now - contain the 12KiB descriptor+gbe generated from ich9gen, by default. -

ICH9 deblob utility

- This was the tool originally used to disable the ME on X200. ich9gen now supersedes it; - ich9gen is better because it does not rely on dumping the factory.rom image (whereas, ich9deblob does). -

- -

- This is what you will use to generate the deblobbed descriptor+gbe regions for your libreboot ROM image. -

- If you are working with libreboot_src (or git), you can find the source under resources/utilities/ich9deblob/ - and will already be compiled if you ran ./builddeps or ./builddeps-ich9deblob from the main directory (./), - otherwise you can build it like so:
- $ ./builddeps-ich9deblob
- An executable file named ich9deblob will now appear under resources/utilities/ich9deblob/ -

- If you are working with libreboot_bin release archive, you can find the utility included, statically compiled - (for i686 and x86_64 on GNU/Linux) under ./ich9deblob/. -

- -

- Place the factory.rom from your X200 - (can be obtained using the guide at ../install/x200_external.html) in - the directory where you have your ich9deblob executable, then run the tool:
- $ ./ich9deblob -

- A 12kiB file named deblobbed_descriptor.bin will now appear. Keep this and the factory.rom stored in a safe location! - The first 4KiB contains the descriptor data region for your machine, and the next 8KiB contains the gbe region (config data for your - gigabit NIC). These 2 regions could actually be separate files, but they are joined into 1 file in this case. -

- -

- Assuming that your X200 libreboot image is named libreboot.rom, copy - the deblobbed_descriptor.bin file to where libreboot.rom is located - and then run:
- $ dd if=deblobbed_descriptor.bin of=libreboot.rom bs=1 count=12k conv=notrunc -

- -

- The utility will also generate 4 additional files: -

mkdescriptor.c
mkdescriptor.h
mkgbe.c
mkgbe.h

- These are C source files that can re-generate the very same Gbe and Descriptor structs - (from ich9deblob/ich9gen). To use these, place them in src/ich9gen/ in ich9deblob, then re-build. - The newly built ich9gen executable will be able to re-create the very same 12KiB file from scratch, - based on the C structs, this time without the need for a factory.rom dump! -

+ This is no longer strictly necessary. Libreboot ROM images for X200 now + contain the 12KiB descriptor+gbe generated from ich9gen, by default. +

+ +

+ This was the tool originally used to disable the ME on X200. ich9gen now supersedes it; + ich9gen is better because it does not rely on dumping the factory.rom image (whereas, ich9deblob does). +

- You should now have a libreboot.rom image containing the correct 4K descriptor and 8K gbe regions, which - will then be safe to flash. Refer back to ../install/index.html#flashrom - for how to flash it. -

+ This is what you will use to generate the deblobbed descriptor+gbe regions for your libreboot ROM image. +

+ If you are working with libreboot_src (or git), you can find the source under resources/utilities/ich9deblob/ + and will already be compiled if you ran ./builddeps or ./builddeps-ich9deblob from the main directory (./), + otherwise you can build it like so:
+ $ ./builddeps-ich9deblob
+ An executable file named ich9deblob will now appear under resources/utilities/ich9deblob/ +

+ If you are working with libreboot_bin release archive, you can find the utility included, statically compiled + (for i686 and x86_64 on GNU/Linux) under ./ich9deblob/. +

+ +

+ Place the factory.rom from your X200 + (can be obtained using the guide at ../install/x200_external.html) in + the directory where you have your ich9deblob executable, then run the tool:
+ $ ./ich9deblob +

+ A 12kiB file named deblobbed_descriptor.bin will now appear. Keep this and the factory.rom stored in a safe location! + The first 4KiB contains the descriptor data region for your machine, and the next 8KiB contains the gbe region (config data for your + gigabit NIC). These 2 regions could actually be separate files, but they are joined into 1 file in this case. +

+ +

+ Assuming that your X200 libreboot image is named libreboot.rom, copy + the deblobbed_descriptor.bin file to where libreboot.rom is located + and then run:
+ $ dd if=deblobbed_descriptor.bin of=libreboot.rom bs=1 count=12k conv=notrunc +

+ +

+ The utility will also generate 4 additional files: +

mkdescriptor.c
mkdescriptor.h
mkgbe.c
mkgbe.h

+ These are C source files that can re-generate the very same Gbe and Descriptor structs + (from ich9deblob/ich9gen). To use these, place them in src/ich9gen/ in ich9deblob, then re-build. + The newly built ich9gen executable will be able to re-create the very same 12KiB file from scratch, + based on the C structs, this time without the need for a factory.rom dump! +

+ +

+ You should now have a libreboot.rom image containing the correct 4K descriptor and 8K gbe regions, which + will then be safe to flash. Refer back to ../install/index.html#flashrom + for how to flash it. +

+ +

The sections below are adapted from (mostly) IRC logs related to early development getting the ME removed on the X200. They are useful for background information. This could not have been done without sgsit's help.

Early notes

@@ -216,9 +224,11 @@

+ +

Flash chips

@@ -243,11 +253,11 @@

Early development notes

 
@@ -312,35 +322,33 @@ Flash Erase Size = 0x1000

- It's a utility called 'Flash Image Tool' for ME 4.x that was used for this. You drag a complete - image into in and the utility decomposes the various components, allowing you to set soft straps. -

- This tool is proprietary, for Windows only, but was used to deblob the X200. End justified means, and - the utility is no longer needed since the ich9deblob utility (documented on this page) can now be - used to create deblobbed descriptors. -

- -

+ It's a utility called 'Flash Image Tool' for ME 4.x that was used for this. You drag a complete + image into in and the utility decomposes the various components, allowing you to set soft straps. +

+ This tool is proprietary, for Windows only, but was used to deblob the X200. End justified means, and + the utility is no longer needed since the ich9deblob utility (documented on this page) can now be + used to create deblobbed descriptors. +

- GBE (gigabit ethernet) region in SPI flash -

+ GBE (gigabit ethernet) region in SPI flash +

- Of the 8K, about 95% is 0xFF. - The data is the gbe region is fully documented in this public datasheet: - http://www.intel.co.uk/content/dam/doc/application-note/i-o-controller-hub-9m-82567lf-lm-v-nvm-map-appl-note.pdf -

+ Of the 8K, about 95% is 0xFF. + The data is the gbe region is fully documented in this public datasheet: + http://www.intel.co.uk/content/dam/doc/application-note/i-o-controller-hub-9m-82567lf-lm-v-nvm-map-appl-note.pdf +

- The only actual content found was: -

+ The only actual content found was: +

 
@@ -358,17 +366,19 @@ DD  CC  18  00  11  20  17  00  DD  DD  18  00  12  20  17  00

- The first part is the MAC address set to all 0x1F. It's repeated haly way through - the 8K area, and the rest is all 0xFF. This is all documented in the datasheet. -

+ The first part is the MAC address set to all 0x1F. It's repeated haly way through + the 8K area, and the rest is all 0xFF. This is all documented in the datasheet. +

- The GBe region starts at 0x20A000 bytes from the *end* of a factory image and is 0x2000 bytes long. - In libreboot (deblobbed) the descriptor is set to put gbe directly after the initial 4K flash descriptor. - So the first 4K of the ROM is the descriptor, and then the next 8K is the gbe region. -

+ The GBe region starts at 0x20A000 bytes from the *end* of a factory image and is 0x2000 bytes long. + In libreboot (deblobbed) the descriptor is set to put gbe directly after the initial 4K flash descriptor. + So the first 4K of the ROM is the descriptor, and then the next 8K is the gbe region. +

GBE region: change MAC address

@@ -399,116 +409,117 @@ DD CC 18 00 11 20 17 00 DD DD 18 00 12 20 17 00 and that has to add up to 0xBABA. In other words, the checksum is 0xBABA minus the total of the first 0x3E 16bit numbers (unsigned), ignoring any overflow. - +

Flash descriptor region

- http://www.intel.co.uk/content/dam/doc/datasheet/io-controller-hub-9-datasheet.pdf - from page 850 onwards. This explains everything that is in the flash descriptor, which can be used to understand what libreboot - is doing about modifying it. -

+ http://www.intel.co.uk/content/dam/doc/datasheet/io-controller-hub-9-datasheet.pdf + from page 850 onwards. This explains everything that is in the flash descriptor, which can be used to understand what libreboot + is doing about modifying it. +

- How to deblob: -

patch the number of regions present in the descriptor from 5 - 3
originally descriptor + bios + me + gbe + platform
modified = descriptor + bios + gbe
the next stage is to patch the part of the descriptor which defines the start and end point of each section
then cut out the gbe region and insert it just after the region
all this can be substantiated with public docs (ICH9 datasheet)
the final part is flipping 2 bits. Halting the ME via 1 MCH soft strap and 1 ICH soft strap
the part of the descriptor described there gives the base address and length of each region (bits 12:24 of each address)
to disable a region, you set the base address to 0xFFF and the length to 0
and you change the number of regions from 4 (zero based) to 2

+ How to deblob: +

patch the number of regions present in the descriptor from 5 - 3
originally descriptor + bios + me + gbe + platform
modified = descriptor + bios + gbe
the next stage is to patch the part of the descriptor which defines the start and end point of each section
then cut out the gbe region and insert it just after the region
all this can be substantiated with public docs (ICH9 datasheet)
the final part is flipping 2 bits. Halting the ME via 1 MCH soft strap and 1 ICH soft strap
the part of the descriptor described there gives the base address and length of each region (bits 12:24 of each address)
to disable a region, you set the base address to 0xFFF and the length to 0
and you change the number of regions from 4 (zero based) to 2

- There's an interesting parameter called 'ME Alternate disable', which allows the ME to only handle hardware errata in the southbridge, - but disables any other functionality. This is similar to the 'ignition' in the 5 series and higher but using the standard firmware - instead of a small 128K version. Useless for libreboot, though. -

+ There's an interesting parameter called 'ME Alternate disable', which allows the ME to only handle hardware errata in the southbridge, + but disables any other functionality. This is similar to the 'ignition' in the 5 series and higher but using the standard firmware + instead of a small 128K version. Useless for libreboot, though. +

- To deblob the x200, you chop out the platform and ME regions and correct the addresses in flReg1-4. - Then you set meDisable to 1 in ICHSTRAP0 and MCHSTRAP0. -

+ To deblob the x200, you chop out the platform and ME regions and correct the addresses in flReg1-4. + Then you set meDisable to 1 in ICHSTRAP0 and MCHSTRAP0. +

How to patch the descriptor from the factory.rom dump

map the first 4k into the struct (minus the gbe region)
set NR in FLMAP0 to 2 (from 4)
adjust BASE and LIMIT in flReg1,2,3,4 to reflect the new location of each region (or remove them in the case of Platform and ME)
set meDisable to 1/true in ICHSTRAP0 and MCHSTRAP0
extract the 8k GBe region and append that to the end of the 4k descriptor
output the 12k concatenated chunk
Then it can be dd'd into the first 12K part of a coreboot image.
the GBe region always starts 0x20A000 bytes from the end of the ROM

How to patch the descriptor from the factory.rom dump

map the first 4k into the struct (minus the gbe region)
set NR in FLMAP0 to 2 (from 4)
adjust BASE and LIMIT in flReg1,2,3,4 to reflect the new location of each region (or remove them in the case of Platform and ME)
set meDisable to 1/true in ICHSTRAP0 and MCHSTRAP0
extract the 8k GBe region and append that to the end of the 4k descriptor
output the 12k concatenated chunk
Then it can be dd'd into the first 12K part of a coreboot image.
the GBe region always starts 0x20A000 bytes from the end of the ROM

- This means that libreboot's descriptor region will simply define the following regions: -

descriptor (4K)
gbe (8K)
bios (rest of flash chip. CBFS also set to occupy this whole size)

+ This means that libreboot's descriptor region will simply define the following regions: +

descriptor (4K)
gbe (8K)
bios (rest of flash chip. CBFS also set to occupy this whole size)

- The data in the descriptor region is little endian, and it represents bits 24:12 of the address - (bits 12-24, written this way since bit 24 is nearer to left than bit 12 in the binary representation). -

- So, x << 12 = address -

- If it's in descriptor mode, then the first 4 bytes will be 5A A5 F0 0F. -

+ The data in the descriptor region is little endian, and it represents bits 24:12 of the address + (bits 12-24, written this way since bit 24 is nearer to left than bit 12 in the binary representation). +

+ So, x << 12 = address +

+ If it's in descriptor mode, then the first 4 bytes will be 5A A5 F0 0F. +

platform data partition in boot flash (factory.rom / lenovo bios)

- Basically useless for libreboot, since it appears to be a blob. - Removing it didn't cause any issues in libreboot. -

- This is a 32K region from the factory image. It could be data - (non-functional) that the original Lenovo BIOS used, but we don't know. -

- -

- It has only a 448 byte fragment different from 0x00 or 0xFF. -

+ Basically useless for libreboot, since it appears to be a blob. + Removing it didn't cause any issues in libreboot. +

+ This is a 32K region from the factory image. It could be data + (non-functional) that the original Lenovo BIOS used, but we don't know. +

+ It has only a 448 byte fragment different from 0x00 or 0xFF. +

+ +

- Copyright © 2014 Francis Rowe <info@gluglug.org.uk>
- This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. - A copy of the license can be found at ../license.txt. -

+ Copyright © 2014, 2015 Francis Rowe <info@gluglug.org.uk>
+ This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. + A copy of the license can be found at ../license.txt. +

- This document is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See ../../license.txt for more information. -

+ This document is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See ../../license.txt for more information. +

+ +

-- cgit v0.9.1