1 /* 2 * Copyright (C) 2020 ARM Limited. All rights reserved. 3 * 4 * Copyright 2016 The Android Open Source Project 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 #ifndef GRALLOC_COMMON_MAPPER_H 20 #define GRALLOC_COMMON_MAPPER_H 21 22 #include <inttypes.h> 23 #include "mali_gralloc_log.h" 24 #include "core/mali_gralloc_bufferdescriptor.h" 25 26 #include "4.x/gralloc_mapper_hidl_header.h" 27 28 namespace arm 29 { 30 namespace mapper 31 { 32 namespace common 33 { 34 35 using android::hardware::hidl_handle; 36 using android::hardware::hidl_vec; 37 using android::hardware::Void; 38 39 /** 40 * Imports a raw buffer handle to create an imported buffer handle for use with 41 * the rest of the mapper or with other in-process libraries. 42 * 43 * @param rawHandle [in] Raw buffer handle to import. 44 * @param hidl_cb [in] HIDL Callback function to export output information 45 * @param hidl_cb [in] HIDL callback function generating - 46 * error : NONE upon success. Otherwise, 47 * BAD_BUFFER for an invalid buffer 48 * NO_RESOURCES when the raw handle cannot be imported 49 * BAD_VALUE when any of the specified attributes are invalid 50 * buffer : Imported buffer handle 51 */ 52 void importBuffer(const hidl_handle &rawHandle, IMapper::importBuffer_cb hidl_cb); 53 54 /** 55 * Frees a buffer handle and releases all the resources associated with it 56 * 57 * @param buffer [in] Imported buffer to free 58 * 59 * @return Error::BAD_BUFFER for an invalid buffer / when failed to free the buffer 60 * Error::NONE on successful free 61 */ 62 Error freeBuffer(void *buffer); 63 64 /** 65 * Locks the given buffer for the specified CPU usage. 66 * 67 * @param buffer [in] Buffer to lock 68 * @param cpuUsage [in] Specifies one or more CPU usage flags to request 69 * @param accessRegion [in] Portion of the buffer that the client intends to access 70 * @param acquireFence [in] Handle for aquire fence object 71 * @param hidl_cb [in] HIDL callback function generating - 72 * error: NONE upon success. Otherwise, 73 * BAD_BUFFER for an invalid buffer 74 * BAD_VALUE for an invalid input parameters 75 * data: CPU-accessible pointer to the buffer data 76 * bytesPerPixel: v3.X Only. Number of bytes per pixel in the buffer 77 * bytesPerStride: v3.X Only. Bytes per stride of the buffer 78 */ 79 void lock(void *buffer, uint64_t cpuUsage, const IMapper::Rect &accessRegion, const hidl_handle &acquireFence, 80 IMapper::lock_cb hidl_cb); 81 82 /** 83 * Unlocks a buffer to indicate all CPU accesses to the buffer have completed 84 * 85 * @param buffer [in] Buffer to lock. 86 * @param hidl_cb [in] HIDL callback function generating - 87 * error: NONE upon success. Otherwise, 88 * BAD_BUFFER for an invalid buffer 89 * releaseFence: Referrs to a sync fence object 90 */ 91 void unlock(void *buffer, IMapper::unlock_cb hidl_cb); 92 93 /** 94 * Validates the buffer against specified descriptor attributes 95 * 96 * @param buffer [in] Buffer which needs to be validated. 97 * @param descriptorInfo [in] Required attributes of the buffer 98 * @param in_stride [in] Buffer stride returned by IAllocator::allocate, 99 * or zero if unknown. 100 * 101 * @return Error::NONE upon success. Otherwise, 102 * Error::BAD_BUFFER upon bad buffer input 103 * Error::BAD_VALUE when any of the specified attributes are invalid 104 */ 105 Error validateBufferSize(void *buffer, const IMapper::BufferDescriptorInfo &descriptorInfo, uint32_t stride); 106 107 /** 108 * Get the transport size of a buffer 109 * 110 * @param buffer [in] Buffer for computing transport size 111 * @param hidl_cb [in] HIDL callback function generating - 112 * error: NONE upon success. Otherwise, 113 * BAD_BUFFER for an invalid buffer 114 * numFds: Number of file descriptors needed for transport 115 * numInts: Number of integers needed for transport 116 */ 117 void getTransportSize(void *buffer, IMapper::getTransportSize_cb hidl_cb); 118 119 /** 120 * Test whether the given BufferDescriptorInfo is allocatable. 121 * 122 * @param description [in] Description for the buffer 123 * @param hidl_cb [in] HIDL callback function generating - 124 * error: NONE, for supported description 125 * BAD_VALUE, Otherwise, 126 * supported: Whether the description can be allocated 127 */ 128 void isSupported(const IMapper::BufferDescriptorInfo &description, IMapper::isSupported_cb hidl_cb); 129 130 /* TODO: implement this feature for exynos */ 131 /** 132 * Flushes the CPU caches of a mapped buffer. 133 * 134 * @param buffer [in] Locked buffer which needs to have CPU caches flushed. 135 * @param hidl_cb [in] HIDL callback function generating - 136 * error: NONE upon success. Otherwise, BAD_BUFFER for an invalid buffer or a buffer that 137 * has not been locked. 138 * releaseFence: Empty fence signaling completion as all work is completed within the call. 139 */ 140 void flushLockedBuffer(void *buffer, IMapper::flushLockedBuffer_cb hidl_cb); 141 142 /* TODO: implement this feature for exynos */ 143 /** 144 * Invalidates the CPU caches of a mapped buffer. 145 * 146 * @param buffer [in] Locked buffer which needs to have CPU caches invalidated. 147 * 148 * @return Error::NONE upon success. 149 * Error::BAD_BUFFER for an invalid buffer or a buffer that has not been locked. 150 */ 151 Error rereadLockedBuffer(void *buffer); 152 153 /** 154 * Retrieves a Buffer's metadata value. 155 * 156 * @param buffer [in] The buffer to query for metadata. 157 * @param metadataType [in] The type of metadata queried. 158 * @param hidl_cb [in] HIDL callback function generating - 159 * error: NONE on success. 160 * BAD_BUFFER on invalid buffer argument. 161 * UNSUPPORTED on error when reading or unsupported metadata type. 162 * metadata: Vector of bytes representing the metadata value. 163 */ 164 void get(void *buffer, const IMapper::MetadataType &metadataType, IMapper::get_cb hidl_cb); 165 166 /** 167 * Sets a Buffer's metadata value. 168 * 169 * @param buffer [in] The buffer for which to modify metadata. 170 * @param metadataType [in] The type of metadata to modify. 171 * @param metadata [in] Vector of bytes representing the new value for the metadata associated with the buffer. 172 * 173 * @return Error::NONE on success. 174 * Error::BAD_BUFFER on invalid buffer argument. 175 * Error::UNSUPPORTED on error when writing or unsupported metadata type. 176 */ 177 Error set(void *buffer, const IMapper::MetadataType &metadataType, const hidl_vec<uint8_t> &metadata); 178 179 /** 180 * Lists all the MetadataTypes supported by IMapper as well as a description 181 * of each supported MetadataType. For StandardMetadataTypes, the description 182 * string can be left empty. 183 * 184 * @param hidl_cb [in] HIDL callback function generating - 185 * error: Error status of the call, which may be 186 * - NONE upon success. 187 * - NO_RESOURCES if the get cannot be fullfilled due to unavailability of 188 * resources. 189 * descriptions: vector of MetadataTypeDescriptions that represent the 190 * MetadataTypes supported by the device. 191 */ 192 void listSupportedMetadataTypes(IMapper::listSupportedMetadataTypes_cb hidl_cb); 193 194 /** 195 * Dumps a buffer's metadata. 196 * 197 * @param buffer [in] Buffer that is being dumped 198 * @param hidl_cb [in] HIDL callback function generating - 199 * error: Error status of the call, which may be 200 * - NONE upon success. 201 * - BAD_BUFFER if the raw handle is invalid. 202 * - NO_RESOURCES if the get cannot be fullfilled due to unavailability of 203 * resources. 204 * bufferDump: Struct representing the metadata being dumped 205 */ 206 void dumpBuffer(void *buffer, IMapper::dumpBuffer_cb hidl_cb); 207 208 /** 209 * Dumps the metadata for all the buffers in the current process. 210 * 211 * @param hidl_cb [in] HIDL callback function generating - 212 * error: Error status of the call, which may be 213 * - NONE upon success. 214 * - NO_RESOURCES if the get cannot be fullfilled due to unavailability of 215 * resources. 216 * bufferDumps: Vector of structs representing the buffers being dumped 217 */ 218 void dumpBuffers(IMapper::dumpBuffers_cb hidl_cb); 219 220 /** 221 * Returns the region of shared memory associated with the buffer that is 222 * reserved for client use. 223 * 224 * The shared memory may be allocated from any shared memory allocator. 225 * The shared memory must be CPU-accessible and virtually contiguous. The 226 * starting address must be word-aligned. 227 * 228 * This function may only be called after importBuffer() has been called by the 229 * client. The reserved region must remain accessible until freeBuffer() has 230 * been called. After freeBuffer() has been called, the client must not access 231 * the reserved region. 232 * 233 * This reserved memory may be used in future versions of Android to 234 * help clients implement backwards compatible features without requiring 235 * IAllocator/IMapper updates. 236 * 237 * @param buffer Imported buffer handle. 238 * @param hidl_cb [in] HIDL callback function generating - 239 * error: Error status of the call, which may be 240 * - NONE upon success. 241 * - BAD_BUFFER if the buffer is invalid. 242 * reservedRegion: CPU-accessible pointer to the reserved region 243 * reservedSize: the size of the reservedRegion that was requested 244 * in the BufferDescriptorInfo. 245 */ 246 void getReservedRegion(void *buffer, IMapper::getReservedRegion_cb _hidl_cb); 247 248 } // namespace common 249 } // namespace mapper 250 } // namespace arm 251 252 #endif /* GRALLOC_COMMON_MAPPER_H */ 253