Guide to create Petalinux project for OctopOS untrusted domain on the Split-Trust hardware

📎 OctopOS Paper 📙 OctopOS Technical Reference Manual

💻 OctopOS Repository 🔌 Split-Trust Hardware Repository

🔦 Formal Verification 🍺 Untrusted Domain Petalinux 🍺 OctopOS Emulator

Authors: Zhihao "Zephyr" Yao, Seyed Mohammadjavad Seyed Talebi, Mingyi Chen, Ardalan Amiri Sani, Thomas Anderson (Collectively, "The OctopOS Authors")

The work was supported by NSF Awards #1617513, #1718923, #1846230, and #1953932.

---

Table of Contents

• Guide to create Petalinux project for OctopOS untrusted domain on the Split-Trust hardware
  • Table of Contents
  • Prerequisites
  • Download a local copy of the Linux and U-Boot sources
  • Create a Petalinux project
  • Configure the Petalinux project
  • Alternative way to configure the Petalinux project
  • Build the Petalinux project
  • Notes on the Linux kernel binary size
  • Output final binaries

Prerequisites

• Petalinux 2020.1 and the BSP file for ZCU102 board (please refer to the Petalinux User Guide for details, https://docs.xilinx.com/v/u/2020.1-English/ug1144-petalinux-tools-reference-guide)

• A Linux desktop with at least 16GB RAM and 100GB free disk space. This machine does not have to be the same machine that prepares other OctopOS components.

Download a local copy of the Linux and U-Boot sources

Run the following commands to download the Linux and U-Boot sources:

   mkdir ~/octopos_untrusted_domain
   git clone https://github.com/trusslab/octopos_uboot.git octopos_uboot
   git clone https://github.com/trusslab/linux-xlnx.git sec_hw_linux

Create a Petalinux project

Use the xsa file (that is generated by Vivado for OctopOS hardware) to create a Petalinux project. Please refer to Step 1-5 in Populating Hardware Design and Launching OctopOS Software from Scratch (https://github.com/trusslab/octopos_hardware/blob/main/README.md) for details.

The Petalinux device tree relies on the correct name of OctopOS mailbox and other hardware components. Please make sure to use the correct xsa file. The sample xsa file provided by Xilinx does not have the block design for OctopOS and therefore will not work.

   cd ~/octopos_untrusted_domain
   petalinux-create --type project -s <PATH_TO_DOWNLOADED_BSP>/xilinx-zcu102-v2020.1-final.bsp --name untrusted
   
   petalinux-config --get-hw-description=<PATH_TO_THE_DIR_CONTAINING_OCTOPOS_XSA> 

The petalinux-config command can be repeated to change or update the hardware xsa file.

Configure the Petalinux project

Run the following commands to configure the Petalinux project:

   cd ~/octopos_untrusted_domain/untrusted
   petalinux-config

In the petalinux-config menu, select the following options:

• Change Linux source to local,

Linux Components Selection -> linux-kernel -> select (ext-local-src), and input the absolute path of the Linux source code downloaded in the previous step (e.g., ~/octopos_untrusted_domain/sec_hw_linux).

• Change U-Boot source to local,

U-Boot Components Selection -> u-boot -> select (ext-local-src), and input the absolute path of the U-Boot source code downloaded in the previous step (e.g., ~/octopos_untrusted_domain/octopos_uboot).

• Change boot configure

Image Packaging Configuration -> Device node of SD device", type "/dev/octopos_blk. This will enable rootfs from OctopOS storage domain.

Image Packaging Configuration -> Root filesystem type, select EXT4 (SD/eMMC/SATA/USB)

Make sure the "Image Packaging Configuration" looks exactly like the following:

   (/dev/octopos_blk) Device node of SD device 
   (image.ub) name for bootable kernel image 
   (cpio cpio.gz cpio.gz.u-boot tar.gz jffs2) Root filesystem format
   (0x1000) DTB padding size

Please ignore tftpboot related options and warnings.

• Config UART

Subsystem AUTO Hardware Settings -> Serial Settings, select psu_uart_0 for all the output sources, and use 115200 as the baud rate.

• Config Ethernet

Subsystem AUTO Hardware Settings -> Ethernet Settings, configure as follows:

    Primary Ethernet (ethernet_subsystem_axi_ethernet_0) 
    [ ] Randomise MAC address                                        
    (00:0a:35:00:22:01) Ethernet MAC address                         
    [ ] Obtain IP address automatically                              
    (192.168.0.10) Static IP ddress                                  
    (255.255.255.0) Static IP netmask
    (192.168.0.1) Static IP gateway  

• Reserve memory for OctopOS Storage Domain as its storage media

Subsystem AUTO Hardware Settings -> Memory Settings, configure as follows:

   Primary Memory (psu_ddr_0)
   (0x40000000) System memory base address 
   (0x3fffffff) System memory size 
   (0x0) kernel base address
   (0x100000) u-boot text base address offset to memory base address

Alternative way to configure the Petalinux project

We provide the pre-configured Petalinux project configuration files in the following directory: sec_hw_linux/samples/octopos/untrusted_domain/petalinux_config

You can copy the files (please backup the original configuration files before overwriting them) to the Petalinux project directory (~/octopos_untrusted_domain/untrusted/project-spec/configs/). Edit the LOCAL_U_BOOT and LOCAL_LINUX path in the config file to match your local path.

In addition to the above configuration, our configuration file also disables some Linux and rootfs features for binary size reduction, which is equivalent to the following configuration:

In the kernel configuration (petalinux-config -c kernel), turned off these features: PCI bus; MTD; Serial ATA; SPI; GPIO; Multimedia; Sound; USB; LED; Virtio; Staging driver; extcon; Industrial IO; Reliability; Android; FPGA.

In root file configuration (petalinux-config -c rootfs), turned off these features: fpga management; havged; mtd-utils; pciutils; run-postinsts; udev-extraconf;packagegroup-core-ssh-dropbear; tcf-agent; watchdog-init; hellopm; hwcodecs; debug-tweaks.

Build the Petalinux project

Run the following commands to build the Petalinux project:

    petalinux-build

The build process will take up to an hour to complete.

After a successful build, run the following command to patch the device tree:

    cp ~/octopos_untrusted_domain/sec_hw_linux/samples/octopos/untrusted_domain/device-tree/system-user.dtsi ~/octopos_untrusted_domain/untrusted/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

This will disable uart, amba_pl controller, and other resources that are not used by the untrusted domain.

Run the following commands to build the Petalinux project again:

    petalinux-build

The second build will take about about a few minutes to complete.

Binaries are generated in the following directory:

~/octopos_untrusted_domain/untrusted/images/linux

Notes on the Linux kernel binary size

Because the size of Linux kernel binary is unknown, when our modified u-boot loads the Linux kernel from OctopOS storage domain, it does not know when to stop. Therefore, we have to manually provide the size of the Linux kernel binary to u-boot.

After a successful build, open ~/octopos_untrusted_domain/octopos_uboot/fs/fs.c, and find the following line:

   int block_size = xxxx;

Replace xxxx with the size of the Linux kernel binary in bytes / 512.

Finally, rebuild Petalinux,

    petalinux-build

Output final binaries

Binaries are generated in the following directory:

~/octopos_untrusted_domain/untrusted/images/linux

Provide this path (or any path containing the same files) to the OctopOS configuration file in Step 23 of Populating Hardware Design and Launching OctopOS Software from Scratch (https://github.com/trusslab/octopos/README.md)