Merge branch 'ryarob01/shared-directory' into 'main'

config: Machanism to share files between host and FVP

See merge request tooling/shrinkwrap!30

8 files changed, 93 insertions, 21 deletions

diff --git a/config/cca-3world.yaml b/config/cca-3world.yaml
index 2b7695c..713ffe5 100644
--- a/config/cca-3world.yaml
+++ b/config/cca-3world.yaml
@@ -19,10 +19,13 @@ description: >-
   .. code-block:: shell
     $ shrinkwrap build cca-3world.yaml --overlay buildroot.yaml --btvar GUEST_ROOTFS='${artifact:BUILDROOT}'
 
-  Once built, the user must place some of the generated assets in their host's
-  rootfs. Or alternatively, for simplicity, they can reuse the guest filesystem
-  generated with buildroot as the host's rootfs, after resizing it so that there
-  is room for the guest's rootfs:
+  Once built, the user must get some of the generated artifacts into the FVP
+  environment. This can either be done by copying them to the host's rootfs or
+  by sharing them into the FVP using 9p.
+
+  If copying to the rootfs, something like this should work. For simplicity,
+  this example reuses the guest filesystem generated with buildroot as the
+  host's rootfs, after resizing it so that there is room for the guest's rootfs:
 
   .. code-block:: shell
     $ cd ~/.shrinkwrap/package/cca-3world
@@ -47,10 +50,20 @@ description: >-
   .. code-block:: shell
     $ shrinkwrap run cca-3world.yaml -r ROOTFS=rootfs.ext2 --rtvar CMDLINE="mem=1G earlycon root=/dev/vda ip=dhcp acpi=force"
 
-  Once the host has booted, log in as "root" (no password), and launch a realm
-  using kvmtool:
+  Or if taking the shared directory approach, simply boot the host with the
+  SHARE rtvar. This only works for DT-based environments:
+
+  .. code-block:: shell
+    $ cd ~/.shrinkwrap/package/cca-3world
+    $ shrinkwrap run cca-3world.yaml --rtvar ROOTFS=rootfs.ext2 SHARE=.
+
+  Finally, once the host has booted, log in as "root" (no password), and launch
+  a realm using kvmtool. Note the mount command is only required if sharing a
+  directory:
 
   .. code-block:: shell
+    # mkdir /cca
+    # mount -t 9p -o trans=virtio,version=9p2000.L FM /cca
     # cd /cca
     # ./lkvm run --realm --disable-sve --irqchip=gicv3-its --firmware KVMTOOL_EFI.fd -c 1 -m 512 --no-pvtime --force-pci --disk guest-disk.img --measurement-algo=sha256
 
diff --git a/config/ns-edk2.yaml b/config/ns-edk2.yaml
index 96406bb..b6f321b 100644
--- a/config/ns-edk2.yaml
+++ b/config/ns-edk2.yaml
@@ -31,6 +31,15 @@ description: >-
   booting UEFI to its UI, override the EDK2FLASH rtvar with an empty string and
   override terminals.'bp.terminal_0'.type to 'telnet'.
 
+  When booting with device tree, a directory can optionally be shared from the
+  host system into the Linux environment running in the FVP. To do so, set the
+  SHARE rtvar to the desired directory, then mount the share inside the FVP with
+  the following (or automate it in fstab):
+
+  .. code-block:: shell
+    # mkdir /share
+    # mount -t 9p -o trans=virtio,version=9p2000.L FM /share
+
 concrete: true
 
 layers:
@@ -74,6 +83,10 @@ run:
       type: path
       value: ''
 
+    SHARE:
+      type: path
+      value: ''
+
     EDK2FLASH:
       type: path
       value: ${artifact:EDK2FLASH}
@@ -84,6 +97,7 @@ run:
     -C bp.virtioblockdevice.image_path: ${rtvar:ROOTFS}
     -C cluster0.cpu0.semihosting-cwd: $${SEMIHOSTDIR}
     -C bp.flashloader1.fname: ${rtvar:EDK2FLASH}
+    -C bp.virtiop9device.root_path: ${rtvar:SHARE}
 
   prerun:
     # We use the FVP's and UEFI's semihosting capability to get the images into
diff --git a/config/ns-preload.yaml b/config/ns-preload.yaml
index 8505a6b..a50640b 100644
--- a/config/ns-preload.yaml
+++ b/config/ns-preload.yaml
@@ -23,6 +23,15 @@ description: >-
   specified at build time, since the command line is added to the chosen node of
   the default dtb.
 
