1/* 2 * Copyright 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package [email protected]; 18 19import [email protected]::BufferUsage; 20import [email protected]::PixelFormat; 21import [email protected]::Rect; 22 23interface IMapper { 24 struct BufferDescriptorInfo { 25 /** 26 * The width specifies how many columns of pixels must be in the 27 * allocated buffer, but does not necessarily represent the offset in 28 * columns between the same column in adjacent rows. The rows may be 29 * padded. 30 */ 31 uint32_t width; 32 33 /** 34 * The height specifies how many rows of pixels must be in the 35 * allocated buffer. 36 */ 37 uint32_t height; 38 39 /** 40 * The number of image layers that must be in the allocated buffer. 41 */ 42 uint32_t layerCount; 43 44 /** Buffer pixel format. */ 45 PixelFormat format; 46 47 /** 48 * Buffer usage mask; valid flags can be found in the definition of 49 * BufferUsage. 50 */ 51 bitfield<BufferUsage> usage; 52 }; 53 54 struct Rect { 55 int32_t left; 56 int32_t top; 57 int32_t width; 58 int32_t height; 59 }; 60 61 /** 62 * Creates a buffer descriptor. The descriptor can be used with IAllocator 63 * to allocate buffers. 64 * 65 * Since the buffer descriptor fully describes a buffer, any device 66 * dependent or device independent checks must be performed here whenever 67 * possible. Specifically, when layered buffers are not supported, this 68 * function must return `UNSUPPORTED` if `description.layers` is great than 69 * 1. 70 * 71 * @param description Attributes of the descriptor. 72 * @return error Error status of the call, which may be 73 * - `NONE` upon success. 74 * - `BAD_VALUE` if any of the specified attributes are invalid or 75 * inconsistent. 76 * - `NO_RESOURCES` if the creation cannot be fullfilled due to 77 * unavailability of resources. 78 * - `UNSUPPORTED` when any of the specified attributes are not 79 * supported. 80 * @return descriptor Newly created buffer descriptor. 81 */ 82 createDescriptor(BufferDescriptorInfo description) 83 generates (Error error, 84 BufferDescriptor descriptor); 85 86 /** 87 * Imports a raw buffer handle to create an imported buffer handle for use 88 * with the rest of the mapper or with other in-process libraries. 89 * 90 * A buffer handle is considered raw when it is cloned (e.g., with 91 * `native_handle_clone()`) from another buffer handle locally, or when it 92 * is received from another HAL server/client or another process. A raw 93 * buffer handle must not be used to access the underlying graphic 94 * buffer. It must be imported to create an imported handle first. 95 * 96 * This function must at least validate the raw handle before creating the 97 * imported handle. It must also support importing the same raw handle 98 * multiple times to create multiple imported handles. The imported handle 99 * must be considered valid everywhere in the process, including in 100 * another instance of the mapper. 101 * 102 * Because of passthrough HALs, a raw buffer handle received from a HAL 103 * may actually have been imported in the process. importBuffer() must treat 104 * such a handle as if it is raw and must not return `BAD_BUFFER`. The 105 * returned handle is independent from the input handle as usual, and 106 * freeBuffer() must be called on it when it is no longer needed. 107 * 108 * @param rawHandle Raw buffer handle to import. 109 * @return error Error status of the call, which may be 110 * - `NONE` upon success. 111 * - `BAD_BUFFER` if the raw handle is invalid. 112 * - `NO_RESOURCES` if the raw handle cannot be imported due to 113 * unavailability of resources. 114 * @return buffer Imported buffer handle that has the type 115 * `buffer_handle_t` which is a handle type. 116 */ 117 importBuffer(handle rawHandle) generates (Error error, pointer buffer); 118 119 /** 120 * Frees a buffer handle. Buffer handles returned by importBuffer() must be 121 * freed with this function when no longer needed. 122 * 123 * This function must free up all resources allocated by importBuffer() for 124 * the imported handle. For example, if the imported handle was created 125 * with `native_handle_create()`, this function must call 126 * `native_handle_close()` and `native_handle_delete()`. 127 * 128 * @param buffer Imported buffer handle. 129 * @return error Error status of the call, which may be 130 * - `NONE` upon success. 131 * - `BAD_BUFFER` if the buffer is invalid. 132 */ 133 freeBuffer(pointer buffer) generates (Error error); 134 135 /** 136 * Validates that the buffer can be safely accessed by a caller who assumes 137 * the specified @p description and @p stride. This must at least validate 138 * that the buffer size is large enough. Validating the buffer against 139 * individual buffer attributes is optional. 140 * 141 * @param buffer Buffer to validate against. 142 * @param description Attributes of the buffer. 143 * @param stride Stride returned by IAllocator::allocate(). 144 * @return error Error status of the call, which may be 145 * - `NONE` upon success. 146 * - `BAD_BUFFER` if the buffer is invalid. 147 * - `BAD_VALUE` if the buffer cannot be safely accessed. 148 */ 149 validateBufferSize(pointer buffer, 150 BufferDescriptorInfo description, 151 uint32_t stride) 152 generates (Error error); 153 154 /** 155 * Calculates the transport size of a buffer. An imported buffer handle is a 156 * raw buffer handle with the process-local runtime data appended. This 157 * function, for example, allows a caller to omit the process-local runtime 158 * data at the tail when serializing the imported buffer handle. 159 * 160 * Note that a client might or might not omit the process-local runtime data 161 * when sending an imported buffer handle. The mapper must support both 162 * cases on the receiving end. 163 * 164 * @param buffer Buffer to get the transport size from. 165 * @return error Error status of the call, which may be 166 * - `NONE` upon success. 167 * - `BAD_BUFFER` if the buffer is invalid. 168 * @return numFds The number of file descriptors needed for transport. 169 * @return numInts The number of integers needed for transport. 170 */ 171 getTransportSize(pointer buffer) 172 generates (Error error, 173 uint32_t numFds, 174 uint32_t numInts); 175 176 /** 177 * Locks the given buffer for the specified CPU usage. 178 * 179 * Locking the same buffer simultaneously from multiple threads is 180 * permitted, but if any of the threads attempt to lock the buffer for 181 * writing, the behavior is undefined, except that it must not cause 182 * process termination or block the client indefinitely. Leaving the 183 * buffer content in an indeterminate state or returning an error are both 184 * acceptable. 185 * 186 * 1D buffers (width = size in bytes, height = 1, pixel_format = BLOB) must 187 * "lock in place". The buffers must be directly accessible via mapping. 188 * 189 * The client must not modify the content of the buffer outside of 190 * @p accessRegion, and the device need not guarantee that content outside 191 * of @p accessRegion is valid for reading. The result of reading or writing 192 * outside of @p accessRegion is undefined, except that it must not cause 193 * process termination. 194 * 195 * On success, @p data must be filled with a pointer to the locked buffer 196 * memory. This address will represent the top-left corner of the entire 197 * buffer, even if @p accessRegion does not begin at the top-left corner. 198 * 199 * On success, bytesPerPixel must contain the number of bytes per pixel in 200 * the buffer. If the bytesPerPixel is unknown or variable, a value of -1 201 * should be returned. bytesPerStride must contain the bytes per stride of 202 * the buffer. If the bytesPerStride is unknown or variable, a value of -1 203 * should be returned. 204 * 205 * @param buffer Buffer to lock. 206 * @param cpuUsage CPU usage flags to request. See +ndk 207 * libnativewindow#AHardwareBuffer_UsageFlags for possible values. 208 * @param accessRegion Portion of the buffer that the client intends to 209 * access. 210 * @param acquireFence Handle containing a file descriptor referring to a 211 * sync fence object, which will be signaled when it is safe for the 212 * mapper to lock the buffer. @p acquireFence may be an empty fence if 213 * it is already safe to lock. 214 * @return error Error status of the call, which may be 215 * - `NONE` upon success. 216 * - `BAD_BUFFER` if the buffer is invalid or is incompatible with this 217 * function. 218 * - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or 219 * is incompatible with the buffer. 220 * - `NO_RESOURCES` if the buffer cannot be locked at this time. Note 221 * that locking may succeed at a later time. 222 * @return data CPU-accessible pointer to the buffer data. 223 * @return bytesPerPixel the number of bytes per pixel in the buffer 224 * @return bytesPerStride the number of bytes per stride of the buffer 225 */ 226 lock(pointer buffer, 227 uint64_t cpuUsage, 228 Rect accessRegion, 229 handle acquireFence) 230 generates (Error error, 231 pointer data, 232 int32_t bytesPerPixel, 233 int32_t bytesPerStride); 234 235 /** 236 * Locks a YCbCr buffer for the specified CPU usage. 237 * 238 * This is largely the same as lock(), except that instead of returning a 239 * pointer directly to the buffer data, it returns a `YCbCrLayout` struct 240 * describing how to access the data planes. 241 * 242 * This function must work on buffers with 243 * `AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_*` if supported by the device, as well 244 * as with any other formats requested by multimedia codecs when they are 245 * configured with a flexible-YUV-compatible color format. 246 * 247 * @param buffer Buffer to lock. 248 * @param cpuUsage CPU usage flags to request. See +ndk 249 * libnativewindow#AHardwareBuffer_UsageFlags for possible values. 250 * @param accessRegion Portion of the buffer that the client intends to 251 * access. 252 * @param acquireFence Handle containing a file descriptor referring to a 253 * sync fence object, which will be signaled when it is safe for the 254 * mapper to lock the buffer. @p acquireFence may be empty if it is 255 * already safe to lock. 256 * @return error Error status of the call, which may be 257 * - `NONE` upon success. 258 * - `BAD_BUFFER` if the buffer is invalid or is incompatible with this 259 * function. 260 * - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or 261 * is incompatible with the buffer. 262 * - `NO_RESOURCES` if the buffer cannot be locked at this time. Note 263 * that locking may succeed at a later time. 264 * @return layout Data layout of the locked buffer. 265 */ 266 lockYCbCr(pointer buffer, 267 uint64_t cpuUsage, 268 Rect accessRegion, 269 handle acquireFence) 270 generates (Error error, 271 YCbCrLayout layout); 272 273 /** 274 * Unlocks a buffer to indicate all CPU accesses to the buffer have 275 * completed. 276 * 277 * @param buffer Buffer to unlock. 278 * @return error Error status of the call, which may be 279 * - `NONE` upon success. 280 * - `BAD_BUFFER` if the buffer is invalid or not locked. 281 * @return releaseFence Handle containing a file descriptor referring to a 282 * sync fence object. The sync fence object will be signaled when the 283 * mapper has completed any pending work. @p releaseFence may be an 284 * empty fence. 285 */ 286 unlock(pointer buffer) generates (Error error, handle releaseFence); 287 288 /** 289 * Test whether the given BufferDescriptorInfo is allocatable. 290 * 291 * If this function returns true, it means that a buffer with the given 292 * description can be allocated on this implementation, unless resource 293 * exhaustion occurs. If this function returns false, it means that the 294 * allocation of the given description will never succeed. 295 * 296 * @param description the description of the buffer 297 * @return supported whether the description is supported 298 */ 299 isSupported(BufferDescriptorInfo description) 300 generates (Error error, 301 bool supported); 302 303}; 304 305