# Generic Bootloader Library

This directory hosts the Generic Bootloader Library project. A Bazel
workspace is setup for building the library as well as an EFI executable that
can be loaded directly from the firmware.

## Get source tree and build

To successfully get and build the tree your machine must have the following dependencies installed:

```
# repo to work with android repositories (https://source.android.com/docs/setup/reference/repo)
# bazel-bootstrap to build (https://bazel.build/)
sudo apt install repo bazel-bootstrap
```

The GBL project are intended to be built from the
[Android UEFI Manifest](https://android.googlesource.com/kernel/manifest/+/refs/heads/uefi-gbl-mainline/default.xml)
checkout:

```
repo init -u https://android.googlesource.com/kernel/manifest -b uefi-gbl-mainline
repo sync -j16
```

To build the EFI application:

```
./tools/bazel run //bootable/libbootloader:gbl_efi_dist --extra_toolchains=@gbl//toolchain:all
```

The above builds the EFI application for all of `x86_64`, `x86_32`, `aarch64`
and `riscv64` platforms.

To run the set of unit tests:

```
./tools/bazel test @gbl//tests --extra_toolchains=@gbl//toolchain:all
```

## IDE Setup

For rust development, we recommend use VSCode + rust-analyzer plugin.

rust-analyzer requires `rust-project.json` to work properly. Luckily, bazel has
support for generating `rust-project.json`:

```
./tools/bazel run @rules_rust//tools/rust_analyzer:gen_rust_project --norepository_disable_download -- --bazel ./tools/bazel @gbl//efi/...
```

`@gbl//efi/...` is the target to generate rust project for, here it means
"everything under @gbl//efi/ directory" . Omitting the target specifier would
result in analyzing "@/..." , which would most likely fail due to some obscure
reason. Should targets get moved around in the future, this path spec also need
to be updated.

After generating `rust-project.json`, you would notice that your IDE still
doesn't offer auto completion. This is because some source file paths pointing
to bazel-output dir, and you are most likely editing source files in
`bootable/libbootloader/gbl`. In addition, the generated rust-project.json sets
"cfg=test" for all targets, which causes certain dependency graph to resolve
incorrectly. To fix this, run

```
python3 bootable/libbootloader/gbl/rewrite_rust_project_path.py rust-project.json
```

And reload your IDE.

## Run the EFI application

### Boot Android on Cuttlefish

If you have a main AOSP checkout and is setup to run
[Cuttlefish](https://source.android.com/docs/setup/create/cuttlefish), you can
run the EFI image directly with:

```
cvd start --android_efi_loader=<path to the EFI image> ...
```

The above uses the same setting as a normal `cvd start` run, except that
instead of booting Android directly, the emulator first hands off to the EFI
application, which will take over booting android.

Note: For x86 platform, use the EFI image built for `x86_32`.

### Boot Fuchsia on Vim3

Booting Fuchsia on a Vim3 development board is supported. To run the
application:

1. Complete all
[bootstrap steps](https://fuchsia.dev/fuchsia-src/development/hardware/khadas-vim3?hl=en)
to setup Vim3 as a Fuchsia device.
2. Reboot the device into fastboot mode.
3. Run fastboot command:
```
fastboot stage <path to the EFI binary> && fastboot oem run-staged-efi
```

### Run on standalone QEMU

If you want to test the EFI image directly on QEMU with your custom
configurations:

1. Install EDK, QEMU and u-boot prebuilts

   ```
   sudo apt-get install qemu-system ovmf u-boot-qemu
   ```

1. Depending on the target architecture you want to run:

   For `x86_64`:
   ```
   mkdir -p /tmp/esp/EFI/BOOT && \
   cp <path to EFI image> /tmp/esp/EFI/BOOT/bootx64.efi && \
   qemu-system-x86_64 -nographic \
       -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
       -drive format=raw,file=fat:rw:/tmp/esp
   ```

   For `aarch64`:
   ```
   mkdir -p /tmp/esp/EFI/BOOT && \
   cp <path to EFI image> /tmp/esp/EFI/BOOT/bootaa64.efi && \
   qemu-system-aarch64 -nographic -machine virt -m 1G -cpu cortex-a57 \
       -drive if=pflash,format=raw,readonly=on,file=/usr/share/AAVMF/AAVMF_CODE.fd \
       -drive format=raw,file=fat:rw:/tmp/esp
   ```

   For `riscv64`:
   ```
   mkdir -p /tmp/esp/EFI/BOOT && \
   cp <path to EFI image> /tmp/esp/EFI/BOOT/bootriscv64.efi && \
   qemu-system-riscv64 -nographic -machine virt -m 256M \
       -bios /usr/lib/u-boot/qemu-riscv64/u-boot.bin \
       -drive format=raw,file=fat:rw:/tmp/esp,id=blk0 \
       -device virtio-blk-device,drive=blk0
   ```

### Boot Fuchsia on emulator

1. Make sure Fuchsia target pass control to GBL.

   Set path to GBL binary here: [fuchsia/src/firmware/gigaboot/cpp/backends.gni : gigaboot_gbl_efi_app](https://cs.opensource.google/fuchsia/fuchsia/+/main:src/firmware/gigaboot/cpp/backends.gni;l=25?q=gigaboot_gbl_efi_app)

   E.g. in `fuchsia/src/firmware/gigaboot/cpp/backends.gni`:
   ```
   $ cat ./fuchsia/src/firmware/gigaboot/cpp/backends.gni
   ...
   declare_args() {
      ...
      gigaboot_gbl_efi_app = "<path to EFI image>/gbl_x86_64.efi"
   }
   ```

   Or in `fx set`:
   ```
   fx set core.x64 --args=gigaboot_gbl_efi_app='"<path to EFI image>/gbl_x86_64.efi"'
   ```

2. Build: (this has to be done every time if EFI app changes)

   `fx build`

3. Run emulator in UEFI mode with raw disk

   ```
   fx qemu -a x64 --uefi --disktype=nvme -D ./out/default/obj/build/images/disk.raw
   ```

## EFI Protocols

List of EFI protocols used by GBL and a brief description of each [here](./docs/efi_protocols.md).

# Copyright (C) 2024 The Android Open Source Project
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
Action that verifies all EFI protocols used by GBL are explicitly listed in README.md
"""

load("@rules_rust//rust/private:providers.bzl", "CrateInfo")

def _readme_test_rule_impl(ctx):
    shell_script = """
while [[ $# -gt 0 ]]; do
  case $1 in
    --in)
      INPUT=$2
      shift
      shift
      ;;
    --out)
      OUTPUT=$2
      shift
      shift
      ;;
    --readme)
      README=$2
      shift
      shift
      ;;
    *)
      echo "Unexpected argument: $1"
      exit 1
      ;;
  esac
done

if [ ! -f $README ]; then
  echo "README file doesn't exist: ${README}"
  exit 1
fi

ALL_INPUTS=$(echo ${INPUT} | sed 's/,/ /g')

# Look for protocols in the source code that do not exist in the documentation.
# The protocol name we match on here is the Rust struct name.
DOCLESS_PROTOCOLS=""
PROTOCOLS=($(grep -hE 'impl ProtocolInfo for .* \\{' ${ALL_INPUTS} | awk '{print $4}' | sort))
for P in ${PROTOCOLS[@]}
do
  grep -Lq $P ${README} || DOCLESS_PROTOCOLS+="\n\t$P"
done

if [ ! -z "${DOCLESS_PROTOCOLS}" ]; then
  echo -e "Missing documentation for protocol(s):$DOCLESS_PROTOCOLS"
  exit 1
fi

# Look for protocols in the documentation that are not in the source, to try to
# prevent stale docs referring to protocols we are no longer using.
# Here we're matching on words ending in "Protocol", except "Protocol" itself.
UNUSED_PROTOCOLS=""
README_PROTOCOLS=($(grep -P " ?[^ ]+Protocol$" ${README} | awk '{print $NF}' | sort | uniq))
for P in ${README_PROTOCOLS[@]}
do
  grep -qhE "impl ProtocolInfo for $P" ${ALL_INPUTS} || UNUSED_PROTOCOLS+="\n\t$P"
done

if [ ! -z "${UNUSED_PROTOCOLS}" ]; then
  echo -e "Unused protocol(s) found in documentation:$UNUSED_PROTOCOLS"
  exit 1
fi

touch $OUTPUT
"""

    out_file = ctx.actions.declare_file("%s.script" % ctx.attr.name)
    in_files = [s for d in ctx.attr.deps for s in d[CrateInfo].srcs.to_list()]
    readme = ctx.attr.readme
    args = ctx.actions.args()
    args.add_joined(
        "--in",
        in_files,
        join_with = ",",
    )
    args.add(
        "--out",
        out_file,
    )
    args.add(
        "--readme",
        readme[DefaultInfo].files.to_list()[0],
    )
    ctx.actions.run_shell(
        inputs = in_files + readme[DefaultInfo].files.to_list(),
        outputs = [out_file],
        arguments = [args],
        command = shell_script,
    )
    return [DefaultInfo(executable = out_file)]

readme_test = rule(
    implementation = _readme_test_rule_impl,
    attrs = {
        "deps": attr.label_list(
            providers = [CrateInfo],
        ),
        "readme": attr.label(
            allow_single_file = [".md"],
        ),
    },
    test = True,
)