+  A directory can optionally be shared from the host system into the Linux
+  environment running in the FVP. To do so, set the SHARE rtvar to the desired
+  directory, then mount the share inside the FVP with the following (or automate
+  it in fstab):
+
+  .. code-block:: shell
+    # mkdir /share
+    # mount -t 9p -o trans=virtio,version=9p2000.L FM /share
+
 concrete: true
 
 layers:
@@ -63,6 +72,10 @@ run:
       type: path
       value: ''
 
+    SHARE:
+      type: path
+      value: ''
+
   params:
     -C cluster0.cpu0.RVBAR: 0x04001000
     -C cluster0.cpu1.RVBAR: 0x04001000
@@ -76,6 +89,7 @@ run:
     ' --data cluster0.cpu0': ${rtvar:DTB}@0x82000000
     '  --data cluster0.cpu0': ${rtvar:KERNEL}@0x84000000
     -C bp.virtioblockdevice.image_path: ${rtvar:ROOTFS}
+    -C bp.virtiop9device.root_path: ${rtvar:SHARE}
 
   terminals:
     bp.terminal_0:
diff --git a/documentation/userguide/configstore/cca-3world.rst b/documentation/userguide/configstore/cca-3world.rst
index 9a22138..3c947b9 100644
--- a/documentation/userguide/configstore/cca-3world.rst
+++ b/documentation/userguide/configstore/cca-3world.rst
@@ -19,7 +19,9 @@ If the user provides an ext2/4 filesystem image via the GUEST_ROOTFS btvar, a gu
   $ shrinkwrap build cca-3world.yaml --overlay buildroot.yaml --btvar GUEST_ROOTFS='${artifact:BUILDROOT}'
 
 
-Once built, the user must place some of the generated assets in their host's rootfs. Or alternatively, for simplicity, they can reuse the guest filesystem generated with buildroot as the host's rootfs, after resizing it so that there is room for the guest's rootfs:
+Once built, the user must get some of the generated artifacts into the FVP environment. This can either be done by copying them to the host's rootfs or by sharing them into the FVP using 9p.
+
+If copying to the rootfs, something like this should work. For simplicity, this example reuses the guest filesystem generated with buildroot as the host's rootfs, after resizing it so that there is room for the guest's rootfs:
 
 .. code-block:: shell
 
@@ -50,10 +52,20 @@ Or alternatively, using ACPI:
   $ shrinkwrap run cca-3world.yaml -r ROOTFS=rootfs.ext2 --rtvar CMDLINE="mem=1G earlycon root=/dev/vda ip=dhcp acpi=force"
 
 
-Once the host has booted, log in as "root" (no password), and launch a realm using kvmtool:
+Or if taking the shared directory approach, simply boot the host with the SHARE rtvar. This only works for DT-based environments:
+
+.. code-block:: shell
+
+  $ cd ~/.shrinkwrap/package/cca-3world
+  $ shrinkwrap run cca-3world.yaml --rtvar ROOTFS=rootfs.ext2 SHARE=.
+
+
+Finally, once the host has booted, log in as "root" (no password), and launch a realm using kvmtool. Note the mount command is only required if sharing a directory:
 
 .. code-block:: shell
 
+  # mkdir /cca
+  # mount -t 9p -o trans=virtio,version=9p2000.L FM /cca
   # cd /cca
   # ./lkvm run --realm --disable-sve --irqchip=gicv3-its --firmware KVMTOOL_EFI.fd -c 1 -m 512 --no-pvtime --force-pci --disk guest-disk.img --measurement-algo=sha256
 
@@ -89,6 +101,7 @@ DTB            ${artifact:DTB}
 CMDLINE        console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp
 KERNEL         ${artifact:KERNEL}
 ROOTFS         <empty>
+SHARE          <empty>
 EDK2FLASH      ${artifact:EDK2FLASH}
 ============== ===============================================================
 
diff --git a/documentation/userguide/configstore/cca-4world.rst b/documentation/userguide/configstore/cca-4world.rst
index 0fd6a1d..81e9247 100644
--- a/documentation/userguide/configstore/cca-4world.rst
+++ b/documentation/userguide/configstore/cca-4world.rst
@@ -39,6 +39,7 @@ DTB            ${artifact:DTB}
 CMDLINE        console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp
 KERNEL         ${artifact:KERNEL}
 ROOTFS         <empty>
+SHARE          <empty>
 EDK2FLASH      ${artifact:EDK2FLASH}
 ============== ===============================================================
 
