From 9393d1cc438d7145bda10ff9083519b1fc83b424 Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Sat, 10 May 2025 23:10:55 -0400 Subject: [PATCH 1/6] Rename supported devices to devices --- {supported-devices => devices}/devices.json | 0 {supported-devices => devices}/index.js | 0 {supported-devices => devices}/os-support.json | 0 package.json | 2 +- src/.vuepress/config.js | 4 ++-- src/.vuepress/public/{supported-devices.js => devices.js} | 0 src/docs/{firmware/supported-devices.md => devices.md} | 2 +- src/docs/firmware/known-issues.md | 2 +- src/docs/firmware/system-info.md | 4 ++-- src/docs/firmware/write-protect.md | 2 +- src/docs/installing/index.md | 2 +- 11 files changed, 9 insertions(+), 9 deletions(-) rename {supported-devices => devices}/devices.json (100%) rename {supported-devices => devices}/index.js (100%) rename {supported-devices => devices}/os-support.json (100%) rename src/.vuepress/public/{supported-devices.js => devices.js} (100%) rename src/docs/{firmware/supported-devices.md => devices.md} (98%) diff --git a/supported-devices/devices.json b/devices/devices.json similarity index 100% rename from supported-devices/devices.json rename to devices/devices.json diff --git a/supported-devices/index.js b/devices/index.js similarity index 100% rename from supported-devices/index.js rename to devices/index.js diff --git a/supported-devices/os-support.json b/devices/os-support.json similarity index 100% rename from supported-devices/os-support.json rename to devices/os-support.json diff --git a/package.json b/package.json index 38bb7f3d..46c05e1f 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "dev": "npm run device-table && vuepress dev src", "dev-prod": "npm run device-table && NODE_ENV=production vuepress dev src", "build": "npm run device-table && vuepress build src", - "device-table": "node supported-devices/index.js" + "device-table": "node devices/index.js" }, "license": "MIT", "devDependencies": { diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 9ea13338..be8e040a 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -64,8 +64,8 @@ export default { link: '/docs/firmware/system-info', }, { - text: 'Supported Devices', - link: '/docs/firmware/supported-devices', + text: 'Devices', + link: '/docs/devices', }, { text: 'Known Issues', diff --git a/src/.vuepress/public/supported-devices.js b/src/.vuepress/public/devices.js similarity index 100% rename from src/.vuepress/public/supported-devices.js rename to src/.vuepress/public/devices.js diff --git a/src/docs/firmware/supported-devices.md b/src/docs/devices.md similarity index 98% rename from src/docs/firmware/supported-devices.md rename to src/docs/devices.md index 182f3bae..4e7ffd63 100644 --- a/src/docs/firmware/supported-devices.md +++ b/src/docs/devices.md @@ -35,7 +35,7 @@ If your device isn't listed, it doesn't have support. If you are on a smaller screen, scroll sideways to see whole table. ::: - +

Search:

diff --git a/src/docs/firmware/known-issues.md b/src/docs/firmware/known-issues.md index 7d3b6fd1..aba406b5 100644 --- a/src/docs/firmware/known-issues.md +++ b/src/docs/firmware/known-issues.md @@ -1,5 +1,5 @@ --- -prev: supported-devices +prev: devices next: developer-mode --- diff --git a/src/docs/firmware/system-info.md b/src/docs/firmware/system-info.md index 011d3c02..22f7195e 100644 --- a/src/docs/firmware/system-info.md +++ b/src/docs/firmware/system-info.md @@ -1,6 +1,6 @@ --- prev: index.md -next: supported-devices +next: devices --- # Finding System Info @@ -61,5 +61,5 @@ Example output: `model name : Intel(R) Celeron(R) CPU N3350 @ 1.10GHz` ### How to find your CPU generation 1. Find your board name using the steps above (ex: `SNAPPY`). -2. Go to the [Supported Devices Page](supported-devices.md). +2. Go to the [Devices Page](devices.md). 3. The Supported Devices Page has sections for each generation that has a list of boards for that specific generation. Use Ctrl+F to locate your board and find which generation it's listed under. diff --git a/src/docs/firmware/write-protect.md b/src/docs/firmware/write-protect.md index 262226a6..29e9ad92 100644 --- a/src/docs/firmware/write-protect.md +++ b/src/docs/firmware/write-protect.md @@ -9,7 +9,7 @@ next: about You do not have to disable write protect if flashing [RW_Legacy](about.md#rw_legacy). ::: -Refer to the [supported devices list](supported-devices.md) to figure out which method you need to use to disable write-protect on your device. +Refer to the [devices list](devices.md) to figure out which method you need to use to disable write-protect on your device. Depending on your device, you will need to do **one** of the following: diff --git a/src/docs/installing/index.md b/src/docs/installing/index.md index 42d7977d..9ecc9434 100644 --- a/src/docs/installing/index.md +++ b/src/docs/installing/index.md @@ -6,7 +6,7 @@ next: false # Installing an OS ::: tip -Be sure to check the [supported devices page](../firmware/supported-devices.md) to see what you can run. +Be sure to check the [devices page](../devices.md) to see what you can run. ::: ## Windows From e1108758369d49ba47049959e0f652b11cfede44 Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Mon, 12 May 2025 16:40:22 -0400 Subject: [PATCH 2/6] Clean up devices page --- src/docs/devices.md | 33 +-------------------------------- 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/src/docs/devices.md b/src/docs/devices.md index 4e7ffd63..191bb355 100644 --- a/src/docs/devices.md +++ b/src/docs/devices.md @@ -1,35 +1,4 @@ ---- -prev: system-info -next: known-issues ---- - -# Supported Devices and Platforms - -Supported devices are listed in the table below, grouped by platform/family. If your device is not listed, it is not supported. Support is determined entirely and exclusively by the boardname. Use your Chromebook's boardname to see if it has support. - -## Determining Device Support - -What's in a name? All ChromeOS devices have a board/device name, which determines which firmware, OS build, etc a device uses. The board name is listed at the bottom of both the Recovery Mode and Developer Mode screens, as part of the hardware ID (HWID). - -The chart below provides a full list of all ChromeOS devices currently supported by Chrultrabook, the firmware type available for each, and notes for Windows, Linux, and macOS operating systems. - -In most cases, all of the devices in a given platform/family are supported, but sometimes there are exceptions (especially with older or newer devices). - -### OS Support - -A device having firmware available (either RW_LEGACY or UEFI Full ROM) does not imply any level of functionality when running an OS other than ChromeOS. Some devices/platforms are better supported in some Linux distros vs others. Some devices/platforms are better supported under Windows than others. - -## Supported Platforms - -| Intel | AMD | ARM | -| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Intel platforms have good support for both Linux and Windows. Some have support for macOS. | Stoneyridge support in Windows is questionable, and installing a custom kernel is required to get working audio in Linux. Ryzen has support for both Linux and Windows. MacOS is **untested** on AMD platforms. | Currently unsupported (WIP). [PostmarketOS](https://wiki.postmarketos.org/wiki/Chrome_OS_devices) has support for many ARM Chromebooks. | - -## Firmware and OS Support - -::: tip -If your device isn't listed, it doesn't have support. -::: +# Device Support Status ::: tip If you are on a smaller screen, scroll sideways to see whole table. From d9b5a98c7280afddb1bc29e3c0ab0b236bcd1958 Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Mon, 12 May 2025 16:43:16 -0400 Subject: [PATCH 3/6] Move device support status to its own section on the sidebar --- src/.vuepress/config.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index be8e040a..2a890cf7 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -54,6 +54,10 @@ export default { text: 'FAQ', link: '/docs/faq', }, + { + text: 'Device Support Status', + link: '/docs/devices', + }, { text: 'Firmware', link: '/docs/firmware/', @@ -63,10 +67,6 @@ export default { text: 'Finding System Info', link: '/docs/firmware/system-info', }, - { - text: 'Devices', - link: '/docs/devices', - }, { text: 'Known Issues', link: '/docs/firmware/known-issues', From 629e73f0e3ab91599f1c33107f4e7e0a1525929d Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Mon, 12 May 2025 16:58:13 -0400 Subject: [PATCH 4/6] Remove firmware pages --- src/.vuepress/config.js | 99 -------------- src/docs/exiting-developer-mode.md | 44 ------ src/docs/firmware/about.md | 35 ----- src/docs/firmware/battery.md | 35 ----- src/docs/firmware/compiling-coreboot.md | 25 ---- src/docs/firmware/developer-mode.md | 38 ------ src/docs/firmware/flashing-firmware.md | 46 ------- src/docs/firmware/index.md | 43 ------ src/docs/firmware/known-issues.md | 27 ---- src/docs/firmware/manually-flashing.md | 20 --- src/docs/firmware/recovery-mode.md | 46 ------- src/docs/firmware/suzyq.md | 38 ------ src/docs/firmware/system-info.md | 65 --------- src/docs/firmware/ti50-ap-ro.md | 57 -------- src/docs/firmware/updating-firmware.md | 17 --- src/docs/firmware/write-protect.md | 23 ---- src/docs/reverting/booting-recovery-usb.md | 22 --- src/docs/reverting/flashing-stock.md | 32 ----- src/docs/reverting/index.md | 21 --- src/docs/reverting/making-recovery-usb.md | 39 ------ src/docs/unbricking/index.md | 30 ----- src/docs/unbricking/unbrick-ch341a.md | 147 --------------------- src/docs/unbricking/unbrick-flipper.md | 59 --------- src/docs/unbricking/unbrick-suzyq.md | 113 ---------------- 24 files changed, 1121 deletions(-) delete mode 100644 src/docs/exiting-developer-mode.md delete mode 100644 src/docs/firmware/about.md delete mode 100644 src/docs/firmware/battery.md delete mode 100644 src/docs/firmware/compiling-coreboot.md delete mode 100644 src/docs/firmware/developer-mode.md delete mode 100644 src/docs/firmware/flashing-firmware.md delete mode 100644 src/docs/firmware/index.md delete mode 100644 src/docs/firmware/known-issues.md delete mode 100644 src/docs/firmware/manually-flashing.md delete mode 100644 src/docs/firmware/recovery-mode.md delete mode 100644 src/docs/firmware/suzyq.md delete mode 100644 src/docs/firmware/system-info.md delete mode 100644 src/docs/firmware/ti50-ap-ro.md delete mode 100644 src/docs/firmware/updating-firmware.md delete mode 100644 src/docs/firmware/write-protect.md delete mode 100644 src/docs/reverting/booting-recovery-usb.md delete mode 100644 src/docs/reverting/flashing-stock.md delete mode 100644 src/docs/reverting/index.md delete mode 100644 src/docs/reverting/making-recovery-usb.md delete mode 100644 src/docs/unbricking/index.md delete mode 100644 src/docs/unbricking/unbrick-ch341a.md delete mode 100644 src/docs/unbricking/unbrick-flipper.md delete mode 100644 src/docs/unbricking/unbrick-suzyq.md diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 2a890cf7..75278f2a 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -58,67 +58,6 @@ export default { text: 'Device Support Status', link: '/docs/devices', }, - { - text: 'Firmware', - link: '/docs/firmware/', - collapsible: false, - children: [ - { - text: 'Finding System Info', - link: '/docs/firmware/system-info', - }, - { - text: 'Known Issues', - link: '/docs/firmware/known-issues', - }, - { - text: 'Developer Mode', - link: '/docs/firmware/developer-mode', - collapsible: true, - children: [ - { - text: 'Recovery Mode', - link: '/docs/firmware/recovery-mode', - } - ] - }, - { - text: 'Disabling Write Protect', - link: '/docs/firmware/write-protect', - collapsible: true, - children: [ - { - text: 'Using a SuzyQable', - link: '/docs/firmware/suzyq', - }, - { - text: 'Unplugging the Battery', - link: '/docs/firmware/battery', - } - ] - }, - { - text: 'Types of Firmware', - link: '/docs/firmware/about' - }, - { - text: 'Flashing Firmware', - link: '/docs/firmware/flashing-firmware' - }, - { - text: 'Updating Firmware', - link: '/docs/firmware/updating-firmware' - }, - { - text: 'Compiling Custom Firmware', - link: '/docs/firmware/compiling-coreboot', - }, - { - text: 'Flashing Manually', - link: '/docs/firmware/manually-flashing', - }, - ] - }, { text: "Installing an OS", link: "/docs/installing/", @@ -183,44 +122,6 @@ export default { } ] }, - { - text: 'Unbricking', - link: '/docs/unbricking/', - collapsible: false, - children: [ - { - text: 'Unbricking with a ch341a USB Programmer', - link: '/docs/unbricking/unbrick-ch341a', - }, - { - text: 'Unbricking with a Suzy-Q Cable', - link: '/docs/unbricking/unbrick-suzyq', - }, - { - text: 'Unbricking with a Flipper Zero', - link: '/docs/unbricking/unbrick-flipper', - } - ] - }, - { - text: 'Reverting to chromeOS', - link: '/docs/reverting/', - collapsible: false, - children: [ - { - text: 'Flashing Stock Firmware', - link: '/docs/reverting/flashing-stock', - }, - { - text: 'Making a Recovery USB', - link: '/docs/reverting/making-recovery-usb', - }, - { - text: 'Booting the Recovery USB', - link: '/docs/reverting/booting-recovery-usb', - } - ] - }, { text: 'Contributing', link: '/docs/contributing', diff --git a/src/docs/exiting-developer-mode.md b/src/docs/exiting-developer-mode.md deleted file mode 100644 index 49bae5fb..00000000 --- a/src/docs/exiting-developer-mode.md +++ /dev/null @@ -1,44 +0,0 @@ -# Developer Mode - -::: danger -Entering and exiting Developer mode will **wipe all** user data! -Backup anything if you have to. -::: - -## Reset GBB Flags - -If you get this error "WARNING: TONORM prohibited by GBB_FORCE_DEV_SWITCH_ON" or find the "Return to secure mode" button missing, you need to reset your gbb flags. - -1. Boot chromeOS. - -2. Press `Control` + `Alt` + `T` to bring up a crosh terminal. - -3. Run [MrChromebox's firmware utility script.](https://mrchromebox.tech/#fwscript) - - - Type `cd; curl -LO mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` and press Enter. - - If you encounter certificate related errors when downloading the script from ChromeOS, then add `-k` to the `curl` and script command to bypass SSL certificate checking as so: - - `cd; curl -LOk mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` - -4. Select option 3: "Set Boot Options (GBB flags)". - -5. Select option 5: "Reset to factory default". - -6. Your done. - -### Entering Developer Mode - -1. Boot your system to the "You are in Developer Mode" or "OS Verification is OFF" screen. - -#### Chromebooks/Chromeboxes - -1. Press the `Spacebar`. If it brings up a warning asking for confirmation, Press `Enter`. - -2. Press `Enter`. The screen should turn off breifly and say that its returning to "Normal (Verified) Mode...". - -3. Once its done, Setup the system like normal. - -#### Tablets - -1. Select "Enable OS Verification". - -2. Once its done, Setup the system like normal. diff --git a/src/docs/firmware/about.md b/src/docs/firmware/about.md deleted file mode 100644 index b487259b..00000000 --- a/src/docs/firmware/about.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -prev: write-protect -next: flashing-firmware ---- - -# Types of Firmware - -## RW_LEGACY - -- Updates/replaces the stock RW_LEGACY payload (SeaBIOS or edk2) included on many older models; supplements the ChromeOS / secure boot payload (depthcharge) -- Leaves all stock functionality intact, including the Developer Mode boot screen and Recovery Mode functionality -- Allows device to dual-boot linux alongside ChromeOS -- Does not require disabling write-protect -- Carries zero risk of bricking the device -- On many models, includes bugfixes and enables additional functionality - -::: warning -Do not run Windows on RW_LEGACY. The RW_LEGACY firmware is for users who want to dual-boot ChromeOS + Linux, or users who want to run Linux without having to open the device/disable the firmware write-protect (and are OK with the accompanying limitations). -::: - -## (UEFI) Full ROM - -- A complete firmware image which includes updated/customized versions of the hardware init component (coreboot) and UEFI boot payload (edk2) -- Removes the developer mode boot ("OS verification is OFF") screen -- Completely removes the ability to run ChromeOS (and ChromeOS Recovery Mode), creating a small risk of bricking your device -- Offers the best support for booting all OSes besides ChromeOS -- Adds full hardware support for virtualization (vmx / VT-x) -- Fixes many bugs and/or idiosyncrasies associated with the stock firmware -- UEFI firmware contains updated EC firmware as well, which brings additional fixes on most Chromebooks (mainly keyboard related) -- Requires installation of a UEFI-compatible OS after flashing -- Essentially turns your ChromeOS device into a "regular" PC / laptop - -::: tip -The (UEFI) Full ROM firmware is the best option for all users who no longer need/want to run ChromeOS (ie, want to run Linux/Windows/macOS exclusively), and who do not mind disabling write-protection on their device. -::: diff --git a/src/docs/firmware/battery.md b/src/docs/firmware/battery.md deleted file mode 100644 index 9f845c57..00000000 --- a/src/docs/firmware/battery.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -prev: write-protect -next: false ---- - -# Disabling Write Protect via Battery - -::: warning -This method requires opening your device. Be sure to use the correct tools to prevent hardware damage. -::: - -## Step 1: Open the device and disconnect the battery - -1. Power down your device. Close the lid and flip it over. -2. Take out all of the screws. - - ::: tip - Screws may be underneath the rubber feet that keep the Chromebook from sliding. - ::: - -3. Gently pry the back off the Chromebook. If you do not have the proper tools a dull knife would be helpful. - - On some Chromebooks, the keyboard needs to be removed instead of the back. Be careful as there's a ribbon wire underneath that needs disconnecting first. -4. Unplug the battery connector. You do not need to take the entire battery out of the Chromebook. - -## Step 2: Boot using AC power, and flash - -1. Plug the Chromebook into a power adapter. - - ::: tip - There is a 15V USB-C PD requirement for booting without the battery. - ::: - -2. Boot the chromebook up - - If you removed the keyboard, make sure to reattach it for this step. -3. Continue to [Flashing Firmware](flashing-firmware.md) diff --git a/src/docs/firmware/compiling-coreboot.md b/src/docs/firmware/compiling-coreboot.md deleted file mode 100644 index 01d50cc9..00000000 --- a/src/docs/firmware/compiling-coreboot.md +++ /dev/null @@ -1,25 +0,0 @@ -# Compiling Custom Firmware - -## Cloning & Building ROMs - -::: danger -Building and flashing your own firmware has the potential to brick your device. Do not do this unless you are sure you know what you are doing/have a way to recover from a bad flash. Some level of knowledge with using the Linux command line is required. -::: - -1. **Install tools and libraries needed for coreboot:** - - Debian based distros: `sudo apt install -y bison build-essential curl flex git gnat imagemagick libncurses5-dev m4 nasm python-is-python3 uuid-dev zlib1g-dev libssl-dev` - - Arch based distros: `sudo pacman --needed -S base-devel curl git gcc-ada ncurses zlib nasm imagemagick` - - Redhat based distros: `sudo dnf install git make gcc-gnat flex bison xz bzip2 gcc g++ ncurses-devel wget zlib-devel patch openssl libuuid-devel nasm texinfo` -2. **Clone the repository:** - - `git clone https://github.com/mrchromebox/coreboot.git` -3. **`cd` to the coreboot folder, then build the coreboot toolchain** - - `make crossgcc-i386 CPUS=$(nproc)` -4. **Make changes now, if needed.** - - Common changes include: - - Replacing the default logo (`Documentation/coreboot_logo.bmp`) - - Changing version string (`CONFIG_LOCALVERSION`) -5. **Build the ROM** - - `./build-uefi.sh ` - - For example, `./build-uefi.sh careena` - - ROMs will be stored in `../roms` -6. **Continue onto [Flashing Manually](manually-flashing.md) to flash** diff --git a/src/docs/firmware/developer-mode.md b/src/docs/firmware/developer-mode.md deleted file mode 100644 index 7de964c0..00000000 --- a/src/docs/firmware/developer-mode.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -prev: known-issues -next: write-protect ---- - -# Developer Mode - -Enabling [developer mode](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md) is the first step to running an alternate OS on your Chromebook! Developer Mode is an alternate mode that all chromeOS devices have that opens up the ability to make unverified changes to the operating system and hardware. - -::: danger -Doing this will wipe **all** user data! Make backups if needed before proceeding. -::: - -::: tip -The battery must be plugged in while enabling developer mode. -::: - -## Enabling Developer Mode - -First, enter [recovery mode](recovery-mode.md). Then proceed with the following instructions for your device. - -### Chromebooks/Chromeboxes - -1. Press Ctrl+D. This should bring up a warning asking for confirmation for either "Turn OS Verification OFF" or "Enable Developer Mode". - -2. Press Enter. The system should reboot and bring you to the "You are in Developer Mode" or "OS Verification is OFF" screen. - -3. Press Ctrl+D to boot from internal disk. - -4. Setup the system like normal, but **do not enable debugging features**. - -### Tablets - -1. Press `Volume Up` + `Volume Down` to bring up the menu selection screen. - -2. Use the `Volume Up` and `Volume Down` to navigate to "Confirm Enabling Developer Mode", then press `Power` to select it. The system should reboot and bring you to the "OS Verification is OFF" screen. - -3. Select "Developer Options", then select "Boot from Internal Disk". diff --git a/src/docs/firmware/flashing-firmware.md b/src/docs/firmware/flashing-firmware.md deleted file mode 100644 index c14c918d..00000000 --- a/src/docs/firmware/flashing-firmware.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -prev: about -next: ../installing/ ---- - -# Flashing Custom Firmware - -Refer to [this page](about) for an overview of both RW_LEGACY and UEFI. - -::: danger -**Flashing the firmware has the potential to brick your device**, requiring relatively inexpensive hardware and some technical knowledge to recover. Not all boards can be tested prior to release, and even then slight differences in hardware can lead to unforeseen failures. If you do not have the ability to recover from a bad flash, **you are taking a risk**. Flashing Full ROM firmware will remove your ability to run ChromeOS. -::: - -To convert your machine from Google's firmware and ChromeOS to Coreboot and AltOS (Linux/Windows/macOS), you will need to first perform the following steps: - -1. [Enable developer mode](developer-mode.md). -2. [Disable write protect](write-protect.md) (If flashing UEFI). -3. Run [MrChromebox's firmware utility script](https://mrchromebox.tech/#fwscript) within VT-2 (`ctrl` + `alt` + `f2` (right arrow)). - - Type `cd; curl -LO mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` and press Enter. - - If you encounter certificate related errors when downloading the script from ChromeOS, then add `-k` to the `curl` and script command to bypass SSL certificate checking as so: - - `cd; curl -LOk mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` -4. If you are flashing Full ROM, the firmware script will prompt you to make a backup of your stock firmware. **Store it in a safe place** (Google Drive, another PC, etc), as reverting to stock firmware without a backup is **very difficult**. -5. If there's no error, shutdown the device without worry. - -::: danger -If flashing fails for UEFI, **DO NOT SHUTDOWN** and immediately attempt to restore stock firmware. -Otherwise, shutdown without worry. -::: - -::: tip -If you unplugged the battery to [disable write protect](battery.md), you can plug it back in now. All flashes after this will not require you to unplug the battery. -::: - -## Booting - -### UEFI - -It can take up to a minute for display to come up on first POST. **Do not interrupt the first boot.** - -### RW_LEGACY - -On the developer mode boot screen, press Ctrl+L. If a selection appears, pick "Tianocore". - -If you are met with a white "Alternative Firmware Menu" screen (after pressing Ctrl+L), press 2 to boot from USB or `0 to boot from internal storage (where you installed your Linux OS). - -Further boot options can be accessed after you have entered a number, by pressing ESC as signified by the booting screen. If you wish to access these options before you've installed an OS, press 0 then ESC. diff --git a/src/docs/firmware/index.md b/src/docs/firmware/index.md deleted file mode 100644 index a22b763c..00000000 --- a/src/docs/firmware/index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -prev: false -next: system-info ---- - -# Flashing Custom Firmware - -::: danger -You are about to make **UNOFFICIAL** changes to your device! This will **VOID ANY WARRANTY** that came with your original purchase. We provide **ZERO WARRANTY** if you encounter bugs, brick your device, lose your job because the alarm clock didn't go off, or if a thermonuclear war starts. **YOU are doing all changes at your own RISK**! -::: - -::: danger -Do not continue if your device is currently owned or enrolled by a organization, such as a school or employer, unless you were given **DIRECT PERMISSION to do so.** -::: - -## Prerequisites - -- Know your hardware - - Your CPU model and generation - - Your storage devices (HDD/SSD, eMMC, NVMe, etc.) - - **Your boardname** - - For example, the boardname for Asus Chromebook C302CA is `Cave` - - If you do not know where to find this info, take a look at the [System Info Page](system-info.md). -- **A basic knowledge of command lines and how to use a terminal/command prompt.** - - We cannot help you if you do not know how to go to a directory or delete a file from a terminal. -- A minimum of an 8GB USB drive or SD Card for creating a bootable OS installer. -- A second device is recommended, and required in some cases. - -::: tip NOTE -Only x86_64 devices are currently supported. -::: - -## Asking for help properly - -If you are facing a issue, please read the [FAQ](../faq.md) first. - -::: tip -When asking for help, ask in English. We can't help you if we do not understand the question. Using a translator is fine. -::: - -**Do not use manufacturer's model name or serial number when asking for help** (i.e: HP Chromebook 14a), it doesn't help with identifying the machine. Provide the boardname, otherwise your support request will be ignored. - -If you do not know where to find your boardname, take a look [here](system-info.md). diff --git a/src/docs/firmware/known-issues.md b/src/docs/firmware/known-issues.md deleted file mode 100644 index aba406b5..00000000 --- a/src/docs/firmware/known-issues.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -prev: devices -next: developer-mode ---- - -# Known Issues - -## Devices - -::: tip -You should avoid buying any devices in this list. -::: - -- Samsung Chromebook 3 (CELES): Numerous hardware bugs that make it difficult to use. -- Samsung Galaxy Chromebook (KOHAKU): Badly designed hardware, deteriorating trackpad grounding, possibly faulty backlight circuit. -- Samsung Chromebox Series 3 (STUMPY): DisplayPort output is non-functional under Windows, and VGA output through the DVI port is non-functional. - -## Firmware - -- **All ARM Chromebooks**: No support, though development is slowly starting. -- GeminiLake: Legacy boot mode/alternative firmware menu works but does not show payload list -- AMD Stoneyridge: Some Stoney Ridge devices may not currently have functional Legacy Boot Mode due to bugs in Google's firmware. -- AMD Cezanne: legacy boot mode/alternative firmware menu works, edk2 boots, but screen backlight is off. Will be fixed in next Google fw update (fingers crossed). - -::: tip -For issues relating to OS support, see [this page](../installing/known-issues.md). -::: diff --git a/src/docs/firmware/manually-flashing.md b/src/docs/firmware/manually-flashing.md deleted file mode 100644 index e50310af..00000000 --- a/src/docs/firmware/manually-flashing.md +++ /dev/null @@ -1,20 +0,0 @@ -# Manually Flashing ROMs - -::: danger -Flashing your own firmware has the potential to brick your device. Do not do this unless you are sure you know what you are doing/have a way to recover from a bad flash. Some level of knowledge with using the Linux command line is required. -::: - -1. Have your firmware rom. We will assume you already have the file you want to flash for this guide. -2. Download flashrom, then give it execute permission. - - For most distributions: `cd; curl -LO https://files.tree123.org/utils/x86_64/gnu/flashrom; chmod +x flashrom` - - For musl (Alpine Linux): `cd; curl -LO https://files.tree123.org/utils/x86_64/musl/flashrom; chmod +x flashrom` -3. Flash your custom ROM - - Backup your current rom, just in case things go wrong: `./flashrom -p internal -r current.rom` - - Note: Intel Chromebooks should be flashed with `--ifd -i bios` ex: `sudo ./flashrom -p internal --ifd -i bios -w coreboot.rom` - - Flash your custom firmware: `sudo ./flashrom -p internal -w firmware.rom` -4. Reboot - - Assuming it said `success` on all checks, reboot. - -::: danger -Do not reboot if any of the checks failed. -::: diff --git a/src/docs/firmware/recovery-mode.md b/src/docs/firmware/recovery-mode.md deleted file mode 100644 index 17c9314d..00000000 --- a/src/docs/firmware/recovery-mode.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -prev: developer-mode.md -next: false ---- - -# Recovery Mode - -Recovery mode is used to restore the OS and RW regions of the firmware. It gets triggered when an issue with the device is detected, or you manually start it. - -::: tip -Your data is unaffected in recovery mode unless you use a recovery image or enter [developer mode](entering-developer-mode.html). -::: - -::: tip NOTE -Images sourced from [Google Support](https://support.google.com/chrome/a/answer/1360642?sjid=16957732159917599441-NC#chromebox&zippy=%2Cwipe-a-chromebox) and [Asus Support](https://www.asus.com/support/FAQ/1039185/). -::: - -::: danger -Do not continue if your device is currently owned or enrolled by a organization, such as a school or employer. Unless you were given permission by your organization, its a crime. -::: - -## Entering Recovery Mode - -### Chromebooks - -Press `ESC` + `Refresh` (arrow icon), + `Power` at the same time. This should bring your system into recovery mode. - -- For some devices the power button is on the side. -- Some devices may need to hold down the `Fullscreen` button (four corners icon) instead of the `Refresh` button. - -Chromebook Keyboard - -### Chromeboxes - -Find the recovery button hole. A reference of what to look for is below. - -Recovery Button Hole - -When you do, use something like a paper clip to hold the button down, then turn on the device. This should bring your system into recovery mode. -You can stop holding down the button at this point. - -### Tablets - -Hold down `Volume Up` + `Volume Down` + `Power` for 10 seconds, then release. This should bring your system into recovery mode. - -tablet Combo diff --git a/src/docs/firmware/suzyq.md b/src/docs/firmware/suzyq.md deleted file mode 100644 index 34b800ed..00000000 --- a/src/docs/firmware/suzyq.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -prev: write-protect -next: false ---- - -# Disabling write protect with a SuzyQable - -::: tip -This method is only available on CR50 devices. -::: - -::: tip -This method requires a SuzyQable, a chromeOS debug cable. -::: - -
- -## Step 1: Enabling Closed Case Debugging (CCD) - -1. Open VT-2 (`ctrl` + `alt` + `f2` (right arrow)). -2. Login as `root`. -3. Run `gsctool -a -o`. -4. You will be prompted to press the `PP` (physical presence) button several times. This is a fancy way of saying to press the power button. This process takes several minutes and ends with the message `PP Done!`. -5. The device will suddenly reboot and exit developer mode. Re-enable developer mode and continue with the instructions. - -## Step 2: Disable Write Protect - -1. Open VT-2 (`ctrl` + `alt` + `f2` (right arrow)). -2. Login as `root`. -3. Plug in your cable -4. Run `ls /dev/ttyUSB*` to verify your cable is working. This should output 3 items, `ttyUSB0`, `ttyUSB1`, and `ttyUSB2`. If you do not see these items, try flipping the `usb-c` end upside-down, and try another `usb-c` port. If there is still no result, confirm your cable was assembled properly. -5. Run the following commands. This will disable hardware write protect. - - `echo "wp false" > /dev/ttyUSB0` - - `echo "wp false atboot" > /dev/ttyUSB0` -6. Run `echo "ccd reset factory" > /dev/ttyUSB0` to be able to unbrick using a suzyqable, if needed. -7. Run `gsctool -a -I` to verify you have opened all the CCD flags. The current value for all CCD flags should be set to Y/Always. -8. Verify `crossystem wpsw_cur` returns `0`. -9. Reboot. diff --git a/src/docs/firmware/system-info.md b/src/docs/firmware/system-info.md deleted file mode 100644 index 22f7195e..00000000 --- a/src/docs/firmware/system-info.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -prev: index.md -next: devices ---- - -# Finding System Info - -::: tip -Some of the following commands require [Developer mode](developer-mode). -::: - -## System Architecture - -Your system architecture is very important as it determines if your device has any support at all. ARM devices are not currently supported by the project, but support for them in the future is planned. - -### How to find your architecture - -1. Open a crosh terminal by pressing Ctrl+Alt+T -2. Type `uname -m` and press enter - -You should now see one of three possible outputs: - -1. `x86_64` -2. `aarch64` -3. `armv7l` - -If you see `x86_64`, your device is very likely to be supported, you will need to find your board name next to see if your device is supported. If you see `armv7l`, `aarch64` or anything with `arm`, you have an ARM device which isn't currently supported. - -## Board Name - -The board name is the special name for your device which determines if it is supported by the custom firmware. - -### How to find your board name - -#### Developer Mode - -1. Open VT-2 by pressing Ctrl + Alt + 🡢 (F2) and login as `chronos` -2. Type `sudo crossystem hwid` and press Enter - -#### Recovery Mode - -1. Enter [Recovery Mode](recovery-mode.md) -2. Find the "Model" line - -You should now see your board name and some extra characters. -Example: `SNAPPY E25-A7C-J2L-I74-A47` -In this example, `SNAPPY` is the board name and you can ignore the extra characters. - -## CPU Model and generation - -The CPU model and generation is used to determine OS support and any extra steps you have to take after installing the OS. - -### How to find your CPU model - -1. Open VT-2 by pressing Ctrl + Alt + 🡢 (F2) and login as `chronos` -2. Type `cat /proc/cpuinfo | grep "model name"` and press Enter - -You should now see your CPU model repeated a few times, we only have to look at the first line. -Example output: `model name : Intel(R) Celeron(R) CPU N3350 @ 1.10GHz` - -### How to find your CPU generation - -1. Find your board name using the steps above (ex: `SNAPPY`). -2. Go to the [Devices Page](devices.md). -3. The Supported Devices Page has sections for each generation that has a list of boards for that specific generation. Use Ctrl+F to locate your board and find which generation it's listed under. diff --git a/src/docs/firmware/ti50-ap-ro.md b/src/docs/firmware/ti50-ap-ro.md deleted file mode 100644 index 5363ba10..00000000 --- a/src/docs/firmware/ti50-ap-ro.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -prev: write-protect -next: false ---- -# Disabling RO firmware protection on Ti50 - -::: tip -This is only applicable to devices with a Ti50 security chip, which is typically found in devices released during or after mid-2023. -::: - -::: tip -If you disabled WP via CCD and reset your CCD flags with `ccd reset factory`, you can skip this step. -::: - -
- -## Step 1: Verify the device has a Ti50 - -1. Open VT-2 (`ctrl` + `alt` + `f2` (right arrow)). -2. Login as `root`. -3. Run `gsctool -a -I | grep AllowUnverifiedRo`. -4. If that command has any output, your device has a Ti50. If you get no output or an error, your device either has a Cr50 or no GSC at all. - -## Step 2: Disable RO verification - -1. Unlock the GSC by running `gsctool -a -o`. -2. Run `gsctool -a -I AllowUnverifiedRo:always`. -3. Press the power button when prompted. - -::: warning -If your device has a Ti50 and you don't disable RO verification, flashing full rom will brick the device (can be recovered with steps listed below). -::: - -## Recovering a device bricked due to RO verification - -### Chromebooks - -1. Press and hold the `Power` button. -2. Press the `Refresh` (arrow icon) button twice. -3. Release the `Power` button. -4. Repeat the above steps a second time. - -### Chromeboxes - -1. Press and hold the `Power` button. -2. Press the recovery pinhole button twice. -3. Release the `Power` button. -4. Repeat the above steps a second time. - -### Tablets - -1. Press and hold the `Power` button. -2. Press and hold `Volume Up` for 10+ seconds. Release and repeat it a second time. -3. Release the `Power` button. -4. Repeat the above steps a second time. - -This will disable RO verification for 15 minutes, allowing you to permanently disable it. diff --git a/src/docs/firmware/updating-firmware.md b/src/docs/firmware/updating-firmware.md deleted file mode 100644 index 78088559..00000000 --- a/src/docs/firmware/updating-firmware.md +++ /dev/null @@ -1,17 +0,0 @@ -# Updating Custom Firmware - -::: tip NOTE -The script does not work on Windows. If you are using Windows, boot a live Linux iso, such as Ubuntu or Fedora, and run the script from there. -::: - -::: tip -curl is not installed by default for Ubuntu or Ubuntu-based distros. To install it, run: `sudo apt update && sudo apt install -y curl` -::: - -1. Run [MrChromebox's Firmware Utility Script](https://mrchromebox.tech/#fwscript). - - In case you forgot, type `cd; curl -LO mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` and press Enter. -2. Choose option 1: `Install/Update UEFI (Full ROM) Firmware`, and reboot if successful. - -::: danger -**DO NOT REBOOT if flash was not successful** -::: diff --git a/src/docs/firmware/write-protect.md b/src/docs/firmware/write-protect.md deleted file mode 100644 index 29e9ad92..00000000 --- a/src/docs/firmware/write-protect.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -prev: developer-mode -next: about ---- - -# Disabling Write Protect - -::: tip -You do not have to disable write protect if flashing [RW_Legacy](about.md#rw_legacy). -::: - -Refer to the [devices list](devices.md) to figure out which method you need to use to disable write-protect on your device. - -Depending on your device, you will need to do **one** of the following: - -- Take out a WP screw -- [Unplug your battery](battery.md) -- Bridge two jumpers -- [Use a SuzyQable](suzyq.md) (A cable that enables CCD (Closed Case Debugging)) - -::: warning -On devices with a Ti50 security chip (2023+), you will additionally need to [disable RO verification](ti50-ap-ro.md). -::: diff --git a/src/docs/reverting/booting-recovery-usb.md b/src/docs/reverting/booting-recovery-usb.md deleted file mode 100644 index f15ae868..00000000 --- a/src/docs/reverting/booting-recovery-usb.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -prev: making-recovery-usb -next: false ---- - -# Booting the Recovery USB - -::: tip -If recovery fails, [disable write protect](../firmware/write-protect.md) since recovery also attempts to update the firmware. -::: - -::: danger -Going through the recovery process will wipe **all** data on the internal drive. -::: - -1. Enter [recovery mode](../firmware/recovery-mode.md). - -2. Plug in your recovery USB drive. - -3. Begin the recovery process. - -4. Once its done, set up the system like normal. diff --git a/src/docs/reverting/flashing-stock.md b/src/docs/reverting/flashing-stock.md deleted file mode 100644 index b4057b1d..00000000 --- a/src/docs/reverting/flashing-stock.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -prev: index.md -next: making-recovery-usb ---- - -# Flashing Stock Firmware - -::: warning -If your device has hit AUE (Auto Update Expiration), you will not be able to revert to chromeOS. -::: - -1. If you already have Linux installed, move on to step 5. Otherwise, make a [bootable Linux live USB](../installing/bootableusb.md). - -2. Connect to WiFi. - -3. Open a terminal, then update and install `curl`. - - - Use the distro's package manager to install it. - -4. Obtain your ROM backup. - -5. Run [MrChromebox's firmware utility script](https://mrchromebox.tech/#fwscript). - - - In case you forgot, type `cd; curl -LO mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh` and press Enter. - -6. Choose option 2: `Restore Stock ChromeOS Firmware`. - - ::: tip - If, for whatever reason, lost your stock firmware backup, Use an additional drive to flash a [recovery image](making-recovery-usb.md). - ::: - -7. Follow on-screen instructions diff --git a/src/docs/reverting/index.md b/src/docs/reverting/index.md deleted file mode 100644 index 4a4f561b..00000000 --- a/src/docs/reverting/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -prev: false -next: flashing-stock ---- - -# Reverting to Stock chromeOS - -::: warning -If your device has hit AUE (Auto Update Expiration), you will not be able to revert to chromeOS using the MrChromebox script. You will need to [flash manually](../firmware/manually-flashing.md). -::: - -## Requirements - -- A PC or laptop to make a ChromeOS recovery USB. -- An external drive like a USB drive or SD card that is at least 8GB. -- Another external drive that contains your stock ROM backup (If backup is avaliable). -- An understanding that this guide has the potential to brick your device. - -You can revert your firmware back to stock and reinstall chromeOS. - -This is useful if your planning to sell your device. diff --git a/src/docs/reverting/making-recovery-usb.md b/src/docs/reverting/making-recovery-usb.md deleted file mode 100644 index 1bc20a21..00000000 --- a/src/docs/reverting/making-recovery-usb.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -prev: flashing-stock -next: booting-recovery-usb ---- - -# Making a Recovery USB - -::: danger -Making a Recovery USB will **wipe all data** on said drive. Back up anything if you need to. -::: - -For you to reinstall chromeOS, you will need to make a Recovery USB. -There are two methods depending on the Operating System Installed. - -## Chromebook Recovery Utility (Windows/ChromeOS/macOS) - -1. Download the [Chromebook Recovery Utility](https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm) from the Chrome Web Store. - -2. Launch the app, then follow on-screen instructions. If you are unable to find your device, you can select the "Select a model from a list" option. - -3. Select the USB drive you want to use. - -4. Wait for it to complete. - -## Manually Flash Recovery Image (Windows/ChromeOS/macOS/Linux) - -1. Go to [cros.tech](https://cros.tech/) and find your device. - -2. Click on the "Recovery Images" dropdown and select the latest one. - -3. Extract the file. - -### Windows - -Use [Rufus](../installing/bootableusb.md#flashing-using-rufus-windows) to flash the recovery .bin file to USB but make sure to flash in "dd" mode. - -### macOS/ChromeOS/Linux - -Use [dd](../installing/bootableusb.md#flashing-with-dd-linux-macos) to flash the recovery .bin file to USB. diff --git a/src/docs/unbricking/index.md b/src/docs/unbricking/index.md deleted file mode 100644 index 53793a06..00000000 --- a/src/docs/unbricking/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -next: false -prev: false ---- - -# Unbricking - -If your device's firmware got into a bad state (will not POST), you can try unbricking it. - -::: tip -Try performing a EC reset beforehand to see if your device can recover. -::: - -::: tip -If your device has a Ti50 chip and you didn't disable RO verification before flashing, follow [this guide](../firmware/ti50-ap-ro.md#recovering-a-device-bricked-due-to-ro-verification) to recover it. -::: - ---- - -Here is the following ways that you can unbrick your device: - -## [Unbricking with a ch341a USB programmer](unbrick-ch341a) - -## [Unbricking with a Suzy-Q cable](unbrick-suzyq) - -## [Unbricking with a flipper Zero](unbrick-flipper) - ---- - -Adapted from https://wiki.mrchromebox.tech/Unbricking diff --git a/src/docs/unbricking/unbrick-ch341a.md b/src/docs/unbricking/unbrick-ch341a.md deleted file mode 100644 index 0b36440b..00000000 --- a/src/docs/unbricking/unbrick-ch341a.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -next: false -prev: false ---- - -# Unbricking/Flashing with a ch341a USB programmer - -## Requirements - -::: tip -Most Skylake and older models (with a few exceptions) use a SOIC-8 flash chip which is easily clippable. Most if not all Kabylake/Apollolake and newer devices use a WSON-8 flash chip which can't be clipped, instead you need a WSON-8 probe. Check the part number of your flash chip to find the correct size needed. -::: - -1. A ChromeOS device -2. A device running Linux from which to run flashrom. For this guide, I will use a Ubuntu live USB. -3. A ch341a USB flash programmer -4. A 1.8v adapter - - ::: tip - The adapter is required for devices which use 1.8v flash chips. Some/Most Baytrail, Braswell, Skylake and many newer devices use a 1.8v flash chip. Baytrail is more reliable flashing at 3.3v though due to current leakage - ::: - -5. Either a SOIC-8 chip clip or a WSON-8 probe - - A ch341a programmer, 1.8v adapter, and a SOIC-8 clip are often bundled together at a lower cost, and if you are unsure if your device uses a 1.8v flash chip or a 3.3v one, it makes sense to have the adapter on hand if needed. You can look up the part number of your flash chip to determine which voltage it needs. - -## Hardware Disassembly - -While this is somewhat device-specific, the main points are the same: - -- Disconnect all external power -- Remove bottom cover (screws are often located under rubber feet or strips) - - Some Chromebooks open up through the back and some through the keyboard, and as mentioned in [Disabling write protect via Battery](../firmware/battery.html). On keyboard, you have to pry it out and remove a ribbon wire under the keyboard. -- Disconnect the internal battery (for Chromeboxes, disconnect the small CMOS battery) -- Locate the SPI flash chip - -::: danger -Most ChromeOS devices use a Winbond flash chip, though some use a compatible chip from another manufacturer, eg Gigadevices. It will be either an 8MB, 16MB, or 32MB chip, with the identifier W25Q64[xx] (8MB), W25Q128[xx] (16MB), or W25Q256[xx] (32MB) where [xx] is usually FV or DV. We do **not** want to touch the EC firmware chip, which is identified by W25X40[xx]. -::: - -::: warning -Unfortunately, many devices have the flash chip located on the top side of the main board, and require fully removing the main board in order to flash. -::: - -::: tip -Pin 1 of the flash chip will be notated by a dot/depression on the chip; be sure to align this with pin 1 on the chip clip wiring. -::: - -Googling should locate a disassembly guide for most models. If you can't find one for your exact model, try to find one for another model of the same manufacturer as the bottom cover (or keyboard) removal tends to be very similar. - -## Prepping to Flash - -Once you have your device disassembled and flash chip located, boot up the flashing environment. Most any Linux setup should do as long as either flashrom is available from the distro's software repositories, or it's 64-bit x86 (in which case you can download a statically compiled build of flashrom from mrchromebox.tech). This guide will use a Ubuntu live session booted from USB. - -So let's get to it: - -1. Boot your Linux environment (Ubuntu live USB or later recommended) -2. Connect to WiFi/internet -3. Open a (non-root) terminal/shell window, change to home directory - - `cd;` -4. Install flashrom via apt: - - `sudo apt update` - - `sudo apt install flashrom` -5. Assemble ch341a programmer, 1.8v adapter (if needed), and chip clip/wiring. Ensure that pin 1 is correct and consistent. - ![image](/ch341aunbrick/500px-Ch341a_annotated.png) -6. Connect the chip clip to the SPI flash chip, or get ready to hold down your WSON-8 probe, rubber bands can be used to hold it down while flashing, then connect the CH341a to the Linux host machine. Note the dot/depression indicating pin 1. - ![image](/ch341aunbrick/500px-SOIC-8_chip.jpg) -7. Test connectivity and ensure the flash chip is properly identified: - - `sudo flashrom -p ch341a_spi` - - Flashrom will produce output identifying the flash chip. If it doesn't, double check your connections to the programmer and the chip clip and retry. - - ![image](/ch341aunbrick/500px-Flashrom_chip_detect.png) - -8. Determine file to be flashed - - Depending on your desired use for the device, you have 3 options for flashing: - - The backup file of the stock firmware created by my Firmware Utility Script - - If using this, simply copy the file from USB into the home directory of the live USB user - - The custom UEFI firmware for the device - - If you were flashing the UEFI firmware when things went sideways, then that's the easiest way to proceed. You can download the UEFI firmware for your device by examining the [sources.sh file from the Firmware Utility Script GitHub repo](https://github.com/MrChromebox/scripts/blob/master/sources.sh). Simply concatenate the device-specific filename to the Full ROM base path: - - `wget ` - - Example for the Acer Chromebook 14 CB3-431 (EDGAR) - - `wget https://mrchromebox.tech/files/firmware/full_rom/coreboot_tiano-edgar-mrchromebox_20180827.rom` - - Do not forget to get the SHA1 file for verification: - - `wget https://mrchromebox.tech/files/firmware/full_rom/coreboot_tiano-edgar-mrchromebox_20180827.rom.sha1` - - Then verify the download: - - `sha1sum -c coreboot_tiano-edgar-mrchromebox_20180827.rom.sha1` - - The shellball firmware for the device - - As with the UEFI firmware above, the shellball ROM can be downloaded by concatenating the shellball base path with the device-specific filename: - - `wget /shellball..bin` - - Example for the Acer Chromebook 14 CB3-431 (EDGAR): - - `wget https://mrchromebox.tech/files/firmware/shellball/shellball.edgar.bin` - -::: tip -If you are not sure which file to use for your device / do not know your device's board name, you can reference [the supported devices page](supported-device.html). -::: - -### Persisting the board's Vital Product Data (VPD) - -The firmware in all ChromeOS devices contains a section (RO_VPD) which stores board-specific data, like the serial number, localization settings, and on many devices which have an Ethernet port, the LAN MAC address as well. When flashing via the Firmware Utility Script, the script will automatically extract this from the running firmware and inject it into the firmware to be flashed, so the device serial, LAN MAC address, etc are all maintained. Without this, the device will use a default/generic LAN MAC address set by coreboot. While not ideal, this is only really an issue if two or more of the same device are on the same LAN segment (or you are statically assigning IP addresses based on MAC). But for completeness, if flashing the UEFI firmware or shellball ROM, we'll extract the VPD (either from the board itself or a backup made by the script) and inject it into the firmware to be flashed. - -::: tip NOTE -You do not need to do this if flashing a stock firmware backup created by the Firmware Utility Script; that image already contains the VPD. -::: - -1. For both the options below, we'll need to use the cbfstool (coreboot filesystem) binary. -If you use Fedora or Ultramarine Linux, you can install the `cbfstool` package from the [Terra repository](https://terra.fyralabs.com/). Otherwise, we can download/extract it. - - `wget https://mrchromebox.tech/files/util/cbfstool.tar.gz && tar -zxf cbfstool.tar.gz` - - Option 1: Extract VPD from the firmware on device - - `sudo flashrom -p ch341a_spi -r badflash.rom` - - `./cbfstool badflash.rom read -r RO_VPD -f vpd.bin` - - Option 2: Extract VPD from stock firmware backup created by Firmware Utility Script (this assumes the file has been copied into working directory) - - `./cbfstool stock-firmware--.rom read -r RO_VPD -f vpd.bin` - - Then we inject the VPD into the firmware image to be flashed. - - `./cbfstool write -r RO_VPD -f vpd.bin` - -Now the firmware image is ready to be flashed, and will maintain the device's unique serial, LAN MAC address, etc. - -## Flashing Your Device - -Now that everything is prepped, time to flash the device. To be thorough, we'll perform a 2nd verification after flashing to ensure the integrity of the flashed firmware. - -1. Flash the firmware: - - If flashing your own backup created by the Firmware Utility Script (or any backup made from a live system), use - - `sudo flashrom -p ch341a_spi --ifd -i bios -w ` - - Otherwise use - - `sudo flashrom -p ch341a_spi -w ` - - Where \ is the name of your backup file, UEFI firmware file, or shellball firmware file. This will usually take 30s-90s to complete; flashrom will first read the flash chip, determine which sectors differ, erase those sectors, write the new data, then verify the data written. - -2. Verify the firmware - -Even though flashrom does this as part of the write process, verifying the entire flash chip is quick and an easy way to ensure everything went as it should: - -- As before, if flashing your own backup created by the Firmware Utility Script (or any backup made from a live system), use - - `sudo flashrom -p ch341a_spi --ifd -i bios -v ` -- Otherwise, use - - `sudo flashrom -p ch341a_spi -v ` - - Using the same filename as before. If the verification passes, then disconnect the CH341a from the host machine, and then remove the chip clip. - -### Clean Up - -Reassembly is the reverse of disassembly. Reconnect the internal battery and replace the bottom cover/keyboard. Flip over the device, connect external power, press the power button, and cross your fingers :) - ---- - -Adapted from https://wiki.mrchromebox.tech/Unbricking diff --git a/src/docs/unbricking/unbrick-flipper.md b/src/docs/unbricking/unbrick-flipper.md deleted file mode 100644 index 66b74cb9..00000000 --- a/src/docs/unbricking/unbrick-flipper.md +++ /dev/null @@ -1,59 +0,0 @@ -# Unbricking with a Flipper Zero - -Yes, this is possible. - -## Prerequisites - -- Your brain (please) -- A Flipper Zero with up-to-date firmware - - It doesn't matter if you are using stock or custom FW. -- A SOIC8 clip chip - - You can buy a cheap Chinese one [here](https://www.amazon.com/Ximimark-SOIC8-Socket-Adpter-Programmer/dp/B07BRSVRXV) -- A screwdriver / pry tool to open your Chromebook -- A copy of your stock ROM -- A way to copy files onto your Flipper Zero - -## Preparations - -1. Locate the SPI flash chip (See [Unbricking Page](./), under "Hardware Disassembly") -2. A understanding that this may not work on your system - -::: danger -**You will NOT be able to preserve the VPD using this method! This will not apply to you if flashing via your backup ROM.** Read the [Unbricking Page](./) for more information. -::: - -### Step 1 - -Obtain your stock ROM and rename it to `.bin`. For this guide, I will be using qFlipper. Your rom file should now look like this: - -![binexample](/flipperunbrick/stockfirmware.png) - -### Step 2 - -Locate the `spi_mem_manager` folder under the path `SD Card/apps_data/spi_mem_manager/`. Copy the .bin file to this newly made folder. - -::: tip -You might see a file size warning. It is safe to ignore it, only files that are 4GB+ will have issues transferring. -::: - -Your `spi_mem_manager/` folder should now look like this: - -![image](/flipperunbrick/spi_mem_manager.png) - -### Step 3 - -On your Flipper Zero, go to `Apps -> GPIO -> SPI Mem Manager -> Saved`. You should see your backup .bin. Verify that the file is there, then proceed to the next step. - -### Step 4 - -Connect your SOIC clip chip to your GPIO pins now. See the image below for the wire setup. - -![image](/flipperunbrick/GPIOSetup.png) - -### Step 5 - -Go back to `Apps -> GPIO -> SPI Mem Manager -> Saved -> Yourfilename.bin`. Open the file, then select the option to "Write". - -### Step 6 - -Assuming all went well, you should no longer have a bricked system. diff --git a/src/docs/unbricking/unbrick-suzyq.md b/src/docs/unbricking/unbrick-suzyq.md deleted file mode 100644 index 45acc013..00000000 --- a/src/docs/unbricking/unbrick-suzyq.md +++ /dev/null @@ -1,113 +0,0 @@ -# Unbricking/Flashing with a Suzy-Q cable - -## Requirements - -- A ChromeOS device with CCD (closed-case debugging) enabled on one of the USB-C ports. If your device uses CR50 for the firmware write protection, then it has CCD capability. - -::: tip NOTE -These instructions do not apply to any device which is locked/managed. Enterprise and/or EDU enrollment locks out CCD functionality completely. -::: - -- A USB-C debug cable ([aka Suzy-Q cable](https://www.sparkfun.com/products/retired/14746)) -- The device must have the CCD flags factory reset (as per instructions to [Disable write protect with a SuzyQable](../firmware/suzyq)), or the battery must be unplugged/disconnected from the mainboard. -- Another device running Linux, preferably a current Debian/Ubuntu-based distro - -## Hardware Disassembly - -As above, this is only needed if you failed to factory reset the CCD flags if you didnt follow the guide to [Disable write protect with a SuzyQable](../firmware/suzyq). While this is somewhat device-specific, the main points are the same: - -- Disconnect all external power -- Remove bottom cover (screws are often located under rubber feet or strips) - - Some Chromebooks open up through the back and some through the keyboard, and as mentioned in [Disabling write protect via Battery](../firmware/battery.html). On keyboard, you have to pry it out and remove a ribbon wire under the keyboard. -- Disconnect the internal battery - -## Prepping to Flash - -Most any 64-bit Debian/Ubuntu based distro should work here, but this guide will use a Ubuntu live session booted from USB (since its version of flashrom supports Suzy-Q flashing). - -Let's get to it: - -1. Boot your Linux environment (Ubuntu live USB or later recommended) -2. Connect to the internet -3. Open a (non-root) terminal/shell window, change to home directory - - `cd;` -4. Install flashrom via apt: - - `sudo apt update` - - `sudo apt install flashrom` -5. Connect the USB-C end of the Suzy-Q cable to the CCD port on your ChromeOS device (usually left USB-C port) and the USB-A end to your Linux device -6. Verify the cable is properly connected: - - `ls /dev/ttyUSB*` - - This command should return 3 items: `ttyUSB0`, `ttyUSB1`, and `ttyUSB2`. - - If not, then your cable is connected to the wrong port or is upside down; adjust and repeat comment until output is as expected -7. Set the CCD state to open: - - `echo "ccd open" | sudo tee -a /dev/ttyUSB0 > /dev/null` -8. Determine file to be flashed - - Depending on your desired use for the device, you have 3 options for flashing: - - The backup file of the stock firmware created by my Firmware Utility Script - - If using this, simply copy the file from USB into the home directory of the live USB user - - The custom UEFI firmware for the device - - If you were flashing the UEFI firmware when things went sideways, then that's the easiest way to proceed. You can download the UEFI firmware for your device by examining the [sources.sh file from the Firmware Utility Script GitHub repo](https://github.com/MrChromebox/scripts/blob/master/sources.sh). Simply concatenate the device-specific filename to the Full ROM base path: - - `wget ` - - Example for the Acer Chromebook 14 CB3-431 (EDGAR) - - `wget https://mrchromebox.tech/files/firmware/full_rom/coreboot_tiano-edgar-mrchromebox_20180827.rom` - - Do not forget to get the SHA1 file for verification: - - `wget https://mrchromebox.tech/files/firmware/full_rom/coreboot_tiano-edgar-mrchromebox_20180827.rom.sha1` - - Then verify the download: - - `sha1sum -c coreboot_tiano-edgar-mrchromebox_20180827.rom.sha1` - - The shellball firmware for the device - - As with the UEFI firmware above, the shellball ROM can be downloaded by concatenating the shellball base path with the device-specific filename: - - `wget /shellball..bin` - - Example for the Acer Chromebook 14 CB3-431 (EDGAR): - - `wget https://mrchromebox.tech/files/firmware/shellball/shellball.edgar.bin` - -::: tip -If you are not sure which file to use for your device / do not know your device's board name, you can reference [the supported devices page](supported-device.html). -::: - -::: tip -On Alderlake devices, you may not see the flash chip right away. In this case you need to do the following: -1. `echo "apshutdown" | sudo tee -a /dev/ttyUSB2` -2. Wait about 5 seconds -3. `echo "gpioset en_s5_rails 1" | sudo tee -a /dev/ttyUSB2` -4. In every flashrom command, replace `raiden_debug_spi:target=AP` with `raiden_debug_spi:target=AP,custom_rst=True` -::: - -### Persisting the board's Vital Product Data (VPD) - -The firmware in all ChromeOS devices contains a section (RO_VPD) which stores board-specific data, like the serial number, localization settings, and on many devices which have an Ethernet port, the LAN MAC address as well. When flashing via the Firmware Utility Script, the script will automatically extract this from the running firmware and inject it into the firmware to be flashed, so the device serial, LAN MAC address, etc are all maintained. Without this, the device will use a default/generic LAN MAC address set by coreboot. While not ideal, this is only really an issue if two or more of the same device are on the same LAN segment (or you are statically assigning IP addresses based on MAC). But for completeness, if flashing the UEFI firmware or shellball ROM, we'll extract the VPD (either from the board itself or a backup made by the script) and inject it into the firmware to be flashed. - -::: tip NOTE -You do not need to do this if flashing a stock firmware backup created by the Firmware Utility Script; that image already contains the VPD. -::: - -1. For both the options below, we'll need to use the cbfstool (coreboot filesystem) binary. -If you use Fedora or Ultramarine Linux, you can install the `cbfstool` package from the [Terra repository](https://terra.fyralabs.com/). Otherwise, we can download/extract it: - - `wget https://mrchromebox.tech/files/util/cbfstool.tar.gz && tar -zxf cbfstool.tar.gz` - - Option 1: Extract VPD from the firmware on device - - `sudo flashrom -p raiden_debug_spi:target=AP -r badflash.rom` - - `./cbfstool badflash.rom read -r RO_VPD -f vpd.bin` - - Option 2: Extract VPD from stock firmware backup created by Firmware Utility Script (this assumes the file has been copied into working directory) - - `./cbfstool stock-firmware--.rom read -r RO_VPD -f vpd.bin` - - Then we inject the VPD into the firmware image to be flashed. - - `./cbfstool write -r RO_VPD -f vpd.bin` - -Now the firmware image is ready to be flashed, and will maintain the device's unique serial, LAN MAC address, etc. - -## Flashing Your Device - -Now that everything is prepped, time to flash the device. - -1. Flash the firmware: - - If flashing your own backup created by the Firmware Utility Script (or any backup made from a live system), use - - `sudo flashrom -p raiden_debug_spi:target=AP -i SI_BIOS -w ` - - Otherwise, if using a UEFI Full ROM image or shellball/recovery-extracted image, use - - `sudo flashrom -p raiden_debug_spi:target=AP -w ` - - Where `` is the name of your backup file, UEFI firmware file, or shellball firmware file. This will usually take 3-5 mins to complete; flashrom will first read the flash chip, determine which sectors differ, erase those sectors, write the new data, then verify the data written. The initial CCD setup make take a minute or so and not show any progress. - -### Clean Up - -Once flashing is complete, disconnect the Suzy-Q cable. If the internal battery was not disconnected, the device will likely reboot as soon as flashing has completed. If the internal battery was disconnected, reconnect it and replace the bottom cover/keyboard. Flip over the device, connect external power, press the power button, and cross your fingers :) - ---- - -Adapted from https://wiki.mrchromebox.tech/Unbricking From 76b89b8fd1d603fe0db8cb34ab7e084e2e97d253 Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Mon, 12 May 2025 21:18:48 -0400 Subject: [PATCH 5/6] Add getting started section --- src/.vuepress/config.js | 15 +++++++++++- src/docs/getting-started/choose-os-fw.md | 30 +++++++++++++++++++++++ src/docs/getting-started/prerequisites.md | 20 +++++++++++++++ src/index.md | 2 +- 4 files changed, 65 insertions(+), 2 deletions(-) create mode 100644 src/docs/getting-started/choose-os-fw.md create mode 100644 src/docs/getting-started/prerequisites.md diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 75278f2a..224e4a15 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -41,7 +41,7 @@ export default { navbar: [ { text: 'Documentation', - link: '/docs/firmware/', + link: '/docs/getting-started/prerequisites.html', }, { text: 'Questions?', @@ -58,6 +58,19 @@ export default { text: 'Device Support Status', link: '/docs/devices', }, + { + text: "Getting Started", + children: [ + { + text: "Prerequisites", + link: "/docs/getting-started/prerequisites" + }, + { + text: "Choosing an OS and Boot Method", + link: "/docs/getting-started/choose-os-fw" + }, + ] + }, { text: "Installing an OS", link: "/docs/installing/", diff --git a/src/docs/getting-started/choose-os-fw.md b/src/docs/getting-started/choose-os-fw.md new file mode 100644 index 00000000..60c2a660 --- /dev/null +++ b/src/docs/getting-started/choose-os-fw.md @@ -0,0 +1,30 @@ +--- +prev: prerequisites +next: ../installing/ +--- + +# Choosing an OS and Boot Method + +## OS + +The OS you choose to install is mostly up to your preference, but there are a few compatibility notes. The TL;DR is: Windows and Linux work on most devices with most hardware supported, macOS is supported on a few devices with some hardware supported, and all ARM devices (not Intel/AMD) only support Linux. Check the [devices page](/docs/devices.html) for more detailed notes for each supported device. + +## Boot Method + +There are three different ways to boot an alternate OS on your device, each with pros and cons. + +### The Stock Bootloader (depthcharge) + +Since ChromeOS is Linux with a custom userspace, the stock bootloader (depthcharge) can load any Linux kernel. This method works on any device and does not modify the firmware at all. It is the only option on ARM devices since they do not have any custom firmware. If you choose method, refer to FyraLabs' [submarine guide](https://developer.fyralabs.com/submarine). + +### RW_LEGACY (AltFW) + +RW_LEGACY (later renamed to AltFW) is a feature in stock firmware that allows you to install a custom payload, either SeaBIOS or edk2, depending on the device. They provide either a standard BIOS or UEFI respectively. The RW_LEGACY firmware region can be written without disabling firmware write protection, which makes it fairly easy to install. RW_LEGACY is only supported on x86 devices (Intel and AMD). RW_LEGACY can only boot Linux and is mostly used to dualboot ChromeOS and Linux. Using RW_LEGACY with only Linux installed is not ideal as you have to deal with the limitations/bugs of the stock firmware, such as having to go through the developer mode screen on each boot, and having certain hardware not work, like touchscreens. If you choose this method, see the firmware flashing section below. + +### UEFI Full Rom Firmware + +UEFI Full Rom replaces the entire firmware with a custom build using upstream coreboot and edk2. It esentially turns your device into a regular pc with UEFI firmware. This method has the most risk as the entire firmware is being replaced. It also requires you to disable firmware write protection. Full Rom supports booting Windows, Linux, and macOS on supported devices. If you choose this method, see the firmware flashing section below. + +## Firmware Flashing + +If you chose to use RW_LEGACY or Full Rom firmware, you need to flash custom firmware before you can install your OS. Read the [MrChromebox](https://mrchromebox.tech) firmware flashing guide in order to flash the firmware on your device. Once you have completed the firmware installation, continue to [Installing an OS](/docs/installing/). diff --git a/src/docs/getting-started/prerequisites.md b/src/docs/getting-started/prerequisites.md new file mode 100644 index 00000000..4762f97a --- /dev/null +++ b/src/docs/getting-started/prerequisites.md @@ -0,0 +1,20 @@ +# Prerequisites + +:::warning +Before getting started, it is important to know that this isn't a simple, one-click process. You must be able to read and understand the documentation in order to successfully modify your device. There is a risk of bricking your device, losing data, etc. YOU ARE RESPONSIBLE FOR YOUR OWN DEVICE! +::: + +* A Chrome device you own (managed devices are unable to be modified) +* Some form of external storage, such as a USB flash drive or SD Card +* Some technical skills (installing an os, troubleshooting issues, etc) +* Patience +* Ideally, another computer to save yourself if something goes wrong +* Your device's HWID + +The device's HWID, often referred to as the board name, is used to identify your device and determine whether or not it is supported. Avoid using marketing names to identify your device, such as "HP Chromebook 14A", as they will usually lead to confusion since OEMs like to recycle the same name between many different devices. + +To find your HWID, either boot into [recovery mode](https://docs.mrchromebox.tech/docs/boot-modes/recovery.html) and look at the bottom of the screen, where it says MODEL, or open `chrome://system` in Chrome and search for `HWID`. + +:::tip +Most of the HWID can be ignored. For example, the most important part is `CAVE` in `CAVE D25-A4B-E4E-33C` and `HAYATO` in `HAYATO-YLRO C6B-C2C-F4F-V9P-G2I-A9Q`. +::: diff --git a/src/index.md b/src/index.md index 4c6bb66f..13ed53a3 100644 --- a/src/index.md +++ b/src/index.md @@ -6,7 +6,7 @@ heroImage: /chrome.svg heroImageDark: /chrome.svg actions: - text: Get Started - link: /docs/firmware/ + link: /docs/getting-started/prerequisites.html - text: Discuss on the forum link: https://forum.chrultrabook.com footerHtml: true From 8a928a963be339c4be635bcf8e707947b1bda01f Mon Sep 17 00:00:00 2001 From: WeirdTreeThing Date: Mon, 26 May 2025 16:49:44 -0400 Subject: [PATCH 6/6] Fix broken links --- src/docs/installing/installing-linux.md | 8 +------- src/docs/installing/known-issues.md | 4 ---- src/docs/installing/macos-firmware.md | 4 ++-- 3 files changed, 3 insertions(+), 13 deletions(-) diff --git a/src/docs/installing/installing-linux.md b/src/docs/installing/installing-linux.md index 10276dbe..2b9a1586 100644 --- a/src/docs/installing/installing-linux.md +++ b/src/docs/installing/installing-linux.md @@ -27,17 +27,11 @@ One possible workaround for Debian 12 (Bookworm) and Ubuntu is using a custom ke ## Installation -1. Create a bootable Linux USB. See [here](bootableusb.md) for a guide. +1. Create a bootable Linux USB. 2. Plug the USB Drive into the Chromebook. 3. Turn on the Chromebook, press ESC at the POST screen (when the coreboot logo appears), and select your USB to boot from. 4. Install as you would on any other computer. -::: tip NOTE -If you are using RW_LEGACY firmware, if after pressing Ctrl+L you reach the "Additional Firmware Menu" screen, you will need to press 2 to boot from a USB. - -See [this page](../firmware/flashing-firmware.md) for more information about RW_LEGACY booting. -::: - ## Fixing Audio You will likely have audio issues after installing Linux. Run the following script to fix them. diff --git a/src/docs/installing/known-issues.md b/src/docs/installing/known-issues.md index 21a8a739..2f63a84e 100644 --- a/src/docs/installing/known-issues.md +++ b/src/docs/installing/known-issues.md @@ -22,7 +22,3 @@ - No PCIe SD card reader support. - No fingerprint reader support. - Continuity features (AirDrop, Sidecar, etc). - -::: tip -For issues relating to hardware/firmware, see [this page](../firmware/known-issues.md). -::: diff --git a/src/docs/installing/macos-firmware.md b/src/docs/installing/macos-firmware.md index df07b38b..ae0385ff 100644 --- a/src/docs/installing/macos-firmware.md +++ b/src/docs/installing/macos-firmware.md @@ -12,7 +12,7 @@ Without the ME interface enabled, the following bugs can occur after waking from ### Building Manually -1. Follow the steps [here](../firmware/compiling-coreboot.md) to download the toolchain and build the firmware +1. Follow the steps [here](https://docs.mrchromebox.tech/docs/support/compiling.html) to download the toolchain and build the firmware - Continue these steps once `build-uefi.sh ` has been ran 2. Run `make menuconfig`. You will be greeted by a menu which looks like the following: @@ -30,4 +30,4 @@ Without the ME interface enabled, the following bugs can occur after waking from ## Flashing Firmware -Follow the steps [on this page](../firmware/manually-flashing.md) to flash the new firmware. +Follow the steps [on this page](https://docs.mrchromebox.tech/docs/firmware/manual-flashing.html) to flash the new firmware.