update edk2-uefi tutorial (#234)

Author: Wenzel

docs/src/tutorials/edk2-uefi/building-the-application.md

@@ -38,7 +38,10 @@ This Dockerfile will obtain the EDK2 source and compile the BaseTools, then copy
 
 We will want to get our built UEFI application from the container, which we can
 do using the `docker cp` command. There are a few files we want to copy, so we'll
-use this script `build.sh` to automate the process:
+use this script `build.sh` to automate the process.
+
+It will also copy the `tsffs.h` header into the harness sources, copy the minimal boot disk
+and create a initial fuzzing corpus to prepare the project.
 
 ```sh
 #!/bin/bash
@@ -49,26 +52,36 @@ CONTAINER_UID=$(echo "${RANDOM}" | sha256sum | head -c 8)
 CONTAINER_NAME="${IMAGE_NAME}-tmp-${CONTAINER_UID}"
 
 mkdir -p "${SCRIPT_DIR}/project/"
+# copy minimal boot disk
+cp "${SCRIPT_DIR}/../../rsrc/minimal_boot_disk.craff" "${SCRIPT_DIR}/project/"
+
+# copy tsffs.h header into src
+cp "${SCRIPT_DIR}/../../../harness/tsffs.h" "${SCRIPT_DIR}/src/"
 docker build -t "${IMAGE_NAME}" -f "Dockerfile" "${SCRIPT_DIR}"
 docker create --name "${CONTAINER_NAME}" "${IMAGE_NAME}"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.efi" \
-    "${SCRIPT_DIR}/project/Tutorial.efi"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.map" \
-    "${SCRIPT_DIR}/project/Tutorial.map"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.debug" \
-    "${SCRIPT_DIR}/project/Tutorial.debug"
+
+for file_ext in efi map debug; do
+    docker cp \
+        "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.efi" \
+        "${SCRIPT_DIR}/project/Tutorial.${file_ext}"
+done
+
 docker rm -f "${CONTAINER_NAME}"
+
+# ensure corpus
+if [ ! -d "${SCRIPT_DIR}/corpus" ]; then
+    mkdir "${SCRIPT_DIR}/corpus"
+    curl -L -o "${SCRIPT_DIR}/corpus/0" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/0
+    curl -L -o "${SCRIPT_DIR}/corpus/1" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/1
+    curl -L -o "${SCRIPT_DIR}/corpus/2" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/2
+    curl -L -o "${SCRIPT_DIR}/corpus/3" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/3
+fi
 ```
 
 The script will build the image, create a container using it, copy the relevant files
 to our host machine (in a `project` directory), then delete the container.
 
-Mark the script executable and then we'll go ahead and run it with:
-
+Let's go ahead and run it:
 ```sh
-chmod +x build.sh
 ./build.sh
-```
+```

docs/src/tutorials/edk2-uefi/configuring-the-fuzzer.md

@@ -75,18 +75,15 @@ Re-compile the application by running the build script.
 
 ## Obtain a Corpus
 
-The fuzzer will take input from the `corpus` directory in the project directory, so
-we'll create that directory and add some sample certificate files in DER format as
-our input corpus.
-
-```sh
-mkdir corpus
-curl -L -o corpus/0 https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/0
-curl -L -o corpus/1 https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/1
-curl -L -o corpus/2 https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/2
-curl -L -o corpus/3 https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/3
+The fuzzer will take input from the `corpus` directory located under `edk2-uefi`:
+
+```python
+@tsffs.corpus_directory = SIM_lookup_file("%simics%/../corpus")
 ```
 
+In `build.sh` we have already created that directory and added some sample
+certificate files in DER format as our input corpus.
+
 ## Configuring the Fuzzer
 
 Even though we loaded the fuzzer module, it didn't run previously because we did not
@@ -95,14 +92,14 @@ script, we'll add each of the following lines.
 
 First, we need to create an actual `tsffs` object to instantiate the fuzzer.
 
-```simics
+```python
 load-module tsffs # You should already have this
 init-tsffs
 ```
 
 Next, we'll set the log level to maximum for demonstration purposes:
 
-```simics
+```python
 tsffs.log-level 4
 ```
 
@@ -111,7 +108,7 @@ into our UEFI application. This is the default, so these calls can be skipped in
 usage unless you want to change the defaults, they are just provided here for
 completeness.
 
-```simics
+```python
 @tsffs.start_on_harness = True
 @tsffs.stop_on_harness = True
 ```
@@ -121,24 +118,28 @@ fuzz for. In our case, these are timeouts (we'll set the timeout to 3 seconds) t
 hangs, and CPU exceptions. we'll enable exceptions 13 for general protection fault and
 14 for page faults to detect out of bounds reads and writes.
 
-```simics
+```python
 @tsffs.timeout = 3.0
 @tsffs.exceptions = [13, 14]
 ```
 
-We'll tell the fuzzer where to take its corpus and save its solutions. The fuzzer will
-take its corpus from the `corpus` directory and save solutions to the `solutions`
-directory in the project by default, so this call can be skipped in real usage unless
-you want to change the defaults.
+By default, TSFFS expects the `corpus` and `solutions` directories to be located within
+the Simics project directory.
+
+However, Since our fuzzer is configured to read its corpus from the `../corpus`
+directory (relative to the `project` directory), we must explicitly specify the
+correct path using the following configuration:
 
-```simics
-@tsffs.corpus_directory = SIM_lookup_file("%simics%/corpus")
+```python
+# project/../corpus
+@tsffs.corpus_directory = SIM_lookup_file("%simics%/../corpus")
+# set solutions directory (default location, explicitly defined for clarity)
 @tsffs.solutions_directory = SIM_lookup_file("%simics%/solutions")
 ```
 
 We'll also *delete* the following code from the `run.simics` script:
 
-```simics
+```python
 script-branch {
   bp.time.wait-for seconds = 30
   quit 0

docs/src/tutorials/edk2-uefi/testing-the-application.md

@@ -18,13 +18,13 @@ You should see (at least, but likely more packages):
 ```txt
 Installed Base Packages
  Package Number  Name         Version  Installed Paths
- 1000            Simics-Base  6.0.169  /home/rhart/simics/simics-6.0.169
+ 1000            Simics-Base  6.0.185  /home/rhart/simics/simics-6.0.185
 
 Installed Addon Packages
  Package Number  Name             Version    Installed Paths
- 2096            QSP-x86          6.0.70     /home/rhart/simics/simics-qsp-x86-6.0.70
- 8112            QSP-CPU          6.0.17     /home/rhart/simics/simics-qsp-cpu-6.0.17
- 31337           TSFFS            6.0.1      /home/rhart/simics/simics-tsffs-6.0.1
+ 2096            QSP-x86          6.0.73     /home/rhart/simics/simics-qsp-x86-6.0.73
+ 8112            QSP-CPU          6.0.21     /home/rhart/simics/simics-qsp-cpu-6.0.21
+ 31337           TSFFS            6.1.6      /home/rhart/simics/simics-tsffs-6.1.6
 ```
 
 in the list!
@@ -35,25 +35,27 @@ The build script for our application created a `project` directory for us if it
 exist, so we'll instantiate that directory as our project with `ispm`:
 
 ```sh
-ispm projects project --create 1000-6.0.185 2096-6.0.70 8112-6.0.17 31337-latest \
+ispm projects project --create 1000-6.0.185 2096-6.0.73 8112-6.0.21 31337-latest \
   --ignore-existing-files
 cd project
 ```
 
-## Get the Minimal Boot Disk
+## Minimal Boot Disk
 
 The TSFFS repository provides a boot disk called `minimal_boot_disk.craff` which
 provides a filesystem and the *Simics Agent* to allow us to easily download our UEFI
-application to the filesystem so we can run it. Copy the file
-`examples/rsrc/minimal_boot_disk.craff` into your `project` directory.
+application to the filesystem so we can run it.
+
+Note: this boot disk has already been copied by `build.sh` into the `project` directory
+in the previous step.
 
 ## Create a Script
 
 Our initial script will load (but not use *yet*) the TSFFS module, then configure and
 start our simple x86-64 platform and run our UEFI application. In the `project`
 directory, create `run.simics`:
 
-```simics
+```python
 # Load the TSFFS module (to make sure we can load it)
 load-module tsffs
 

docs/src/tutorials/edk2-uefi/writing-the-application.md

@@ -82,7 +82,7 @@ The exact meaning of all the entries in the `Tutorial.inf` file is out of scope
 tutorial, but in general this file declares the packages and libraries our application
 needs.
 
-```txt
+```ini
 [Defines]
   INF_VERSION                    = 0x00010005
   BASE_NAME                      = Tutorial
@@ -112,7 +112,7 @@ needs.
 The descriptor file also declares classes and libraries that are needed to build the
 whole platform including our application and requisite additional libraries.
 
-```txt
+```ini
 [Defines]
   PLATFORM_NAME                  = Tutorial
   PLATFORM_GUID                  = 0458dade-8b6e-4e45-b773-1b27cbda3e06
@@ -204,15 +204,14 @@ UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable) {
   Print(L"CA Certificate:\n");
   hexdump(CACert, CACertSize);
 
-  BOOLEAN Status = X509VerifyCert(Cert, CertSize, CACert, CACertSize);
+  X509VerifyCert(Cert, CertSize, CACert, CACertSize);
 
   if (Input) {
     FreePages(Input, EFI_SIZE_TO_PAGES(MaxInputSize));
   }
 
   return EFI_SUCCESS;
 }
-
 ```
 
 Now that we have some code, we'll move on to building.

examples/tutorials/edk2-uefi/.gitignore

@@ -1,2 +1,3 @@
 project/*
-!project/run.simics
+src/tsffs.h
+!project/run.simics

examples/tutorials/edk2-uefi/Dockerfile

@@ -4,9 +4,9 @@ ENV DEBIAN_FRONTEND=noninteractive
 
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 
-ENV EDK2_REPO_URL "https://github.com/tianocore/edk2.git"
-ENV EDK2_REPO_HASH "edk2-stable202505"
-ENV EDK2_PATH "/edk2"
+ENV EDK2_REPO_URL="https://github.com/tianocore/edk2.git"
+ENV EDK2_REPO_HASH="edk2-stable202505"
+ENV EDK2_PATH="/edk2"
 
 
 RUN git clone "${EDK2_REPO_URL}" "${EDK2_PATH}" && \

examples/tutorials/edk2-uefi/build.sh

@@ -11,15 +11,27 @@ CONTAINER_UID=$(echo "${RANDOM}" | sha256sum | head -c 8)
 CONTAINER_NAME="${IMAGE_NAME}-tmp-${CONTAINER_UID}"
 
 mkdir -p "${SCRIPT_DIR}/project/"
+# copy minimal boot disk
+cp "${SCRIPT_DIR}/../../rsrc/minimal_boot_disk.craff" "${SCRIPT_DIR}/project/"
+
+# copy tsffs.h header into src
+cp "${SCRIPT_DIR}/../../../harness/tsffs.h" "${SCRIPT_DIR}/src/"
 docker build -t "${IMAGE_NAME}" -f "Dockerfile" "${SCRIPT_DIR}"
 docker create --name "${CONTAINER_NAME}" "${IMAGE_NAME}"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.efi" \
-    "${SCRIPT_DIR}/project/Tutorial.efi"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.map" \
-    "${SCRIPT_DIR}/project/Tutorial.map"
-docker cp \
-    "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.debug" \
-    "${SCRIPT_DIR}/project/Tutorial.debug"
-docker rm -f "${CONTAINER_NAME}"
+
+for file_ext in efi map debug; do
+    docker cp \
+        "${CONTAINER_NAME}:/edk2/Tutorial/Build/CryptoPkg/All/DEBUG_GCC/X64/Tutorial/Tutorial/DEBUG/Tutorial.${file_ext}" \
+        "${SCRIPT_DIR}/project/Tutorial.${file_ext}"
+done
+
+docker rm -f "${CONTAINER_NAME}"
+
+# ensure corpus
+if [ ! -d "${SCRIPT_DIR}/corpus" ]; then
+    mkdir "${SCRIPT_DIR}/corpus"
+    curl -L -o "${SCRIPT_DIR}/corpus/0" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/0
+    curl -L -o "${SCRIPT_DIR}/corpus/1" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/1
+    curl -L -o "${SCRIPT_DIR}/corpus/2" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/2
+    curl -L -o "${SCRIPT_DIR}/corpus/3" https://github.com/dvyukov/go-fuzz-corpus/raw/master/x509/certificate/corpus/3
+fi