1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Copyright (C) 2017 Google, Inc. 4 * 5 */ 6 7 #ifndef _UAPI_LINUX_VSOC_SHM_H 8 #define _UAPI_LINUX_VSOC_SHM_H 9 10 #include <linux/types.h> 11 12 /** 13 * A permission is a token that permits a receiver to read and/or write an area 14 * of memory within a Vsoc region. 15 * 16 * An fd_scoped permission grants both read and write access, and can be 17 * attached to a file description (see open(2)). 18 * Ownership of the area can then be shared by passing a file descriptor 19 * among processes. 20 * 21 * begin_offset and end_offset define the area of memory that is controlled by 22 * the permission. owner_offset points to a word, also in shared memory, that 23 * controls ownership of the area. 24 * 25 * ownership of the region expires when the associated file description is 26 * released. 27 * 28 * At most one permission can be attached to each file description. 29 * 30 * This is useful when implementing HALs like gralloc that scope and pass 31 * ownership of shared resources via file descriptors. 32 * 33 * The caller is responsibe for doing any fencing. 34 * 35 * The calling process will normally identify a currently free area of 36 * memory. It will construct a proposed fd_scoped_permission_arg structure: 37 * 38 * begin_offset and end_offset describe the area being claimed 39 * 40 * owner_offset points to the location in shared memory that indicates the 41 * owner of the area. 42 * 43 * owned_value is the value that will be stored in owner_offset iff the 44 * permission can be granted. It must be different than VSOC_REGION_FREE. 45 * 46 * Two fd_scoped_permission structures are compatible if they vary only by 47 * their owned_value fields. 48 * 49 * The driver ensures that, for any group of simultaneous callers proposing 50 * compatible fd_scoped_permissions, it will accept exactly one of the 51 * propopsals. The other callers will get a failure with errno of EAGAIN. 52 * 53 * A process receiving a file descriptor can identify the region being 54 * granted using the VSOC_GET_FD_SCOPED_PERMISSION ioctl. 55 */ 56 struct fd_scoped_permission { 57 __u32 begin_offset; 58 __u32 end_offset; 59 __u32 owner_offset; 60 __u32 owned_value; 61 }; 62 63 /* 64 * This value represents a free area of memory. The driver expects to see this 65 * value at owner_offset when creating a permission otherwise it will not do it, 66 * and will write this value back once the permission is no longer needed. 67 */ 68 #define VSOC_REGION_FREE ((__u32)0) 69 70 /** 71 * ioctl argument for VSOC_CREATE_FD_SCOPE_PERMISSION 72 */ 73 struct fd_scoped_permission_arg { 74 struct fd_scoped_permission perm; 75 __s32 managed_region_fd; 76 }; 77 78 #define VSOC_NODE_FREE ((__u32)0) 79 80 /* 81 * Describes a signal table in shared memory. Each non-zero entry in the 82 * table indicates that the receiver should signal the futex at the given 83 * offset. Offsets are relative to the region, not the shared memory window. 84 * 85 * interrupt_signalled_offset is used to reliably signal interrupts across the 86 * vmm boundary. There are two roles: transmitter and receiver. For example, 87 * in the host_to_guest_signal_table the host is the transmitter and the 88 * guest is the receiver. The protocol is as follows: 89 * 90 * 1. The transmitter should convert the offset of the futex to an offset 91 * in the signal table [0, (1 << num_nodes_lg2)) 92 * The transmitter can choose any appropriate hashing algorithm, including 93 * hash = futex_offset & ((1 << num_nodes_lg2) - 1) 94 * 95 * 3. The transmitter should atomically compare and swap futex_offset with 0 96 * at hash. There are 3 possible outcomes 97 * a. The swap fails because the futex_offset is already in the table. 98 * The transmitter should stop. 99 * b. Some other offset is in the table. This is a hash collision. The 100 * transmitter should move to another table slot and try again. One 101 * possible algorithm: 102 * hash = (hash + 1) & ((1 << num_nodes_lg2) - 1) 103 * c. The swap worked. Continue below. 104 * 105 * 3. The transmitter atomically swaps 1 with the value at the 106 * interrupt_signalled_offset. There are two outcomes: 107 * a. The prior value was 1. In this case an interrupt has already been 108 * posted. The transmitter is done. 109 * b. The prior value was 0, indicating that the receiver may be sleeping. 110 * The transmitter will issue an interrupt. 111 * 112 * 4. On waking the receiver immediately exchanges a 0 with the 113 * interrupt_signalled_offset. If it receives a 0 then this a spurious 114 * interrupt. That may occasionally happen in the current protocol, but 115 * should be rare. 116 * 117 * 5. The receiver scans the signal table by atomicaly exchanging 0 at each 118 * location. If a non-zero offset is returned from the exchange the 119 * receiver wakes all sleepers at the given offset: 120 * futex((int*)(region_base + old_value), FUTEX_WAKE, MAX_INT); 121 * 122 * 6. The receiver thread then does a conditional wait, waking immediately 123 * if the value at interrupt_signalled_offset is non-zero. This catches cases 124 * here additional signals were posted while the table was being scanned. 125 * On the guest the wait is handled via the VSOC_WAIT_FOR_INCOMING_INTERRUPT 126 * ioctl. 127 */ 128 struct vsoc_signal_table_layout { 129 /* log_2(Number of signal table entries) */ 130 __u32 num_nodes_lg2; 131 /* 132 * Offset to the first signal table entry relative to the start of the 133 * region 134 */ 135 __u32 futex_uaddr_table_offset; 136 /* 137 * Offset to an atomic_t / atomic uint32_t. A non-zero value indicates 138 * that one or more offsets are currently posted in the table. 139 * semi-unique access to an entry in the table 140 */ 141 __u32 interrupt_signalled_offset; 142 }; 143 144 #define VSOC_REGION_WHOLE ((__s32)0) 145 #define VSOC_DEVICE_NAME_SZ 16 146 147 /** 148 * Each HAL would (usually) talk to a single device region 149 * Mulitple entities care about these regions: 150 * - The ivshmem_server will populate the regions in shared memory 151 * - The guest kernel will read the region, create minor device nodes, and 152 * allow interested parties to register for FUTEX_WAKE events in the region 153 * - HALs will access via the minor device nodes published by the guest kernel 154 * - Host side processes will access the region via the ivshmem_server: 155 * 1. Pass name to ivshmem_server at a UNIX socket 156 * 2. ivshmemserver will reply with 2 fds: 157 * - host->guest doorbell fd 158 * - guest->host doorbell fd 159 * - fd for the shared memory region 160 * - region offset 161 * 3. Start a futex receiver thread on the doorbell fd pointed at the 162 * signal_nodes 163 */ 164 struct vsoc_device_region { 165 __u16 current_version; 166 __u16 min_compatible_version; 167 __u32 region_begin_offset; 168 __u32 region_end_offset; 169 __u32 offset_of_region_data; 170 struct vsoc_signal_table_layout guest_to_host_signal_table; 171 struct vsoc_signal_table_layout host_to_guest_signal_table; 172 /* Name of the device. Must always be terminated with a '\0', so 173 * the longest supported device name is 15 characters. 174 */ 175 char device_name[VSOC_DEVICE_NAME_SZ]; 176 /* There are two ways that permissions to access regions are handled: 177 * - When subdivided_by is VSOC_REGION_WHOLE, any process that can 178 * open the device node for the region gains complete access to it. 179 * - When subdivided is set processes that open the region cannot 180 * access it. Access to a sub-region must be established by invoking 181 * the VSOC_CREATE_FD_SCOPE_PERMISSION ioctl on the region 182 * referenced in subdivided_by, providing a fileinstance 183 * (represented by a fd) opened on this region. 184 */ 185 __u32 managed_by; 186 }; 187 188 /* 189 * The vsoc layout descriptor. 190 * The first 4K should be reserved for the shm header and region descriptors. 191 * The regions should be page aligned. 192 */ 193 194 struct vsoc_shm_layout_descriptor { 195 __u16 major_version; 196 __u16 minor_version; 197 198 /* size of the shm. This may be redundant but nice to have */ 199 __u32 size; 200 201 /* number of shared memory regions */ 202 __u32 region_count; 203 204 /* The offset to the start of region descriptors */ 205 __u32 vsoc_region_desc_offset; 206 }; 207 208 /* 209 * This specifies the current version that should be stored in 210 * vsoc_shm_layout_descriptor.major_version and 211 * vsoc_shm_layout_descriptor.minor_version. 212 * It should be updated only if the vsoc_device_region and 213 * vsoc_shm_layout_descriptor structures have changed. 214 * Versioning within each region is transferred 215 * via the min_compatible_version and current_version fields in 216 * vsoc_device_region. The driver does not consult these fields: they are left 217 * for the HALs and host processes and will change independently of the layout 218 * version. 219 */ 220 #define CURRENT_VSOC_LAYOUT_MAJOR_VERSION 2 221 #define CURRENT_VSOC_LAYOUT_MINOR_VERSION 0 222 223 #define VSOC_CREATE_FD_SCOPED_PERMISSION \ 224 _IOW(0xF5, 0, struct fd_scoped_permission) 225 #define VSOC_GET_FD_SCOPED_PERMISSION _IOR(0xF5, 1, struct fd_scoped_permission) 226 227 /* 228 * This is used to signal the host to scan the guest_to_host_signal_table 229 * for new futexes to wake. This sends an interrupt if one is not already 230 * in flight. 231 */ 232 #define VSOC_MAYBE_SEND_INTERRUPT_TO_HOST _IO(0xF5, 2) 233 234 /* 235 * When this returns the guest will scan host_to_guest_signal_table to 236 * check for new futexes to wake. 237 */ 238 /* TODO(ghartman): Consider moving this to the bottom half */ 239 #define VSOC_WAIT_FOR_INCOMING_INTERRUPT _IO(0xF5, 3) 240 241 /* 242 * Guest HALs will use this to retrieve the region description after 243 * opening their device node. 244 */ 245 #define VSOC_DESCRIBE_REGION _IOR(0xF5, 4, struct vsoc_device_region) 246 247 /* 248 * Wake any threads that may be waiting for a host interrupt on this region. 249 * This is mostly used during shutdown. 250 */ 251 #define VSOC_SELF_INTERRUPT _IO(0xF5, 5) 252 253 /* 254 * This is used to signal the host to scan the guest_to_host_signal_table 255 * for new futexes to wake. This sends an interrupt unconditionally. 256 */ 257 #define VSOC_SEND_INTERRUPT_TO_HOST _IO(0xF5, 6) 258 259 enum wait_types { 260 VSOC_WAIT_UNDEFINED = 0, 261 VSOC_WAIT_IF_EQUAL = 1, 262 VSOC_WAIT_IF_EQUAL_TIMEOUT = 2 263 }; 264 265 /* 266 * Wait for a condition to be true 267 * 268 * Note, this is sized and aligned so the 32 bit and 64 bit layouts are 269 * identical. 270 */ 271 struct vsoc_cond_wait { 272 /* Input: Offset of the 32 bit word to check */ 273 __u32 offset; 274 /* Input: Value that will be compared with the offset */ 275 __u32 value; 276 /* Monotonic time to wake at in seconds */ 277 __u64 wake_time_sec; 278 /* Input: Monotonic time to wait in nanoseconds */ 279 __u32 wake_time_nsec; 280 /* Input: Type of wait */ 281 __u32 wait_type; 282 /* Output: Number of times the thread woke before returning. */ 283 __u32 wakes; 284 /* Ensure that we're 8-byte aligned and 8 byte length for 32/64 bit 285 * compatibility. 286 */ 287 __u32 reserved_1; 288 }; 289 290 #define VSOC_COND_WAIT _IOWR(0xF5, 7, struct vsoc_cond_wait) 291 292 /* Wake any local threads waiting at the offset given in arg */ 293 #define VSOC_COND_WAKE _IO(0xF5, 8) 294 295 #endif /* _UAPI_LINUX_VSOC_SHM_H */ 296
