diff options
author | Dov Shlachter <dovs@google.com> | 2024-05-13 16:13:31 -0700 |
---|---|---|
committer | Dov Shlachter <dovs@google.com> | 2024-05-14 12:07:46 -0700 |
commit | 5e713b7ecd8d7b670e53904a6c46f68564415393 (patch) | |
tree | 37d01c4f18b55b4e6e742a5744748b7341380f15 | |
parent | 345af2e774e80449b56ca672115da41af76bf2cd (diff) | |
download | libbootloader-master.tar.gz |
Include the required, conditionally required, and optional protocols
in addition to a brief description of what the protocol does and how
it is used within GBL.
Bug: b/340322551
Change-Id: Id4909170643fe704e540455d6c7e8858175882f3
-rw-r--r-- | gbl/BUILD | 2 | ||||
-rw-r--r-- | gbl/README.md | 4 | ||||
-rw-r--r-- | gbl/docs/efi_protocols.md | 65 | ||||
-rw-r--r-- | gbl/readme.bzl | 20 | ||||
-rw-r--r-- | gbl/tests/BUILD | 3 |
5 files changed, 88 insertions, 6 deletions
@@ -16,7 +16,7 @@ load(":readme.bzl", "readme_test") readme_test( name = "readme_test", - readme = "README.md", + readme = "docs/efi_protocols.md", # Note: can't read files in subpackages, not sure how to add a dependency on all, # globbed, subpackages and all the rust_lib targets they contain. deps = [ diff --git a/gbl/README.md b/gbl/README.md index 430040a..d0b33c4 100644 --- a/gbl/README.md +++ b/gbl/README.md @@ -96,3 +96,7 @@ configurations: -drive format=raw,file=fat:rw:/tmp/esp,id=blk0 \ -device virtio-blk-device,drive=blk0 ``` + +## EFI Protocols + +List of EFI protocols used by GBL and a brief description of each [here](./docs/efi_protocols.md). diff --git a/gbl/docs/efi_protocols.md b/gbl/docs/efi_protocols.md new file mode 100644 index 0000000..32d09f3 --- /dev/null +++ b/gbl/docs/efi_protocols.md @@ -0,0 +1,65 @@ +The EFI application of GBL requires certain EFI protocols in order to boot, +and can require other protocols for certain targets or to enable optional features. + +### Required Protocols + +#### BlockIoProtocol + +The BlockIo protocol is required for loading system images from disk. +If a target supports Fastboot mode, it is also used for writing images to disk. + +#### SimpleTextOutputProtocol + +The SimpleTextOutput protocol is used for logging +and the text-based interface of Fastboot. +On systems where there is no output functionality, +this can be implemented as a series of no-op functions. + +### Conditionally Required Protocols + +#### RiscvBootProtocol + +Determines the boot hart ID which is then passed to the kernel. +Only required for RISC-V targets. + +### Optional Protocols + +#### AndroidBootProtocol + +This is a custom protocol intended to provide +specific functionality needed to boot Android. +A full description is available [here](./EFI_ANDROID_BOOT_PROTOCOL.md). + +#### DevicePathProtocol + +The DevicePath protocol is a variable length binary structure +made of variable length Device Path nodes. +A handle representing a hardware resource is mapped +to the protocol and provides specific data about that resource. + +If all three of DevicePath protocol, DevicePathToText protocol, +and LoadedImage protocol are present, the GBL image path is logged +to the console on load. + +This is a useful proof of concept for development to demonstrate +that GBL is running and can interact with the UEFI environment. + +#### DevicePathToTextProtocol + +The DevicePathToText protocol converts device paths and nodes to text. + +#### LoadedImageProtocol + +The LoadedImage protocol can be used on the handle of an image to provide +information about the image, including its device handle and device path. + +#### SimpleNetworkProtocol + +If present, the SimpleNetwork protocol is used to provide Fastboot over TCP. +No other EFI protocols are required: GBL wraps SimpleNetwork to provide TCP. + +Note: for security reasons, Fastboot over TCP is only available in dev builds. + +#### SimpleTextInputProtocol + +TODO: remove this protocol diff --git a/gbl/readme.bzl b/gbl/readme.bzl index fe8f7c2..cc8bdc9 100644 --- a/gbl/readme.bzl +++ b/gbl/readme.bzl @@ -49,15 +49,29 @@ if [ ! -f $README ]; then exit 1 fi +ALL_INPUTS=$(echo ${INPUT} | sed 's/,/ /g') + DOCLESS_PROTOCOLS="" -PROTOCOLS=($(echo $INPUT | sed 's/,/ /g' | xargs grep -h -E 'impl ProtocolInfo for .* \\{' | awk '{print $4}' | sort)) +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" + grep -Lq $P ${README} || DOCLESS_PROTOCOLS+="\n\t$P" done if [ ! -z "${DOCLESS_PROTOCOLS}" ]; then - echo "Missing documentation for protocol(s):$DOCLESS_PROTOCOLS" + echo -e "Missing documentation for protocol(s):$DOCLESS_PROTOCOLS" + exit 1 +fi + +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 diff --git a/gbl/tests/BUILD b/gbl/tests/BUILD index fc44e64..e51b5cd 100644 --- a/gbl/tests/BUILD +++ b/gbl/tests/BUILD @@ -15,8 +15,7 @@ test_suite( name = "tests", tests = [ - # TODO(b/340322551): protocols are properly documented - # "@gbl//:readme_test", + "@gbl//:readme_test", "@gbl//libabr:libabr_tests", "@gbl//libbootconfig:libbootconfig_test", "@gbl//libbootimg:libbootimg_test", |