From 140c02d233efeac1e9dfee9e2cb2b2a9af107c99 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 18 Aug 2025 13:21:31 +0800 Subject: [PATCH 1/4] README: Document installation on distros Signed-off-by: Daniel Schaefer --- README.md | 51 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 0c72bef..69e52ab 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,33 @@ The tool works on Linux, Windows and the UEFI shell. Download it from the latest [GH Actions](https://github.com/FrameworkComputer/framework-system/actions?query=branch%3Amain) run on the main branch. Most features are supported on every "OS". See below for details. +## Installation + +### Linux + +- [NixOS](https://github.com/NixOS/nixpkgs/blob/nixos-25.05/pkgs/by-name/fr/framework-tool/package.nix) + - `nix-shell -p framework-tool` +- [ArchLinux](https://archlinux.org/packages/extra/x86_64/framework-system/) + - `pacman -Sy framework-system` +- [Bazzite](https://github.com/ublue-os/bazzite/pull/3026) +- Others + - Build from source + - Or download [latest binary](https://github.com/FrameworkComputer/framework-system/releases/latest/download/framework_tool) +- ChromeOS + - Build from source + +### Windows + +``` +winget install FrameworkComputer.framework_tool +``` + +### FreeBSD + +``` +sudo pkg install framework-system +``` + ## Features To check which features are supported on which OS and platform, @@ -153,6 +180,9 @@ ls -l framework_uefi/build/x86_64-unknown-uefi/boot.efi # NixOS nix-shell --run fish -p cargo systemd udev hidapi pkg-config direnv shell + +# FreeBSD +sudo pkg install hidapi ``` ## Install local package @@ -226,15 +256,6 @@ Many actions require root. First build with cargo and then run the binary with s cargo build && sudo ./target/debug/framework_tool ``` -###### Running on Windows - -On newly released systems since 2025 the Framework driver installer includes the EC driver. -This includes Framework 12, Framework 13 AMD Ryzen AI 300, Framework Desktop. - -Previous platforms will be enabled next. - -Installing: `winget install FrameworkComputer.framework_tool` - ##### Running on ChromeOS The application can run on ChromeOS but most commands rely on custom host @@ -329,15 +350,3 @@ Keyboard backlight: 0% [DEBUG] send_command(command=0x22, ver=0, data_len=0) Keyboard backlight: 0% ``` - -## FreeBSD - -``` -sudo pkg install hidapi - -# Build the library and tool -cargo build - -# Running the tool -cargo run -``` From 5ac001ddd5decf36e8eab4146b183e34c5159043 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 18 Aug 2025 13:21:56 +0800 Subject: [PATCH 2/4] README: Move more into advanced example file Clean up readme Signed-off-by: Daniel Schaefer --- EXAMPLES_ADVANCED.md | 83 +++++++++++++++++++++++++++++++++++++++++ README.md | 88 ++------------------------------------------ 2 files changed, 86 insertions(+), 85 deletions(-) diff --git a/EXAMPLES_ADVANCED.md b/EXAMPLES_ADVANCED.md index 8e938e1..a350df3 100644 --- a/EXAMPLES_ADVANCED.md +++ b/EXAMPLES_ADVANCED.md @@ -1,5 +1,33 @@ # Advanced debugging +## Verbosity + +To debug, increase the verbosity from the commandline with `-v`. +The verbosity levels are: + +| Commandline | Level | +|-------------|--------| +| `-q` | No log | +| None | Error | +| `-v` | Warn | +| `-vv` | Info | +| `-vvv` | Debug | +| `-vvvv` | Trace | + +For example it is useful to check which EC driver is used: + +``` +> framework_tool --kblight -vvv +[DEBUG] Chromium EC Driver: CrosEc +[DEBUG] send_command(command=0x22, ver=0, data_len=0) +Keyboard backlight: 0% + +> framework_tool --driver portio --kblight -vvv +[DEBUG] Chromium EC Driver: Portio +[DEBUG] send_command(command=0x22, ver=0, data_len=0) +Keyboard backlight: 0% +``` + ## PD ### Check PD state @@ -189,3 +217,58 @@ Capsule Header Capsule Size: 2180 KB Type: Framework Retimer23 (Right) ``` + +## Version Check + +Check if the firmware version is what you expect, returns exit code 0 on +succcess, 1 on failure. + +``` +# Check which devices it's available for +> ./framework_tool --device + [possible values: bios, ec, pd0, pd1, rtm01, rtm23, ac-left, ac-right] + +For more information try '--help' + +# Successful compare +> ./framework_tool --device bios --compare-version 03.01 +Target Version "03.01" +Comparing BIOS version "03.01" +Compared version: 0 +> echo $? +0 + +# Failed compare +> ./framework_tool --device bios --compare-version 03.00 + Finished dev [unoptimized + debuginfo] target(s) in 0.05s +Target Version "03.00" +Comparing BIOS version "03.01" +Compared version: 1 +Error: "Fail" + +> echo $? +1 +``` + +On UEFI Shell: + +``` +# Check if AC is attached on left side +Shell> fs0:framework_tool.efi --device ac-left --compare-version 1 +Target Version "1" +Comparing AcLeft "1" +Comparison Result: 0 +# It is +Shell> echo %lasterror% +0x0 + +# Check if AC is attached on right side +Shell> fs0:framework_tool.efi --device ac-right --compare-version 1 +Target Version "1" +Comparing AcLeft "0" +Comparison Result: 1 + +# It is not +Shell> echo %lasterror% +0x1 +``` diff --git a/README.md b/README.md index 69e52ab..018fcba 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ Rust libraries and tools to interact with the system. The tool works on Linux, Windows and the UEFI shell. -Download it from the latest [GH Actions](https://github.com/FrameworkComputer/framework-system/actions?query=branch%3Amain) run on the main branch. -Most features are supported on every "OS". See below for details. +Most features are supported on every "OS". + +You can find lots of examples in [EXAMPLES.md](./EXAMPLES.md). ## Installation @@ -267,86 +268,3 @@ own EC firmware and flash it. - [x] Basic unit tests - [x] Test parsing real binaries - -## Version Check - -Check if the firmware version is what you expect, returns exit code 0 on -succcess, 1 on failure. - -``` -# Check which devices it's available for -> ./framework_tool --device - [possible values: bios, ec, pd0, pd1, rtm01, rtm23, ac-left, ac-right] - -For more information try '--help' - -# Successful compare -> ./framework_tool --device bios --compare-version 03.01 -Target Version "03.01" -Comparing BIOS version "03.01" -Compared version: 0 -> echo $? -0 - -# Failed compare -> ./framework_tool --device bios --compare-version 03.00 - Finished dev [unoptimized + debuginfo] target(s) in 0.05s -Target Version "03.00" -Comparing BIOS version "03.01" -Compared version: 1 -Error: "Fail" - -> echo $? -1 -``` - -On UEFI Shell: - -``` -# Check if AC is attached on left side -Shell> fs0:framework_tool.efi --device ac-left --compare-version 1 -Target Version "1" -Comparing AcLeft "1" -Comparison Result: 0 -# It is -Shell> echo %lasterror% -0x0 - -# Check if AC is attached on right side -Shell> fs0:framework_tool.efi --device ac-right --compare-version 1 -Target Version "1" -Comparing AcLeft "0" -Comparison Result: 1 - -# It is not -Shell> echo %lasterror% -0x1 -``` - -## Debugging - -To debug, increase the verbosity from the commandline with `-v`. -The verbosity levels are: - -| Commandline | Level | -|-------------|--------| -| `-q` | No log | -| None | Error | -| `-v` | Warn | -| `-vv` | Info | -| `-vvv` | Debug | -| `-vvvv` | Trace | - -For example it is useful to check which EC driver is used: - -``` -> framework_tool --kblight -vvv -[DEBUG] Chromium EC Driver: CrosEc -[DEBUG] send_command(command=0x22, ver=0, data_len=0) -Keyboard backlight: 0% - -> framework_tool --driver portio --kblight -vvv -[DEBUG] Chromium EC Driver: Portio -[DEBUG] send_command(command=0x22, ver=0, data_len=0) -Keyboard backlight: 0% -``` From 9cd82b51dc7e4097ab78bb21519cc129ec620754 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 18 Aug 2025 13:27:20 +0800 Subject: [PATCH 3/4] README: Move more examples away Signed-off-by: Daniel Schaefer --- EXAMPLES.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 100 ++++++++------------------------------ 2 files changed, 156 insertions(+), 81 deletions(-) diff --git a/EXAMPLES.md b/EXAMPLES.md index 2361b19..557d834 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -1,5 +1,142 @@ # Example usage +Built-in help: + +``` +> framework_tool +Swiss army knife for Framework laptops + +Usage: framework_tool [OPTIONS] + +Options: + --flash-gpu-descriptor + + -v, --verbose... + Increase logging verbosity + -q, --quiet... + Decrease logging verbosity + --versions + List current firmware versions + --version + Show tool version information (Add -vv for more details) + --features + Show features support by the firmware + --esrt + Display the UEFI ESRT table + --device + [possible values: bios, ec, pd0, pd1, rtm01, rtm23, ac-left, ac-right] + --compare-version + + --power + Show current power status of battery and AC (Add -vv for more details) + --thermal + Print thermal information (Temperatures and Fan speed) + --sensors + Print sensor information (ALS, G-Sensor) + --fansetduty [...] + Set fan duty cycle (0-100%) + --fansetrpm [...] + Set fan RPM (limited by EC fan table max RPM) + --autofanctrl + Turn on automatic fan speed control + --pdports + Show information about USB-C PD ports + --info + Show info from SMBIOS (Only on UEFI) + --pd-info + Show details about the PD controllers + --pd-reset + Reset a specific PD controller (for debugging only) + --pd-disable + Disable all ports on a specific PD controller (for debugging only) + --pd-enable + Enable all ports on a specific PD controller (for debugging only) + --dp-hdmi-info + Show details about connected DP or HDMI Expansion Cards + --dp-hdmi-update + Update the DisplayPort or HDMI Expansion Card + --audio-card-info + Show details about connected Audio Expansion Cards (Needs root privileges) + --privacy + Show privacy switch statuses (camera and microphone) + --pd-bin + Parse versions from PD firmware binary file + --ec-bin + Parse versions from EC firmware binary file + --capsule + Parse UEFI Capsule information from binary file + --dump + Dump extracted UX capsule bitmap image to a file + --h2o-capsule + Parse UEFI Capsule information from binary file + --dump-ec-flash + Dump EC flash contents + --flash-ec + Flash EC (RO+RW) with new firmware from file - may render your hardware unbootable! + --flash-ro-ec + Flash EC with new RO firmware from file - may render your hardware unbootable! + --flash-rw-ec + Flash EC with new RW firmware from file + --intrusion + Show status of intrusion switch + --inputdeck + Show status of the input modules (Framework 16 only) + --inputdeck-mode + Set input deck power mode [possible values: auto, off, on] (Framework 16 only) [possible values: auto, off, on] + --expansion-bay + Show status of the expansion bay (Framework 16 only) + --charge-limit [] + Get or set max charge limit + --charge-current-limit ... + Set max charge current limit + --charge-rate-limit ... + Set max charge current limit + --get-gpio [] + Get GPIO value by name or all, if no name provided + --fp-led-level [] + Get or set fingerprint LED brightness level [possible values: high, medium, low, ultra-low, auto] + --fp-brightness [] + Get or set fingerprint LED brightness percentage + --kblight [] + Set keyboard backlight percentage or get, if no value provided + --remap-key + Remap a key by changing the scancode + --rgbkbd ... + Set the color of to . Multiple colors for adjacent keys can be set at once. [ ...] Example: 0 0xFF000 0x00FF00 0x0000FF + --tablet-mode + Set tablet mode override [possible values: auto, tablet, laptop] + --touchscreen-enable + Enable/disable touchscreen [possible values: true, false] + --stylus-battery + Check stylus battery level (USI 2.0 stylus only) + --console + Get EC console, choose whether recent or to follow the output [possible values: recent, follow] + --reboot-ec + Control EC RO/RW jump [possible values: reboot, jump-ro, jump-rw, cancel-jump, disable-jump] + --ec-hib-delay [] + Get or set EC hibernate delay (S5 to G3) + --hash + Hash a file of arbitrary data + --driver + Select which driver is used. By default portio is used [possible values: portio, cros-ec, windows] + --pd-addrs + Specify I2C addresses of the PD chips (Advanced) + --pd-ports + Specify I2C ports of the PD chips (Advanced) + -t, --test + Run self-test to check if interaction with EC is possible + -f, --force + Force execution of an unsafe command - may render your hardware unbootable! + --dry-run + Simulate execution of a command (e.g. --flash-ec) + --flash-gpu-descriptor-file + File to write to the gpu EEPROM + --dump-gpu-descriptor-file + File to dump the gpu EEPROM to + -h, --help + Print help +``` + ## Check firmware versions ### BIOS (Mainboard, UEFI, EC, PD, Retimer) diff --git a/README.md b/README.md index 018fcba..440cff0 100644 --- a/README.md +++ b/README.md @@ -137,18 +137,32 @@ All of these need EC communication support in order to work. - [x] Using [Framework EC Windows driver](https://github.com/FrameworkComputer/crosecbus) based on [coolstar's](https://github.com/coolstar/crosecbus) - [x] Using [DHowett's Windows CrosEC driver](https://github.com/DHowett/FrameworkWindowsUtils) -## Prerequisites +## Building -Only [Rustup](https://rustup.rs/) is needed. Based on `rust-toolchain.toml` it -will install the right toolchain and version for this project. +### Dependencies -## Building +[Rustup](https://rustup.rs/) is convenient for setting up the right Rust version. +Based on `rust-toolchain.toml` it will install the right toolchain and version for this project. MSRV (Minimum Supported Rust Version): - 1.74 for Linux/Windows - 1.74 for UEFI +System dependencies + +``` +# NixOS +nix-shell --run fish -p cargo systemd udev hidapi pkg-config +direnv shell + +# Fedora +sudo dnf install systemd-devel hidapi-devel + +# FreeBSD +sudo pkg install hidapi +``` + ```sh # Running linter cargo clippy @@ -175,17 +189,6 @@ make -C framework_uefi ls -l framework_uefi/build/x86_64-unknown-uefi/boot.efi ``` -### Dependencies - -``` -# NixOS -nix-shell --run fish -p cargo systemd udev hidapi pkg-config -direnv shell - -# FreeBSD -sudo pkg install hidapi -``` - ## Install local package ``` @@ -196,75 +199,10 @@ sudo pkg install hidapi ## Running -Run without any arguments to see the help: - -``` -> cargo run -Swiss army knife for Framework laptops - -Usage: framework_tool [OPTIONS] - -Options: - -v, --verbose... More output per occurrence - -q, --quiet... Less output per occurrence - --versions List current firmware versions version - --esrt Display the UEFI ESRT table - --power Show current power status (battery and AC) - --pdports Show information about USB-C PD ports - --info Show info from SMBIOS (Only on UEFI) - --pd-info Show details about the PD controllers - --dp-hdmi-info Show details about connected DP or HDMI Expansion Cards - --dp-hdmi-update Update the DisplayPort or HDMI Expansion Card - --audio-card-info Show details about connected Audio Expansion Cards (Needs root privileges) - --privacy Show privacy switch statuses (camera and microphone) - --pd-bin Parse versions from PD firmware binary file - --ec-bin Parse versions from EC firmware binary file - --capsule Parse UEFI Capsule information from binary file - --dump Dump extracted UX capsule bitmap image to a file - --h2o-capsule Parse UEFI Capsule information from binary file - --intrusion Show status of intrusion switch - --inputdeck Show status of the input deck - --input-deck-mode - Set input deck power mode [possible values: auto, off, on] (Framework 16 only) [possible values: auto, off, on] - --expansion-bay Show status of the expansion bay (Framework 16 only) - --charge-limit [] - Get or set max charge limit - --get-gpio [] - Get GPIO value by name or all, if no name provided - --fp-led-level [] - Get or set fingerprint LED brightness level [possible values: high, medium, low, ultra-low, auto] - --fp-brightness [] - Get or set fingerprint LED brightness percentage - --kblight [] Set keyboard backlight percentage or get, if no value provided - --tablet-mode Set tablet mode override [possible values: auto, tablet, laptop] - --touchscreen-enable - Enable/disable touchscreen [possible values: true, false] - --console Get EC console, choose whether recent or to follow the output [possible values: recent, follow] - --reboot-ec Control EC RO/RW jump [possible values: reboot, jump-ro, jump-rw, cancel-jump, disable-jump] - --hash Hash a file of arbitrary data - --driver Select which driver is used. By default portio is used [possible values: portio, cros-ec, windows] - --pd-addrs - Specify I2C addresses of the PD chips (Advanced) - --pd-ports - Specify I2C ports of the PD chips (Advanced) - -t, --test Run self-test to check if interaction with EC is possible - -h, --help Print help information -``` +Run without any arguments to see the help. Many actions require root. First build with cargo and then run the binary with sudo: ```sh cargo build && sudo ./target/debug/framework_tool ``` - -##### Running on ChromeOS - -The application can run on ChromeOS but most commands rely on custom host -commands that we built into the EC firmware of non-Chromebook Framework laptops. -In theory you could add those patches to the Chromebook platform, build your -own EC firmware and flash it. - -## Tests - -- [x] Basic unit tests -- [x] Test parsing real binaries From 4f7c0f56a84e13206ac527eaf774b77a88a16a09 Mon Sep 17 00:00:00 2001 From: Daniel Schaefer Date: Mon, 18 Aug 2025 17:33:58 +0800 Subject: [PATCH 4/4] Intel Core Ultra Windows driver supported in BIOS 3.06 https://community.frame.work/t/framework-laptop-13-intel-core-ultra-series-1-bios-3-06-release-beta/74084 Signed-off-by: Daniel Schaefer --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 440cff0..eb44489 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ On UEFI and FreeBSD raw port I/O is used - on Linux this can also be used as a f | Intel Core 12th Gen | Yes | [6.13](https://github.com/torvalds/linux/commit/dcd59d0d7d51b2a4b768fc132b0d74a97dfd6d6a) | Not yet | | Intel Core 13th Gen | Yes | [6.13](https://github.com/torvalds/linux/commit/dcd59d0d7d51b2a4b768fc132b0d74a97dfd6d6a) | Not yet | | AMD Ryzen 7040 | Yes | [6.10](https://github.com/torvalds/linux/commit/c8f460d991df93d87de01a96b783cad5a2da9616) | BIOS 3.16+ | -| Intel Core Ultra 1S | Yes | [6.12](https://github.com/torvalds/linux/commit/62be134abf4250474a7a694837064bc783d2b291) | Soon | +| Intel Core Ultra S1 | Yes | [6.12](https://github.com/torvalds/linux/commit/62be134abf4250474a7a694837064bc783d2b291) | BIOS 3.06+ | | AMD Ryzen AI 300 | Yes | [6.12](https://github.com/torvalds/linux/commit/62be134abf4250474a7a694837064bc783d2b291) | Yes | | Framework 16 | | | | | AMD Ryzen 7040 | Yes | [6.10](https://github.com/torvalds/linux/commit/c8f460d991df93d87de01a96b783cad5a2da9616) | BIOS 3.06+ |