1 /* SPDX-License-Identifier: Apache-2.0 OR MIT */ 2 /* 3 * Copyright (c) 2015 Rockchip Electronics Co., Ltd. 4 */ 5 6 #ifndef __MPP_BUFFER_H__ 7 #define __MPP_BUFFER_H__ 8 9 #include "rk_type.h" 10 #include "mpp_err.h" 11 12 /* 13 * MppBuffer module has several functions: 14 * 15 * 1. buffer get / put / reference management / external commit / get info. 16 * this part is the basic user interface for MppBuffer. 17 * 18 * function: 19 * 20 * mpp_buffer_get 21 * mpp_buffer_put 22 * mpp_buffer_inc_ref 23 * mpp_buffer_commit 24 * mpp_buffer_info_get 25 * 26 * 2. user buffer working flow control abstraction. 27 * buffer should attach to certain group, and buffer mode control the buffer usage flow. 28 * this part is also a part of user interface. 29 * 30 * function: 31 * 32 * mpp_buffer_group_get 33 * mpp_buffer_group_normal_get 34 * mpp_buffer_group_limit_get 35 * mpp_buffer_group_put 36 * mpp_buffer_group_limit_config 37 * 38 * 3. buffer allocator management 39 * this part is for allocator on different os, it does not have user interface 40 * it will support normal buffer, Android ion buffer, Linux v4l2 vb2 buffer 41 * user can only use MppBufferType to choose. 42 * 43 */ 44 45 /* 46 * mpp buffer group support two work flow mode: 47 * 48 * normal flow: all buffer are generated by MPP 49 * under this mode, buffer pool is maintained internally 50 * 51 * typical call flow: 52 * 53 * mpp_buffer_group_get() return A 54 * mpp_buffer_get(A) return a ref +1 -> used 55 * mpp_buffer_inc_ref(a) ref +1 56 * mpp_buffer_put(a) ref -1 57 * mpp_buffer_put(a) ref -1 -> unused 58 * mpp_buffer_group_put(A) 59 * 60 * commit flow: all buffer are commited out of MPP 61 * under this mode, buffers is commit by external api. 62 * normally MPP only use it but not generate it. 63 * 64 * typical call flow: 65 * 66 * ==== external allocator ==== 67 * mpp_buffer_group_get() return A 68 * mpp_buffer_commit(A, x) 69 * mpp_buffer_commit(A, y) 70 * 71 * ======= internal user ====== 72 * mpp_buffer_get(A) return a 73 * mpp_buffer_get(A) return b 74 * mpp_buffer_put(a) 75 * mpp_buffer_put(b) 76 * 77 * ==== external allocator ==== 78 * mpp_buffer_group_put(A) 79 * 80 * NOTE: commit interface required group handle to record group information 81 */ 82 83 /* 84 * mpp buffer group has two buffer limit mode: normal and limit 85 * 86 * normal mode: allows any buffer size and always general new buffer is no unused buffer 87 * is available. 88 * This mode normally use with normal flow and is used for table / stream buffer 89 * 90 * limit mode : restrict the buffer's size and count in the buffer group. if try to calloc 91 * buffer with different size or extra count it will fail. 92 * This mode normally use with commit flow and is used for frame buffer 93 */ 94 95 /* 96 * NOTE: normal mode is recommanded to work with normal flow, working with limit mode is not. 97 * limit mode is recommanded to work with commit flow, working with normal mode is not. 98 */ 99 typedef enum { 100 MPP_BUFFER_INTERNAL, 101 MPP_BUFFER_EXTERNAL, 102 MPP_BUFFER_MODE_BUTT, 103 } MppBufferMode; 104 105 /* 106 * the mpp buffer has serval types: 107 * 108 * normal : normal malloc buffer for unit test or hardware simulation 109 * ion : use ion device under Android/Linux, MppBuffer will encapsulte ion file handle 110 * ext_dma : the DMABUF(DMA buffers) come from the application 111 * drm : use the drm device interface for memory management 112 * 113 * MPP default allocator select priority for kernel above 5.10: 114 * MPP_BUFFER_TYPE_DMA_HEAP > MPP_BUFFER_TYPE_DRM > MPP_BUFFER_TYPE_ION 115 * MPP_BUFFER_TYPE_EXT_DMA is only used for general external dma_buf fd import. 116 */ 117 typedef enum { 118 MPP_BUFFER_TYPE_NORMAL, 119 MPP_BUFFER_TYPE_ION, 120 MPP_BUFFER_TYPE_EXT_DMA, 121 MPP_BUFFER_TYPE_DRM, 122 MPP_BUFFER_TYPE_DMA_HEAP, 123 MPP_BUFFER_TYPE_BUTT, 124 } MppBufferType; 125 126 #define MPP_BUFFER_TYPE_MASK 0x0000FFFF 127 128 /* 129 * MPP_BUFFER_FLAGS cooperate with MppBufferType 130 * 16 high bits of MppBufferType are used in flags 131 * 132 * eg: 133 * DMA_HEAP CMA buffer : MPP_BUFFER_TYPE_DMA_HEAP | MPP_BUFFER_FLAGS_CONTIG 134 * = 0x00010004 135 * DRM SECURE buffer : MPP_BUFFER_TYPE_DRM | MPP_BUFFER_FLAGS_SECURE 136 * = 0x00080003 137 * 138 * The dma buffer source can also be set by format: flags | type. 139 * dma buffer source flags: 140 * MPP_BUFFER_FLAGS_CONTIG means cma 141 * MPP_BUFFER_FLAGS_CACHABLE means cachable 142 * MPP_BUFFER_FLAGS_DMA32 means dma32 143 * 144 * flags originate from drm_rockchip_gem_mem_type 145 */ 146 #define MPP_BUFFER_FLAGS_MASK 0x003f0000 //ROCKCHIP_BO_MASK << 16 147 #define MPP_BUFFER_FLAGS_CONTIG 0x00010000 //ROCKCHIP_BO_CONTIG << 16 148 #define MPP_BUFFER_FLAGS_CACHABLE 0x00020000 //ROCKCHIP_BO_CACHABLE << 16 149 #define MPP_BUFFER_FLAGS_WC 0x00040000 //ROCKCHIP_BO_WC << 16 150 #define MPP_BUFFER_FLAGS_SECURE 0x00080000 //ROCKCHIP_BO_SECURE << 16 151 #define MPP_BUFFER_FLAGS_ALLOC_KMAP 0x00100000 //ROCKCHIP_BO_ALLOC_KMAP << 16 152 #define MPP_BUFFER_FLAGS_DMA32 0x00200000 //ROCKCHIP_BO_DMA32 << 16 153 154 /* 155 * MppBufferInfo variable's meaning is different in different MppBufferType 156 * 157 * Common 158 * index - the buffer index used to track buffer in buffer pool 159 * size - the buffer size 160 * 161 * MPP_BUFFER_TYPE_NORMAL 162 * 163 * ptr - virtual address of normal malloced buffer 164 * fd - unused and set to -1, the allocator would return its 165 * internal buffer counter number 166 * 167 * MPP_BUFFER_TYPE_ION 168 * 169 * ptr - virtual address of ion buffer in user space 170 * hnd - ion handle in user space 171 * fd - ion buffer file handle for map / unmap 172 * 173 */ 174 typedef struct MppBufferInfo_t { 175 MppBufferType type; 176 size_t size; 177 void *ptr; 178 void *hnd; 179 int fd; 180 int index; 181 } MppBufferInfo; 182 183 #define BUFFER_GROUP_SIZE_DEFAULT (SZ_1M*80) 184 185 /* 186 * mpp_buffer_import_with_tag(MppBufferGroup group, MppBufferInfo *info, MppBuffer *buffer) 187 * 188 * 1. group - specified the MppBuffer to be attached to. 189 * group can be NULL then this buffer will attached to default legecy group 190 * Default to NULL on mpp_buffer_import case 191 * 192 * 2. info - input information for the output MppBuffer 193 * info can NOT be NULL. It must contain at least one of ptr/fd. 194 * 195 * 3. buffer - generated MppBuffer from MppBufferInfo. 196 * buffer can be NULL then the buffer is commit to group with unused status. 197 * Otherwise generated buffer will be directly got and ref_count increased. 198 * Default to NULL on mpp_buffer_commit case 199 * 200 * mpp_buffer_commit usage: 201 * 202 * Add a external buffer info to group. This buffer will be on unused status. 203 * Typical usage is on Android. MediaPlayer gralloc Graphic buffer then commit these buffer 204 * to decoder's buffer group. Then decoder will recycle these buffer and return buffer reference 205 * to MediaPlayer for display. 206 * 207 * mpp_buffer_import usage: 208 * 209 * Transfer a external buffer info to MppBuffer but it is not expected to attached to certain 210 * buffer group. So the group is set to NULL. Then this buffer can be used for MppFrame/MppPacket. 211 * Typical usage is for image processing. Image processing normally will be a oneshot operation 212 * It does not need complicated group management. But in other hand mpp still need to know the 213 * imported buffer is leak or not and trace its usage inside mpp process. So we attach this kind 214 * of buffer to default misc buffer group for management. 215 */ 216 #define mpp_buffer_commit(group, info) \ 217 mpp_buffer_import_with_tag(group, info, NULL, MODULE_TAG, __FUNCTION__) 218 219 #define mpp_buffer_import(buffer, info) \ 220 mpp_buffer_import_with_tag(NULL, info, buffer, MODULE_TAG, __FUNCTION__) 221 222 #define mpp_buffer_get(group, buffer, size) \ 223 mpp_buffer_get_with_tag(group, buffer, size, MODULE_TAG, __FUNCTION__) 224 225 #define mpp_buffer_put(buffer) \ 226 mpp_buffer_put_with_caller(buffer, __FUNCTION__) 227 228 #define mpp_buffer_inc_ref(buffer) \ 229 mpp_buffer_inc_ref_with_caller(buffer, __FUNCTION__) 230 231 #define mpp_buffer_info_get(buffer, info) \ 232 mpp_buffer_info_get_with_caller(buffer, info, __FUNCTION__) 233 234 #define mpp_buffer_read(buffer, offset, data, size) \ 235 mpp_buffer_read_with_caller(buffer, offset, data, size, __FUNCTION__) 236 237 #define mpp_buffer_write(buffer, offset, data, size) \ 238 mpp_buffer_write_with_caller(buffer, offset, data, size, __FUNCTION__) 239 240 #define mpp_buffer_get_ptr(buffer) \ 241 mpp_buffer_get_ptr_with_caller(buffer, __FUNCTION__) 242 243 #define mpp_buffer_get_fd(buffer) \ 244 mpp_buffer_get_fd_with_caller(buffer, __FUNCTION__) 245 246 #define mpp_buffer_get_size(buffer) \ 247 mpp_buffer_get_size_with_caller(buffer, __FUNCTION__) 248 249 #define mpp_buffer_get_index(buffer) \ 250 mpp_buffer_get_index_with_caller(buffer, __FUNCTION__) 251 252 #define mpp_buffer_set_index(buffer, index) \ 253 mpp_buffer_set_index_with_caller(buffer, index, __FUNCTION__) 254 255 #define mpp_buffer_get_offset(buffer) \ 256 mpp_buffer_get_offset_with_caller(buffer, __FUNCTION__) 257 258 #define mpp_buffer_set_offset(buffer, offset) \ 259 mpp_buffer_set_offset_with_caller(buffer, offset, __FUNCTION__) 260 261 #define mpp_buffer_set_discard(buffer) \ 262 mpp_buffer_discard_with_caller(buffer, __FUNCTION__) 263 264 #define mpp_buffer_sync_begin(buffer) \ 265 mpp_buffer_sync_begin_f(buffer, 0, __FUNCTION__) 266 #define mpp_buffer_sync_end(buffer) \ 267 mpp_buffer_sync_end_f(buffer, 0, __FUNCTION__) 268 #define mpp_buffer_sync_partial_begin(buffer, offset, length) \ 269 mpp_buffer_sync_partial_begin_f(buffer, 0, offset, length, __FUNCTION__) 270 #define mpp_buffer_sync_partial_end(buffer, offset, length) \ 271 mpp_buffer_sync_partial_end_f(buffer, 0, offset, length, __FUNCTION__) 272 273 #define mpp_buffer_sync_ro_begin(buffer) \ 274 mpp_buffer_sync_begin_f(buffer, 1, __FUNCTION__) 275 #define mpp_buffer_sync_ro_end(buffer) \ 276 mpp_buffer_sync_end_f(buffer, 1, __FUNCTION__) 277 #define mpp_buffer_sync_ro_partial_begin(buffer, offset, length) \ 278 mpp_buffer_sync_partial_begin_f(buffer, 1, offset, length, __FUNCTION__) 279 #define mpp_buffer_sync_ro_partial_end(buffer, offset, length) \ 280 mpp_buffer_sync_partial_end_f(buffer, 1, offset, length, __FUNCTION__) 281 282 #define mpp_buffer_group_get_internal(group, type, ...) \ 283 mpp_buffer_group_get(group, (MppBufferType)(type), MPP_BUFFER_INTERNAL, MODULE_TAG, __FUNCTION__) 284 285 #define mpp_buffer_group_get_external(group, type, ...) \ 286 mpp_buffer_group_get(group, (MppBufferType)(type), MPP_BUFFER_EXTERNAL, MODULE_TAG, __FUNCTION__) 287 288 #ifdef __cplusplus 289 extern "C" { 290 #endif 291 292 /* 293 * MppBuffer interface 294 * these interface will change value of group and buffer so before calling functions 295 * parameter need to be checked. 296 * 297 * IMPORTANT: 298 * mpp_buffer_import_with_tag - compounded interface for commit and import 299 * 300 */ 301 MPP_RET mpp_buffer_import_with_tag(MppBufferGroup group, MppBufferInfo *info, MppBuffer *buffer, 302 const char *tag, const char *caller); 303 MPP_RET mpp_buffer_get_with_tag(MppBufferGroup group, MppBuffer *buffer, size_t size, 304 const char *tag, const char *caller); 305 MPP_RET mpp_buffer_put_with_caller(MppBuffer buffer, const char *caller); 306 MPP_RET mpp_buffer_inc_ref_with_caller(MppBuffer buffer, const char *caller); 307 MPP_RET mpp_buffer_discard_with_caller(MppBuffer buffer, const char *caller); 308 309 MPP_RET mpp_buffer_info_get_with_caller(MppBuffer buffer, MppBufferInfo *info, const char *caller); 310 MPP_RET mpp_buffer_read_with_caller(MppBuffer buffer, size_t offset, void *data, size_t size, const char *caller); 311 MPP_RET mpp_buffer_write_with_caller(MppBuffer buffer, size_t offset, void *data, size_t size, const char *caller); 312 void *mpp_buffer_get_ptr_with_caller(MppBuffer buffer, const char *caller); 313 int mpp_buffer_get_fd_with_caller(MppBuffer buffer, const char *caller); 314 size_t mpp_buffer_get_size_with_caller(MppBuffer buffer, const char *caller); 315 int mpp_buffer_get_index_with_caller(MppBuffer buffer, const char *caller); 316 MPP_RET mpp_buffer_set_index_with_caller(MppBuffer buffer, int index, const char *caller); 317 size_t mpp_buffer_get_offset_with_caller(MppBuffer buffer, const char *caller); 318 MPP_RET mpp_buffer_set_offset_with_caller(MppBuffer buffer, size_t offset, const char *caller); 319 320 /** 321 * @brief MppBuffer cache operation function 322 * @param buffer The MppBuffer to run the cache operation 323 * @param ro for readonly option 324 * @param offset partial sync data start offset 325 * @param length partial sync data length 326 */ 327 MPP_RET mpp_buffer_sync_begin_f(MppBuffer buffer, RK_S32 ro, const char* caller); 328 MPP_RET mpp_buffer_sync_end_f(MppBuffer buffer, RK_S32 ro, const char* caller); 329 MPP_RET mpp_buffer_sync_partial_begin_f(MppBuffer buffer, RK_S32 ro, RK_U32 offset, RK_U32 length, const char* caller); 330 MPP_RET mpp_buffer_sync_partial_end_f(MppBuffer buffer, RK_S32 ro, RK_U32 offset, RK_U32 length, const char* caller); 331 332 MPP_RET mpp_buffer_group_get(MppBufferGroup *group, MppBufferType type, MppBufferMode mode, 333 const char *tag, const char *caller); 334 MPP_RET mpp_buffer_group_put(MppBufferGroup group); 335 MPP_RET mpp_buffer_group_clear(MppBufferGroup group); 336 RK_S32 mpp_buffer_group_unused(MppBufferGroup group); 337 size_t mpp_buffer_group_usage(MppBufferGroup group); 338 MppBufferMode mpp_buffer_group_mode(MppBufferGroup group); 339 MppBufferType mpp_buffer_group_type(MppBufferGroup group); 340 341 /* 342 * size : 0 - no limit, other - max buffer size 343 * count : 0 - no limit, other - max buffer count 344 */ 345 MPP_RET mpp_buffer_group_limit_config(MppBufferGroup group, size_t size, RK_S32 count); 346 347 RK_U32 mpp_buffer_total_now(); 348 RK_U32 mpp_buffer_total_max(); 349 350 #ifdef __cplusplus 351 } 352 #endif 353 354 #endif /*__MPP_BUFFER_H__*/ 355