Overview 

Hafnium is a reference Secure Partition Manager (SPM) for systems that implement the Armv8.4-A Secure-EL2 extension. It enables multiple, isolated Secure Partitions (SPs) to run at Secure-EL1. 

The Total Compute software stack also includes the BL32 (SPM), which is implemented as a Hafnium software component. You can find the introduction information at Total Compute Platform Software Components. 

The following figure shows the software stack of the TC platform: 

The TC software stack can support both the buildroot and Android file systems, because Hafnium is part of firmware. This guide uses the buildroot file system as an example.

Debugging Hafnium on the TC Platform requires three major steps:

Step 1: Set up the workspace

Step 2: Work on the Hafnium

Step 3: Set up Arm DS to debug Hafnium

Step 1: Set up the workspace 

Perform the following steps to build the whole software stack. Consider the buildroot file system as an example. For more information about seting up workspace, see the Total Compute (TC) User Guide.

1. Download and set up the workspace.

The content of the workspace directory is as follows: 

2. Build the software stack.

For example, you can use the build command ./run_docker.sh ./build-all.sh build. After the build is successfully complete, the output images are as follows:

3. Run the related image as follows to boot up successfully:

./run-scripts/tc2/run_model.sh -m <model binary path> -d buildroot

Step 2: Work on the Hafnium

The boot flow of AP firmware is as follows:

BL1 --> BL2 --> BL1 --> BL31 --> BL32(SPM) --> BL31 --> BL33

For the AP firmware, the SPM (Hafnium) is booted as a BL32 image. You can perform the following steps to add the debug option and rebuild the Hafnium to further debug.

1. Enable the debug build option.

Add the debug build option to ensure that the symbol file can be used for later debugging as follows:

diff --git a/build/BUILD.gn b/build/BUILD.gn
index 1baac1ba..80b9f44d 100644
--- a/build/BUILD.gn
+++ b/build/BUILD.gn
@@ -20,6 +20,7 @@ config("compiler_defaults") {
     "-fstack-protector-all",
   ]

+  asmflags = ["-g"]
   cflags_c = [ "-std=c11" ]

   cflags_cc = [ "-std=c++2a" ]

2. Modify and build Hafnium seperatly.

The build scirpt build-scripts/build-hafnium.sh can be used to build the Hafnium seperately, but the hafnium.bin image is added into the FIP package. Therefore, when you modify and build the source code of Hafnium, you must re-package again. The steps can be as follows:

 

build-scripts/run_docker.sh build-scripts/build-hafnium.sh build
build-scripts/run_docker.sh build-scripts/build-hafnium.sh deploy
build-scripts/run_docker.sh build-scripts/build-tfa.sh build
build-scripts/run_docker.sh build-scripts/build-tfa.sh deploy
build-scripts/run_docker.sh build-scripts/build-flash-image.sh build
build-scripts/run_docker.sh build-scripts/build-flash-image.sh deploy

Step 3: Set up Arm DS to debug Hafnium 

Perform the following steps:

1. Import the TC22 FVP model by following steps:

A. Click Arm DS Debug Control pannel, and select Debug Congtrol--> New Debug Connection as follows:




B. Choose Model Connection.

Specify the Debug connection name, such as TC22-Hafnium-debug as follows:

C.  Add New Model.  

Click the Next button for Target Selection. You can select Add a new model ... as follows:

D. Configure the FVP Model Path.

Choose Select Model Interface(Iris)--> Next--> Launch and connect to specific model --> Next, and browse the Model Path to select the downloaded file path of TC22 model as follows:

E. Show the Imported model.

The model is imported as follows:

2. Connect the model.

Perform the following steps:

A. Find the created debug connection.

Open the Debug Configrations as follows:

B. Configure the model parameters.

For example, copy below model paramters into the label as follows:

