diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index f57d2150..575c16e5 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -76,7 +76,7 @@ export default { link: '/docs/firmware/known-issues', }, { - text: 'Enabling Developer Mode', + text: 'Developer Mode', link: '/docs/firmware/developer-mode', collapsible: true, children: [ diff --git a/src/docs/debugging/bugreport.md b/src/docs/debugging/bugreport.md index 39c8a12d..36a13e06 100644 --- a/src/docs/debugging/bugreport.md +++ b/src/docs/debugging/bugreport.md @@ -5,9 +5,9 @@ So you find a bug in one of our projects, and want to report it. It's faily simp 1. Use your brain (please) 2. Open a issue in our [bugtracker](https://github.com/chrultrabook/bugtracker/issues) 3. Be descriptive. Describe what the issue is, steps to reproduce, affected devices, etc etc. - - If you need help, a generic bug report template is available. + - If you need help, a generic bug report template is available. 4. Wait patiently for a contributor to fix the issue. - - Please keep in mind the majority of us contributors have other things going on in our lives. + - Please keep in mind the majority of us contributors have other things going on in our lives.
diff --git a/src/docs/debugging/contributing.md b/src/docs/debugging/contributing.md index 686bdb3c..da57fa8c 100644 --- a/src/docs/debugging/contributing.md +++ b/src/docs/debugging/contributing.md @@ -1,29 +1,28 @@ # Supporting the Docs Want to help support the docs? Well there's some ways you can help! -### Contributing via Issues +## Contributing via Issues Contributing via Issues is pretty simple but there are some rules: * Reserve the issues tab exclusively for documentation-related matters; refrain from discussing personal support issues or OS installation problems there. * When reporting a typo or suggesting better clarification, please specify the page where the issue is found. It would be helpful to avoid searching extensively for these problems. -### Contributing via PRs +## Contributing via PRs Some guidelines when contributing via PRs: * Use your brain (please). * Proofread your submissions. * Pull Requests may be rejected if they do not align with the docs's content or if they contain inaccurate information. Generally, we will provide reasons for rejection or request revisions. - * Additionally, it would be appreciated if you can provide sources for significant commits. This helps us verify the validity of the information you provide. + * Additionally, it would be appreciated if you can provide sources for significant commits. This helps us verify the validity of the information you provide. * Ensure that the pages adhere to the markdown style used in the docs. -### How to Contribute +## How to Contribute The best way to test your commits and ensure proper formatting is by forking the repository, making and testing changes locally, then contributing with a pull request. - -**Simple step-by-step guide** +### Simple step-by-step guide * Install NodeJS * You can download NodeJS from [the NodeJS download page](https://nodejs.org/en/download). @@ -36,7 +35,7 @@ The best way to test your commits and ensure proper formatting is by forking the Vuepress will automatically regenerate pages when you make changes. ::: -### Tips +## Tips Some tools that make contributing a bit easier: diff --git a/src/docs/debugging/index.md b/src/docs/debugging/index.md index 48e9706b..034334a7 100644 --- a/src/docs/debugging/index.md +++ b/src/docs/debugging/index.md @@ -11,8 +11,6 @@ prev: false * If you're experiencing issues with Windows, provide screenshots from Device Manager, Event Viewer, coredumps etc. * If you're experiencing issues with macOS, please ask for help using the [Chrultrabook Forums](https://forum.chrultrabook.com/). ---- - ## Firmware To debug firmware, you will need the following tools: @@ -23,33 +21,31 @@ To debug firmware, you will need the following tools: To dump the cbmem buffer, follow these steps: 1. Download the tar archive from MrChromebox's website: - * `wget https://mrchromebox.tech/files/util/cbmem.tar.gz` + - `wget https://mrchromebox.tech/files/util/cbmem.tar.gz` 2. Unzip the file and give the binary executable permissions: - * `tar -xf cbmem.tar.gz;rm cbmem.tar.gz;chmod +x cbmem` + - `tar -xf cbmem.tar.gz;rm cbmem.tar.gz;chmod +x cbmem` 3. Run `cbmem` and pipe its output to `cbmem.log` file: - * `sudo ./cbmem -1 > cbmem.log` + - `sudo ./cbmem -1 > cbmem.log` 4. Upload `cbmem.log` file for further analysis. To interface with the Embedded Controller: 1. Download the tar archive from MrChromebox's website: - * `wget https://mrchromebox.tech/files/util/ectool.tar.gz` + - `wget https://mrchromebox.tech/files/util/ectool.tar.gz` 2. Unzip the file and give the binary executable permissions: - * `tar -xf ectool.tar.gz;rm ectool.tar.gz;chmod +x ectool` + - `tar -xf ectool.tar.gz;rm ectool.tar.gz;chmod +x ectool` 3. Issue commands to EC by executing commands, for example setting the fan to 100%: - * `sudo ./ectool --name=cros_ec fanduty 100` - * Running `./ectool help` will provide you with a list of available commands, or you can [take a look at ectool's source code directly](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/util/ectool.c#63) - ---- + - `sudo ./ectool --name=cros_ec fanduty 100` + - Running `./ectool help` will provide you with a list of available commands, or you can [take a look at ectool's source code directly](https://chromium.googlesource.com/chromiumos/platform/ec/+/master/util/ectool.c#63) ## SuzyQ Debug Cable If you need to use SuzyQ, you can use `minicom` or `picocom` for example. It exposes three serial devices: 1. AP (CR50) console under /dev/ttyUSB0: - * `minicom -D /dev/ttyUSB0 -b 115200` + * `minicom -D /dev/ttyUSB0 -b 115200` 2. Coreboot/platform serial under /dev/ttyUSB1: - * `minicom -D /dev/ttyUSB1 -b 115200` + * `minicom -D /dev/ttyUSB1 -b 115200` 3. Embedded Controller console under /dev/ttyUSB2 - * `minicom -D /dev/ttyUSB2 -b 115200` + * `minicom -D /dev/ttyUSB2 -b 115200` * Platform serial can be used to debug the payload or kernel, but you need to re-compile coreboot with following configuration options enabled: `CONSOLE_SERIAL=y` @@ -57,14 +53,12 @@ If you need to use SuzyQ, you can use `minicom` or `picocom` for example. It exp * To use SuzyQ as platform debugger, you will also need to append the following to your kernel commandline: `loglevel=15 console=ttyS4,115200n8` ---- - ## ACPI and Linux kernelspace 1. Download our debugging script. - * `cd ~/Desktop;wget https://raw.githubusercontent.com/chrultrabook/linux-tools/main/debugging.sh` + * `cd ~/Desktop;wget https://raw.githubusercontent.com/chrultrabook/linux-tools/main/debugging.sh` - It will dump: +It will dump: * ACPI tables from sysfs (`/sys/firmware/acpi/*`) * DMI information (`dmidecode`) * Coreboot buffer (`cbmem`) @@ -78,58 +72,54 @@ If you need to use SuzyQ, you can use `minicom` or `picocom` for example. It exp 2. Run it: `chmod +x debugging.sh;./debugging.sh` 3. Upload this file if you need help with troubleshooting. - * Remember to remove WiFi information from dmesg to protect your privacy. - ---- + * Remember to remove WiFi information from dmesg to protect your privacy. ## flashrom Flashrom is used to read and write from the SPI flash ### Read flash: - * `sudo flashrom -p -r ` - * Example: - * `sudo flashrom -p internal -r backup.rom` +* `sudo flashrom -p -r ` +* Example: + * `sudo flashrom -p internal -r backup.rom` ::: danger If you have an Intel Chromebook, you will need to add `--ifd -i bios` if you want to write to the flash or else flashrom will fail. ::: ### Write flash: - * `sudo flashrom -p -w ` - * Intel Example: - * `sudo flashrom -p internal --ifd -i bios -w stock.rom` - * AMD Example: - * `sudo flashrom -p internal -w stock.rom` +* `sudo flashrom -p -w ` +* Intel Example: + * `sudo flashrom -p internal --ifd -i bios -w stock.rom` +* AMD Example: + * `sudo flashrom -p internal -w stock.rom` ### Write protection: View status: - * `sudo flashrom -p internal --wp-status` +* `sudo flashrom -p internal --wp-status` Enable WP: - * `sudo flashrom -p internal --wp-enable` +* `sudo flashrom -p internal --wp-enable` Disable WP: - * `sudo flashrom -p internal --wp-disable` +* `sudo flashrom -p internal --wp-disable` Clear WP range: - * `sudo flashrom -p internal --wp-range 0 0` +* `sudo flashrom -p internal --wp-range 0 0` Common programmers: * `internal`: Use this when you run flashrom on the chromebook you want to program. * `ch341a_spi`: Use this when you use a ch341a external programmer. * `raiden_debug_spi:target=AP`: Use then when you want to flash using a Suzy-Q cable. ---- - ## gsctool gsctool is used to communicate with the GSC (Google Security Chip) from ChromeOS and is usually used to unlock CCD without removing the back of the Chromebook. View status: - * `sudo gsctool -a -I` +* `sudo gsctool -a -I` Unlock CCD: - * `sudo gsctool -a -o` - * This will prompt you multiple times to press the power button, on the last time, the device will reboot back into verified mode +* `sudo gsctool -a -o` +* This will prompt you multiple times to press the power button, on the last time, the device will reboot back into verified mode diff --git a/src/docs/faq.md b/src/docs/faq.md index 83d32e2f..2b33bc96 100644 --- a/src/docs/faq.md +++ b/src/docs/faq.md @@ -14,7 +14,7 @@ Please read this page before asking a question in the Discord. Your help request * No. Only the Linux drivers are free. #### How come audio isn't working on Ubuntu / Ubuntu forks? -* Ubuntu and Ubuntu-based distros may have issues, try swtiching to another distro. +* Ubuntu and Ubuntu-based distros may have issues, try switching to another distro. #### What Linux distros are recommended? * See [this page](installing/installing-linux.md). @@ -82,7 +82,7 @@ Please read this page before asking a question in the Discord. Your help request * Then exit developer mode by running `sudo crossystem disable_dev_request=1; reboot` #### Can I modify the fan speed? -* Yes, using ectool. On windows this is installed along with the [`crosec` driver](https://github.com/coolstar/driverinstallers/raw/master/crosec/crosec.2.0.2-installer.exe) (will be located at `C:\Program Files\crosec\ectool.exe`), on linux you can grab it from [here](https://tree123.org/files/utils/ectool). To set the fan to auto, run: `ectool autofanctrl`. To specify a percentage, run `ectool fanduty [0-100]`. +* Yes, using ectool. To set the fan to auto, run: `ectool autofanctrl`. To specify a percentage, run `ectool fanduty [0-100]`. #### Can I overclock the fan? * No. diff --git a/src/docs/firmware/about.md b/src/docs/firmware/about.md index 605e4e42..6f49430d 100644 --- a/src/docs/firmware/about.md +++ b/src/docs/firmware/about.md @@ -4,7 +4,7 @@ next: flashing-firmware --- # Types of Firmware -### RW_LEGACY +## RW_LEGACY * Updates/replaces the stock RW_LEGAGY 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 @@ -17,7 +17,7 @@ next: flashing-firmware 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 +## (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 diff --git a/src/docs/firmware/battery.md b/src/docs/firmware/battery.md index e7e2209a..0d0e7883 100644 --- a/src/docs/firmware/battery.md +++ b/src/docs/firmware/battery.md @@ -18,7 +18,7 @@ Screws may be underneath "feet", or the material that keeps the Chromebook from ::: 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. + * 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. @@ -30,5 +30,5 @@ 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) + * If you removed the keyboard, make sure to reattach it for this step. +3. Contmnue to [Flashing Firmware](flashing-firmware.md) diff --git a/src/docs/firmware/compiling-coreboot.md b/src/docs/firmware/compiling-coreboot.md index 9e0d1703..a7a8b19e 100644 --- a/src/docs/firmware/compiling-coreboot.md +++ b/src/docs/firmware/compiling-coreboot.md @@ -7,20 +7,20 @@ Building and flashing your own firmware has the potential to brick your device. ::: 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` + * 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` + * `git clone https://github.com/mrchromebox/coreboot.git` 3. **`cd` to the coreboot folder, then build the coreboot toolchain** - * `make crossgcc-i386 CPUS=$(nproc)` + * `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`) + * Common changes include: + * Replacing the default logo (`Documentation/coreboot_logo.bmp`) + * Changing version string (`CONFIG_LOCALVERSION`) 5. **Build the ROM** - * create build dir: `mkdir -p ~/dev/firmware` - * `./build-uefi.sh ` - * For example, `./build-uefi.sh careena` - * Roms will be stored in `~/dev/firmware` + * create build dir: `mkdir -p ~/dev/firmware` + * `./build-uefi.sh ` + * For example, `./build-uefi.sh careena` + * ROMs will be stored in `~/dev/firmware` 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 index 88fad58e..bd9685f3 100644 --- a/src/docs/firmware/developer-mode.md +++ b/src/docs/firmware/developer-mode.md @@ -2,9 +2,9 @@ prev: known-issues next: write-protect --- -# Enabling Developer Mode +# 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! +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. @@ -14,24 +14,24 @@ Doing this will wipe **all** user data! Make backups if needed before proceeding The battery must be plugged in while enabling developer mode. ::: -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. +## Enabling Developer Mode -1. Enter [recovery mode](recovery-mode.md). +First, enter [recovery mode](recovery-mode.md). Then proceed with the following instructions for your device. -#### Chromebooks/Chromeboxes +### Chromebooks/Chromeboxes -1. Press `CTRL` + `D` at the same time. This should bring up a warning asking for confirmation for either "Turn OS Verification OFF" or "Enable Developer Mode". +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. +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. +3. Press Ctrl+D to boot from internal disk. 4. Setup the system like normal, but **do not enable debugging features**. -#### Tablets +### 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. +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 index 6cdc4494..f679670e 100644 --- a/src/docs/firmware/flashing-firmware.md +++ b/src/docs/firmware/flashing-firmware.md @@ -15,9 +15,9 @@ To convert your machine from Google's firmware and ChromeOS to Coreboot and AltO 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` + * 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. @@ -30,14 +30,16 @@ Otherwise, shutdown without worry. If you unplugged the battery to [disable write protect](battery.md), you can plug it back in now. All subsequent flashing won't require it from now on. ::: -**UEFI** +## 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** +### RW_LEGACY -On the developer mode boot screen, press `CTRL` + `L`. If a selection appears, pick "Tianocore". +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`), enter `2` to boot from USB or `0` to boot from internal storage (where you installed your Linux OS). +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`. \ No newline at end of file +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 index eb58fa12..c52ff3e3 100644 --- a/src/docs/firmware/index.md +++ b/src/docs/firmware/index.md @@ -13,6 +13,7 @@ Do not continue if your device is currently owned or enrolled by a organization, ::: ## Prerequisites + * Know your hardware * Your CPU model and generation * Your storage devices (HDD/SSD, eMMC, NVMe, etc.) @@ -24,17 +25,16 @@ Do not continue if your device is currently owned or enrolled by a organization, * 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 +::: tip NOTE Only x86_64 devices are currently supported. ::: ::: tip -If you only have one device. Please be sure to [setup a usb with your OS to install](ventoy.md) before flashing. +If you only have one device, please be sure to [setup a usb with your OS to install](ventoy.md) before flashing. ::: ------- +## Asking for help properly -### Asking for help properly: If you are facing a issue, please read the [FAQ](../faq.md) first. ::: tip diff --git a/src/docs/firmware/known-issues.md b/src/docs/firmware/known-issues.md index f21a6d59..72144cee 100644 --- a/src/docs/firmware/known-issues.md +++ b/src/docs/firmware/known-issues.md @@ -14,9 +14,8 @@ You should avoid buying any devices in this list. * 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. diff --git a/src/docs/firmware/manually-flashing.md b/src/docs/firmware/manually-flashing.md index 0f72d456..35876a49 100644 --- a/src/docs/firmware/manually-flashing.md +++ b/src/docs/firmware/manually-flashing.md @@ -6,14 +6,14 @@ Flashing your own firmware has the potential to brick your device. Do not do thi 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. - * `cd; curl -LO https://tree123.org/chrultrabook/utils/flashrom-libpci38; chmod +x flashrom-libpci38` + * `cd; curl -LO https://tree123.org/chrultrabook/utils/flashrom-libpci38; chmod +x flashrom-libpci38` 3. Flash your custom ROM - * Backup your current rom, just in case things go wrong: `./flashrom-libpci38 -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-libpci38 -p internal -w firmware.rom` + * Backup your current rom, just in case things go wrong: `./flashrom-libpci38 -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-libpci38 -p internal -w firmware.rom` 4. Reboot - * Assuming it said `success` on all checks, reboot. + * Assuming it said `success` on all checks, reboot. - ::: danger - Do not reboot if any of the checks failed. - ::: +::: 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 index f7a8c0ba..fca8ab6b 100644 --- a/src/docs/firmware/recovery-mode.md +++ b/src/docs/firmware/recovery-mode.md @@ -4,23 +4,23 @@ next: false --- # Recovery Mode -::: tip -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/). -::: +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. ::: -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. -### Entering Recovery Mode -
+## Entering Recovery Mode -#### Chromebooks +### 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. @@ -28,7 +28,7 @@ Press `ESC` + `Refresh` (arrow icon), + `Power` at the same time. This should br -#### Chromeboxes +### Chromeboxes Find the recovery button hole. A reference of what to look for is below. @@ -37,7 +37,7 @@ Find the recovery button hole. A reference of what to look for is below. 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 +### Tablets Hold down `Volume Up` + `Volume Down` + `Power` for 10 seconds, then release. This should bring your system into recovery mode. diff --git a/src/docs/firmware/suzyq.md b/src/docs/firmware/suzyq.md index db0c395a..cbf30325 100644 --- a/src/docs/firmware/suzyq.md +++ b/src/docs/firmware/suzyq.md @@ -28,8 +28,8 @@ This method requires a SuzyQable, a chromeOS debug cable. 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` + - `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`. diff --git a/src/docs/firmware/system-info.md b/src/docs/firmware/system-info.md index 8f32976f..b1f12130 100644 --- a/src/docs/firmware/system-info.md +++ b/src/docs/firmware/system-info.md @@ -12,8 +12,9 @@ Some of the following commands require [Developer mode](developer-mode). 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 `Control` + `Alt` + `T` +### 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: @@ -23,8 +24,6 @@ You should now see one of three possible outputs: 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. @@ -32,29 +31,25 @@ The board name is the special name for your device which determines if it is sup ### How to find your board name #### Developer Mode -1. Open VT-2 (`ctrl` + `alt` + `f2` (right arrow)). -2. Login as `chronos`. -3. Type `sudo crossystem hwid` and press enter. +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. +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 a crosh terminal by pressing `Control` + `Alt` + `T` -2. Type `shell` and press enter -3. Type `cat /proc/cpuinfo | grep "model name"` and press enter +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` @@ -63,4 +58,4 @@ Example output: `model name : Intel(R) Celeron(R) CPU N3350 @ 1.10GHz` 1. Find your board name using the steps above (ex: `SNAPPY`). 2. Go to the [Supported Devices Page](supported-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. +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/updating-firmware.md b/src/docs/firmware/updating-firmware.md index bd43cc52..aab444e1 100644 --- a/src/docs/firmware/updating-firmware.md +++ b/src/docs/firmware/updating-firmware.md @@ -1,7 +1,7 @@ # Updating Custom Firmware -::: tip -These steps require linux. **Firmware Cannot be flashed from Windows**. Do not try to flash from a virtual machine such as wsl. If you are using Windows, boot a live linux iso, such as Ubuntu or Fedora Workstation. +::: 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 @@ -9,7 +9,7 @@ curl is not installed by default for Ubuntu / Ubuntu distros. To install it, run ::: 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. + * 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 diff --git a/src/docs/firmware/ventoy.md b/src/docs/firmware/ventoy.md index 93a547d0..5ab553f7 100644 --- a/src/docs/firmware/ventoy.md +++ b/src/docs/firmware/ventoy.md @@ -1,18 +1,22 @@ # Installing Ventoy to a USB drive with chromeOS + Ventoy is a useful tool that allows you to have multiple OS installer images on a single drive. It is also the only way to properly create an installer for Windows using chromeOS. ## Backing up your drive + Before we begin, be sure to backup any data that may be on your USB drive as it will be erased during this process. ## Downloading Ventoy + Grab the latest Ventoy release from [GitHub](https://github.com/ventoy/Ventoy/releases). Be sure to get the Linux version. ## Extracting Ventoy -Open VT-2 by pressing `Ctrl` + `Alt` + `F2` (Right arrow/Refresh) and run the following commands as root: + +Open VT-2 by pressing Ctrl + Alt + 🡢 (F2) and run the following commands as root: 1. `cd /usr/local` 2. `tar xf /home/chronos/user/Downloads/ventoy--linux.tar.gz` @@ -22,21 +26,23 @@ Open VT-2 by pressing `Ctrl` + `Alt` + `F2` (Right arrow/Refresh) and run the fo On commands 2 and 3, after typing `ventoy`, you can press tab to fill in the rest of the filename automatically. ::: -You can then run `ls` to verify you have the correct files, it should look something like this +You can then run `ls` to verify you have the correct files, it should look something like this: ## Starting Ventoy + Run the following command to start the Ventoy Web GUI: * `./VentoyWeb.sh` -Next, switch back to VT-1 by pressing `Ctrl` + `Alt` + `F1` (Left arrow) and open `http://localhost:24680` in Chrome. +Next, switch back to VT-1 by pressing Ctrl + Alt + 🡠 (F1)and open `http://localhost:24680` in Chrome. -You should see this on your screen now +You should see this on your screen now: -## Installing Ventoy +## Installing Ventoy to USB + Plug in your USB drive and click the green circle to refresh devices. You should see your USB drive get detected. Now click options, then Partition Style, then choose GPT. @@ -44,6 +50,7 @@ Plug in your USB drive and click the green circle to refresh devices. You should Once you have done that and your drive is detected, click on Install and click Ok twice when prompted and again once the installation has completed. Once installation is complete, unplug and plug back in your USB drive. ## Adding OS images + Download an image of any OS you want. For Windows we recommend that you only use official ISOs from Microsoft. Open Files and click on your USB drive, you should then see a device named "Ventoy". diff --git a/src/docs/firmware/write-protect.md b/src/docs/firmware/write-protect.md index eee4b4e2..8409f522 100644 --- a/src/docs/firmware/write-protect.md +++ b/src/docs/firmware/write-protect.md @@ -11,7 +11,7 @@ You do not have to disable write protect if flashing [RW_Legacy](about.md#rw_leg 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. 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 Debug)) +* 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)) diff --git a/src/docs/installing/bootableusb.md b/src/docs/installing/bootableusb.md index d95fd135..bc4c7097 100644 --- a/src/docs/installing/bootableusb.md +++ b/src/docs/installing/bootableusb.md @@ -1,52 +1,53 @@ # Making a Bootable USB ::: danger -Flashing Ventoy or ISO's to an external drive will **wipe all data** on said drive. Back up anything if you need to. +Flashing Ventoy or ISOs to an external drive will **wipe all data** on said drive. Back up anything if you need to. ::: ## Prerequisites + 1. Another PC or laptop with at least 8GB storage 2. An internet connection 3. An external drive like a USB drive or SD card that is at least 8GB. ## Downloading a ISO + 1. Determine what OS you want. - - For Linux, keep in mind Ubuntu and any derivatives **may have issues**. - - For Windows, keep in mind only official versions of Windows 10 and newer are supported. + * For Linux, keep in mind Ubuntu and Ubuntu-based derivatives **are not supported**. + * For Windows, keep in mind only official versions of Windows 10 and newer are supported. 2. Place the ISO in a safe place. -### Flashing using Rufus (Windows) +## Flashing using Rufus (Windows) + +For this guide, we will be using Rufus to create our bootable USB. Rufus is a useful tool that allows you to flash ISOs to an external drive. -For this guide, we will be using Rufus to create our bootable USB. -Rufus is a useful tool that allows you to flash ISO's to an external drive. 1. Download Rufus from [here](https://rufus.ie/en/). The standard Windows x64 version will do. - ![image](/rufus.png) + ![image](/rufus.png) 2. Plug in your external drive. 3. Locate and launch Rufus. It should ask you to launch with administrator privileges, select YES. -4. On the right hand side, there should be a button with the words `SELECT` on it. -5. A File Explorer window should pop up, find your ISO of choice, then click `Open`. -6. Click `Start`. The default options should work just fine. -7. Wait for the green bar to say `READY`, then click `Close` and eject your newly made external drive. +4. Press the "SELECT" button on the right-hand side. +5. A File Explorer window should pop up, find your ISO of choice, then click "Open". +6. Click "Start". The default options should work just fine. +7. Wait for the green bar to say "READY", then click "Close" and eject your newly made external drive. 8. Profit -### Flashing using Ventoy (Windows/Linux/macOS) +## Flashing using Ventoy (Windows/Linux/macOS) For this guide, we will be using Ventoy to create our bootable USB. Ventoy allows you to boot multiple ISO's from a single drive. 1. Download and extract the latest version from [Github](https://www.ventoy.net/en/download.html). - - Download the respective file for your platform. - - - ![image](/ventoy/download-alt.png) + * Download the respective file for your platform. + ![image](/ventoy/download-alt.png) 2. Run `Ventoy2Disk.exe` for Windows or `VentoyGUI.x86_64` for Linux. - - Make sure to allow administrator privilages when prompted. + * Make sure to allow administrator privilages when prompted. 3. Plug in your external drive and click the green circle to refresh devices. It should pick up your external drive. -4. Click Options > Partition Style and select `GPT`. -5. Once you have done Step 4, click `Install` and click ok twice to start the install. -6. Open your Files App and find a drive thats labed as `Ventoy`. +4. Click Options > Partition Style and select "GPT". +5. Once you have done Step 4, click "Install" and click ok twice to start the install. +6. Open your Files App and find a drive that's labeled as "Ventoy". 7. Copy the ISO you downloaded into that drive, after that eject it. 8. Profit diff --git a/src/docs/installing/ectool.md b/src/docs/installing/ectool.md index 42a9f3cd..1ac613b2 100644 --- a/src/docs/installing/ectool.md +++ b/src/docs/installing/ectool.md @@ -2,8 +2,11 @@ `ectool` is a utility that is used to interface with the ChromeOS Embedded Controller. It is used to communicate with the embedded controller from userspace and vice versa. -## Uses +## Installing Ectool + +If you use Fedora or Ultramarine Linux, you can install the `chromium-ectool` package from the [Terra repository](https://terra.fyralabs.com). Otherwise, you can download `ectool` for Linux from [here](https://tree123.org/files/utils/ectool). For Windows users, `ectool` is installed when you install CoolStar's Chrome EC driver and is located in `C:\Program Files\crosec\ectool.exe`. +## Uses :::tip Run `ectool help` for a full list of commands. @@ -11,6 +14,6 @@ Run `ectool help` for a full list of commands. Some common uses of `ectool` include: -- Accessing the EC console: `ectool console` -- Controlling the fan with `ectool fanduty ` -- Set the keyboard backlight in devices that have it: `ectool pwmsetkblight ` +* Accessing the EC console: `ectool console` +* Controlling the fan with `ectool fanduty ` +* Set the keyboard backlight in devices that have it: `ectool pwmsetkblight ` diff --git a/src/docs/installing/index.md b/src/docs/installing/index.md index 451b6b8a..987c95e1 100644 --- a/src/docs/installing/index.md +++ b/src/docs/installing/index.md @@ -27,8 +27,6 @@ Be sure to check the [supported devices page](../firmware/supported-devices.md) ¹Some devices such as CELES need workarounds. Refer to the [known issues page](known-issues.html) to check whether you need patches. ---- - ## Linux ### Pros: @@ -41,16 +39,14 @@ Be sure to check the [supported devices page](../firmware/supported-devices.md) * Requires some work on the end user (running audio script, configuring keyboard mapping) * AVS and SOF users experience instability at times - ::: warning - Ubuntu and Ubuntu-based distributions **may have issues** and are **not supported**. - ::: + ::: warning + Ubuntu and Ubuntu-based distributions **may have issues** and are **not supported**. + :::
### [Installing Linux →](installing-linux.md) ---- - ## macOS ### Pros: diff --git a/src/docs/installing/installing-linux.md b/src/docs/installing/installing-linux.md index 8c55172c..7906758f 100644 --- a/src/docs/installing/installing-linux.md +++ b/src/docs/installing/installing-linux.md @@ -26,37 +26,31 @@ Debian versions older than Debian 12 (Bookworm) are **not supported**. Debian 12 * openSUSE Tumbleweed * Debian 12 (Bookworm) ---- - ## Installation 1. Create a bootable Linux USB. See [here](bootableusb.md) for a guide. 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. +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 -If you are using `RW_LEGACY` firmware, if after pressing `CTRL` + `L` you reach the `Additional Firmware Menu` white screen, you will need to press `2` to boot from a USB. +::: 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. -### Fixing Audio +#### Prerequisites +* Python 3.10 or newer +* Git ::: danger Using AVS on a device with max98357a will blow your speakers. You have been warned. ::: -#### Prerequisites -- Python 3.10 or newer -- Git - #### How to run the script 1. Open a terminal. 2. `git clone https://github.com/WeirdTreeThing/chromebook-linux-audio.git` diff --git a/src/docs/installing/installing-macos.md b/src/docs/installing/installing-macos.md index 36d98cd9..4324df77 100644 --- a/src/docs/installing/installing-macos.md +++ b/src/docs/installing/installing-macos.md @@ -8,12 +8,12 @@ Before we begin, it's important to know whether your Chromebook is even supporte **You will also need:** * Patience - * This is not a one click setup thing. It usually takes one or more weeks to have a stable hack. + * This is not a one click setup thing. It usually takes one or more weeks to have a stable hack. * A USB drive - * 4 gigabytes or more for a online installer. - * 32 gigabytes or more for offline installer. + * 4 gigabytes or more for a online installer. + * 32 gigabytes or more for offline installer. * The ability to use a command line - * We won't help you if you don't know how to `cd` to a directory. + * We won't help you if you don't know how to `cd` to a directory. ## Tested Devices @@ -39,17 +39,17 @@ This list is incomplete. Feel free to improve it. **The following devices have dedicated guides written for them:** * [ChromebookOSX](https://github.com/meghan06/ChromebookOSX): - * Asus C425 (LEONA) - * Asus C434 (SHYVANA) - * Asus C433 (SHYVANA) + * Asus C425 (LEONA) + * Asus C434 (SHYVANA) + * Asus C433 (SHYVANA) * [PixelbookOSX](https://github.com/olm3ca/PixelbookOSX): - * Google Pixelbook (2017) (EVE) - * Google Pixel Slate (NOCTURNE) - * Google Pixelbook Go (2019) (ATLAS) + * Google Pixelbook (2017) (EVE) + * Google Pixel Slate (NOCTURNE) + * Google Pixelbook Go (2019) (ATLAS) * [macOS-Dragonair](https://github.com/mine-man3000/macOS-Dragonair): - * HP Chromebook x360 14c (DRAGONAIR) + * HP Chromebook x360 14c (DRAGONAIR) * [LuluMacOS](https://isi95010.github.io/LuluMacOS/) * Dell Chromebook 13 7310 (LULU) @@ -69,23 +69,23 @@ Start by following the [Dortania guide](https://dortania.github.io/OpenCore-Inst Amber Lake Chromebooks should follow config.plist setup for Kaby Lake. Add the following SSDTs, kexts and modifications as needed: -#### Config.plist Fixes +### config.plist Fixes - Disable `Booter->Quirks->DevirtualiseMmio`: Fixes NVRAM and other runtime EFI services -#### SSDTs and ACPI Fixes: +### SSDTs and ACPI Fixes: - [croscorebootpatch](https://github.com/meghan06/croscorebootpatch): Fixes freeze during boot when using coreboot 4.20 and newer. Not needed when custom rom is used. - [Keyboard Map](https://github.com/1Revenger1/Acer-Spin-713-Hackintosh/blob/main/src/ACPI/SSDT-ChromeKeys.dsl): Maps FNx keys to ChromeOS mapping. This is an example, you may need to do your own mapping. - - Will need to be compiled with either `iASL` or `MaciASL`. + - Will need to be compiled with either `iASL` or `MaciASL`. - [Fake Ambient Light Sensor](https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/AcpiSamples/Source/SSDT-ALS0.dsl): Creates a fake ambient light sensor which is needed by macOS to recognize the keyboard backlight. - - This is only needed if your device does not come with a light sensor. - - A pre-compiled version comes in OpenCore's release zip under `Docs/AcpiSamples/Binaries/SSDT-ASL0.aml` + - This is only needed if your device does not come with a light sensor. + - A pre-compiled version comes in OpenCore's release zip under `Docs/AcpiSamples/Binaries/SSDT-ASL0.aml` -#### Kexts +### Kexts - [EmeraldSDHC.kext](https://github.com/acidanthera/EmeraldSDHC/releases): eMMC driver - [VoodooPS2.kext](https://github.com/1Revenger1/VoodooPS2/releases): Fork of Acidanthera's VoodooPS2 which allows mapping keyboard brightness and other useful keys - [CrosEC.kext](https://github.com/1Revenger1/CrosEC/releases): Adds keyboard brightness, tablet mode, and other functionality -### Snapshot (cmd + r) or (ctrl + r) your `config.plist` after making modifications. +#### Snapshot (cmd + r) or (ctrl + r) your `config.plist` after making modifications. ::: danger If you dualboot with the SSDTs mentioned above, you might run into issues on other OSes. An `OSI_` check is not present in these SSDTs. diff --git a/src/docs/installing/installing-windows.md b/src/docs/installing/installing-windows.md index 0d9775fb..6c0ac89b 100644 --- a/src/docs/installing/installing-windows.md +++ b/src/docs/installing/installing-windows.md @@ -20,21 +20,19 @@ If you want to create a Windows installer from ChromeOS, see the [Installing Ven 2. Bypassing Windows 11 installation checks: - 1. At the Windows installer, select "Repair my Computer". - 2. Select "Command prompt". (May be hidden under an advanced section) - 2. Type in `regedit` and press Enter - 3. Navigate to `HKEY_LOCAL_MACHINE\SYSTEM\Setup` - 4. Right click `Setup` and create a new `Key` called `LabConfig` - 5. Right click `LabConfig` and create new `DWORD` (32-bit) called `BypassSecureBootCheck` and set its value to 1 - 6. Right click `LabConfig` and create new `DWORD` (32-bit) called `BypassTPMCheck` and set its value to 1 - 7. Close Registry Editor. - 8. Run `setup` in the command prompt. - 9. Install Windows as you would normally. + 1. At the Windows installer, select "Repair my Computer". + 2. Select "Command prompt". (May be hidden under an advanced section) + 3. Type in `regedit` and press Enter + 4. Navigate to `HKEY_LOCAL_MACHINE\SYSTEM\Setup` + 5. Right click `Setup` and create a new `Key` called `LabConfig` + 6. Right click `LabConfig` and create new `DWORD` (32-bit) called `BypassSecureBootCheck` and set its value to 1 + 7. Right click `LabConfig` and create new `DWORD` (32-bit) called `BypassTPMCheck` and set its value to 1 + 8. Close Registry Editor. + 9. Run `setup` in the command prompt. + 10. Install Windows as you would normally. -4. Install drivers: - - See [Coolstar's Windows Install Helper](https://coolstar.org/chromebook/windows-install.html) for drivers. Some of the drivers may be paid. - ---- +3. Install drivers: + - See [Coolstar's Windows Install Helper](https://coolstar.org/chromebook/windows-install.html) for drivers. Some of the drivers may be paid. ## Installing `.cab` drivers Cab drivers are a little weird, but they're easy to install. @@ -46,14 +44,10 @@ Cab drivers are a little weird, but they're easy to install. 5. Right click on all the `.inf` files, and select install. 6. Reboot. ---- - ## Paid Drivers Please see [CoolStar's driver portal](https://coolstar.org/chromebook/driverlicense/login.html) for a step by step tutorial on purchasing drivers. ---- - ### What drivers do I need to buy? | CPU Generation | Paid Drivers | Notes | diff --git a/src/docs/installing/macos-firmware.md b/src/docs/installing/macos-firmware.md index 88bd8d42..6dbcae37 100644 --- a/src/docs/installing/macos-firmware.md +++ b/src/docs/installing/macos-firmware.md @@ -2,10 +2,10 @@ It is recommended to flash coreboot with the Intel Management Engine interface enabled to prevent bugs after waking from sleep. Without the ME interface enabled, the following bugs can occur after waking from sleep: -- Blank Electron / Chromium apps -- Buggy video playback in web browsers like Firefox or Safari -- Display/Wallpaper settings in SysPref/SysSettings -- Logging out freezes your system +* Blank Electron / Chromium apps +* Buggy video playback in web browsers like Firefox or Safari +* Display/Wallpaper settings in SysPref/SysSettings +* Logging out freezes your system ## Custom Firmware @@ -16,20 +16,20 @@ Prebuilts can be found at [ethanthesleepy.one](https://ethanthesleepy.one/macos/ ### Building Manually 1. Follow the steps [here](../firmware/compiling-coreboot.md) to download the toolchain and build the firmware - * Continue these steps once `build-uefi.sh ` has been ran -1. Run `make menuconfig`. You will be greeted by a menu which looks like the following: + * 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: - ![image](/macos/menuconfig.png) + ![image](/macos/menuconfig.png) -1. Select `Chipset` -1. Select `Disable HECI1 at the end of boot` then press `N` to disable. The asterik should be gone: +3. Select `Chipset` +4. Select `Disable HECI1 at the end of boot` then press `N` to disable. The asterik should be gone: - ![image](/macos/heci1.png) + ![image](/macos/heci1.png) -1. Use the right arrow keys to select `Save` at the bottom, then press `Ok` -1. Use the right/left arrow keys to select `Exit` until back at the prompt. -1. Run `make -j$(nproc)` to build the firmware. -1. The output will be found at `./build/coreboot.rom` +5. Use the right arrow keys to select `Save` at the bottom, then press `Ok` +6. Use the right/left arrow keys to select `Exit` until back at the prompt. +7. Run `make -j$(nproc)` to build the firmware. +8. The output will be found at `./build/coreboot.rom` ## Flashing Firmware diff --git a/src/docs/installing/macos-hibernation.md b/src/docs/installing/macos-hibernation.md index 230b8436..322ea747 100644 --- a/src/docs/installing/macos-hibernation.md +++ b/src/docs/installing/macos-hibernation.md @@ -5,9 +5,9 @@ Some fixes in the `config.plist` are required in order to take advantage of this - Disable `Booter->Quirks->DevirtualiseMmio` - Set `Misc->Boot->HibernateMode` to `Auto` - - By default, OpenCore will not look for hibernated images of macOS. + - By default, OpenCore will not look for hibernated images of macOS. - Set `Misc->Boot->HibernationSkipsPicker` to `True` to skip the picker when resuming from hibernation - - While not strictly required, this speeds up resume times and prevents accidently booting another OS and changing hardware state underneath macOS. + - While not strictly required, this speeds up resume times and prevents accidently booting another OS and changing hardware state underneath macOS. - Create a reserved memory region under `UEFI->ReservedMemory` with the properties: | Field | Type | Value | @@ -43,7 +43,7 @@ Pmset exposes a few different hibernation modes which can be set through `sudo p - 0: Disables hibernation - 3: Hibernates after either `standbydelaylow` or `standbydelayhigh` seconds of sleep - - Which one is used is dependent on the battery percentage. Anything above `highstandbythreshold` will use `standbydelayhigh` instead of `standbydelaylow`. + - Which one is used is dependent on the battery percentage. Anything above `highstandbythreshold` will use `standbydelayhigh` instead of `standbydelaylow`. - 25: Hibernates instead of S3 sleep When using hibernate mode 3, macOS may keep sleeping even after the standby time has elapsed. diff --git a/src/docs/installing/post-install.md b/src/docs/installing/post-install.md index 92cc090d..b0ae8583 100644 --- a/src/docs/installing/post-install.md +++ b/src/docs/installing/post-install.md @@ -10,28 +10,26 @@ Install [Chrultrabook Controller](https://github.com/death7654/Chrultrabook-Cont ## Windows -#### Drivers and QOL improvements +### Drivers and QOL improvements * Compress the install with `compact.exe /compactos:always` in a Command Prompt with admin privileges if necessary. * Install [CoolStar's drivers](https://coolstar.org/chromebook/windows-install.html) if you haven't already * Buy audio and Thunderbolt/USB4 drivers (if needed), see [CoolStar's driver portal](https://coolstar.org/chromebook/driverlicense/login.html) -#### CELES Post Install Workaround +### CELES Post Install Workaround 1. Boot the Windows install media you used to install Windows. 2. Click "Repair my computer" and select the Command Prompt option. 3. Type `bcdedit /set {default} useplatformclock true` and press Enter. 4. Reboot ---- - ## Linux -#### General QOL Fixes +### General QOL Fixes * Run the [audio script](https://github.com/WeirdTreeThing/chromebook-linux-audio) if you haven't already. * Run the [cros-keyboard-map](https://github.com/WeirdTreeThing/cros-keyboard-map) script to remap top row FX keys. -#### Fixing USB C on TigerLake and AlderLake +### Fixing USB C on TigerLake and AlderLake 1. Create a file called `chromebook-usbc.service` file in `/etc/systemd/system/` 2. Paste the following contents into the file: @@ -52,7 +50,7 @@ Install [Chrultrabook Controller](https://github.com/death7654/Chrultrabook-Cont 3. Enable the systemd service by typing `systemctl enable --now chromebook-usbc.service`, then it should work. -#### CELES Post Install Workaround +### CELES Post Install Workaround If you experience issues in applications such as Parsec, or encounter disruptive freezes, adding the kernel parameters `clocksource=hpet hpet=force` may fix your problem. The following instructions assume you're using GRUB, and will be different for other bootloaders. Do your own research on how to set kernel parameters in your bootloader if these do not apply. @@ -61,8 +59,6 @@ If you experience issues in applications such as Parsec, or encounter disruptive 3. Type `grub-mkconfig -o /boot/grub/grub.cfg` or `update-grub` into a terminal and press Enter. Use sudo, su, or doas if necessary. 4. Reboot ---- - ## macOS * [Remove Verbose](https://dortania.github.io/OpenCore-Post-Install/cosmetic/verbose.html#macos-decluttering) diff --git a/src/docs/reverting/booting-recovery-usb.md b/src/docs/reverting/booting-recovery-usb.md index 896edc2f..bcc091b3 100644 --- a/src/docs/reverting/booting-recovery-usb.md +++ b/src/docs/reverting/booting-recovery-usb.md @@ -9,7 +9,7 @@ If recovery fails, [disable write protect](../firmware/write-protect.md) since r ::: ::: danger -Going through the recovery proccess will wipe **all** data on the internal drive. +Going through the recovery process will wipe **all** data on the internal drive. ::: 1. Enter [recovery mode](../firmware/recovery-mode.md). diff --git a/src/docs/reverting/flashing-stock.md b/src/docs/reverting/flashing-stock.md index 227536ea..2ea8b5c5 100644 --- a/src/docs/reverting/flashing-stock.md +++ b/src/docs/reverting/flashing-stock.md @@ -13,17 +13,15 @@ If your device has hit AUE (Auto Update Expiration), you will not be able to rev 2. Connect to WiFi. 3. Open a terminal, then update and install `curl`. - - - Use the distro's package manager to install it. + * 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. + * 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). ::: diff --git a/src/docs/reverting/making-recovery-usb.md b/src/docs/reverting/making-recovery-usb.md index 009bbaf0..e6f46b6b 100644 --- a/src/docs/reverting/making-recovery-usb.md +++ b/src/docs/reverting/making-recovery-usb.md @@ -10,7 +10,9 @@ Making a Recovery USB will **wipe all data** on said drive. Back up anything if 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) + +## 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. @@ -19,34 +21,19 @@ There are two methods depending on the Operating System Installed. 4. Wait for it to complete. -## Manually Flash Recovery Image (Windows/ChromeOS/MacOS/Linux) +## Manually Flash Recovery Image (Windows/ChromeOS/macOS/Linux) 1. Go to [cros.tech](https://cros.tech/) and find your device. -2. Select on "Recovery Images" and select the latest one. +2. Click on the "Recovery Images" dropdown and select the latest one. 3. Extract the file. -#### Windows - -1. You can either: - - Use [Rufus](../installing/bootableusb.md#flashing-using-rufus-windows) but make sure to flash in "dd" mode. - - Use the [Chromebook Recovery Utility](https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm) but open settings (gear icon) and select "Use local image". - - Use [dd](../installing/bootableusb.md#flashing-with-dd-linux-macos) - -#### macOS/ChromeOS - -1. Use the [Chromebook Recovery Utility](https://chrome.google.com/webstore/detail/chromebook-recovery-utili/pocpnlppkickgojjlmhdmidojbmbodfm) but open settings (gear icon) and select "Use local image". - -#### Linux - -1. Make sure that your USB drive is unmounted (not unplugged). +### Windows -2. Open a terminal and run `lsblk`. +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. -3. Find your USB drive. USB drives usually appear as sdXX, while SD Cards usually appear as mmcblkX. - - If your using a SD card adapter, It might appear as sdXX instead. +### macOS/ChromeOS/Linux -4. Run `sudo dd if=PLACEHOLDER of=/dev/PLACEHOLDER bs=4M status=progress` but replace the placeholders with the path to the recovery image and USB drive respectivly. +Use [dd](../installing/bootableusb.md#flashing-with-dd-linux-macos) to flash the recovery .bin file to USB. -5. Wait for it to complete, after that unplug the USB drive. diff --git a/src/docs/unbricking/index.md b/src/docs/unbricking/index.md index 763f50b1..75e39ad1 100644 --- a/src/docs/unbricking/index.md +++ b/src/docs/unbricking/index.md @@ -4,11 +4,12 @@ prev: false --- # Unbricking +If your device's firmware got into a bad state (won't POST), you can try unbricking it. + ::: tip -Try preforming a EC reset beforehand to see if your device can recover. +Try performing a EC reset beforehand to see if your device can recover. ::: ---- -If your device's firmware got into a bad state (wont POST), you can try unbricking it. + Here is the following ways that you can unbrick your device: ### [Unbricking with a ch341a USB programmer](unbrick-ch341a) diff --git a/src/docs/unbricking/unbrick-ch341a.md b/src/docs/unbricking/unbrick-ch341a.md index 287dd111..9cfafa03 100644 --- a/src/docs/unbricking/unbrick-ch341a.md +++ b/src/docs/unbricking/unbrick-ch341a.md @@ -5,51 +5,50 @@ prev: false # Unbricking/Flashing with a ch341a USB programmer -### Requirements - -1. A ChromeOS device +## 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 device running Linux from which to run flashrom. For this guide, I will use a Ubuntu live USB. -2. A ch341a USB flash programmer -3. A 1.8v adapter +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 - ::: +::: 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're 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 +## 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. + * 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]. - ::: +::: 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]. +::: - ::: tip - 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. - ::: +::: 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. - ::: +::: 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 +## 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. @@ -57,40 +56,40 @@ 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;` +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` + * `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) + ![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) + ![image](/ch341aunbrick/500px-SOIC-8_chip.jpg) 7. Test connectivity and ensure the flash chip is properly identified: - * `sudo flashrom -p ch341a_spi` + * `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) +![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` - * Don't 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` + * 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` + * Don't 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're not sure which file to use for your device / don't know your device's board name, you can reference [the supported devices page](supported-device.html). @@ -100,45 +99,43 @@ If you're not sure which file to use for your device / don't know your device's 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're 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 +::: tip NOTE You don't 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, so let's download/extract that: - * `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` + * `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 +## 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 ` + * 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. +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. +* 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 diff --git a/src/docs/unbricking/unbrick-flipper.md b/src/docs/unbricking/unbrick-flipper.md index d24dbd84..1fd338aa 100644 --- a/src/docs/unbricking/unbrick-flipper.md +++ b/src/docs/unbricking/unbrick-flipper.md @@ -1,32 +1,35 @@ # 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're 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 + +* Your brain (please) +* A Flipper Zero with up-to-date firmware + * It doesn't matter if you're 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 @@ -38,18 +41,23 @@ 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 unbricked system. ## Got Questions? + Please ask in the Chrultrabook Discord, or email me (meghan6) at [meghann6@proton.me](mailto:meghann6@proton.me). diff --git a/src/docs/unbricking/unbrick-suzyq.md b/src/docs/unbricking/unbrick-suzyq.md index 307c20ac..ba0634b8 100644 --- a/src/docs/unbricking/unbrick-suzyq.md +++ b/src/docs/unbricking/unbrick-suzyq.md @@ -1,28 +1,27 @@ - # Unbricking/Flashing with a Suzy-Q cable -### Requirements +## 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. - ::: danger - These instructions do not apply to any device which is locked/managed. Enterprise and/or EDU enrollment locks out CCD functionality completely. - ::: +::: 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 +## 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. + - 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 +## 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). @@ -30,35 +29,35 @@ 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;` + * `cd;` 4. Install flashrom via apt: - * `sudo apt update` - * `sudo apt install flashrom` + * `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 + * `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` - * Don't 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` + * `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` + * Don't 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're not sure which file to use for your device / don't know your device's board name, you can reference [the supported devices page](supported-device.html). @@ -68,32 +67,32 @@ If you're not sure which file to use for your device / don't know your device's 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're 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 +::: tip NOTE You don't 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, so let's download/extract that: - * `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` + * `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 +## 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. + * 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 diff --git a/supported-devices/template.md b/supported-devices/template.md index 467cbc55..1f2fa9de 100644 --- a/supported-devices/template.md +++ b/supported-devices/template.md @@ -10,7 +10,7 @@ NOTE - do not edit the supported-devices.md file, edit the template file in the # 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 +## 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 MrChromebox's Firmware Utility Script, the firmware types available for each, the hardware write-protect method used, and notes for Windows, Linux, and macOS operating systems. @@ -23,17 +23,13 @@ Be aware that EOL (End Of Life) devices **DO NOT** have RW_Legacy avaliable 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 +## 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 unsupported on all AMD platforms. | Currently unsupported by the Chrultrabook dev team. [PostmarketOS](https://wiki.postmarketos.org/wiki/Chrome_OS_devices) has support for a few ARM Chromebooks. | ---------- - -### Firmware and OS Support +## Firmware and OS Support ::: tip If your device isn't listed, it doesn't have support.