Embedded Controller (EC)#

Issues such as sudden shutoffs, failure to charge the battery, or failure to resume from suspend often relate to the EC firmware. To troubleshoot these issues, Purism Support may ask you to provide a field log. The EC field log is a short history of hardware and firmware events captured by the EC itself, even if the OS is not running. Due to limited space in the EC, the field log is very compact and is not directly human-readable.

Collect a field log#

If Purism Support asks you to provide a field log:

  1. If Support gave you a customized EC build, install it. This might contain new diagnostics related to the issue.

  2. Reproduce the problem.

    • If you know how to reproduce the problem, do that now.

    • If the problem occurs intermittently or on its own, wait for the problem to occur.

  3. If the system is off, boot your operating system.

  4. Download purism_ectool from firmware tools, and save it in your Downloads folder.

  5. Open a terminal.

  6. Change to Downloads and prepare the tool: cd ~/Downloads && gunzip purism_ectool.gz && chmod a+x purism_ectool

  7. Run: sudo ./purism_ectool field_log > ~/Documents/field_log.txt

  8. Send field_log.txt from your Documents folder to Support.

If you can’t collect the log right away#

After reproducing a problem, it is important to collect the field log right away, or the log contents relating to the problem will be overwritten. Boot up the computer once if it was not on, then collect the log. Avoid rebooting or suspending the computer, which logs more events.

If you can’t collect the log right away, you can have the EC save the log internally, so you can collect it later. The EC saves a failure log automatically for some types of issues. You can also press Fn+X to save a field log at any time, even if the OS is not responding.

When the EC saves a failure log, that log will be available until it is overwritten by saving another failure log.

  1. If Support gave you a customized EC build, install it. This might contain new diagnostics related to the issue.

  2. Reproduce the problem.

    • If you know how to reproduce the problem, do that now.

    • If the problem occurs intermittently or on its own, wait for the problem to occur.

  3. When the problem occurs, capture a failure log:

    • For some types of problems, the EC captures a failure log automatically. This includes:

      • Sudden shutoffs. If the entire system shut down unexpectedly, the EC detects this when it starts up again and captures the failure log.

      • Force-off by holding the ⏻ (Power) key. The EC captures a failure log since this usually means that the OS is unresponsive.

    • For other problems, you can press Fn+X to capture a failure log at any time.

  4. If the system is off, boot your operating system. You can wait as long as is needed to collect the log, even if you need to use the computer in the meantime.

  5. Download purism_ectool from firmware tools, and save it in your Downloads folder.

  6. Open a terminal.

  7. Change to Downloads and prepare the tool: cd ~/Downloads && gunzip purism_ectool.gz && chmod a+x purism_ectool

  8. Run: sudo ./purism_ectool field_log failed > ~/Documents/field_log.txt

  9. Send field_log.txt from your Documents folder to Support.

Inspecting a field log#

Although the field log is not directly readable, you can inspect it if you want to see the events. (This is not necessary to send a log to Purism Support.)

The field log contains only event indicators, timing information, and some limited system information. There is no information that can identify you or your device.

To inspect the field log:

  1. Get the field log analysis spreadsheet: https://source.puri.sm/firmware/librem-ec/-/blob/master/ec_field_log.ods

    • If Support gave you a customized EC build, you may need the field log spreadsheet from that feature branch to see any new events.

  2. Open the field log analysis spreadsheet.

  3. Open the field_log.txt in a text editor and copy the contents.

  4. In the field log analysis spreadsheet, go to the log_128b sheet and select cell B1.

  5. Press Ctrl+Alt+Shift+V (“Paste unformatted text”)

  6. In the text import wizard, select “Separated by”.

  7. Uncheck all delimiters (paste as a single column).

  8. Check trim spaces.

  9. Select OK.

The events appear in the column labeled “event”. Timing differences between events appear in the column “delta (ms)”.

If the field log wrapped around, the beginning of the log might not be at the top of the file. Look for the write pointer (marked “nxt wr” in the “wr ptr” column). If the event next to it is not EventNone, that is the oldest event in the log. The log proceeds downward, wrapping from bottom to top.