-C board.flashloader0.fname=/data/jetzho01/tc22-2023.04.21/build-scripts/output/deploy/tc2/fip_gpt-tc.bin -C css.rss.rom.raw_image=/data/jetzho01/tc22-2023.04.21/build-scripts/output/deploy/tc2/rss_rom.bin -C css.scp.c0_pik.rvbaraddr_lw=0x1000 -C css.scp.c0_pik.rvbaraddr_up=0x0000 -C css.rss.VMADDRWIDTH=23 -C css.rss.CMU0_NUM_DB_CH=16 -C displayController=2 -C board.smsc_91c111.enabled=1 -C board.hostbridge.userNetworking=1 -C board.hostbridge.userNetPorts="5555=5555,8080=80,8022=22" --data board.dram=/data/jetzho01/tc22-2023.04.21/build-scripts/output/deploy/tc2/tc-fitImage.bin@0x20000000

C. Set the Debug Configurations.

 1). Load the symbol files to apply and debug as follows:

2). On the window that opens, choose Debugger -> Connect only -> Execute debugger commands, and copy-paste the following lines into the text box to automatically load all symbols into the correct virtual address space each time you connect to the model:

add-symbol-file "<workspace>/build-scripts/output/tmp_build/tfa/build/tc/debug/bl1/bl1.elf" EL3:0x0
add-symbol-file "<workspace>/build-scripts/output/tmp_build/tfa/build/tc/debug/bl2/bl2.elf" EL1S:0x0
add-symbol-file "<workspace>/build-scripts/output/tmp_build/tfa/build/tc/debug/bl31/bl31.elf" EL3:0x0
add-symbol-file "<workspace>/build-scripts/output/tmp_build/hafnium/secure_tc_clang/hafnium.elf" EL2S:0x0

3). Replace <workspace> with the path to your workspace directory.

Each command includes an EL number at the end of it, for example EL2S:0.It ensures that the symbols are loaded into the correct virtual address space and at the correct memory offset. For software to use absolute addresses for its symbols, ensure that the offset is 0.

4). Click Apply -> Debug to connect to the paused model.

You can now step through the Hafnium code or set a breakpoint on the symbol corresponding to the functionality that you are interested in.

3 Debug entrypoint for Hafnium.

A. Find the entrypoint for the Hafnium image.

Entry point of the Hafnium code piece is here, for example:

.section .init.entry, "ax"
.global entry
entry:
	/* Linux aarch64 image header. */
	b 0f
	.word 0
	.quad 0x1000      /* text_offset */
	.quad image_size  /* image_size */
	.quad 0           /* flags */
	.quad 0           /* res2 */
	.quad 0           /* res3 */
	.quad 0           /* res4 */
	.word 0x644d5241  /* magic */
	.word 0

	/*
	 * Calculate the difference between the actual load address and the
	 * preferred one. We'll use this to relocate.
	 */
0:	adrp x25, entry
	add x25, x25, :lo12:entry

Regarding the entrypoint (loading address) of Hafnium for the TC22 platform, the Hafnium (BL32) is loaded by AP BL2. The image address is defined as BL32_BASE, which can be found at here. Specifically for the TC22 platform, the address is redefined as:

"#define TC_EL2SPMC_LOAD_ADDR            (TC_TZC_DRAM1_BASE + 0x04000000)"

The TC_TZC_DRAM1_BASE is defined as 0xF900_0000, so the loading address for Hafnium (BL32_BASE) is 0xFD00_0000.

More platform definitions about this can be found here.

B. Stop at the entrypoint.

Set the breakpoint of entry, which is the entrypoint of Hafnium as follows:

C. Check the entry address of Hafnium. 

Then click the Run button to run the software stack, and it stops at the first instruction. The address is 0xFD000000 as follows:

              

About debugging other related functions

The following figure shows you the initialization flow of Hafnium:

Example: one_time_init function

Consider the example of setting a breakpoint of one_time_init. You can instruct the debug to jump into the function one_time_init as shown in the following figure: