1/*
2 * Copyright 2019, Data61, CSIRO (ABN 41 687 119 230)
3 *
4 * SPDX-License-Identifier: BSD-2-Clause
5 */
6
7#pragma once
8
9/***
10 * @module cross_vm_connection.h
11 * The crossvm connection module facilitates the creation of communication channels between VM's and other
12 * components on a seL4-based system. The module exports registered cross vm connections to a Linux VM such that
13 * processes can access them from userlevel. This being facilitated over a virtual PCI device.
14 */
15
16#include <sel4vm/guest_vm.h>
17
18#include <sel4vmmplatsupport/drivers/virtio.h>
19#include <sel4vmmplatsupport/drivers/pci_helper.h>
20#include <pci/helper.h>
21
22typedef void (*event_callback_fn)(void *arg);
23typedef void (*emit_fn)(void);
24typedef int (*consume_callback_fn)(event_callback_fn, void *arg);
25typedef int (*alloc_free_interrupt_fn)(void);
26
27/***
28 * @struct crossvm_dataport_handle
29 * Datastructure representing a dataport of a crossvm connection
30 * @param {size_t} size         The size of the crossvm dataport
31 * @param {int} num_frames      Total number of frames in the `frames` member
32 * @param {seL4_CPtr *} frames  The set of frames backing the dataport
33 */
34typedef struct crossvm_dataport_handle {
35    size_t size;
36    unsigned int num_frames;
37    seL4_CPtr *frames;
38} crossvm_dataport_handle_t;
39
40/***
41 * @struct crossvm_handle
42 * Datastructure representing a single crossvm connection
43 * @param {crossvm_dataport_handle_t *} dataport    The dataport associated with the crossvm connection
44 * @param {emit_fn} emit_fn                         The function pointer to the crossvm emit method
45 * @param {seL4_Word} consume_id                    The identifier used for the crossvm connection when receiving incoming notifications
46 *                                                  This is matched on when invoking `consume_connection_event`
47 */
48typedef struct crossvm_handle {
49    crossvm_dataport_handle_t *dataport;
50    emit_fn emit_fn;
51    seL4_Word consume_id;
52    const char *connection_name;
53} crossvm_handle_t;
54
55/***
56 * @function cross_vm_connections_init_common(vm, connection_base_addr, connections, num_connections, pci, alloc_irq)
57 * Install a set of cross vm connections into a guest VM (for either x86 or ARM VM platforms)
58 * @param {vm_t *} vm                           A handle to the VM
59 * @param {uintptr_t} connection_base_addr      The base guest physical address that can be used to reserve memory
60 *                                              for the crossvm connectors
61 * @param {crossvm_handle_t *} connections      The set of crossvm connections to be initialised and installed in the guest
62 * @param {int} num_connection                  The number of connections passed in through the 'connections' parameter
63 * @param {vmm_pci_space_t *} pci               A handle to the VM's host PCI device. The connections are advertised through the
64 *                                              PCI device
65 * @param {alloc_free_interrupt_fn} alloc_irq   A function that is used to allocated an irq number for the crossvm connections
66 * @return                                      -1 on failure otherwise 0 for success
67 */
68int cross_vm_connections_init_common(vm_t *vm, uintptr_t connection_base_addr, crossvm_handle_t *connections,
69                                     int num_connections, vmm_pci_space_t *pci, alloc_free_interrupt_fn alloc_irq);
70
71/***
72 * @function consume_connection_event(vm, event_id, inject_irq)
73 * Handler to consume a cross vm connection event. This being called by the VMM when it recieves a notification from an
74 * external process. The event is then relayed onto the VM.
75 * @param {vm_t *} vm                   A handle to the VM
76 * @param {seL4_Word} event_id          The id that corresponds to the occuring event
77 * @param {bool} inject_irq             Whether to inject an interrupt into the VM
78 */
79void consume_connection_event(vm_t *vm, seL4_Word event_id, bool inject_irq);
80