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/*=============================================================================
29VideoCore OS Abstraction Layer - fixed size allocator support
30=============================================================================*/
31
32#ifndef VCOS_BLOCKPOOL_H
33#define VCOS_BLOCKPOOL_H
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#include "interface/vcos/vcos_types.h"
40#include "vcos.h"
41
42/** \file
43 *
44 * Thread safe, fixed size allocator API.
45 *
46 */
47
48/** Initialises a block pool to use already allocated (e.g. statically)
49 * allocated memory.
50 *
51 * Different implementations will incur different overheads. Use
52 * VCOS_BLOCKPOOL_SIZE(num_blocks, block_size) to calculate the number
53 * of bytes required including overheads for the desired pools.
54 *
55 * @param pool Pointer to pool object
56 * @param num_blocks The number of blocks required.
57 * @param block_size The size of an individual block.
58 * @param start The address of the start of the pool.
59 * @param pool_size The size of the pool in bytes.
60 * @param align Alignment for block data. Use VCOS_BLOCKPOOL_ALIGN_DEFAULT
61 * for default word alignment.
62 * @param flags Reserved for future use.
63 * @param name Name of the pool. Used for diagnostics.
64 *
65 * @return VCOS_SUCCESS if the pool was created.
66 */
67
68VCOS_INLINE_DECL
69VCOS_STATUS_T vcos_blockpool_init(VCOS_BLOCKPOOL_T *pool,
70 VCOS_UNSIGNED num_blocks, VCOS_UNSIGNED block_size,
71 void *start, VCOS_UNSIGNED pool_size, VCOS_UNSIGNED align,
72 VCOS_UNSIGNED flags, const char *name);
73
74/** Creates a pool of blocks of a given size within a buffer allocated on
75 * the heap.
76 *
77 * The heap memory is freed when the block pool is destroyed by
78 * calling vcos_blockpool_delete.
79 *
80 * @param pool Pointer to pool object
81 * @param num_blocks The number of blocks required.
82 * @param block_size The size of an individual block.
83 * @param align Alignment for block data. Use VCOS_BLOCKPOOL_ALIGN_DEFAULT
84 * for default word alignment.
85 * @param flags Reserved for future use.
86 * @param name Name of the pool. Used for diagnostics.
87 *
88 * @return VCOS_SUCCESS if the pool was created.
89 */
90VCOS_INLINE_DECL
91VCOS_STATUS_T vcos_blockpool_create_on_heap(VCOS_BLOCKPOOL_T *pool,
92 VCOS_UNSIGNED num_blocks, VCOS_UNSIGNED block_size,
93 VCOS_UNSIGNED align, VCOS_UNSIGNED flags,
94 const char *name);
95
96/** Allocate a block from the pool
97 *
98 * @param pool Pointer to the pool to allocate from.
99 * @return a pointer to the newly allocated block or NULL if no blocks were
100 * available.
101 */
102VCOS_INLINE_DECL
103void *vcos_blockpool_alloc(VCOS_BLOCKPOOL_T *pool);
104
105/** Allocate a block from the pool and zero it.
106 *
107 * @param pool Pointer to the pool to allocate from.
108 * @return a pointer to the newly allocated block or NULL if no blocks were
109 * available.
110 */
111VCOS_INLINE_DECL
112void *vcos_blockpool_calloc(VCOS_BLOCKPOOL_T *pool);
113
114/** Returns a block to the pool.
115 *
116 * @param block The block to free.
117 */
118VCOS_INLINE_DECL
119void vcos_blockpool_free(void *block);
120
121/** Queries the number of available blocks in the pool.
122 * @param pool The pool to query.
123 */
124VCOS_INLINE_IMPL
125 VCOS_UNSIGNED vcos_blockpool_available_count(VCOS_BLOCKPOOL_T *pool);
126
127/** Queries the number of used blocks in the pool.
128 * @param pool The pool to query.
129 */
130VCOS_INLINE_IMPL
131 VCOS_UNSIGNED vcos_blockpool_used_count(VCOS_BLOCKPOOL_T *pool);
132
133/** Deinitialize a memory pool.
134 *
135 * @param pool The pool to de-initialize.
136 */
137VCOS_INLINE_DECL
138void vcos_blockpool_delete(VCOS_BLOCKPOOL_T *pool);
139
140/** Return an integer handle for a given allocated block. */
141VCOS_INLINE_DECL
142uint32_t vcos_blockpool_elem_to_handle(void *block);
143
144/** Convert an integer handle back into a pointer.
145 * Returns NULL if invalid. */
146VCOS_INLINE_DECL
147void *vcos_blockpool_elem_from_handle(VCOS_BLOCKPOOL_T *pool, uint32_t handle);
148
149/** Checks whether a pointer is an allocated block within the specified pool.
150 * Returns true if the block is valid, otherwise, false is returned. */
151VCOS_INLINE_DECL
152uint32_t vcos_blockpool_is_valid_elem(
153 VCOS_BLOCKPOOL_T *pool, const void *block);
154
155/** May be called once to allow the block pool to be extended by dynamically
156 * adding subpools. The block size cannot be altered.
157 *
158 * @param num_extensions The number of extensions that may be created.
159 * The maximum is (VCOS_BLOCKPOOL_MAX_SUBPOOLS - 1)
160 * @param num_blocks The number of blocks to allocate in each in each
161 * dynamically allocated subpool.
162 * @return VCOS_SUCCESS if successful.
163 */
164VCOS_INLINE_DECL
165 VCOS_STATUS_T vcos_blockpool_extend(VCOS_BLOCKPOOL_T *pool,
166 VCOS_UNSIGNED num_extensions, VCOS_UNSIGNED num_blocks);
167
168#ifdef __cplusplus
169}
170#endif
171#endif
172