Exploring the Embedded Controller

DHowett · June 23, 2024, 8:13pm

Hey @TomsonTom! Sorry for the delay. I pushed a mirror to GitHub and brought in the BSD 3-clause license from the upstream repo.

Feel free to send in a pull request, and we can discuss it over there!

TomsonTom · June 24, 2024, 10:40am

Thank you @DHowett ! Great work on that repo, happy to see it mirrored on GitHub!

Here is the pull request for WinRing0 with Secure Boot:

github.com/DHowett/ectool

Add support for Secure Boot on Windows by adding the WinRing0 interface

DHowett:main ← tomasiser:winring0

opened 10:39AM - 24 Jun 24 UTC

tomasiser

+397 -2

Hi there! This PR allows users to run ectool on **Windows with Secure Boot en…abled** as shown on the following screenshot: ![image](https://github.com/DHowett/ectool/assets/10374559/77ee08ec-df5c-45d7-8541-ae3d49a0d553) ## User manual To run `ectool` with Secure Boot enabled, you have to do the following: - You have to [download](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor/releases) and start [Libre Hardware Monitor](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor) (LHM). Remember that LHM needs to keep running in the background so that `ectool` can access the WinRing0 driver that is properly signed and embedded in LHM. - You have to execute `ectool` **with admin privileges** and with the `--interface=winring0` argument. **Example:** To run the `battery` command, you have to execute the application as follows: ``` ectool.exe --interface=winring0 battery ``` ## Developer manual In order to pass Secure Boot, we need a properly signed driver that can communicate with the embedded controller (EC). But signing a custom Windows driver is expensive and complicated (there is a whole subdiscussion about it [on the Framework forums](https://community.frame.work/t/exploring-the-embedded-controller/12846)). As a workaround, I figured that we could use an existing driver that was signed a long time ago and still passes Microsoft's strict signing policies, which is exactly what **WinRing0** is. Just beware that the driver is very powerful and: - I don't like downloading random drivers from random internet sources that can be full of viruses. - Some antivirus software does not like WinRing0. For these reasons, I believe the best we can do is to **not embed WinRing0 in here** and instead rely on [Libre Hardware Monitor](https://github.com/LibreHardwareMonitor/LibreHardwareMonitor) (LHM), which is a trusted software that is doing all sorts of tricks to bypass some antivirus software (for example, by modifying the bits in the embedded archive that contains WinRing0 so that it is undetected by the antivirus). To use WinRing0, I basically copy-pasted the `comm-lpc.cc` code into a `comm-winring0.cc` file that now contains a helper class for communicating with the driver. I also needed to modify parts of the file so that it compiles on Windows (e.g., by using `std::this_thread::sleep_for` instead of `usleep`). The helper class is called `WinRing0PortInputOutput`, it's at the top of the `comm-winring0.cc` file, and the API is straightforward. I wrote the class by reverse engineering LHM and checking how they communicate with the driver. All the magic is in the `read_byte` and `write_byte` methods that use `DeviceIoControl` for communication. ### Notes for compiling on Windows: Something to keep in mind is that the current version of ectool can only be compiled with Clang, so if you want to compile via Visual Studio, you have to first install the clang toolset and set it in your CMakeSettings.json via Visual Studio. Also, I had some troubles with an include file (`win32_shim.h`), so I also commited a fix for that in `CMakeLists.txt`. ## Known issues I randomly found out that the `powerinfo` command does not work. Currently I am unsure if it has anything to do with WinRing0.

2disbetter · June 24, 2024, 10:20pm

Going to give this a go tomorrow! Really appreciate the work for the windows crowd!

Awashcard0 · June 29, 2024, 5:08pm

I don’t know if this is the right place for this. I was having issues with keylightd so I looked for something about the Error: No such file or directory (os error 2) it was giving me. I came here the find out what was wrong but everyone who got the

Missing Chromium EC memory map.
Cannot find I2C adapter
Unable to establish host communication
Couldn't find EC

was using AMD but I am on 11th Gen Intel. Does anyone have any ideas on why this is happening.

System:
CPU: 11th Gen Intel i7-1165G7
BIOS: 3.19
OS: EndeavourOS

olivia_Barker · June 30, 2024, 10:10pm

hello, Sorry if this has been said elsewhere but am i correct in thinking that changing the colour of the power led on the framework 16 isn’t possible?
when i try to change it i get result code 3
i also get code 3 when trying to specify a side which i remeber someone saying isnt do able on the fw 16.
is there any reason why that inst exposed on the newer versions?
and one more thing is it possible to trigger the battery disconnect in ectool rather than limiting the charge can do the same thing as the bios disconnect option?

Andrew_Worsley · July 9, 2024, 5:05am

I notice that Dave Howett’s framework ec page is dated 22-Dec-2022 and so doesn’t mention the AMD Framework 16 laptop. But his ectool does support it.

To save others from figuring out how to compile it - just clone the repo and then follow the commands listed in the .gitlab-ci.yml file. Note: it needs root permissions to work. The command: ectool version gave

RO version:    lotus_v3.4.113353-ec:b4c1fb,os:
RW version:    lotus_v3.4.113353-ec:b4c1fb,os:
Firmware copy: RO
Build info:    lotus_v3.4.113353-ec:b4c1fb,os:7b88e1,cmsis:4aa3ff 2024-03-26 07:08:43 lotus@ip-172-26-3-226
Tool version:  0.0.1-isolate Jul  9 2024 none

DHowett in this discussion mentions the code is Zephyr port of the ChromeOS EC
which I presume is chromiumos ec platform but then links through to some very long complex multi-git extractions to build .

Sigh - it does seem very hard to find the actual EC source code.

Also it seems that the AMD Framework 16 EC datasheet is not freely available - probably have to have a login account at nuvoton to get it…

The good news is that the ectool is working well even if the documentation of the EC and the firmware source is very difficult to obtain.

Also interestingly

ectool chipinfo

gives

Chip info:
  vendor:    Nuvoton
  name:      npcx9m3f
  revision:  00160207

pierce · July 12, 2024, 7:48am

The actual EC source code for the Framework 13/16 AMD models is around here: EmbeddedController/zephyr/program/lotus at lotus-zephyr · FrameworkComputer/EmbeddedController · GitHub

Andrew_Worsley · July 13, 2024, 11:44am

Thanks – I’ve downloaded it - now look at how to build it - seems I need the zmake command as per zephyr build instructions

I have downloaded the chromium code which builds depot_tools

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

PATH=/bin:/usr/bin:/sbin:/usr/sbin:/usr/games:/usr/local/bin:/usr/local/sbin:/usr/local/games:/snap/bin:/home/amw/src/depot_tools export PATH

fetch chromium
cd src && ./build/install-build-deps.sh
gclient sync

which took about 12 hours… and gets me the cros_sdk tool but not zmake…

Mapleleaf · July 13, 2024, 2:16pm

There’s a CMakeLists.txt in their repos, so you should try compiling using cmake.

DHowett · July 13, 2024, 7:57pm

I’m not sure whether “EndeavourOS” packages the ChromeOS EC drivers by default; you should be able to discover if it does by checking…

Is there a cros_ec_lpcs.ko under /lib/modules?
- `find /lib/modules -name ‘cros_ec*’
Is /dev/cros_ec present?
- ls -l /dev/cros_ec
Are the modules throwing any errors?
- dmesg | grep cros

LEDs

Unfortunately, yes - both of these things have changed with the AMD framework laptops.

The power LED no longer supports anything but white; it was updated for compatibility with the chromebook edition which only supported white.

I suspect they wanted to keep documentation between the models similar.

The side LEDs are treated as one entity, “charge” or “battery”, in the AMD boards and probably any newer boards as well.

Battery

You can issue a battery disconnect manually with ectool batterycutoff.

The machine is not intended to be used with the battery shut down. Do this only for experimentation.

In addition to what @pierce said (thank you!), I wrote up a quick gist explaining how to take a clean Debian install (I used a container, but you can use bare metal or whatever) to a Zephyr build environment. It’s actually terrible.

That gist is here.

If you are trying to build for the Framework Laptop 16 AMD, use lotus anywhere you see the name azalea.

James3 · July 13, 2024, 8:38pm

On a FW16 I have:
lsmod |grep cros
cros_ec_lpcs 20480 0
cros_ec 20480 1 cros_ec_lpcs

/dev/cros_ec is not present.
dmesg | grep cros
[ 21.416956] cros_ec_lpcs cros_ec_lpcs.0: EC ID not detected

My guess is the ACPI config is not set up correctly.

DHowett · July 13, 2024, 8:45pm

For the AMD Framework Laptops, you need to be on kernel 6.11 or greater, or apply the kernel patch here: [PATCH v3 0/4] platform/chrome: cros_ec_lpc: add support for AMD Framework Laptops - Dustin L. Howett

James3 · July 13, 2024, 9:40pm

@DHowett
Thank you, that works, I now have the /dev/cros_ec device and ectool uses it.

Andrew_Worsley · July 14, 2024, 6:01am

Thanks - that worked fine!
Surprisingly I did need to explicitly add contrib to my repository - perhaps that is no longer default on Debian bookworm.

Now perhaps I can debug some of these black screen crashes.

Andrew_Worsley · July 14, 2024, 6:53am

Tricky - linux mainline master is 6.10-rc7 - https://github.com/torvalds/linux/blob/master/Makefile

LK_1 · July 14, 2024, 8:46am

I’m getting this error on FW 13 Intel 13th gen, is there any way to fix this? I couldn’t figure it out… Just FYI I’m on BIOS 3.05 (recently released)

❯ sudo ectool chargecontrol
ERROR: Old EC doesn't support GET.

  Usage: chargecontrol
    Get current settings.
  Usage: chargecontrol normal|idle|discharge
    Set charge mode (and disable battery sustainer).
  Usage: chargecontrol normal <lower> <upper>
    Enable battery sustainer. <lower> and <upper> are battery SoC
    between which EC tries to keep the battery level.

❯ sudo ectool chargecontrol normal 20 80
ERROR: Old EC doesn't support sustainer.

  Usage: chargecontrol
    Get current settings.
  Usage: chargecontrol normal|idle|discharge
    Set charge mode (and disable battery sustainer).
  Usage: chargecontrol normal <lower> <upper>
    Enable battery sustainer. <lower> and <upper> are battery SoC
    between which EC tries to keep the battery level.

Morpheus636 · July 14, 2024, 1:26pm

I may be mistaken, but I think those commands are only functional on the AMD platform’s EC, which uses a new architecture.

Andrew_Worsley · July 18, 2024, 4:10am

I just built mainline v6.10 and Dustin’s patches are already present -

commit c8f460d991df
Author: Dustin L. Howett <dustin@howett.net>
Date:   Tue Apr 2 19:47:13 2024 -0500

    platform/chrome: cros_ec_lpc: add quirks for the Framework Laptop (AMD)
    
    The original Framework Laptop 13 platform (Intel 11th, 12th, and 13th
    Generation at this time) uses a Microchip embedded controller in a
    standard configuration.
    
    The newer devices in this product line--Framework Laptop 13 and 16 (AMD
    Ryzen)--use a NPCX embedded controller. However, they deviate from the
    configuration of ChromeOS platforms built with the NPCX EC.
    
    * The MMIO region for EC memory begins at port 0xE00 rather than the
      expected 0x900.
    
    cros_ec_lpc's quirks system is used to address this issue.
    
    Signed-off-by: Dustin L. Howett <dustin@howett.net>
    Reviewed-by: Thomas Weißschuh <linux@weissschuh.net>
    Tested-by: Thomas Weißschuh <linux@weissschuh.net>
    Tested-by: Mario Limonciello <superm1@gmail.com>
    Link: https://lore.kernel.org/r/20240403004713.130365-5-dustin@howett.net
    Signed-off-by: Tzung-Bi Shih <tzungbi@kernel.org>

M       drivers/platform/chrome/cros_ec_lpc.c

My FW 16 hibernates and recovers ok with power cable plugged in
But if I then unplug the power and use zoom-client (a snap in debian bookworm) to connect to a meeting it freezes for a about 3-5s then goes black screen and after a while reboots. Strangely the ectool console shows no sign of the reboot that I can see - https://paste.debian.net/1323605/

DHowett · July 18, 2024, 4:11am

I didn’t realize it had made it into 6.10. Thanks!

Awashcard0 · July 19, 2024, 8:33pm

@DHowett I could not find anything about the ectool. How would I install it?