1/*
2 * Copyright (c) 2021 Rockchip Electronics Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef __MPP_BUFFER_H__
17#define __MPP_BUFFER_H__
18
19#include "rk_type.h"
20#include "mpp_err.h"
21
22/*
23 * MppBuffer module has several functions:
24 *
25 * 1. buffer get / put / reference management / external commit / get info.
26 *    this part is the basic user interface for MppBuffer.
27 *
28 *    function:
29 *
30 *    mpp_buffer_get
31 *    mpp_buffer_put
32 *    mpp_buffer_inc_ref
33 *    mpp_buffer_commit
34 *    mpp_buffer_info_get
35 *
36 * 2. user buffer working flow control abstraction.
37 *    buffer should attach to certain group, and buffer mode control the buffer usage flow.
38 *    this part is also a part of user interface.
39 *
40 *    function:
41 *
42 *    mpp_buffer_group_get
43 *    mpp_buffer_group_normal_get
44 *    mpp_buffer_group_limit_get
45 *    mpp_buffer_group_put
46 *    mpp_buffer_group_limit_config
47 *
48 * 3. buffer allocator management
49 *    this part is for allocator on different os, it does not have user interface
50 *    it will support normal buffer, ion buffer, Linux v4l2 vb2 buffer
51 *    user can only use MppBufferType to choose.
52 *
53 */
54
55/*
56 * mpp buffer group support two work flow mode:
57 *
58 * normal flow: all buffer are generated by MPP
59 *              under this mode, buffer pool is maintained internally
60 *
61 *              typical call flow:
62 *
63 *              mpp_buffer_group_get()          return A
64 *              mpp_buffer_get(A)               return a    ref +1 -> used
65 *              mpp_buffer_inc_ref(a)                       ref +1
66 *              mpp_buffer_put(a)                           ref -1
67 *              mpp_buffer_put(a)                           ref -1 -> unused
68 *              mpp_buffer_group_put(A)
69 *
70 * commit flow: all buffer are commited out of MPP
71 *              under this mode, buffers is commit by external api.
72 *              normally MPP only use it but not generate it.
73 *
74 *              typical call flow:
75 *
76 *              ==== external allocator ====
77 *              mpp_buffer_group_get()          return A
78 *              mpp_buffer_commit(A, x)
79 *              mpp_buffer_commit(A, y)
80 *
81 *              ======= internal user ======
82 *              mpp_buffer_get(A)               return a
83 *              mpp_buffer_get(A)               return b
84 *              mpp_buffer_put(a)
85 *              mpp_buffer_put(b)
86 *
87 *              ==== external allocator ====
88 *              mpp_buffer_group_put(A)
89 *
90 *              NOTE: commit interface required group handle to record group information
91 */
92
93/*
94 * mpp buffer group has two buffer limit mode: normal and limit
95 *
96 * normal mode: allows any buffer size and always general new buffer is no unused buffer
97 *              is available.
98 *              This mode normally use with normal flow and is used for table / stream buffer
99 *
100 * limit mode : restrict the buffer's size and count in the buffer group. if try to calloc
101 *              buffer with different size or extra count it will fail.
102 *              This mode normally use with commit flow and is used for frame buffer
103 */
104
105/*
106 * NOTE: normal mode is recommanded to work with normal flow, working with limit  mode is not.
107 *       limit  mode is recommanded to work with commit flow, working with normal mode is not.
108 */
109typedef enum {
110    MPP_BUFFER_INTERNAL,
111    MPP_BUFFER_EXTERNAL,
112    MPP_BUFFER_MODE_BUTT,
113} MppBufferMode;
114
115/*
116 * the mpp buffer has serval types:
117 *
118 * normal   : normal malloc buffer for unit test or hardware simulation
119 * ion      : use ion device under Linux, MppBuffer will encapsulte ion file handle
120 * ext_dma  : the DMABUF(DMA buffers) come from the application
121 * drm      : use the drm device interface for memory management
122 */
123typedef enum {
124    MPP_BUFFER_TYPE_NORMAL,
125    MPP_BUFFER_TYPE_ION,
126    MPP_BUFFER_TYPE_EXT_DMA,
127    MPP_BUFFER_TYPE_DRM,
128    MPP_BUFFER_TYPE_BUTT,
129} MppBufferType;
130
131#define MPP_BUFFER_TYPE_MASK 0x0000FFFF
132
133/*
134 * MPP_BUFFER_FLAGS cooperate with MppBufferType
135 * 16 high bits of MppBufferType are used in flags
136 *
137 * eg:
138 * DRM CMA buffer : MPP_BUFFER_TYPE_DRM | MPP_BUFFER_FLAGS_CONTIG
139 *                  = 0x00010003
140 * DRM SECURE buffer: MPP_BUFFER_TYPE_DRM | MPP_BUFFER_FLAGS_SECURE
141 *                  = 0x00080003
142 *
143 * flags originate from drm_rockchip_gem_mem_type
144 */
145
146#define MPP_BUFFER_FLAGS_MASK 0x000f0000     // 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
152/*
153 * MppBufferInfo variable's meaning is different in different MppBufferType
154 *
155 * Common
156 * index - the buffer index used to track buffer in buffer pool
157 * size  - the buffer size
158 *
159 * MPP_BUFFER_TYPE_NORMAL
160 *
161 * ptr  - virtual address of normal malloced buffer
162 * fd   - unused and set to -1, the allocator would return its
163 *         internal buffer counter number
164 *
165 * MPP_BUFFER_TYPE_ION
166 *
167 * ptr  - virtual address of ion buffer in user space
168 * hnd  - ion handle in user space
169 * fd   - ion buffer file handle for map / unmap
170 *
171 */
172typedef struct MppBufferInfo_t {
173    MppBufferType type;
174    size_t size;
175    void *ptr;
176    void *hnd;
177    int fd;
178    int index;
179} MppBufferInfo;
180
181#define BUFFER_GROUP_SIZE_DEFAULT (SZ_1M * 80)
182
183/*
184 * mpp_buffer_import_with_tag(MppBufferGroup group, MppBufferInfo *info, MppBuffer *buffer)
185 *
186 * 1. group - specified the MppBuffer to be attached to.
187 *    group can be NULL then this buffer will attached to default legecy group
188 *    Default to NULL on mpp_buffer_import case
189 *
190 * 2. info  - input information for the output MppBuffer
191 *    info can NOT be NULL. It must contain at least one of ptr/fd.
192 *
193 * 3. buffer - generated MppBuffer from MppBufferInfo.
194 *    buffer can be NULL then the buffer is commit to group with unused status.
195 *    Otherwise generated buffer will be directly got and ref_count increased.
196 *    Default to NULL on mpp_buffer_commit case
197 *
198 * mpp_buffer_commit usage:
199 *
200 * Add a external buffer info to group. This buffer will be on unused status.
201 * Typical usage is on MediaPlayer gralloc Graphic buffer then commit these buffer
202 * to decoder's buffer group. Then decoder will recycle these buffer and return buffer reference
203 * to MediaPlayer for display.
204 *
205 * mpp_buffer_import usage:
206 *
207 * Transfer a external buffer info to MppBuffer but it is not expected to attached to certain
208 * buffer group. So the group is set to NULL. Then this buffer can be used for MppFrame/MppPacket.
209 * Typical usage is for image processing. Image processing normally will be a oneshot operation
210 * It does not need complicated group management. But in other hand mpp still need to know the
211 * imported buffer is leak or not and trace its usage inside mpp process. So we attach this kind
212 * of buffer to default misc buffer group for management.
213 */
214#define mpp_buffer_commit(group, info) mpp_buffer_import_with_tag(group, info, NULL, MODULE_TAG, __FUNCTION__)
215
216#define mpp_buffer_import(buffer, info) mpp_buffer_import_with_tag(NULL, info, buffer, MODULE_TAG, __FUNCTION__)
217
218#define mpp_buffer_get(group, buffer, size) mpp_buffer_get_with_tag(group, buffer, size, MODULE_TAG, __FUNCTION__)
219
220#define mpp_buffer_put(buffer) mpp_buffer_put_with_caller(buffer, __FUNCTION__)
221
222#define mpp_buffer_inc_ref(buffer) mpp_buffer_inc_ref_with_caller(buffer, __FUNCTION__)
223
224#define mpp_buffer_info_get(buffer, info) mpp_buffer_info_get_with_caller(buffer, info, __FUNCTION__)
225
226#define mpp_buffer_read(buffer, offset, data, size)                                                                    \
227    mpp_buffer_read_with_caller(buffer, offset, data, size, __FUNCTION__)
228
229#define mpp_buffer_write(buffer, offset, data, size)                                                                   \
230    mpp_buffer_write_with_caller(buffer, offset, data, size, __FUNCTION__)
231
232#define mpp_buffer_get_ptr(buffer) mpp_buffer_get_ptr_with_caller(buffer, __FUNCTION__)
233
234#define mpp_buffer_get_fd(buffer) mpp_buffer_get_fd_with_caller(buffer, __FUNCTION__)
235
236#define mpp_buffer_get_size(buffer) mpp_buffer_get_size_with_caller(buffer, __FUNCTION__)
237
238#define mpp_buffer_get_index(buffer) mpp_buffer_get_index_with_caller(buffer, __FUNCTION__)
239
240#define mpp_buffer_set_index(buffer, index) mpp_buffer_set_index_with_caller(buffer, index, __FUNCTION__)
241
242#define mpp_buffer_get_offset(buffer) mpp_buffer_get_offset_with_caller(buffer, __FUNCTION__)
243
244#define mpp_buffer_set_offset(buffer, offset) mpp_buffer_set_offset_with_caller(buffer, offset, __FUNCTION__)
245
246#define mpp_buffer_group_get_internal(group, type, ...)                                                                \
247    mpp_buffer_group_get(group, type, MPP_BUFFER_INTERNAL, MODULE_TAG, __FUNCTION__)
248
249#define mpp_buffer_group_get_external(group, type, ...)                                                                \
250    mpp_buffer_group_get(group, type, MPP_BUFFER_EXTERNAL, MODULE_TAG, __FUNCTION__)
251
252#ifdef __cplusplus
253extern "C" {
254#endif
255
256/*
257 * MppBuffer interface
258 * these interface will change value of group and buffer so before calling functions
259 * parameter need to be checked.
260 *
261 * IMPORTANT:
262 * mpp_buffer_import_with_tag - compounded interface for commit and import
263 *
264 */
265MPP_RET mpp_buffer_import_with_tag(MppBufferGroup group, MppBufferInfo *info, MppBuffer *buffer, const char *tag,
266                                   const char *caller);
267MPP_RET mpp_buffer_get_with_tag(MppBufferGroup group, MppBuffer *buffer, size_t size, const char *tag,
268                                const char *caller);
269MPP_RET mpp_buffer_put_with_caller(MppBuffer buffer, const char *caller);
270MPP_RET mpp_buffer_inc_ref_with_caller(MppBuffer buffer, const char *caller);
271
272MPP_RET mpp_buffer_info_get_with_caller(MppBuffer buffer, MppBufferInfo *info, const char *caller);
273MPP_RET mpp_buffer_read_with_caller(MppBuffer buffer, size_t offset, void *data, size_t size, const char *caller);
274MPP_RET mpp_buffer_write_with_caller(MppBuffer buffer, size_t offset, void *data, size_t size, const char *caller);
275void *mpp_buffer_get_ptr_with_caller(MppBuffer buffer, const char *caller);
276int mpp_buffer_get_fd_with_caller(MppBuffer buffer, const char *caller);
277size_t mpp_buffer_get_size_with_caller(MppBuffer buffer, const char *caller);
278int mpp_buffer_get_index_with_caller(MppBuffer buffer, const char *caller);
279MPP_RET mpp_buffer_set_index_with_caller(MppBuffer buffer, int index, const char *caller);
280size_t mpp_buffer_get_offset_with_caller(MppBuffer buffer, const char *caller);
281MPP_RET mpp_buffer_set_offset_with_caller(MppBuffer buffer, size_t offset, const char *caller);
282
283MPP_RET mpp_buffer_group_get(MppBufferGroup *group, MppBufferType type, MppBufferMode mode, const char *tag,
284                             const char *caller);
285MPP_RET mpp_buffer_group_put(MppBufferGroup group);
286MPP_RET mpp_buffer_group_clear(MppBufferGroup group);
287signed int mpp_buffer_group_unused(MppBufferGroup group);
288size_t mpp_buffer_group_usage(MppBufferGroup group);
289MppBufferMode mpp_buffer_group_mode(MppBufferGroup group);
290MppBufferType mpp_buffer_group_type(MppBufferGroup group);
291
292/*
293 * size  : 0 - no limit, other - max buffer size
294 * count : 0 - no limit, other - max buffer count
295 */
296MPP_RET mpp_buffer_group_limit_config(MppBufferGroup group, size_t size, signed int count);
297
298unsigned int mpp_buffer_total_now(void);
299unsigned int mpp_buffer_total_max(void);
300
301#ifdef __cplusplus
302}
303#endif
304
305#endif /* __MPP_BUFFER_H__ */