{"id":19608680,"url":"https://github.com/sel4/camkes-vm-examples","last_synced_at":"2025-04-27T20:33:06.321Z","repository":{"id":38889637,"uuid":"133463696","full_name":"seL4/camkes-vm-examples","owner":"seL4","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-01T02:12:11.000Z","size":83543,"stargazers_count":16,"open_issues_count":10,"forks_count":27,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-01T03:24:45.797Z","etag":null,"topics":["camkes"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seL4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-15T05:29:27.000Z","updated_at":"2025-03-29T19:18:55.000Z","dependencies_parsed_at":"2023-02-10T06:31:23.235Z","dependency_job_id":"e339c947-eec7-4dd8-b776-29147e1ef548","html_url":"https://github.com/seL4/camkes-vm-examples","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seL4%2Fcamkes-vm-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seL4%2Fcamkes-vm-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seL4%2Fcamkes-vm-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seL4%2Fcamkes-vm-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seL4","download_url":"https://codeload.github.com/seL4/camkes-vm-examples/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251204725,"owners_count":21552280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camkes"],"created_at":"2024-11-11T10:16:25.612Z","updated_at":"2025-04-27T20:33:01.303Z","avatar_url":"https://github.com/seL4.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)\n\n  SPDX-License-Identifier: CC-BY-SA-4.0\n--\u003e\n\n# camkes-vm-apps\n\nThis project is for running virtualised Linux guests on seL4 for ARM and x86 platforms. The `camkes-vm` implements\na virtual machine monitor (VMM) server, facilitating the initialisation, booting and run-time management of a guest OS.\nYou can view the code for the VMMs in the `camkes-vm` repository under `VM_Arm` and `VM`.\n\nCurrently the supported platforms include:\n\n* Exynos5 (exynos5410, exynos5422)\n* TK1\n* TX1\n* TX2\n* QEMU ARM virt machine\n* ZCU102\n* x86\n* x86_64\n\n## Getting and Building\n\n### Cloning the repository set and preparing a build directory\n\n```sh\nrepo init -u https://github.com/seL4/camkes-vm-examples-manifest.git\nrepo sync\nmkdir build\ncd build\n```\n\nArm and x86 have slightly differing build instructions. See the sections below.\n\n### Building for Arm\n\nThe following example builds the CAmkES Arm VMM for the TK1. In the `build` directory, run:\n\n```sh\n../init-build.sh -DCAMKES_VM_APP=vm_minimal -DPLATFORM=tk1\nninja\n```\n\n*Note: To buid for another platform you can substitute the value of the `-DPLATFORM` variable e.g. (exynos5422, tx1, tx2, zcu102, qemu-arm-virt)*\n\nAn EFI application file will be left in `images/capdl-loader-image-arm-tk1` We normally boot using TFTP, by first copying `capdl-loader-image-arm-tk1` to a tftpserver then on the U-Boot serial console doing:\n\n```sh\ndhcp\ntftpboot ${loadaddr} /capdl-loader-image-arm-tk1\nbootefi ${loadaddr}\n```\n\n### Building for x86\n\nThe following example builds the CAmkES VMM for x64. In the `build` directory, run:\n\n```sh\n../init-build.sh -DCAMKES_VM_APP=minimal_64\nninja\n```\n\nBoot `images/kernel-x86_64-pc99` and `images/capdl-loader-image-x86_64-pc99` with the multiboot boot loader of your choice. Use `*.ia32-pc99` if built for 32-bit with `../init-build.sh -DCAMKES_VM_APP=minimal`.\n\n## CAmkES ARM VMM Applications\n\nThis project contains various reference CAmkES applications that incorporate the VMM component. These applications include:\n\n* `vm_minimal`: A simple VMM application, launching a single guest Linux with a buildroot RAM-based file system\n* `vm_cross_connector`: Application demonstrating communication between a Linux guest user-level process and a native seL4 component. This leveraging\ncross vm communication channels established between the VMM and the seL4 component.\n* `vm_multi`: Application demonstrating running multiple guest VM's. This is achieved through having multiple VMM components, each managing a single\nLinux guest (1-1 model).\n* `vm_serial_server`: Application demonstrating the use of Virtio Console, where a VM's serial I/O is forwarded to/from a serial server.\n* `vm_virtio_net`: Application demonstrating the use of Virtio Net, where a virtual network interface is presented to a VM and subsequent network\ntraffic on the virtual network interface is sent to/from other native seL4 components.\n\nSee the `apps/Arm/` subdirectory for all the supported virtual machine manager apps, their implementations and the platforms they target.\n\n## CAmkES x86 VMM Applications\n\n* The `minimal` application is a simple CAmkES VM application. The application is configured with:\n\n  * *1 Guest Linux VM:* The Linux guest is a [buildroot](https://buildroot.org/) built image sourced from the [the camkes-vm repo](https://github.com/seL4/camkes-vm). The Linux images (rootfs and kernel) are defined in the `CMakeLists.txt` file of the `minimal` application. In the `CMakeLists.txt` file we are able to find that the rootfs and kernel images  are added to the `FileServer` under the names `\"rootfs.cpio\"` and  `\"bzimage\"` respectively.\n\n* The `optiplex9020` VM application is configured with:\n\n  * *2 Guest Linux VM's:* The Linux guests are [buildroot](https://buildroot.org/) built images sourced from the [the camkes-vm repo](https://github.com/seL4/camkes-vm).\n  * *Cross VM Connectors:* To demo the use of cross-vm connectors a series of shared dataports and events are established between `vm0` and the `StringReverse` component. The `StringReverse` demo can be invoked from the command-line of `vm0`:\n\n    ```\n    Welcome to Buildroot\n    buildroot login: root\n    Password:\n    \\# string_reverse\n    [   19.739028] dataport received mmap for minor 1\n    [   19.743337] dataport received mmap for minor 2\n    hello\n    olleh\n    ```\n\n* The `cma34cr_centos` application is a more complex CAmkES VM configuration demonstrating the use of passthrough hardware. The `cma34cr_centos` application is configured with:\n\n  * *1 Guest Linux VM:* The Linux guest images (`bzimage` and `roofs.cpio`) are located in the applications directory (`cma34cr_centos/centos_linux`), originally sourced from an i386 altarch CentOS-7 installation. Additionally the CentosOS installation should be on a flash drive passed-through to the `cma34cr` application. Further information regarding the Linux installation can be found in the applications [README](https://github.com/seL4/camkes-vm-examples/blob/master/apps/x86/cma34cr_centos/README.md).\n  * *Cross VM Connectors:* A series of shared dataports and events are established between `vm0` and the `StringReverse` component.\n  * *Ethernet Driver, UDPSever, Echo, Firewall:* A passthrough ethernet configuration demo. The guest VM is configured to use the Ethernet driver component through a virtio configuration.\n  * *Passthrough hardware storage (SATA/USB)*: A hardware configuration to boot the CentOS installation.\n\n* The `zmq_samples` application demonstrates messaging between VMs using the ZeroMQ messaging library.\nSee the README.md in its folder for more information.\n\nSee the `apps/x86/` subdirectory for all the supported virtual machine manager apps, their implementations and the platforms they target.\n\n## Arm Features\n\nSee the below feature matrix for the various features the CAmkES ARM VMM implements/facilitates across the various supported platforms.\n\n| Plaform | Guest Mode | SMP Support | Multiple VM Support | Virtio PCI | Virtio Console | Virtio Net | Cross VM Connector Support | *Notes* |\n|:----------:|:----------:|:-----------:|:-------------------:|:-----------:|:--------------:|:-----------:|:--------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|\n| exynos5422 | 32-bit  | Unsupported | Supported | Supported | Supported | Supported | Supported | SMP configurations are unsupported due to: * No exynos5422 kernel SMP support * No virtual power device interface to manage VCPU's at runtime (e.g. core startup) |\n| TK1 | 32-bit | Unsupported | Unsupported | Unsupported | Unsupported | Unsupported | Unsupported | SMP configurations are unsupported due to: * No TK1 kernel SMP support * No virtual power device interface to manage VCPU's at runtime (e.g. core startup) Virtio PCI, Console, Net, Cross VM connector support \u0026 Multi-VM are untested  |\n| TX1 | 64-bit | Supported | Unsupported | Unsupported | Unsupported | Unsupported | Unsupported | Virtio PCI, Console, Net, Cross VM connector support \u0026 Multi-VM are untested |\n| TX2 | 64-bit | Supported | Supported | Supported | Supported | Supported | Unsupported | Cross VM connector support is untested |\n| ZCU102 | 64-bit | Supported | Supported | Supported | Supported | Supported | Unsupported | Cross VM connector support is untested |\n| QEMU Virt | 64-bit | Supported | Unsupported | Supported | Supported | Supported | Supported | Multi-VM support depends on porting the TimeServer to QEMU (See https://github.com/sel4/global-components/tree/master/components/TimeServer) |\n\n\n## Arm Platform Configuration Notes\n\n### Exynos5422, TX1, TX2, ZCU102, QEMU ARM Virt configuration\n\nWe provide a pre-built Linux image and Buildroot image for our guest VM's. See the images in the `camkes-vm-images` repository at \u003chttps://github.com/sel4/camkes-vm-images\u003e.\nFeel free also to compile your own Linux and Rootfs images, see the README's in each platform subdirectory (within `camkes-vm-images`) for information about our\nimage build configurations.\n\n### TK1 configuration\n\nWe currently provide two linux binaries and two device tree configurations.\n\n* `linux-tk1-debian` will try and load a debian userspace off of an emmc partition\n* `linux-tk1-initrd` will load an included buildroot ramdisk\n* `linux-tk1-secure.dts` is a device tree configuration with the devices that aren't provided to the linux are disabled.\n* `linux-tk1-nonsecured.dts` is a device tree configuration with all devices enabled.\n\nIn the tk1 app configuration there is a `boot mode selection` option that chooses between the two linux binaries, and\nan `Insecure` option which selects whether to provide all hardware devices to the linux vm or not. If `Insecure` is not set\nthen the VM will only be provided a minimal amount of hardware frames and the `linux-tk1-secure.dts` DTS will be used.  If `Insecure`\nis set then the VM will be provided all device frames apart from the Memory controller and the `linux-tk1-nonsecured.dts` DTS will be used.\n\nU-Boot is required to initialise the USB devices if `linux-tk1-secure.dts` is used.  This is done by: `usb start 0`.\n\nThe tk1 currently uses linux binaries constructed using [Buildroot 2016.08.1](https://buildroot.org/downloads/) with the following configs:\n\n* `buildroot_tk1_initrd_defconfig` builds linux with an included ramdisk that will be loaded at boot.\n* `buildroot_tk1_emmc_defconfig` builds linux without a ramdisk and it will mount and run /sbin/init /dev/mmcblk0p2\n\nTo copy the files back into this project, change into the Linux directory and run make for each file as shown below. **Note that you can only\nupdate one of linux-tk1-debian or linux-tk1-initrd at a time as they are built from different Buildroot configs**:\n\n```sh\ncd projects/vm/linux\nLINUX_FILE=linux-tk1-initrd BUILDROOT_DIR=~/workspaces/buildroot-2016.08.1/ make\nLINUX_FILE=linux-tk1-dtb-secure BUILDROOT_DIR=~/workspaces/buildroot-2016.08.1/ make\n```\n\n\nBoth of these configs use the tegra124-jetson-tk1-sel4vm-secure device tree file.\nTo change to the tegra124-jetson-tk1-sel4vm.dts this will need to be changed in the buildroot make menuconfig.\nTo change the mounted emmc partition the chosen dts file's bootargs entry will need to be updated.\n\nThe Linux version used can be found in the seL4 branch of our [linux-tegra repo](https://github.com/SEL4PROJ/linux-tegra/tree/sel4).\n\n\nWhen buildroot starts:\n\n```\nbuildroot login: root\n#\n```\n\nWhen debian starts:\n\n```\nDebian GNU/Linux 8 tk1 ttyS0\ntk1 login: root\nPassword: root\nroot@tk1:~#\n```\n\n#### Wireless Configuration\n\nTo configure the Ralink 2780 USB wifi dongle:\n\n```sh\nifconfig wlan0 up\niw wlan0 scan\nwpa_passphrase SSID_NAME \u003e\u003e /etc/wpa_supplicant.conf\n  ENTER_SSID_PASSPHRASE\nwpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf\niw wlan0 link\ndhclient wlan0\n```\n\n### TK1 Build Notes\n\nThe default setup does not pass though many devices to the Linux kernel. If you `make menuconfig` you can set `insecure` mode in the `Applications` submenu; this is meant to pass through all devices, but not\neverything has been tested and confirmed to work yet. In particular, the SMMU needs to have extra entries added for any DMA-capable devices such as SATA.\n\n## Useful Links for Developing VM Applications\n\n1. [CAmkES VM: Adding a Linux Guest](https://docs.sel4.systems/Tutorials/camkes-vm-linux.html)\n2. [CAmkES VM: Cross VM Connectors](https://docs.sel4.systems/Tutorials/camkes-vm-crossvm.html)\n\n## Arm FAQ and Implementation Notes\n\n### How do I update camkes-vm-apps to support platform 'X'\n\nWhilst large parts of the ARM VMM implementation tries to be platform agnostic, there are a few things to keep in mind and implement in order to correctly run the camkes-arm-vm on your new target platform.\nSee the below list as as a rough list of items to check off:\n\n* Ensure the platform is already supported by seL4 (or you have developed support for the platform prior). See the [following](https://docs.sel4.systems/Hardware/) page for a list of supported platforms.\n* The platform supports ARM's hardware virtualisation features, these being found on ARMv7 (with virtualisation extensions) and ARMv8.\n  * Second to this, the seL4 port to the given platform also supports running with `KernelArmHypervisorSupport`\n* Does your platform use a GICv2 or GICv3? *Note: We currently only support a virtual GICV2, with virtual GICV3 support under-development. See the listed features of libsel4vm for further information: https://github.com/sel4/seL4_projects_libs/tree/master/libsel4vm*\n* When porting a VMM application to your platform, say `vm_minimal`, ensure you provide the following:\n  * A `devices.camkes` file for your platform. These containing platform specific definitions, see in particular the vm `dtb` field and the `untyped_mmios` field (for device passthrough). The values in the aforementioned fields corresponding with those found in the kernel device tree.\n  * A `vmlinux.h` header for you platform. See the header file for the other supported platforms at `components/VM_Arm/plat_include` in `camkes-vm` repository.\n* Provide a pre-compiled Linux kernel and initrd image for your platform. Once compiled these are usually linked in through your apps `CMakeLists.txt`. See `apps/Arm/vm_minimal/CMakeLists.txt` for examples of how other platforms link in their images.\n\nFeel free to contact the [team](https://docs.sel4.systems/processes/#contact) for further support on porting the camkes-arm-vm to your desired platform. We are also always open to contributions for new platforms.\n\n### Can a single VMM component support running multiple VM's?\n\nCurrently, No. A VMM component only creates and manages a single VM instance.\nTo support multiple VM's, you can run multiple VMM components, each managing its own VM. See `apps/vm_multi` for an example of this configuration.\n\n### How do I enable SMP support for a VM instance?\n\nTo configure your VM with multiple VCPU's, you can set the VM instance attribute `num_vcpus` in your camkes configuration. See [here](https://github.com/sel4/camkes-vm-apps/blob/master/apps/Arm/vm_minimal/tx2/devices.camkes#L40) for an example.\nIn addition, when initialising your build, ensure the `KernelMaxNumNodes` configuration option is set to your desired value. You can also initialise your build with variable `-DNUM_NODES` variable e.g.\n\n```sh\n../init-build.sh -DCAMKES_VM_APP=vm_minimal -DPLATFORM=tx2 -DNUM_NODES=4\n```\n\n*Note: ensure your platform supports SMP configurations through the above feature matrix*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsel4%2Fcamkes-vm-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsel4%2Fcamkes-vm-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsel4%2Fcamkes-vm-examples/lists"}