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 **Note**
 143
 144 For the above steps to get working, compile the kernels separately with the following configurations(in the menuconfig):
 145
 146 - One with `UIO_IVSHMEM`(for backend) and,
 147 - another with `VIRTIO_IVSHMEM`(for frontend).
 148
 149 For the frontend kernel you can also use the minimal Configurations present [here](https://github.com/siemens/jailhouse-images/blob/master/recipes-kernel/linux/files/amd64_defconfig_5.10). You can also build this kernel externally and copy the kernel-image later in the target image.
 150
 151 ---
 152
 153 After this check for the PCI device using `lspci -k`, you will see something like this below:
 154
 155 ```sh
 156
 157 qemux86-64:~# lspci -k
 158
 159 .
 160
 161 .
 162
 163 .
 164
 165 00:0c.0 Unassigned class [ff80]: Siemens AG Device 4106
 166
 167 Subsystem: Siemens AG Device 4106
 168
 169 .
 170
 171 .
 172
 173 .
 174
 175 ```
 176
 177 After confirming, run the below command, this will create a virtio block backend
 178
 179 ```sh
 180
 181 qemux86-64:~# echo "110a 4106 110a 4106 ffc002 ffffff" >
 182
 183 /sys/bus/pci/drivers/uio_ivshmem/new_id
 184
 185 ```
 186
 187 And after that, start the backend service like this:
 188
 189 ```sh
 190
 191 qemux86-64:~# ./virtio-ivshmem-block /dev/uio0 disk.img
 192
 193 Waiting for peer to be ready...
 194
 195 ```
 196 > Note: If you can not find the device at `/dev/uio0` then look for other devices like `/dev/uio*`.
 197
 198 After running the backend-service boot or reboot another cell, and backend will show something like this:
 199
 200 ```sh
 201
 202 qemux86-64:~ # ./virtio-ivshmem-block /dev/uio0 disk.img
 203
 204 Waiting for peer to be ready...
 205
 206 Starting virtio device
 207
 208 device_status: 0x0
 209
 210 device_status: 0x1
 211
 212 device_status: 0x3
 213
 214 device_features_sel: 1
 215
 216 device_features_sel: 0
 217
 218 .
 219
 220 .
 221
 222 .
 223
 224 ```
 225
 226 In the Non-Root-Linux, the disk will show up as /dev/vda and can be accessed normally.
 227
 228 ---
 229 **Note**
 230
 231 - 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`.
 232
 233 - 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.
 234
 235 e.g:
 236
 237 ```sh
 238 $ dd if=/dev/zero of=disk.img bs=1M count=1024
 239 $ mkfs.ext4 disk.img
 240 ```
 241 this can be accessed via `/dev/vda` in the frontend.
 242
 243 ---
 244
 245 For manually configuring the setup, refer [`meta-agl-jailhouse.md`](meta-agl-jailhouse.md).