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 ac_device.h
11 * The ARM access control device interface facilitates the creation of generic virtual devices in a VM instance with
12 * access control permissions over the devices addressable memory. An access controlled device is often used to abstract
13 * the memory of a specific platform hardware device e.g a clock device. This allows the user to present hardware devices
14 * to a VM instance but limit their permissions with regards to modifying its register state.
15 */
16
17#include <sel4vm/guest_vm.h>
18
19#include <sel4vmmplatsupport/device.h>
20
21enum vacdev_default {
22    VACDEV_DEFAULT_ALLOW,
23    VACDEV_DEFAULT_DENY
24};
25
26enum vacdev_action {
27    VACDEV_REPORT_ONLY,
28    VACDEV_MASK_ONLY,
29    VACDEV_REPORT_AND_MASK
30};
31
32/***
33 * @function vm_install_generic_ac_device(vm, d, mask, size, action)
34 * Installs a generic access controlled device
35 * @param {vm_t *} vm                       The VM to install the device into
36 * @param {const struct device *} d         A description of the device to install
37 * @param {void *} mask                     An access mask. The mask provides a map of device bits that
38 *                                          are modifiable by the guest.
39 *                                          '1' represents bits that the guest can read and write
40                                            '0' represents bits that can only be read by the guest
41 *                                          Underlying memory for the mask should remain accessible for
42 *                                          the life of this device. The mask may be updated at run time
43 *                                          on demand.
44 * @param {size_t} size                     The size of the mask. This is useful for conserving memory in
45 *                                          cases where the underlying device does not occupy a full
46 *                                          page. If an access lies outside of the range of the mask,
47 *                                          guest access.
48 * @param {enum vacdev_action} action       Action to take when access is violated.
49 * @return                                  0 on success, -1 on error
50 */
51int vm_install_generic_ac_device(vm_t *vm, const struct device *d, void *mask,
52                                 size_t size, enum vacdev_action action);
53