Exploring the Embedded Controller

General Topics
#21

Alright! I’ve pushed an update to fw-ectool that fixes reading mapped memory; now commands like battery and temps work properly.

$ ectool temps all
--sensor name -------- temperature -------- fan speed --
F75303_Local          303 K (= 30 C)           0%
F75303_CPU            303 K (= 30 C)           0%
F75303_DDR            301 K (= 28 C)           0%
Battery               296 K (= 23 C)           0%
PECI                  306 K (= 33 C)           0%

$ ectool battery
EC returned error result code 3
Battery info:
  OEM name:               NVT
  Model number:           Framewo
  Chemistry   :           LION
  Serial number:          00CD
  Design capacity:        3572 mAh
  Last full charge:       3560 mAh
  Design output voltage   15400 mV
  Cycle count             37
  Present voltage         16625 mV
  Present current         0 mA
  Remaining capacity      2896 mAh
  Flags                   0x0b AC_PRESENT BATT_PRESENT CHARGING

In addition, I’ve documented a few more host commands:

3E09 - Chassis Intrusion Data (more info)

This host command reports whether the chassis has ever been opened and if so, how many times.

3E0F - Chassis Status

Reports whether the chassis is open right now. Does not include historical data.

3E04 - Get Fan 0 RPM

Returns the RPM of the system fan as a 32-bit integer:

3e04(...0 bytes...)
Read 4 bytes
 ff 06 00 00 |....|  #<< 1791 RPM

Operates very similarly to pwmgetfanrpm 0, which returns Fan 0 RPM: 1789

Undocumented Interactions

You can reboot the EC by holding power for 20 seconds. The charge LEDs will flash to indicate that you’ve done so.

Since I’m no longer on holiday from real life, updates are going to slow down… but I still hope to write a Windows driver/userland application pair that will let you control the charge limit (among other things) without getting your hands too dirty. We’ll see!

13 Likes
#22

Jan 7 Update:

Linux Kernel Support

I’ve submitted a patch series to add support to the kernel for the Framework EC. It’s a small change to the ChromeOS EC driver to make it suitable for Framework, and the ChromeOS person who owns that code (1) is in support of the patch and (2) is a fan of the Framework Laptop!

When this merges, I can remove the code from fw-ectool that supports --interface=fwk since all communication can be delegated to the existing kernel interface. Upstream ectool (which should be available in your distributor’s repository) will work without modification!¹

¹ Caveat being that it won’t do anything Framework-specific.

Windows Support

I’m currently working on a Windows driver that is compatible (or mostly compatible) with the Linux cros_ec device driver, and have ported ectool to use it².

image
image1828×957 55.3 KB

This is, of course, going to be open-source . . . but I need to assign an appropriate license and write up some documentation before I do so. Eventually, I’d like to pursue code signing so that you all don’t need to enable test mode (which disables driver signature enforcement and slaps a watermark on your desktop) on your computers.

² Also, got ectool building on Windows. It has surprisingly few Linuxisms, but there were a couple.

15 Likes
#23

How does this affect the fwk command words you added earlier? Do we have to go back to the raw command hex codes?

Good on you for bringing this to more platforms and hopefully more distros/repos, to make it even easier for end users to find and implement…

#24

So, the plan is that the kernel device only replaces the “communication” layer–how the commands are sent to the EC and how responses are received–in ectool. The commands ectool offers (and an eventual standalone user-mode application!) will remain, and I’ll continue maintaining fw-ectool until there’s a better option for both communication and sending specific commands.

In working on this, I learned that the Linux kernel already had support for speaking the specific version of the protocol the Framework Laptop uses. I suspect that this is why ectool did not: if they added support in the kernel, they wouldn’t need a user-mode implementation of it at all.

Switching to a supported kernel driver obviates the need to turn off Secure Boot and disable lockdown, as there will no longer be a user-mode application interacting directly with hardware I/O resources. It’ll be an important part of achieving broad availability.

On the Windows side, the hardest part is going to be code signing. Kernel-mode drivers must be signed with an EV certificate (typically only granted to company entities, and I do not have one of those at the moment :slight_smile:) and cross-signed by Microsoft before they will work outside of test mode and with Secure Boot enabled. The second part is easy… the first part, not so much. If you have any ideas, I am all ears!

