Snap for 11841552 from 5e713b7ecd8d7b670e53904a6c46f68564415393 to sdk-releasesdk-release

Change-Id: Idc3d751a3c2cb56b5909e2a9d2a6c003d2fae8c9

5 files changed, 224 insertions, 0 deletions

diff --git a/gbl/BUILD b/gbl/BUILD
index e69de29..96485a3 100644
--- a/gbl/BUILD
+++ b/gbl/BUILD
@@ -0,0 +1,37 @@
+# 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.
+
+load(":readme.bzl", "readme_test")
+
+readme_test(
+    name = "readme_test",
+    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 = [
+        "@gbl//efi:main",
+        "@gbl//libavb:sysdeps",
+        "@gbl//libboot",
+        "@gbl//libbootconfig",
+        "@gbl//libbootimg",
+        "@gbl//libc",
+        "@gbl//libefi",
+        "@gbl//libfastboot",
+        "@gbl//libfdt",
+        "@gbl//libgbl",
+        "@gbl//libmisc",
+        "@gbl//libsafemath",
+        "@gbl//libstorage",
+    ],
+)
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
new file mode 100644
index 0000000..cc8bdc9
--- /dev/null
+++ b/gbl/readme.bzl
@@ -0,0 +1,117 @@
+# 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')
+
+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
+
+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,
+)
diff --git a/gbl/tests/BUILD b/gbl/tests/BUILD
index 3a9fbda..e51b5cd 100644
--- a/gbl/tests/BUILD
+++ b/gbl/tests/BUILD
@@ -15,6 +15,7 @@
 test_suite(
     name = "tests",
     tests = [
+        "@gbl//:readme_test",
         "@gbl//libabr:libabr_tests",
         "@gbl//libbootconfig:libbootconfig_test",
         "@gbl//libbootimg:libbootimg_test",