|
| 1 | +.. SPDX-License-Identifier: GPL-2.0 |
| 2 | +
|
| 3 | +Introduction of Uacce |
| 4 | +--------------------- |
| 5 | + |
| 6 | +Uacce (Unified/User-space-access-intended Accelerator Framework) targets to |
| 7 | +provide Shared Virtual Addressing (SVA) between accelerators and processes. |
| 8 | +So accelerator can access any data structure of the main cpu. |
| 9 | +This differs from the data sharing between cpu and io device, which share |
| 10 | +only data content rather than address. |
| 11 | +Because of the unified address, hardware and user space of process can |
| 12 | +share the same virtual address in the communication. |
| 13 | +Uacce takes the hardware accelerator as a heterogeneous processor, while |
| 14 | +IOMMU share the same CPU page tables and as a result the same translation |
| 15 | +from va to pa. |
| 16 | + |
| 17 | +:: |
| 18 | + |
| 19 | + __________________________ __________________________ |
| 20 | + | | | | |
| 21 | + | User application (CPU) | | Hardware Accelerator | |
| 22 | + |__________________________| |__________________________| |
| 23 | + |
| 24 | + | | |
| 25 | + | va | va |
| 26 | + V V |
| 27 | + __________ __________ |
| 28 | + | | | | |
| 29 | + | MMU | | IOMMU | |
| 30 | + |__________| |__________| |
| 31 | + | | |
| 32 | + | | |
| 33 | + V pa V pa |
| 34 | + _______________________________________ |
| 35 | + | | |
| 36 | + | Memory | |
| 37 | + |_______________________________________| |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +Architecture |
| 42 | +------------ |
| 43 | + |
| 44 | +Uacce is the kernel module, taking charge of iommu and address sharing. |
| 45 | +The user drivers and libraries are called WarpDrive. |
| 46 | + |
| 47 | +The uacce device, built around the IOMMU SVA API, can access multiple |
| 48 | +address spaces, including the one without PASID. |
| 49 | + |
| 50 | +A virtual concept, queue, is used for the communication. It provides a |
| 51 | +FIFO-like interface. And it maintains a unified address space between the |
| 52 | +application and all involved hardware. |
| 53 | + |
| 54 | +:: |
| 55 | + |
| 56 | + ___________________ ________________ |
| 57 | + | | user API | | |
| 58 | + | WarpDrive library | ------------> | user driver | |
| 59 | + |___________________| |________________| |
| 60 | + | | |
| 61 | + | | |
| 62 | + | queue fd | |
| 63 | + | | |
| 64 | + | | |
| 65 | + v | |
| 66 | + ___________________ _________ | |
| 67 | + | | | | | mmap memory |
| 68 | + | Other framework | | uacce | | r/w interface |
| 69 | + | crypto/nic/others | |_________| | |
| 70 | + |___________________| | |
| 71 | + | | | |
| 72 | + | register | register | |
| 73 | + | | | |
| 74 | + | | | |
| 75 | + | _________________ __________ | |
| 76 | + | | | | | | |
| 77 | + ------------- | Device Driver | | IOMMU | | |
| 78 | + |_________________| |__________| | |
| 79 | + | | |
| 80 | + | V |
| 81 | + | ___________________ |
| 82 | + | | | |
| 83 | + -------------------------- | Device(Hardware) | |
| 84 | + |___________________| |
| 85 | + |
| 86 | + |
| 87 | +How does it work |
| 88 | +---------------- |
| 89 | + |
| 90 | +Uacce uses mmap and IOMMU to play the trick. |
| 91 | + |
| 92 | +Uacce creates a chrdev for every device registered to it. New queue is |
| 93 | +created when user application open the chrdev. The file descriptor is used |
| 94 | +as the user handle of the queue. |
| 95 | +The accelerator device present itself as an Uacce object, which exports as |
| 96 | +a chrdev to the user space. The user application communicates with the |
| 97 | +hardware by ioctl (as control path) or share memory (as data path). |
| 98 | + |
| 99 | +The control path to the hardware is via file operation, while data path is |
| 100 | +via mmap space of the queue fd. |
| 101 | + |
| 102 | +The queue file address space: |
| 103 | + |
| 104 | +:: |
| 105 | + |
| 106 | + /** |
| 107 | + * enum uacce_qfrt: qfrt type |
| 108 | + * @UACCE_QFRT_MMIO: device mmio region |
| 109 | + * @UACCE_QFRT_DUS: device user share region |
| 110 | + */ |
| 111 | + enum uacce_qfrt { |
| 112 | + UACCE_QFRT_MMIO = 0, |
| 113 | + UACCE_QFRT_DUS = 1, |
| 114 | + }; |
| 115 | + |
| 116 | +All regions are optional and differ from device type to type. |
| 117 | +Each region can be mmapped only once, otherwise -EEXIST returns. |
| 118 | + |
| 119 | +The device mmio region is mapped to the hardware mmio space. It is generally |
| 120 | +used for doorbell or other notification to the hardware. It is not fast enough |
| 121 | +as data channel. |
| 122 | + |
| 123 | +The device user share region is used for share data buffer between user process |
| 124 | +and device. |
| 125 | + |
| 126 | + |
| 127 | +The Uacce register API |
| 128 | +---------------------- |
| 129 | + |
| 130 | +The register API is defined in uacce.h. |
| 131 | + |
| 132 | +:: |
| 133 | + |
| 134 | + struct uacce_interface { |
| 135 | + char name[UACCE_MAX_NAME_SIZE]; |
| 136 | + unsigned int flags; |
| 137 | + const struct uacce_ops *ops; |
| 138 | + }; |
| 139 | + |
| 140 | +According to the IOMMU capability, uacce_interface flags can be: |
| 141 | + |
| 142 | +:: |
| 143 | + |
| 144 | + /** |
| 145 | + * UACCE Device flags: |
| 146 | + * UACCE_DEV_SVA: Shared Virtual Addresses |
| 147 | + * Support PASID |
| 148 | + * Support device page faults (PCI PRI or SMMU Stall) |
| 149 | + */ |
| 150 | + #define UACCE_DEV_SVA BIT(0) |
| 151 | + |
| 152 | + struct uacce_device *uacce_alloc(struct device *parent, |
| 153 | + struct uacce_interface *interface); |
| 154 | + int uacce_register(struct uacce_device *uacce); |
| 155 | + void uacce_remove(struct uacce_device *uacce); |
| 156 | + |
| 157 | +uacce_register results can be: |
| 158 | + |
| 159 | +a. If uacce module is not compiled, ERR_PTR(-ENODEV) |
| 160 | + |
| 161 | +b. Succeed with the desired flags |
| 162 | + |
| 163 | +c. Succeed with the negotiated flags, for example |
| 164 | + |
| 165 | + uacce_interface.flags = UACCE_DEV_SVA but uacce->flags = ~UACCE_DEV_SVA |
| 166 | + |
| 167 | + So user driver need check return value as well as the negotiated uacce->flags. |
| 168 | + |
| 169 | + |
| 170 | +The user driver |
| 171 | +--------------- |
| 172 | + |
| 173 | +The queue file mmap space will need a user driver to wrap the communication |
| 174 | +protocol. Uacce provides some attributes in sysfs for the user driver to |
| 175 | +match the right accelerator accordingly. |
| 176 | +More details in Documentation/ABI/testing/sysfs-driver-uacce. |
0 commit comments