3 Likes
#25

I’m trying to figure out the purpose of the value stored in flash at 0x3C040, and I could use a little help! To that end, I’ve got a couple questions:

Would any of you be willing to share the contents of that region? If so, can you run the following commands? Also, do you remember the date when you first booted your laptop?

Steps

  1. Unlock flash
    • ectool --interface=fwk raw 0x3e01 b00
  2. Read the region of interest
    • ectool --interface=fwk flashread 0x3c040 16 dump.bin
  3. Re-lock flash
    • ectool --interface=fwk raw 0x3e01 b03
  4. Print the contents of the dump to the screen
    • hexdump dump.bin (or od -t x1 dump.bin or xxd dump.bin)

My answers:

00000000: 0610 2100 0000 0000 0000 0000 0000 0000  ..!.............

I think I booted my laptop for the first time on 2021-10-06. :thinking:

1 Like
#26

That appears to be correct. Mine matches the delivery date of the package which would have been the first time that I booted the machine.

1 Like
#27

Same here; mine is the date of my first boot.

0000000 01 12 21 00 00 00 00 00 00 00 00 00 00 00 00 00
0000020
1 Like
#28

Thanks all! Coupled with me learning that I/O port 0x70/0x71 is for the CMOS/RTC, it seems pretty certain that that’s what this is for.

I’ll update the page with that info later. By default, I’ll include links back to your forum profiles as attribution. Please let me know if you don’t want this. :slight_smile:

Much appreciated!

EDIT: This is now published!

4 Likes
#29

@DHowett Great writeup and tools! And really great job RE the firmware. What is your RE tool of choice? My go to tool lately is Ghidra.

EC flash from 0x3C000 to 0x3D000 is for factory tooling to write a mix of status and some info to.

The power button is RGW, so that is why you dont get blue.
We are going to post the EC source soon. So you should get a lot of questions answered.

Some of the commands are for factory use like 3E02 is used to remap some of the keyboard keys so that we can complete keyboard functional testing in the OS during manufacturing by having them emit normal scan codes.

The laptop has 2 power buttons. There is one on the mainboard in the upper right corner. If you hold it for about 10 seconds it will perform a battery disconnect sequence to safely put the battery into ship mode. The main power button does not do this.

If you hold the main power button for about 20 seconds it will reboot the EC as you noted.

If you have any questions I am happy to answer them.

15 Likes
Battery slowly drains when completely shut down
Recent Linux Kernel Hardware Support
#30

@Kieran_Levin I’ve been wondering if it’s possible to get the details about the USB PD negotiations and state. My main goal is to programmatically determine the wattage of the currently-attached power source.

#31

@Sean_Greenslade I am not sure if I enabled some of the host commands for the charge manager. But if they are enabled you should be able to get the per port current/voltage that is negociated using the result data from HC
EC_CMD_USB_PD_POWER_INFO 0x0103
hc_pd_power_info.

A lot of the PD commands wont work because our design uses a PD controller instead of a TCPC, so we dont care about populating the data to the PD policy manager engine.

2 Likes
#32

Thanks so much! I’ve been using Ghidra as well, with the ghidra-firmware-utils plugin. It maps known UEFI protocols/guids/types and scans the target for them. Really takes the hassle out.

This is all excellent stuff, and I appreciate it! I do have a couple questions and notes :slight_smile:

  1. I’m planning on releasing (and hopefully getting signed) the CrosEC driver [DISCLOSURE: GPLv2!] and a cross-platform userland tool for setting up things like the charge limit/keyboard mapping. Please don’t let its existence stop you from changing how these host commands work–it’s supposed to be informative, not normative, and I’m happy to adapt¹ it–as it’s your firmware at the end of the day.
  2. What does the high bit in 3E03's flags do? I saw that it propagates something to the charge limit value (High bit + charge limit 80 => 0xD0), but I can’t figure out what it does with that bit afterwards.
  3. What’s the “ME Lock” (3E06 possibly toggles it?)
  4. Do you actually read the chassis intrusion counters into a TPM PCR? That would be super cool from a platform security perspective, but I might have made it up!
  5. Is the UEFI configured not to load DriverOrder/Driver#### entries? I wrote FrameworkKeyMapDriver [MIT] which, right now, remaps Caps to Esc, but it only works with a bootloader that loads auxiliary drivers.
  6. This is a feature idea, not a question, which you are free to ignore. If the Fn key toggled the use of a different matrix->scancode map² instead of a hardcoded post-scancode lookup, folks could add additional Fn mappings . . . which might be a really neat power user feature.

