meta-agl-jailhouse/meta-agl-jailhouse.md

   1 ## Jailhouse support layer
   2
   3
   4 Yocto layer that enables the use of the Jailhouse partitioning hypervisor - <https://github.com/siemens/jailhouse>.
   5
   6 ### How to Enable and Use
   7
   8 ### For QEmu x86_64
   9
  10 > Note: Right now the below setup is only working for Intel Machines.
  11
  12 The AGL feature `agl-jailhouse` has to be enabled. That needs to be done when including aglsetup.sh, for example:
  13
  14 ```sh
  15 $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b build agl-devel agl-jailhouse
  16 ```
  17
  18 That will enable this layer and include the `jailhouse` package in the image.
  19
  20
  21 Then, in the target system, the cell configurations (*.cell) are placed in `/usr/share/jailhouse/cells/` and the demo inmates (bare-metal applications to run in a non-root cell) are located in `/usr/share/jailhouse/inmates`.
  22
  23
  24 After that follow the [AGL-Documentation](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software/) as usual and build the image using `bitbake core-image-minimal`.
  25
  26
  27 After successfully building the image we need to QEmulate the Image using `runqemu`:
  28
  29
  30 ```sh
  31
  32 $ runqemu qemux86-64 slirp kvm publicvnc serial bootparams="verbose ipv6.disable=1 intel_iommu=off"
  33
  34 ```
  35
  36 After successful emulation of the Image, you will see something similar to this:
  37
  38
  39 ```sh
  40
  41 [ 0.021231] [Firmware Bug]: TSC_DEADLINE disabled due to Errata; please update microcode to version: 0xb2 (or later)
  42
  43 [ 0.588075] kvm: already loaded the other module
  44
  45 [ 0.926525] hdaudio hdaudioC0D0: Unable to bind the codec
  46
  47 Automotive Grade Linux 11.91.0 qemux86-64 ttyS0
  48
  49 qemux86-64 login: root
  50
  51 ```
  52
  53 ### For Running the Linux Cell
  54
  55
  56 In order to spin-up the Root cell and Inmates, you will need Cell Configurations (*.cell) and Inmates, which you will find at `/usr/share/jailhouse/cell` and `/usr/share/jailhouse/inmates`.
  57
  58
  59 But for Linux-Cell some preparation is needed and the things which you will require include:
  60
  61
  62 - `bzImage`
  63
  64 - `rootfs.cpio`
  65
  66
  67 These files you can find easily in the `build/tmp/deploy/images/qemux86-64/`.
  68
  69 After obtaining these files you have to `scp` these to the emulated Image.
  70
  71 Now you should have everything in the target system and you can now spin up the things but before that check, if `jailhouse` is present or not:
  72
  73 ```sh
  74
  75 qemux86-64:~# lsmod
  76
  77 Module Size Used by
  78
  79 jailhouse 36864 0
  80
  81 ```
  82 As you can see it’s showing present, In case if it’s not present then run `modprobe jailhouse`, it will load the Jailhouse kernel module.
  83
  84 After loading the module now we have to enable the Jailhouse-Root-Cell, enable this by the below command:
  85
  86 ```sh
  87
  88 qemux86-64:~# jailhouse enable /usr/share/jailhouse/cells/qemu-agl.cell
  89
  90 ```
  91
  92  And check the console for the logs.
  93
  94 After loading jailhouse Root-cell, now we have to load the Non-root Linux cell, so for that run the below commands:
  95
  96
  97 ```sh
  98
  99 qemux86-64:~# jailhouse cell linux /usr/share/jailhouse/cells/agl-linux-x86-demo.cell bzImage -i rootfs.cpio -w out.file -c "console=ttyS2,115200 earlycon earlyprintk"
 100
 101 ```
 102
 103
 104 > Note: In the above command, when you add the `-w out.file` option then it will spit out some commands to start the non-root cell, if not then the cell will boot as usual. Those spitted out commands would look something like these below, you have to run it one by one:
 105
 106
 107
 108 ```sh
 109
 110 qemux86-64:~# jailhouse cell create /usr/share/jailhouse/cells/agl-linux-x86-demo.cell
 111
 112 qemux86-64:~# jailhouse cell load linux-x86-demo linux-loader.bin -a 0x0 bzImage -a 0xffc600 rootfs.cpio -a 0x3d89000 out.file -a 0x1000
 113
 114 qemux86-64:~# jailhouse cell start linux-x86-demo.cell
 115
 116 ```
 117
 118 > Note: As you can see in the spit-out commands there is a `linux-loader.bin` is present, this is a tiny bootloader that is required to boot the Linux-inmate or Linux-non-root cell. It is located in `/usr/libexec/jailhouse/linux-loader.bin` in the Emulated Image.
 119
 120 After running the above commands you will see that Linux is booting in another console.
 121
 122 Some helper scripts are present to automate all this, and it can be found [here](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl-devel.git;a=tree;f=meta-agl-jailhouse/recipes-extended/jailhouse/files/helper-scripts).
 123
 124
 125 ### For Testing Virtio over IVSHMEM Block
 126
 127 You can test the Virtio-block over IVSHMEM by following the steps below:
 128
 129 **This is for the Root-cell <---> Non-Root-Cell communication.**
 130
 131 First, you have to boot the Image and enable the `qemu-agl.cell` into the target system, as described in the above sections.
 132
 133 After that follow the below steps to get it spinning:
 134
 135 ```sh
 136
 137 qemux86-64:~# jailhouse enable /usr/share/jailhouse/cells/qemu-agl.cell
 138 qemux86-64:~# modprobe uio_ivshmem
 139
 140 ```
 141
 142 After this check for the PCI device using `lspci -k`, you will see something like this below:
 143
 144 ```sh
 145
 146 qemux86-64:~# lspci -k
 147
 148 .
 149
 150 .
 151
 152 .
 153
 154 00:0c.0 Unassigned class [ff80]: Siemens AG Device 4106
 155
 156 Subsystem: Siemens AG Device 4106
 157
 158 .
 159
 160 .
 161
 162 .
 163
 164 ```
 165
 166 After confirming, run the below command, this will create a virtio block backend
 167
 168 ```sh
 169
 170 qemux86-64:~# echo "110a 4106 110a 4106 ffc002 ffffff" >
 171
 172 /sys/bus/pci/drivers/uio_ivshmem/new_id
 173
 174 ```
 175
 176 And after that, start the backend service like this:
 177
 178 ```sh
 179
 180 qemux86-64:~# ./virtio-ivshmem-block /dev/uio0 disk.img
 181
 182 Waiting for peer to be ready...
 183
 184 ```
 185
 186 After running the backend-service boot or reboot another cell, and backend will show something like this:
 187
 188 ```sh
 189
 190 qemux86-64:~ # ./virtio-ivshmem-block /dev/uio0 disk.img
 191
 192 Waiting for peer to be ready...
 193
 194 Starting virtio device
 195
 196 device_status: 0x0
 197
 198 device_status: 0x1
 199
 200 device_status: 0x3
 201
 202 device_features_sel: 1
 203
 204 device_features_sel: 0
 205
 206 .
 207
 208 .
 209
 210 .
 211
 212 ```
 213
 214 In the Non-Root-Linux, the disk will show up as /dev/vda and can be accessed normally.
 215
 216
 217 >Note:
 218 >- For the `virtio-ivshmem-block` you can find it in target system at `/usr/bin/`, if not then copy it from here `build/tmp/work-shared/qemux86-64/kernel-source/tools/virtio/virtio-ivshmem-block`.
 219 >
 220 >- For the `disk.img`, It needs to be a raw image. But its size matters as that defines the virtual disk size, but you may even leave it empty and only partition or format it from the front-end guest.
 221 >
 222 > e.g:
 223 >
 224 > $ dd if=/dev/zero of=disk.img bs=1M count=1024
 225 >
 226 > $ mkfs.ext4 disk.img
 227
 228
 229 For manually configuring the setup, refer [`meta-agl-jailhouse.md`](meta-agl-jailhouse.md).