Getting started

Install Rust from rustup, then some other tools and the target we need:

$ sudo apt install clang build-essential lld
$ rustup target add aarch64-unknown-none-softfloat
$ rustup component add llvm-tools
$ cargo install cargo-binutils

Add your SSH public key then get the source:

$ git clone ssh://$TF_USERNAME@review.trustedfirmware.org:29418/RF-A/rusted-firmware-a
$ cd rusted-firmware-a

Also fetch the Trusted Firmware-A repository and record its path into the TFA environment variable:

$ git clone ssh://$TF_USERNAME@review.trustedfirmware.org:29418/TF-A/trusted-firmware-a
$ export TFA=`pwd`/trusted-firmware-a

Getting started with QEMU

Install the required QEMU dependencies:

$ sudo apt install qemu-system-arm

Build and run in QEMU

Build C BL1 and BL2 and Rust BL31:

$ make TFA_FLAGS="CC=clang NEED_BL32=yes NEED_BL31=no" \
    PLAT=qemu DEBUG=1 all

Build Rust BL31 and run in QEMU:

$ make DEBUG=1 qemu

Debugging with QEMU

To connect GDB to QEMU:

$ make PLAT=qemu DEBUG=1 qemu-wait

Then, in a separate terminal window, attach gdb:

$ make PLAT=qemu DEBUG=1 gdb

If you want QEMU's gdb listener listen on a port other than the default (which is 1234), specify the GDB_PORT environment variable in both make invocations:

$ GDB_PORT=4096 make PLAT=qemu DEBUG=1 qemu-wait

# In your 2nd terminal, of course:
$ GDB_PORT=4096 make PLAT=qemu DEBUG=1 gdb

(This could be useful if you needed to run many instances of QEMU, such as to run many tests in parallel.)

Getting started with FVP

Arm FVPs are complete simulations of an Arm system, including processor, memory and peripherals. They enable software development without the need for real hardware.

There exists many types of FVPs.

The rust Makefile is currently using FVP_Base_RevC-2xAEMvA to run the FVP. Please refer to this link to download this or any other FVP.

Build and run in FVP

Without RME support

Build C BL1 and BL2, Rust BL31 and FIP, then run everything in FVP:

$ make TFA_FLAGS="FVP_TRUSTED_SRAM_SIZE=512 SPD=spmd SPMD_SPM_AT_SEL2=0 NEED_BL31=no" \
    DEBUG=1 fvp

Note 1: In the above command, the user may notice that we use SPMD_SPM_AT_SEL2=0 even though the project is enabling S-EL2 using the default sel2 feature. The rusted-firmware-a project is currently leveraging on the trusted-firmware-a project's build system and the latter requires a SP layout file for building with SPMD_SPM_AT_SEL2=1. We currently use the temporary workaround of building with SPMD_SPM_AT_SEL2=0 to avoid using this sp layout file.

Note 2: By default, TF-A considers that the Base FVP platform has 256 kB of Trusted SRAM. Actually it can simulate up to 512 kB of Trusted SRAM, which is the configuration we use for RF-A (because a debug build of RF-A is too big to fit in 256 kB). The FVP_TRUSTED_SRAM_SIZE=512 TF-A build flag is required to stop TF-A from complaining that RF-A does not fit.

With RME support

Build C BL1 and BL2 with RME support, Rust BL31 with RME support and FIP:

$ make TFA_FLAGS="FVP_TRUSTED_SRAM_SIZE=512 ENABLE_RME=1 NEED_BL31=no" \
    FEATURES=rme DEBUG=1 fvp

Running the FVP with RME through RF-A build system is not supported at this time.

Documentation

Build the Rustdoc documentation for a given platform:

make PLAT=<platform> cargo-doc

... the built documentation will be found under target/<target>/doc/rf_a_bl31.

To display the documentation, open it with your preferred application of choice, for example:

xdg-open target/aarch64-unknown-none-softfloat/doc/rf_a_bl31/index.html