¹ Especially if you’d be willing to coordinate updates :wink: but that’s a hope, not a request.

² Probably three maps, since it looks like there’s a table for “fn locked/always”, “fn held only” and “something after fn held, but I can’t figure out why it’s not part of the second lookup”.

5 Likes
#33

I would power-use the ▒▒▒ out of this.

2 Likes
#34

@DHowett thanks again for the reverse-engineering! I have a question:

cross-platform userland tool for setting up things like the charge limit/keyboard [

Specifically for charge limits, do your upstream kernel driver changes enable the standard threshold API under /sys/class/power_supply/...? If so then tlp should also work as a charge threshold tool, correct?

#35

Unfortunately, no. Since this EC uses a custom implementation of charge limiting, additional driver support would be required to expose it to the threshold API.

The proposed patch set only adds support for communicating with the EC to the existing EC driver. :slight_smile:

#36
  1. I would also be interested in this, and keeping it GPLv2. If you want to coordinate/collaborate we could build on your work. I don’t have much experience with windows driver development. But would be interested in some collaboration as this is really useful. If you need help getting it signed we could do a code review and get some CI running on it, and release signed builds (I think we would need to clone the repo under the Framework org and setup some code review process for pull requests).
  2. The high bit allows you to set a limit but allow the laptop to charge to 100%. The idea with this is if we had an os utility we could trigger a 1 time override to the limit. Eg if you knew you had a long day of meetings you could charge up the battery once to 100%.
  3. ME lock sets the ME region CPU strap pin to lock or unlock the ME region on boot.
  4. We don’t load them into the TPM. This only drives bios password behavior. Eg trigger a bios password on boot.
  5. I will need to check on this.
  6. I would like to add an additional layer to the keyboard that could remap any key. But I think it would be better to map a different scancode to this, as the Fn key has some behavior that mixes with Fn lock. Eg Fn+Esc triggers Fn lock, and this only applies to the top row keys on the keyboard layer. But there is also Fn+ keys in the character section which need to only be active when Fn is held down, even if Fn Lock is active. Eg
    Fn+ Delete = Insert
    Fn+K = Scroll Lock
    Fn+S = Sysreq
    Fn+Left,right, up, down = Home, End, PageUp, PageDown
    The second function for Fn+ Mapping is for the following keys, and is separate because these keys require multiple scancodes to send the command to the host. Eg Pause is actually 8 bytes. If you look up scanset 2, these are kind of special multibyte key codes so they have a separate function PS2 Keyboard Scan Codes | Online Documentation for Altium Products.
    Fn+B = Break
    Fn+P = Pause
13 Likes
#37

2022-01-21 status update

Not much to report – I’m into the “slog” part of the work:

  1. Cross-platform application that takes advantage of CrosEC (the windows driver I mentioned before) and cros_ec (the Linux one)
  2. Pursuing EV driver signing still! :slight_smile:

It’s not pretty today, but it does work:

image

image

yes: that is a DVD player icon, it uses QT, and it does run on Linux!

18 Likes
#39

Thanks @DHowett for exploring this and @Kieran_Levin / team for releasing the latest newsletter about open sourcing the EC firmware

3 Likes
#40

I’m really looking forward to having any way to adjust the charge level / one shot 100% on screen in windows.

Love that you are “slogging” through this, and the FW support of it. Every time I check the forum and see the progress going on, I am so happy I bought a Framework Laptop.

8 Likes
#41

Just two quick notes:

  1. I’ve updated the post linked above to be true to the actual upstream code (yay!), and archived the original reverse engineered info. It also includes a section on ongoing work, which contains a blurb about the patches and the Windows CrosEC driver.
  2. Some positive developments on v2 of the linux patch series, suggesting that it might get in for v5.18.
6 Likes
Open Sourcing our Firmware