Documentation for “Zerocat Chipflasher: ‘kick’”
Generated on: Mon, 06 May 2024 18:51:05 +0200
Repository: git://zerocat.org/zerocat/projects/chipflasher.git
Board: board-v2.0.0-1477-619b5f407
Version: v2.0.5-0-619b5f407
Branch: master

Zerocat Chipflasher: kick

The first firmware, and its interface to connect.

Section #../../firmware1/doc/README.md

README

How to Build kick, the First Firmware

Configure: Board Version

To configure kick for board v2 (e.g. Chipflasher v2), the default, type:

    [env]$ make -C ../../firmware1/src config-BOARD_V2

To configure kick for board v1 (e.g. Chipflasher ‘board-edition-1’), type:

    [env]$ make -C ../../firmware1/src config-BOARD_V1

Configure: Baudrate

The host utility and the firmware use a serial connection for their communication. The speed of that connection is specified as baudrate.

The default baudrate is: 115200

Baudrate configuration is retrieved from file ../../firmware1/start/board.cfg, which in turn is managed via ../../firmware1/start/Makefile.

Compile

To build kick, type:

    [env]$ make -C ../../firmware1/src kick

Help

To get a full list of available targets, type:

    [env]$ make -C ../../firmware1/src help

Clean Up

To clean files and folders, type:

    [env]$ make -C ../../firmware1/src clean

How to Upload kick

To upload kick to onboard, free-design RAM, type:

    [env]$ make -C ../../firmware1/start kick-ram

To upload kick to onboard, proprietary-design EEPROM, type:

    [env]$ make -C ../../firmware1/start kick-eeprom

Help

To get a full list of available targets, type:

    [env]$ make -C ../../firmware1/start help
Section #../../firmware1/doc/configuration-registers.md

Configuration Registers

The chipflasher not only accesses the main memory array of SPI chips, it also gives you full control over the chips’ configuration registers:

../../images/screenshot-20211222-170705.png

Set register values using `kick'/`connect', the first firmware.

In case of chips made by Macronix, it even provides access to the lock bits of the security register, as well as to the secured, one-time-programmable region of these chips (typically 64 bytes in size):

../../images/screenshot-20211222-170328.png

Write and read SOTP Region using `kick'/`connect'.

Clean up and lock the region, before someone else will do it!

Clean-up Examples:

Section #../../firmware1/doc/how-to-use-board-edition-1.md

How to Use Chipflasher ‘board-edition-1’

Thank you for trying kick, the first firmware, with Zerocat Chipflasher ‘board-edition-1’!

Zerocat Chipflasher is your free-design hardware tool for flashing free firmware to BIOS chips. See #../../doc/targets.md for supported chips and targets.

Hardware Features

Recommended Add-Ons in Case of Purchase

Typical Setup

The typical setup requires a host that has an RS232 serial port available, as the chipflasher board doesn't provide its USB port for data, it is used for power only.

../../images/IMG_8020.jpeg

Zerocat Chipflasher, typical setup with an Y-USB-Cable

We recommend to drive the flasher with a librebooted or corebooted 64bit X60 ThinkPad. These machines can be flashed with the flashrom user space utility. A serial port is part of their docking station.

