From 7a2d4da31f30087547383b83004281ce0f6096b2 Mon Sep 17 00:00:00 2001 From: Tim Crawford Date: Wed, 21 Feb 2024 08:40:01 -0700 Subject: [PATCH] docs: Move info from README to docs/ Signed-off-by: Tim Crawford --- CHANGELOG.md | 2 +- LICENSE.md | 2 +- README.md | 61 ++++----------------------------- docs/SUMMARY.md | 2 ++ docs/building.md | 31 +++++++++++++++++ FEATURES.md => docs/features.md | 2 +- docs/index.md | 8 +++-- docs/schematics.md | 18 ++++++++++ 8 files changed, 65 insertions(+), 61 deletions(-) create mode 100644 docs/building.md rename FEATURES.md => docs/features.md (99%) create mode 100644 docs/schematics.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 697f89a..d85d4dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ Changes are identified by the date of the released firmware including them. If you are running System76 Open Firmware, opening the boot menu will show this date followed by an underscore and a short git revision. To see if specific features apply to your model and firmware version, see the -[feature matrix](./FEATURES.md). +[feature matrix](./docs/features.md). ## unreleased diff --git a/LICENSE.md b/LICENSE.md index a83712f..9e9d206 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -33,7 +33,7 @@ The license for the embedded controller firmware depends on the binary used. #### Intel binaries -Intel provides biniaries under a redistributable license, which may be +Intel provides binaries under a redistributable license, which may be different per binary. - `me.rom`: Intel CSME diff --git a/README.md b/README.md index bfc9d87..7fb2f1d 100644 --- a/README.md +++ b/README.md @@ -3,59 +3,10 @@ An open source distribution of firmware utilizing coreboot, EDK2, and System76 firmware applications. -## Supported models and features +## Resources -To view models that are supported and will receive updates through the firmware -manager, as well as available features for those models, please see the -[feature matrix](./FEATURES.md). - -Other models may be in development or available without support, and can be -seen in the `models/` directory. - -If the device becomes bricked it will require restoring the current firmware -using an external programmer. See [flashing](./docs/flashing.md) for details. - -### Schematics - -System76 customers may request board schematics for their system by sending an -email to firmware@system76.com with the subject line "Schematics for _model_", -where _model_ is one of the supported models listed above. Please include the -serial number of your system for verification. - -You may not share these without explicit permission from System76. - -## Changelog - -For a list of important changes please see the [changelog](./CHANGELOG.md). - -## Building - -Dependencies can be installed with the provided script. - -```sh -./scripts/install-deps.sh -``` - -If rustup was installed for the first time, it will be required to source the -environment file it installed to use the correct Rust toolchain. - -``` -source ~/.cargo/env -``` - -A script is provided to build the firmware. The available targets for building -are the model folders in `models/`. For example, to build for QEMU: - -``` -./scripts/build.sh qemu -``` - -Once built, the firmware must be flashed to use. Several scripts are available -to flash the new firmware, depending on how it is going to be written. - -- `scripts/qemu.sh`: [Run the firmware in QEMU](./docs/debugging.md#using-qemu) (specific to the QEMU model) -- `scripts/flash.sh`: Flash using the internal flasher -- `scripts/ch341a-flash.sh`: Flash using a CH341A programmer -- `scripts/spipi-flash.sh`: Flash using a Raspberry Pi - -See [Flashing firmware](./docs/flashing.md) for more details. +- [Project site](https://github.com/system76/firmware-open) +- [Documentation](./docs/index.md) +- [Issue tracker](https://github.com/system76/firmware-open/issues/) +- [Changelog](./CHANGELOG.md) +- [Legal information](./LICENSE.md) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 8a6ed21..1713f55 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,8 +2,10 @@ - [Index](./index.md) - [Firmware features](./features.md) +- [Building firmware](./building.md) - [Flashing firmware](./flashing.md) - [Debugging](./debugging.md) - [Adding a new board](./adding-a-new-board.md) - [Intel CSME](./intel-me.md) - [UEFI](./uefi.md) +- [Schematics](./schematics.md) diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 0000000..c860b0e --- /dev/null +++ b/docs/building.md @@ -0,0 +1,31 @@ +# Building + +Dependencies can be installed with the provided script. + +``` +./scripts/install-deps.sh +``` + +If rustup was installed for the first time, it will be required to source the +environment file it installed to use the correct Rust toolchain. + +``` +. ~/.cargo/env +``` + +A script is provided to build the firmware. The available targets for building +are the model folders in `models/`. For example, to build for QEMU: + +``` +./scripts/build.sh qemu +``` + +Once built, the firmware must be flashed to use. Several scripts are available +to flash the new firmware, depending on how it is going to be written. + +- `scripts/qemu.sh`: [Run the firmware in QEMU](./debugging.md#using-qemu) (specific to the QEMU model) +- `scripts/flash.sh`: Flash using firmware-update +- `scripts/ch341a-flash.sh`: Flash using a CH341A programmer +- `scripts/spipi-flash.sh`: Flash using a Raspberry Pi + +See [Flashing firmware](./flashing.md) for more details. diff --git a/FEATURES.md b/docs/features.md similarity index 99% rename from FEATURES.md rename to docs/features.md index 3ab829c..f615d5a 100644 --- a/FEATURES.md +++ b/docs/features.md @@ -4,7 +4,7 @@ This lists important features provided by System76 Open Firmware. Your system must be updated to at least the firmware version specified in the following [platform tables](#platforms) to include all specified [features](#features). To see the changes in specific firmware versions, see the -[changelog](./CHANGELOG.md). +[changelog](./../CHANGELOG.md). ## Platforms diff --git a/docs/index.md b/docs/index.md index 9574bd1..093138c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,9 @@ # Documentation This is the documentation for System76 Open Firmware. It is set up to be used -with [mdBook], which can generate HTML output for easy navigation. +with [mdBook](https://github.com/rust-lang/mdBook), which can generate HTML +output for easy navigation. - -[mdBook]: https://github.com/rust-lang/mdBook +``` +mdbook build --open docs/ +``` diff --git a/docs/schematics.md b/docs/schematics.md new file mode 100644 index 0000000..0fba344 --- /dev/null +++ b/docs/schematics.md @@ -0,0 +1,18 @@ +# Schematics + +## Systems using System76 Open Firmware + +System76 customers may request board schematics for their system by sending an +email to `firmware@system76.com` with the subject line: + +> Schematics for <model> + +where `` is a model that uses firmware-open. Include the serial number +of your system for verification. + +You may not share these without explicit permission from System76. + +## Other models and components + +System76 cannot provide schematics for models not using firmware-open, nor +datasheets for any components that are not already publicly available.