docs: add GDB stub and source-level debugging to reproducing-runs tutorial

[Wenzel]

No description provided.

[Copilot]

Pull request overview

Updates the EDK2 UEFI “Reproducing Runs” tutorial to document attaching a GDB remote stub and performing source-level debugging, and adjusts the tutorial build script to copy EDK2 sources locally to support symbol/source mapping.

Changes:

• Copy /edk2 sources out of the Docker build container to enable source-level debugging workflows.
• Expand the reproducing-runs tutorial with sections on GDB stub usage and loading symbols/source paths.
• Add a cross-link from the “Disable Auto-Continue in Repro Mode” config option to the new GDB-stub walkthrough.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
examples/tutorials/edk2-uefi/build.sh	Copies EDK2 sources from the container to the host for GDB source mapping.
docs/src/tutorials/edk2-uefi/reproducing-runs.md	Adds detailed GDB-stub + source-level debugging walkthrough to the repro tutorial.
docs/src/config/common-options.md	Links config option docs to the new tutorial walkthrough section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The intro links “repro functionality” to the “Disable Auto-Continue in Repro Mode” option, but that section is specifically about pausing before execution rather than explaining repro mode itself. Consider linking “repro mode/functionality” to the general repro documentation (e.g., docs/src/fuzzing/analyzing-results.md) and keep the auto-continue section linked where you discuss attaching a debugger.

Suggested change

	but we can still test the ["repro" functionality](../../config/common-options.md#disable-auto-continue-in-repro-mode) which allows you to replay an execution
	but we can still test the ["repro" functionality](../../fuzzing/analyzing-results.md) which allows you to replay an execution

[Copilot]

rm -rf + docker cp can leave a large edk2/ directory in the working tree on every build (and it’s not currently ignored by examples/tutorials/edk2-uefi/.gitignore), which can create significant disk usage and noisy git status. Consider making the source copy opt-in (e.g., env var/flag) and/or copying only the minimal subtrees needed for debugging, and add edk2/ to the tutorial’s .gitignore if it’s expected to be generated.

Suggested change

	# copy edk2 sources for source-level GDB debugging
	# rm -rf first to work around a docker cp bug where existing directories are not updated
	rm -rf "${SCRIPT_DIR}/edk2"
	docker cp "${CONTAINER_NAME}:/edk2" "${SCRIPT_DIR}/edk2"
	# copy edk2 sources for source-level GDB debugging (optional)
	# set EDK2_COPY_SOURCES=1 to enable; rm -rf first to work around a docker cp bug where existing directories are not updated
	if [ "${EDK2_COPY_SOURCES:-0}" != "0" ]; then
	rm -rf "${SCRIPT_DIR}/edk2"
	docker cp "${CONTAINER_NAME}:/edk2" "${SCRIPT_DIR}/edk2"
	fi

[Copilot]

Because the script uses set -e, any failure in the added docker cp step will exit before docker rm -f, leaving the temporary container behind. Consider adding a trap (e.g., trap 'docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true' EXIT) so the container is always cleaned up even when a copy/build step fails.

[Copilot]

The OS-awareness snippet uses uefi_fw_tracker_comp, which comes from the uefi-fw-tracker module. examples/tutorials/edk2-uefi/project/run.simics currently doesn’t load that module, and this section doesn’t mention adding load-module uefi-fw-tracker, so the commands here will fail if followed as-written. Please update the instructions to include loading uefi-fw-tracker (and indicate where it should be placed relative to load-target / run).

[Copilot]

The instructions say to add new-gdb-remote “after the run line”, but run starts the simulation and typically blocks script execution. If new-gdb-remote is placed after run, it likely won’t execute until the simulation stops (too late to attach before the testcase runs). Please adjust the guidance to start the GDB stub before run (or explicitly use a non-blocking run mode) and ensure the command-line -e new-gdb-remote example still executes at the intended time with run.simics as written.