diff --git a/documentation/userguide/configstore/ffa-tftf.rst b/documentation/userguide/configstore/ffa-tftf.rst
index 8700871..d377cb6 100644
--- a/documentation/userguide/configstore/ffa-tftf.rst
+++ b/documentation/userguide/configstore/ffa-tftf.rst
@@ -38,6 +38,7 @@ DTB            ${artifact:DTB}
 CMDLINE        console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp
 KERNEL         <null>                                                         
 ROOTFS         <empty>                                                        
+SHARE          <empty>                                                        
 EDK2FLASH      ${artifact:EDK2FLASH}                                          
 ============== ===============================================================
 
diff --git a/documentation/userguide/configstore/ns-edk2.rst b/documentation/userguide/configstore/ns-edk2.rst
index 915b572..3ac99d6 100644
--- a/documentation/userguide/configstore/ns-edk2.rst
+++ b/documentation/userguide/configstore/ns-edk2.rst
@@ -20,6 +20,13 @@ By default (if not overriding the rtvars) a sensible command line is used that w
 
 Note that by default, a pre-canned flash image is loaded into the model, which contains UEFI variables directing EDK2 to boot to the shell. This will cause startup.nsh to be executed and will start the kernel boot. This way everything is automatic. By default, all EDK2 output is muxed to stdout. If you prefer booting UEFI to its UI, override the EDK2FLASH rtvar with an empty string and override terminals.'bp.terminal_0'.type to 'telnet'.
 
+When booting with device tree, a directory can optionally be shared from the host system into the Linux environment running in the FVP. To do so, set the SHARE rtvar to the desired directory, then mount the share inside the FVP with the following (or automate it in fstab):
+
+.. code-block:: shell
+
+  # mkdir /share
+  # mount -t 9p -o trans=virtio,version=9p2000.L FM /share
+
 Concrete
 ########
 
@@ -37,15 +44,16 @@ Run-Time Variables
 ##################
 
 ============== ===============================================================
-rtvar          default                                                        
+rtvar          default
 ============== ===============================================================
-LOCAL_NET_PORT 8022                                                           
-BL1            ${artifact:BL1}                                                
-FIP            ${artifact:FIP}                                                
-DTB            ${artifact:DTB}                                                
+LOCAL_NET_PORT 8022
+BL1            ${artifact:BL1}
+FIP            ${artifact:FIP}
+DTB            ${artifact:DTB}
 CMDLINE        console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp
-KERNEL         <null>                                                         
-ROOTFS         <empty>                                                        
-EDK2FLASH      ${artifact:EDK2FLASH}                                          
+KERNEL         <null>
+ROOTFS         <empty>
+SHARE          <empty>
+EDK2FLASH      ${artifact:EDK2FLASH}
 ============== ===============================================================
 
diff --git a/documentation/userguide/configstore/ns-preload.rst b/documentation/userguide/configstore/ns-preload.rst
index 3bc3a5b..4531fd0 100644
--- a/documentation/userguide/configstore/ns-preload.rst
+++ b/documentation/userguide/configstore/ns-preload.rst
@@ -16,6 +16,13 @@ A simple, non-secure-only configuration where all components are preloaded into
 
 By default (if not overriding the rtvars), the upstream kernel device tree is used along with a sensible command line that will set up the console for logging and attempt to mount the rootfs image from the FVP's virtio block device. However the default rootfs image is empty, so the kernel will panic when attempting to mount; the user must supply a rootfs if it is required that the kernel completes its boot. No default kernel image is supplied and the config will refuse to run unless it is explicitly specified.  Note: If specifying a custom dtb at runtime, this will also override any command line specified at build time, since the command line is added to the chosen node of the default dtb.
 
+A directory can optionally be shared from the host system into the Linux environment running in the FVP. To do so, set the SHARE rtvar to the desired directory, then mount the share inside the FVP with the following (or automate it in fstab):
+
+.. code-block:: shell
+
+  # mkdir /share
+  # mount -t 9p -o trans=virtio,version=9p2000.L FM /share
+
 Concrete
 ########
 
@@ -33,12 +40,13 @@ Run-Time Variables
 ##################
 
 ============== ================
-rtvar          default         
+rtvar          default
 ============== ================
-LOCAL_NET_PORT 8022            
+LOCAL_NET_PORT 8022
 BL31           ${artifact:BL31}
-DTB            ${artifact:DTB} 
-KERNEL         <null>          
-ROOTFS         <empty>         
+DTB            ${artifact:DTB}
+KERNEL         <null>
+ROOTFS         <empty>
+SHARE          <empty>
 ============== ================