util/kbc1126/README.md

   1 KBC1126 firmware tools
   2 ======================
   3
   4 Many HP laptops use 8051-based SMSC KBC1098/KBC1126 as embedded
   5 controller. Two blobs can be found in the HP firmware images. The
   6 `kbc1126_ec_dump` and `kbc1126_ec_insert` tools are used to dump the
   7 two blobs from the factory firmware and insert them to the firmware
   8 image.
   9
  10
  11 Firmware format
  12 ---------------
  13
  14 We can easily find the BIOS region of the HP laptop firmware from the
  15 HP firmware update tool, which can be downloaded from the HP
  16 website. Now I take HP Elitebook 8470p as an example. This laptop has
  17 a 16MB flash chip, the last 5MB of which is the BIOS region.
  18
  19 I use [radare2](https://radare.org) to analyze the firmware. Open the
  20 firmware image, and we can see 8 bytes at `$s-0x100` (`$s` means the
  21 image size).
  22
  23   [0x00000000]> x @ $s-0x100
  24   - offset -   0 1  2 3  4 5  6 7  8 9  A B  C D  E F  0123456789ABCDEF
  25   0x00ffff00  fff7 0008 f700 08ff 0000 0000 0000 0000  ................
  26
  27 X86 machines map the firmware at the end of the memory address
  28 space. These 8 bytes tell the address of the two blobs, which we call
  29 FW1 (uses bytes 0-3) and FW2 (uses bytes 4-7).
  30
  31 Let's look at FW1. The first two bytes mean the address of FW1 is
  32 0xfff700 (these two bytes use big endian), i.e. `$s-0x900`. Byte 2 and
  33 3 are just complements of byte 1 and 2 (in this case,
  34 0x0008=0xffff-0xfff7).
  35
  36   [0x00000000]> x @ $s-0x900
  37   - offset -   0 1  2 3  4 5  6 7  8 9  A B  C D  E F  0123456789ABCDEF
  38   0x00fff700  fc07 c13e 02ff 1000 0000 0000 0000 0000  ...>............
  39
  40 Both FW1 and FW2 use the same format: the first two bytes is payload
  41 length, then a two-byte checksum, then the payload. The payload length
  42 and checksum are both in little endian. The checksum is
  43 [SYSV checksum](https://en.wikipedia.org/wiki/SYSV_checksum).
  44
  45
  46 How to use the tools
  47 --------------------
  48
  49 `kbc1126_ec_dump` is used to dump FW1 and FW2. Run `kbc1126_ec_dump
  50 bios.rom`, then bios.rom.fw1 and bios.rom.fw2 are generated in the
  51 working directory.
  52
  53 `kbc1126_ec_insert` will overwrite a firmware image by inserting FW1
  54 and FW2 in it. Please run it for its usage. You need to specify the
  55 offsets for FW1 and FW2. Using negative offset is recommended, which
  56 means the distance to the end of the image. For example, if we want to
  57 insert FW1 and FW2 at `$s-0x900` and `$s-0x90000` as the hp/8470p
  58 factory firmware to coreboot.rom, you can run `kbc1126_ec_insert
  59 coreboot.rom bios.rom.fw1 bios.rom.fw2 -0x900 -0x90000`.