1  .TH me_cleaner 1 "JUNE 2018"
  2  .SH me_cleaner
  3  .PP
  4  me_cleaner \-  Tool for partial deblobbing of Intel ME/TXE firmware images
  5  .SH SYNOPSIS
  6  .PP
  7  \fB\fCme_cleaner.py\fR [\-h] [\-v] [\-O output_file] [\-S | \-s] [\-r] [\-k]
  8  [\-w whitelist | \-b blacklist] [\-d] [\-t] [\-c] [\-D output_descriptor]
  9  [\-M output_me_image] \fIfile\fP
 10  .SH DESCRIPTION
 11  .PP
 12  \fB\fCme_cleaner\fR is a tool able to disable parts of Intel ME/TXE by:
 13  .RS
 14  .IP \(bu 2
 15  removing most of the code from its firmware
 16  .IP \(bu 2
 17  setting a special bit to force it to disable itself after the hardware
 18  initialization
 19  .RE
 20  .PP
 21  Using both the modes seems to be the most reliable way on many platforms.
 22  .PP
 23  The resulting modified firmware needs to be flashed (in most of the cases) with
 24  an external programmer, often a dedicated SPI programmer or a Linux board with
 25  a SPI master interface.
 26  .PP
 27  \fB\fCme_cleaner\fR works at least from Nehalem to Coffee Lake (for Intel ME) and on
 28  Braswell/Cherry Trail (for Intel TXE), but may work as well on newer or
 29  different architectures.
 30  .PP
 31  While \fB\fCme_cleaner\fR have been tested on a great number of platforms, fiddling
 32  with the Intel ME/TXE firmware is \fIvery dangerous\fP and can easily lead to a
 33  dead PC.
 34  .PP
 35  \fIYOU HAVE BEEN WARNED.\fP
 36  .SH POSITIONAL ARGUMENTS
 37  .TP
 38  \fB\fCfile\fR
 39  ME/TXE image or full dump.
 40  .SH OPTIONAL ARGUMENTS
 41  .TP
 42  \fB\fC\-h\fR, \fB\fC\-\-help\fR
 43  Show the help message and exit.
 44  .TP
 45  \fB\fC\-v\fR, \fB\fC\-\-version\fR
 46  Show program's version number and exit.
 47  .TP
 48  \fB\fC\-O\fR, \fB\fC\-\-output\fR
 49  Save the modified image in a separate file, instead of modifying the
 50  original file.
 51  .TP
 52  \fB\fC\-S\fR, \fB\fC\-\-soft\-disable\fR
 53  In addition to the usual operations on the ME/TXE firmware, set the
 54  MeAltDisable bit or the HAP bit to ask Intel ME/TXE to disable itself after
 55  the hardware initialization (requires a full dump).
 56  .TP
 57  \fB\fC\-s\fR, \fB\fC\-\-soft\-disable\-only\fR
 58  Instead of the usual operations on the ME/TXE firmware, just set the
 59  MeAltDisable bit or the HAP bit to ask Intel ME/TXE to disable itself after
 60  the hardware initialization (requires a full dump).
 61  .TP
 62  \fB\fC\-r\fR, \fB\fC\-\-relocate\fR
 63  Relocate the FTPR partition to the top of the ME region to save even more
 64  space.
 65  .TP
 66  \fB\fC\-t\fR, \fB\fC\-\-truncate\fR
 67  Truncate the empty part of the firmware (requires a separated ME/TXE image or
 68  \fB\fC\-\-extract\-me\fR).
 69  .TP
 70  \fB\fC\-k\fR, \fB\fC\-\-keep\-modules\fR
 71  Don't remove the FTPR modules, even when possible.
 72  .TP
 73  \fB\fC\-w\fR, \fB\fC\-\-whitelist\fR
 74  Comma separated list of additional partitions to keep in the final image.
 75  This can be used to specify the MFS partition for example, which stores PCIe
 76  and clock settings.
 77  .TP
 78  \fB\fC\-b\fR, \fB\fC\-\-blacklist\fR
 79  Comma separated list of partitions to remove from the image. This option
 80  overrides the default removal list.
 81  .TP
 82  \fB\fC\-d\fR, \fB\fC\-\-descriptor\fR
 83  Remove the ME/TXE Read/Write permissions to the other regions on the flash
 84  from the Intel Flash Descriptor (requires a full dump).
 85  .TP
 86  \fB\fC\-D\fR, \fB\fC\-\-extract\-descriptor\fR
 87  Extract the flash descriptor from a full dump; when used with \fB\fC\-\-truncate\fR
 88  save a descriptor with adjusted regions start and end.
 89  .TP
 90  \fB\fC\-M\fR, \fB\fC\-\-extract\-me\fR
 91  Extract the ME firmware from a full dump; when used with \fB\fC\-\-truncate\fR save a
 92  truncated ME/TXE image.
 93  .TP
 94  \fB\fC\-c\fR, \fB\fC\-\-check\fR
 95  Verify the integrity of the fundamental parts of the firmware and exit.
 96  .SH SUPPORTED PLATFORMS
 97  .PP
 98  Currently \fB\fCme_cleaner\fR has been tested on the following platforms:
 99  .TS
100  allbox;
101  cb cb cb cb
102  c c c c
103  c c c c
104  c c c c
105  c c c c
106  c c c c
107  c c c c
108  c c c c
109  c c c c
110  .
111  PCH	CPU	ME	SKU
112  Ibex Peak	Nehalem/Westmere	6.0	Ignition
113  Ibex Peak	Nehalem/Westmere	6.x	1.5/5 MB
114  Cougar Point	Sandy Bridge	7.x	1.5/5 MB
115  Panther Point	Ivy Bridge	8.x	1.5/5 MB
116  Lynx/Wildcat Point	Haswell/Broadwell	9.x	1.5/5 MB
117  Wildcat  Point LP	Broadwell Mobile	10.0	1.5/5 MB
118  Sunrise Point	Skylake/Kabylake	11.x	CON/COR
119  Union Point	Kabylake	11.x	CON/COR
120  .TE
121  .TS
122  allbox;
123  cb cb cb
124  c c c
125  .
126  SoC	TXE	SKU
127  Braswell/Cherry Trail	2.x	1.375 MB
128  .TE
129  .PP
130  All the reports are available on the project's GitHub page \[la]https://github.com/corna/me_cleaner/issues/3\[ra]\&.
131  .SH EXAMPLES
132  .PP
133  Check whether the provided image has a valid structure and signature:
134  .IP
135  \fB\fCme_cleaner.py \-c dumped_firmware.bin\fR
136  .PP
137  Remove most of the Intel ME firmware modules but don't set the HAP/AltMeDisable
138  bit:
139  .IP
140  \fB\fCme_cleaner.py \-S \-O modified_me_firmware.bin dumped_firmware.bin\fR
141  .PP
142  Remove most of the Intel ME firmware modules and set the HAP/AltMeDisable bit,
143  disable the Read/Write access of Intel ME to the other flash region, then
144  relocate the code to the top of the image and truncate it, extracting a modified
145  descriptor and ME image:
146  .IP
147  \fB\fCme_cleaner.py \-S \-r \-t \-d \-D ifd_shrinked.bin \-M me_shrinked.bin \-O modified_firmware.bin full_dumped_firmware.bin\fR
148  .SH BUGS
149  .PP
150  Bugs should be reported on the project's GitHub page \[la]https://github.com/corna/me_cleaner\[ra]\&.
151  .SH AUTHOR
152  .PP
153  Nicola Corna \[la]nicola@corna.info\[ra]
154  .SH SEE ALSO
155  .PP
156  .BR flashrom (8),
157  me_cleaner's Wiki \[la]https://github.com/corna/me_cleaner/wiki\[ra]