A typical setup looks like this:

  1. Computer with RS232 port, i.e.:

    • ThinkPad X60 with Docking Station and coreboot/libreboot firmware
    • Intel D945GCLF board with coreboot, no blobs required
    • other blobless desktop boards like GA-945GCM-S2L and GA-G41M-ES2L
  2. The Zerocat Chipflasher

  3. supported SPI flash chip, a single one or one soldered in place on its system board (section #../../doc/targets.md)

  4. external USB-Power-Adapter (5V @ 1000mA) or at least two USB-ports from the computer.

You will use three cables for connection:

Setup with External USB Power Adapter

    +------------+                +-------------+           +·············+
    | Host, i.e. |                | Zerocat     |           +---------+   :
    |  X60 +     |                | Chipflasher |---+3.3V-->| SPI     |   :
    |  Docking   |<--RS232-data-->|             |<---SPI--->|  Chip   |   :
    |            |                | firmware:   |           +---------+   :
    | software:  |      +--+5V--->|  `kick'     |           :             :
    | `connect'  |      |         +-------------+           : Systemboard :
    +------------+      |                                   : without     :
                    +--------------------+                  : Battery     :
                    | External USB Power |                  : nor Power   :
                    |  5V @ 1000mA       |                  +·············+
                    +--------------------+

Setup with Non-standard Y-USB-Cable

    +------------+                +-------------+           +·············+
    | Host, i.e. |                | Zerocat     |           +---------+   :
    |  X60 +     |<--RS232-data-->| Chipflasher |---+3.3V-->| SPI     |   :
    |  Docking   |                |             |<---SPI--->|  Chip   |   :
    |            |----+-+5V-USB-->| firmware:   |           +---------+   :
    | software:  |   /            |  `kick'     |           :             :
    | `connect'  |--+             +-------------+           : Systemboard :
    |            |                                          : without     :
    +------------+                                          : Battery     :
                                                            : nor Power   :
                                                            +·············+

Power Supply

WARNING: Proceed on your own risk!

  1. Discharge your body (touch any grounded metal like a water pipe) and make sure your are not electrostatically charged.

  2. If you are flashing a sysboard:

    • Do not power the sysboard on, nor connect any power plug.
    • Remove the main battery.
    • Unplug the small coin-battery.
  3. Power and GND will be applied to the SPI-chip by the chipflasher board only.

    Make sure you have not mixed these wires!
    See ../../hardware/gschem/chipflasher-page13.sch.png for pinouts.

  4. To power the chipflasher:

    • You may safely use your computer’s USB port according to official specs if you are going to flash a single desoldered chip.

    • In case of flashing chips in situ, soldered onto sysboards, please use an external USB-Power-Adapter (5VDC @ 1.000mA).

    • As a workaround, you may try a non-standard Y-USB-Cable which should work well in many cases, as the maximal requested current per USB port typically won't exceed 500mA. See #../../doc/power-profiles.md to get into details.

Clock Quality

The Zerocat Chipflasher is a handmade tool with long wires/open case that may catch or generate electromagnetic interference. To give you an idea about clock pulse quality and speed, we probed the signals right at the test-clip for you. The maximal SPI clock speed should be above 2.5MHz.

../../images/IMG_5716-small.jpg

Zerocat Chipflasher, typical clock pulse quality; here: 2.2MHz

Precautions

The software connect and the firmware kick are talking to each other via serial RS232 lines. Occasional transmission errors will be repaired automatically. However, if you encounter severe connection problems that render you helpless when trying to verify your data, boot the host with WLAN and network switched off, make sure that no other resource demanding process will start up (e.g. browser), and try again.

As long as the SPI-Bus Status LED (red) is not active, the SPI-Chip is not powered and you may feel free to connect/disconnect your target. However, if the LED is active, don't touch the connection!

If the system hangs for any reason, you should be save to kill the chipflasher’s power, because all SPI bus pins are configured to enter a harmless tristate mode right at brown-out or power-off. However, you might notice some flickering¹ of the SPI-Power LED, so better do not rely on that procedure.

¹ fixed with Chipflasher v2 design

Prerequisites

It is assumed that you have followed the steps mentioned in #../../doc/README.md and now have two terminal windows available, with proper environments set up, i.e. Terminal#1 and Terminal#2.

Get Prepared

Connect host and chipflasher with each other, i.e. attach the Y-USB-power-cable to two USB-Ports, attach the RS232-data-cable.

Attach the SPI-cable, but omit the target board (or chip) for now.

  1. Switch the chipflasher device on and verify that the power status LED is bright.

  2. Use a screwdriver to adjust the flasher’s CE# pull-up resistor to its clock-wise maximal position, that is to its biggest value.

  3. Attach the free pinheader connectors of the SPI-cable to the SPI-Chip...

    • by using the 8-pin DIL-socket for discrete chips,
    • by using a test-clip for chips in place,
    • or by connecting previously soldered, flying wires.

    WARNING: You must not mix wires! See ../../hardware/gschem/chipflasher-page13.sch.png and check pinouts in advance.

Operate the Chipflasher

Change the directory to ease operation:

    [env]$ cd ../../host/start/

Get familiar with targets, provided by ../../host/start/Makefile:

    [env]$ make help

Get familiar with targets, provided by ../../host/start/Workflow.mk:

    [env]$ make -f Workflow.mk help

The flasher is operated via two terminal windows in parallel:

Feel free to switch between terminals as required.

Try a Real Target

  1. In Terminal#1, select d: probe chip in order to probe the BIOS-chip for its ID:

    ../../images/screenshot-20211222-161453.png

    Screenshot: Probe Chip

    Use a screwdriver in counter-clock-wise direction to adjust the CE# pull-up resistor to smaller values until your chip gets clearly detected. See #../../doc/targets.md.

  2. Select ?: show menu to get a verbose menu output:

    ../../images/screenshot-20211222-161531.png

    Screenshot: Show Menu

  3. Select c: read chip in order to store chip’s content in your first chip2file.txt.

    WARNING: Consider to create backups between read operations, as file chip2file.txt gets overwritten without prompt!

  4. Switch to Terminal#2 in order to monitor and manipulate in- and outgoing chip data.

  5. Continue to Operate the Flasher via Menu (Terminal#1)

    You may now use the menu for dumping, erasing, flashing, verifying your chip. Check register bits for appropriate configurations.

    WARNING: Proceed with care, you may brick your machine!
    Potentially dangerous hotkeys are all upper case, thus protecting you from accidental key hits as long as <CAPS-LOCK> is inactive.

    When using the menu, wait until your selected procedure finishes.
    With q: cancel/(SPI-Bus off)/quit you may cancel it at any time.

  6. When done, hit q in order to quit connect.

    NOTE: In case the SPI bus has been left powered after chip detection due to volatile bits in status registers, it is powered off as an intermediate step before you actually quit the program with an additional q.

  7. Detach the SPI-cables from the target SPI-chip and power off the flasher device.

    Remember to plug a system board’s coin-battery back in.

Done!

Onboard EEPROM (Terminal#1)

Until now, we have taken care to always start from free-design RAM using the make -C ../../host/start/ kick-ram command. The pre-flashed firmware in the onboard EEPROM has not been touched, yet.

If you want to try the pre-flashed firmware, type:

    [env]$ make -C ../../host/start/ reset-kick
    [env]$ make -C ../../host/start/ connect-115200

If you want to upload a newly built firmware and make things permanent, type:

    [env]$ make -C ../../host/start/ kick-eeprom

Custom Invocation of connect (Terminal#1)

Alternatively, you might invoke the connect utility manually:

  1. Adjust the port pointer, e.g.:

        [env]$ ln -sf /dev/ttyS1 ../../host/start/tty_port_pointer
    
  2. Clean and compile connect, the utility:

        [env]$ make -C ../../host/src/ clean
        [env]$ make -C ../../host/src/ connect
    
  3. Configure and compile kick, the firmware:

        [env]$ make -C ../../firmware1/src/ clean
        [env]$ make -C ../../firmware1/src/ config-BOARD_V1
        [env]$ make -C ../../firmware1/src/ kick
    
  4. Adjust baudrate and upload kick to RAM:

        [env]$ make -C ../../firmware1/start/ config-baud57600
        [env]$ make -C ../../firmware1/start/ kick-ram
    
  5. Invoke connect with matching parameters, i.e.:

        [env]$ ../../host/src/connect\
            ../../firmware1/start/chip-out.txt\
            ../../firmware1/start/chip-in.txt\
            ../../host/start/tty_port_pointer\
            B57600
    
  6. In order to process in- and outgoing data via ../../host/start/Workflow.mk, update macros ROOT_HOST_IO, CHIP2FILE and FILE2CHIP according to your choices.

  7. Clean-up your custom configuration:

        [env]$ make -C ../../firmware1/start/ clean-config