1 /*
2  * Host IOMMU device abstract declaration
3  *
4  * Copyright (C) 2024 Intel Corporation.
5  *
6  * Authors: Zhenzhong Duan <zhenzhong.duan@intel.com>
7  *
8  * This work is licensed under the terms of the GNU GPL, version 2.  See
9  * the COPYING file in the top-level directory.
10  */
11 
12 #ifndef HOST_IOMMU_DEVICE_H
13 #define HOST_IOMMU_DEVICE_H
14 
15 #include "qom/object.h"
16 #include "qapi/error.h"
17 
18 /**
19  * struct HostIOMMUDeviceCaps - Define host IOMMU device capabilities.
20  *
21  * @type: host platform IOMMU type.
22  *
23  * @aw_bits: host IOMMU address width. 0xff if no limitation.
24  */
25 typedef struct HostIOMMUDeviceCaps {
26     uint32_t type;
27     uint8_t aw_bits;
28 } HostIOMMUDeviceCaps;
29 
30 #define TYPE_HOST_IOMMU_DEVICE "host-iommu-device"
31 OBJECT_DECLARE_TYPE(HostIOMMUDevice, HostIOMMUDeviceClass, HOST_IOMMU_DEVICE)
32 
33 struct HostIOMMUDevice {
34     Object parent_obj;
35 
36     char *name;
37     void *agent; /* pointer to agent device, ie. VFIO or VDPA device */
38     PCIBus *aliased_bus;
39     int aliased_devfn;
40     HostIOMMUDeviceCaps caps;
41 };
42 
43 /**
44  * struct HostIOMMUDeviceClass - The base class for all host IOMMU devices.
45  *
46  * Different types of host devices (e.g., VFIO or VDPA device) or devices
47  * with different backend (e.g., VFIO legacy container or IOMMUFD backend)
48  * will have different implementations of the HostIOMMUDeviceClass.
49  */
50 struct HostIOMMUDeviceClass {
51     ObjectClass parent_class;
52 
53     /**
54      * @realize: initialize host IOMMU device instance further.
55      *
56      * Mandatory callback.
57      *
58      * @hiod: pointer to a host IOMMU device instance.
59      *
60      * @opaque: pointer to agent device of this host IOMMU device,
61      *          e.g., VFIO base device or VDPA device.
62      *
63      * @errp: pass an Error out when realize fails.
64      *
65      * Returns: true on success, false on failure.
66      */
67     bool (*realize)(HostIOMMUDevice *hiod, void *opaque, Error **errp);
68     /**
69      * @get_cap: check if a host IOMMU device capability is supported.
70      *
71      * Optional callback, if not implemented, hint not supporting query
72      * of @cap.
73      *
74      * @hiod: pointer to a host IOMMU device instance.
75      *
76      * @cap: capability to check.
77      *
78      * @errp: pass an Error out when fails to query capability.
79      *
80      * Returns: <0 on failure, 0 if a @cap is unsupported, or else
81      * 1 or some positive value for some special @cap,
82      * i.e., HOST_IOMMU_DEVICE_CAP_AW_BITS.
83      */
84     int (*get_cap)(HostIOMMUDevice *hiod, int cap, Error **errp);
85     /**
86      * @get_iova_ranges: Return the list of usable iova_ranges along with
87      * @hiod Host IOMMU device
88      *
89      * @hiod: handle to the host IOMMU device
90      * @errp: error handle
91      */
92     GList* (*get_iova_ranges)(HostIOMMUDevice *hiod, Error **errp);
93 };
94 
95 /*
96  * Host IOMMU device capability list.
97  */
98 #define HOST_IOMMU_DEVICE_CAP_IOMMU_TYPE        0
99 #define HOST_IOMMU_DEVICE_CAP_AW_BITS           1
100 
101 #define HOST_IOMMU_DEVICE_CAP_AW_BITS_MAX       64
102 #endif
103