Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated markdown formatting and removed contractions #181

Closed
wants to merge 13 commits into from
35 changes: 18 additions & 17 deletions src/docs/contributing.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,36 @@
# Supporting the Docs

Want to help support the docs? Well there's some ways you can help!

## 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.
- 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

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.
* Ensure that the pages adhere to the markdown style used in the docs.
- 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.
- Ensure that the pages adhere to the markdown style used in the docs.

## 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

* Install NodeJS
* You can download NodeJS from [the NodeJS download page](https://nodejs.org/en/download).
* [Fork this repo](https://github.com/chrultrabook/docs/fork/)
* Clone your fork, open a terminal and `cd` to it
* Run the `npm i` command, then `npm run dev`
* Visit `localhost:8080` in your web browser and preview your changes.
- Install NodeJS
- You can download NodeJS from [the NodeJS download page](https://nodejs.org/en/download).
- [Fork this repo](https://github.com/chrultrabook/docs/fork/)
- Clone your fork, open a terminal and `cd` to it
- Run the `npm i` command, then `npm run dev`
- Visit `localhost:8080` in your web browser and preview your changes.

::: tip
Vuepress will automatically regenerate pages when you make changes.
Expand All @@ -39,7 +40,7 @@ Vuepress will automatically regenerate pages when you make changes.

Some tools that make contributing a bit easier:

* [Visual Studio Code](https://code.visualstudio.com/)
* [Typora](https://typora.io/) for real time markdown rendering.
* [TextMate](https://macromates.com/) for easy and powerful mass find/replace.
* [GitHub Desktop](https://desktop.github.com/) for more user friendly GUI.
- [Visual Studio Code](https://code.visualstudio.com/)
- [Typora](https://typora.io/) for real time markdown rendering.
- [TextMate](https://macromates.com/) for easy and powerful mass find/replace.
- [GitHub Desktop](https://desktop.github.com/) for more user friendly GUI.
2 changes: 1 addition & 1 deletion src/docs/debugging/bugreport.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ So you find a bug in one of our projects, and want to report it. It's faily simp
<br>

::: tip
Do not submit personal help requests in the bugtracker.
Do not submit personal help requests in the bugtracker.
:::
102 changes: 58 additions & 44 deletions src/docs/debugging/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,26 @@
next: false
prev: false
---

# Debugging

## Grabbing Logs

* If you're experiencing firmware bugs, provide output from `cbmem` console.
* If you're experiencing issues with Linux, provide output from `dmesg`, `dmidecode` and `journalctl` or `/var/log/messages`, respectively
* 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/).
- If you are experiencing firmware bugs, provide output from `cbmem` console.
- If you are experiencing issues with Linux, provide output from `dmesg`, `dmidecode` and `journalctl` or `/var/log/messages`, respectively
- If you are experiencing issues with Windows, provide screenshots from Device Manager, Event Viewer, coredumps etc.
- If you are 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:

1. `cbmem` - To view Coreboot logs
2. `ectool` - To interface with ChromeOS Embedded Controller
3. SuzyQ - If you're experiencing severe system instability (lockups, crashes), preventing you from on-device debugging.
3. SuzyQ - If you are experiencing severe system instability (lockups, crashes), preventing you from on-device debugging.

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`
2. Unzip the file and give the binary executable permissions:
Expand All @@ -29,6 +31,7 @@ To dump the cbmem buffer, follow these steps:
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`
2. Unzip the file and give the binary executable permissions:
Expand All @@ -40,86 +43,97 @@ To interface with the Embedded Controller:
## 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`
`EDK2_SERIAL_SUPPORT=y`
* To use SuzyQ as platform debugger, you will also need to append the following to your kernel commandline:
`loglevel=15 console=ttyS4,115200n8`
- 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`
`EDK2_SERIAL_SUPPORT=y`
- 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:
* ACPI tables from sysfs (`/sys/firmware/acpi/*`)
* DMI information (`dmidecode`)
* Coreboot buffer (`cbmem`)
* Linux kernel logs (`dmesg`)
* List of PCI devices (`lspci`)
* List of USB devices (`lsusb`)
* Information about soundcards present in the system and their configuration

Into `debug-logs.tar.gz` archive on your desktop.
- ACPI tables from sysfs (`/sys/firmware/acpi/*`)
- DMI information (`dmidecode`)
- Coreboot buffer (`cbmem`)
- Linux kernel logs (`dmesg`)
- List of PCI devices (`lspci`)
- List of USB devices (`lsusb`)
- Information about soundcards present in the system and their configuration

Into `debug-logs.tar.gz` archive on your desktop.

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 <programmer> -r <filename.rom>`
* Example:
* `sudo flashrom -p internal -r backup.rom`

- `sudo flashrom -p <programmer> -r <filename.rom>`
- 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 <programmer> -w <filename.rom>`
* Intel Example:
* `sudo flashrom -p internal --ifd -i bios -w stock.rom`
* AMD Example:
* `sudo flashrom -p internal -w stock.rom`

- `sudo flashrom -p <programmer> -w <filename.rom>`
- 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.

- `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
12 changes: 6 additions & 6 deletions src/docs/exiting-developer-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,25 @@ 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.

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`

- 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.


### Exiting Developer Mode

1. Boot your system to the "You are in Developer Mode" or "OS Verification is OFF" screen.
Expand All @@ -41,4 +42,3 @@ If you get this error "WARNING: TONORM prohibited by GBB_FORCE_DEV_SWITCH_ON" or
1. Select "Enable OS Verification".

2. Once its done, Setup the system like normal.

Loading
Loading