Documentation/inter-cell-communication.txt

   1 Inter-Cell communication of the Jailhouse Hypervisor
   2 ====================================================
   3
   4 The hypervisor isolates cells but sometimes there is a need to exchange data
   5 between cells. For that purpose Jailhouse provides shared memory and signaling
   6 between cells.
   7
   8 One channel is always between exactly two cells, there is no 1:n or n:m
   9 communication.
  10
  11 The interface used between the cell and the hypervisor
  12 ------------------------------------------------------
  13
  14 One end of such a communication channel is modeled as a PCI device that a cell
  15 can discover on it's PCI bus. The device model used closely follows the
  16 "ivshmem" device known from Qemu (see qemu docs/specs/ivshmem_device_spec.txt
  17 and https://gitorious.org/nahanni/).
  18 The device implemented by jailhouse supports MSI-X for signaling. While the
  19 spec would allow for multiple interrupts, Jailhouse supports exactly one per
  20 virtual device.
  21
  22 The ivshmem device implemented by the jailhouse hypervisor is different to the
  23 mentioned specification in one regard. The location and the size of the shared
  24 memory region itself are not encoded in a PCI BAR. Device drivers get the
  25 relevant information by accessing custom PCI config space registers. See
  26 hypervisor/pci_ivshmem.c IVSHMEM_CFG_SHMEM_* or the ivshmem demo in the
  27 inmates directory.
  28
  29 Adding Inter-cell communication to cells
  30 ----------------------------------------
  31
  32 In order to set up a communication channel between two cells you first have to
  33 add a memory region to both cells. Add a read/write region with matching size
  34 and physical address to both cells. Non-root cells sharing memory with the
  35 root cell need the memory flag "JAILHOUSE_MEM_ROOTSHARED" on the region.
  36 To allow cells to discover shared memory and send each other MSIs you also
  37 need to add a virtual PCI device to both cells. The "type" should be set to
  38 "JAILHOUSE_PCI_TYPE_IVSHMEM" and "shmem_region" should be set to the index
  39 of the memory region. "num_msix_vectors" should be set to 1 and for your root
  40 cell config you should make sure that "iommu" is set to the correct value,
  41  try using the same value that works for the other pci devices.
  42 The link between two such virtual PCI devices is established by using the same
  43 "bdf". The size and location of the shared memory can be configured freely but
  44 you have to make sure that the values match on both sides.
  45 For an example have a look at the cell configuration files of qemu and the
  46 ivshmem-demo.
  47
  48 Demo code
  49 ---------
  50
  51 You can go ahead and connect two non-root cells and run the ivshmem-demo. They
  52 will send each other interrupts.
  53 For the root cell you can find some test code in the following git repository:
  54 https://github.com/henning-schild/ivshmem-guest-code
  55 Check out the jailhouse branch and have a look at README.jailhouse.