1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#ifndef MMAL_POOL_H
29#define MMAL_POOL_H
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** \defgroup MmalPool Pools of buffer headers
36 * A pool of buffer headers is composed of a queue (\ref MMAL_QUEUE_T) and a user
37 * specified number of buffer headers (\ref MMAL_BUFFER_HEADER_T). */
38/* @{ */
39
40#include "mmal_queue.h"
41
42/** Definition of a pool */
43typedef struct MMAL_POOL_T
44{
45 MMAL_QUEUE_T *queue; /**< Queue used by the pool */
46 uint32_t headers_num; /**< Number of buffer headers in the pool */
47 MMAL_BUFFER_HEADER_T **header; /**< Array of buffer headers belonging to the pool */
48} MMAL_POOL_T;
49
50/** Allocator alloc prototype
51 *
52 * @param context The context pointer passed in on pool creation.
53 * @param size The size of the allocation required, in bytes.
54 * @return The pointer to the newly allocated memory, or NULL on failure.
55 */
56typedef void *(*mmal_pool_allocator_alloc_t)(void *context, uint32_t size);
57/** Allocator free prototype
58 *
59 * @param context The context pointer passed in on pool creation.
60 * @param mem The pointer to the memory to be released.
61 */
62typedef void (*mmal_pool_allocator_free_t)(void *context, void *mem);
63
64/** Create a pool of MMAL_BUFFER_HEADER_T.
65 * After allocation, all allocated buffer headers will have been added to the queue.
66 *
67 * It is valid to create a pool with no buffer headers, or with zero size payload buffers.
68 * The mmal_pool_resize() function can be used to increase or decrease the number of buffer
69 * headers, or the size of the payload buffers, after creation of the pool.
70 *
71 * The payload buffers may also be allocated independently by the client, and assigned
72 * to the buffer headers, but it will be the responsibility of the client to deal with
73 * resizing and releasing the memory. It is recommended that mmal_pool_create_with_allocator()
74 * is used in this case, supplying allocator function pointers that will be used as
75 * necessary by MMAL.
76 *
77 * @param headers Number of buffer headers to be allocated with the pool.
78 * @param payload_size Size of the payload buffer that will be allocated in
79 * each of the buffer headers.
80 * @return Pointer to the newly created pool or NULL on failure.
81 */
82MMAL_POOL_T *mmal_pool_create(unsigned int headers, uint32_t payload_size);
83
84/** Create a pool of MMAL_BUFFER_HEADER_T.
85 * After allocation, all allocated buffer headers will have been added to the queue.
86 *
87 * It is valid to create a pool with no buffer headers, or with zero size payload buffers.
88 * The mmal_pool_resize() function can be used to increase or decrease the number of buffer
89 * headers, or the size of the payload buffers, after creation of the pool. The allocators
90 * passed during creation shall be used when resizing the payload buffers.
91 *
92 * @param headers Number of buffer headers to be allocated with the pool.
93 * @param payload_size Size of the payload buffer that will be allocated in
94 * each of the buffer headers.
95 * @param allocator_context Pointer to the context of the allocator.
96 * @param allocator_alloc Function pointer for the alloc call of the allocator.
97 * @param allocator_free Function pointer for the free call of the allocator.
98 *
99 * @return Pointer to the newly created pool or NULL on failure.
100 */
101MMAL_POOL_T *mmal_pool_create_with_allocator(unsigned int headers, uint32_t payload_size,
102 void *allocator_context, mmal_pool_allocator_alloc_t allocator_alloc,
103 mmal_pool_allocator_free_t allocator_free);
104
105/** Destroy a pool of MMAL_BUFFER_HEADER_T.
106 * This will also deallocate all of the memory which was allocated when creating or
107 * resizing the pool.
108 *
109 * If payload buffers have been allocated independently by the client, they should be
110 * released prior to calling this function. If the client provided allocator functions,
111 * the allocator_free function shall be called for each payload buffer.
112 *
113 * @param pool Pointer to a pool
114 */
115void mmal_pool_destroy(MMAL_POOL_T *pool);
116
117/** Resize a pool of MMAL_BUFFER_HEADER_T.
118 * This allows modifying either the number of allocated buffers, the payload size or both at the
119 * same time.
120 *
121 * @param pool Pointer to the pool
122 * @param headers New number of buffer headers to be allocated in the pool.
123 * It is not valid to pass zero for the number of buffers.
124 * @param payload_size Size of the payload buffer that will be allocated in
125 * each of the buffer headers.
126 * If this is set to 0, all payload buffers shall be released.
127 * @return MMAL_SUCCESS or an error on failure.
128 */
129MMAL_STATUS_T mmal_pool_resize(MMAL_POOL_T *pool, unsigned int headers, uint32_t payload_size);
130
131/** Definition of the callback used by a pool to signal back to the user that a buffer header
132 * has been released back to the pool.
133 *
134 * @param pool Pointer to the pool
135 * @param buffer Buffer header just released
136 * @param userdata User specific data passed in when setting the callback
137 * @return True to have the buffer header put back in the pool's queue, false if the buffer
138 * header has been taken within the callback.
139 */
140typedef MMAL_BOOL_T (*MMAL_POOL_BH_CB_T)(MMAL_POOL_T *pool, MMAL_BUFFER_HEADER_T *buffer, void *userdata);
141
142/** Set a buffer header release callback to the pool.
143 * Each time a buffer header is released to the pool, the callback will be triggered.
144 *
145 * @param pool Pointer to a pool
146 * @param cb Callback function
147 * @param userdata User specific data which will be passed with each callback
148 */
149void mmal_pool_callback_set(MMAL_POOL_T *pool, MMAL_POOL_BH_CB_T cb, void *userdata);
150
151/** Set a pre-release callback for all buffer headers in the pool.
152 * Each time a buffer header is about to be released to the pool, the callback
153 * will be triggered.
154 *
155 * @param pool Pointer to the pool
156 * @param cb Pre-release callback function
157 * @param userdata User-specific data passed back with each callback
158 */
159void mmal_pool_pre_release_callback_set(MMAL_POOL_T *pool, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata);
160
161/* @} */
162
163#ifdef __cplusplus
164}
165#endif
166
167#endif /* MMAL_POOL_H */
168