Commit 6aa2a05e authored by Guillaume Tucker's avatar Guillaume Tucker
Browse files

README.md: update instructions with octopus example



Update the instructions about how to use the tools in this repository
and provide an example based on octopus.  This includes setting up a
Docker container and building a firmware image.
Signed-off-by: Guillaume Tucker's avatarGuillaume Tucker <guillaume.tucker@collabora.com>
parent 1a1029be
......@@ -47,24 +47,89 @@ SUCCESS
# Building
The Chromebook firmware needs to be rebuilt and flashed with extra patches and
configuration options turned on in order to enable the serial console in the
bootloader and boot with a kernel image and ramdisk supplied over TFTP
interactively. The standard firmware shipped with the products is only
configured to boot the Chrome OS image present on the device, with no serial
console and no way to override it. This is not suitable for automating the
Chromebook in a test lab such as LAVA, or for doing low-level kernel
development.
configuration options turned on in order to enable the serial console and boot
with a kernel image and ramdisk supplied over TFTP interactively. The standard
firmware shipped with the products is only configured to boot the Chrome OS
image present on the device, with no serial console and no way to override it.
This is not suitable for automating the Chromebook in a test lab such as LAVA,
or for doing low-level kernel development.
Collabora maintains a set of
[`Depthcharge`](https://gitlab.collabora.com/chromium/depthcharge/) branches
with such changes. The tools in this repository make use of them to build the
firmware images used in LAVA.
## Docker containers
Building the firmware for a Chromebook can be non-trivial. To make things
easier, this repository contains a Docker container and some helper scripts to
build firmware images for some known device types.
easier, this repository provides tools to create Docker containers and some
helper scripts to build firmware images for some known device types. All this is kept under the [`cros-build`](https://gitlab.collabora.com/chromium/firmware-tools/-/blob/master/cros-build/) directory.
The containers are using the following local directories on the host:
* cache: used by the SDK tools, for example to store SDK tarballs
* firmware: where the firmware binaries are kept and new ones are placed
* chroot-*: dedicated chroot directory for each device type
## Chrombeook device types
Each device type uses a different revision of the Chromium OS source tree,
which means a different Docker image and a different Docker container with a
different chroot directory. Each device type will also have a different build
script, as the steps can vary slightly for each of them.
The
[`cros-build/bootstrap.sh`](https://gitlab.collabora.com/chromium/firmware-tools/-/blob/master/cros-build/bootstrap.sh)
script can be used to create local directories, then build the Docker container
which will be using them and start it. It takes only one argument which is the
device type. For example:
script can be used to create a Docker container for a particular device type.
It will download the Chromium OS source code necessary to build a Chromebook
firmware and set up the Chromium OS SDK chroot. Then it's possible to run some
build scripts provided in this repository to build a new image.
All these device-specific things can be found in the
[`setup`](https://gitlab.collabora.com/chromium/firmware-tools/-/blob/master/cros-build/setup/)
sub-directory. See the example below for the `octopus` device type.
## Example: octopus
For example, the `octopus` device type has a
[`octopus.env`](https://gitlab.collabora.com/chromium/firmware-tools/-/blob/master/cros-build/setup/octopus.env)
file with environment variables defining the parameters for the Docker
container and a
[`octopus.sh`](https://gitlab.collabora.com/chromium/firmware-tools/-/blob/master/cros-build/setup/octopus.sh)
build script which will get copied in the container.
To set up a container for `octopus`:
```
cd cros-build
./bootstrap.sh octopus
Using environment file: setup/octopus.env
------------------------
CROS_DEVICE=octopus
CROS_SDK_BRANCH=firmware-octopus-11297.83.B
------------------------
[...]
(cr) (firmware-octopus-11297.83.B/(8c78090...)) cros-build@4d71a209fc9f ~/trunk/src/scripts $
```
This can take a while the first time. Once it has completed, exiting from the
container and running the `bootstrap.sh` script again should only take a few
seconds as everything is kept in the `cache` and `chroot-octopus` directories.
Then to start building the firmware, the `octopus.sh` script is available
```
./octopus.sh setup # to configure the chroot for "octopus"
./octopus.sh checkout # to check out the Depthcharge branch
./octopus.sh build # to build Depthcharge
./octopus.sh image # to create a new firmware image
```
Likewise, the `setup` and `build` steps can take a while the first time but
should be very quick when run again in the same chroot.
If everything went well, there should be a new firmware image:
```
-rw-r--r-- 1 cros-build chronos 16777216 Oct 21 10:20 firmware/octopus-new.bin
```
This can be accessed from the host, in the `firmware` directory.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment