jcs.org
"Das U-Boot" Source Tree
1/* SPDX-License-Identifier: GPL-2.0+ */
2/*
3 * Handles a buffer that can be allocated and freed
4 *
5 * Copyright 2021 Google LLC
6 * Written by Simon Glass <sjg@chromium.org>
7 */
8
9#ifndef __ABUF_H
10#define __ABUF_H
11
12#ifdef USE_HOSTCC
13#include <sys/types.h>
14#else
15#include <linux/types.h>
16#endif
17
18/**
19 * struct abuf - buffer that can be allocated and freed
20 *
21 * This is useful for a block of data which may be allocated with malloc(), or
22 * not, so that it needs to be freed correctly when finished with.
23 *
24 * For now it has a very simple purpose.
25 *
26 * Using memset() to zero all fields is guaranteed to be equivalent to
27 * abuf_init().
28 *
29 * @data: Pointer to data
30 * @size: Size of data in bytes
31 * @alloced: true if allocated with malloc(), so must be freed after use
32 */
33struct abuf {
34 void *data;
35 size_t size;
36 bool alloced;
37};
38
39static inline void *abuf_data(const struct abuf *abuf)
40{
41 return abuf->data;
42}
43
44static inline size_t abuf_size(const struct abuf *abuf)
45{
46 return abuf->size;
47}
48
49/**
50 * abuf_addr() - Get the address of a buffer's data
51 *
52 * @abuf: Buffer to check
53 * Return: address of buffer
54 */
55ulong abuf_addr(const struct abuf *abuf);
56
57/**
58 * abuf_set() - set the (unallocated) data in a buffer
59 *
60 * This simply makes the abuf point to the supplied data, which must be live
61 * for the lifetime of the abuf. It is not alloced.
62 *
63 * Any existing data in the abuf is freed and the alloced member is set to
64 * false.
65 *
66 * @abuf: abuf to adjust
67 * @data: New contents of abuf
68 * @size: New size of abuf
69 */
70void abuf_set(struct abuf *abuf, void *data, size_t size);
71
72/**
73 * abuf_map_sysmem() - calls map_sysmem() to set up an abuf
74 *
75 * This is equivalent to abuf_set(abuf, map_sysmem(addr, size), size)
76 *
77 * Any existing data in the abuf is freed and the alloced member is set to
78 * false.
79 *
80 * @abuf: abuf to adjust
81 * @addr: Address to set the abuf to
82 * @size: New size of abuf
83 */
84void abuf_map_sysmem(struct abuf *abuf, ulong addr, size_t size);
85
86/**
87 * abuf_realloc() - Change the size of a buffer
88 *
89 * This uses realloc() to change the size of the buffer, with the same semantics
90 * as that function. If the abuf is not currently alloced, then it will alloc
91 * it if the size needs to increase (i.e. set the alloced member to true)
92 *
93 * @abuf: abuf to adjust
94 * @new_size: new size in bytes.
95 * if 0, the abuf is freed
96 * if greater than the current size, the abuf is extended and the new
97 * space is not inited. The alloced member is set to true
98 * if less than the current size, the abuf is contracted and the data at
99 * the end is lost. If @new_size is 0, this sets the alloced member to
100 * false
101 * Return: true if OK, false if out of memory
102 */
103bool abuf_realloc(struct abuf *abuf, size_t new_size);
104
105/**
106 * abuf_realloc_inc() - Increment abuf size by a given amount
107 *
108 * @abuf: abuf to adjust
109 * @inc: Size incrmement to use (the buffer size will be increased by this much)
110 * Return: true if OK, false if out of memory
111 */
112bool abuf_realloc_inc(struct abuf *abuf, size_t inc);
113
114/**
115 * abuf_uninit_move() - Return the allocated contents and uninit the abuf
116 *
117 * This returns the abuf data to the caller, allocating it if necessary, so that
118 * the caller receives data that it can be sure will hang around. The caller is
119 * responsible for freeing the data.
120 *
121 * If the abuf has allocated data, it is returned. If the abuf has data but it
122 * is not allocated, then it is first allocated, then returned.
123 *
124 * If the abuf size is 0, this returns NULL
125 *
126 * The abuf is uninited as part of this, except if the allocation fails, in
127 * which NULL is returned and the abuf remains untouched.
128 *
129 * The abuf must be inited before this can be called.
130 *
131 * @abuf: abuf to uninit
132 * @sizep: if non-NULL, returns the size of the returned data
133 * Return: data contents, allocated with malloc(), or NULL if the data could not
134 * be allocated, or the data size is 0
135 */
136void *abuf_uninit_move(struct abuf *abuf, size_t *sizep);
137
138/**
139 * abuf_init_move() - Make abuf take over the management of an allocated region
140 *
141 * After this, @data must not be used. All access must be via the abuf.
142 *
143 * @abuf: abuf to init
144 * @data: Existing allocated buffer to place in the abuf
145 * @size: Size of allocated buffer
146 */
147void abuf_init_move(struct abuf *abuf, void *data, size_t size);
148
149/**
150 * abuf_init_set() - Set up a new abuf
151 *
152 * Inits a new abuf and sets up its (unallocated) data
153 *
154 * @abuf: abuf to set up
155 * @data: New contents of abuf
156 * @size: New size of abuf
157 */
158void abuf_init_set(struct abuf *abuf, void *data, size_t size);
159
160/**
161 * abuf_init_const() - Set up a new const abuf
162 *
163 * Inits a new abuf and sets up its (unallocated) data. The only current
164 * difference between this and abuf_init_set() is the 'data' parameter is a
165 * const pointer. At some point a flag could be used to indicate const-ness.
166 *
167 * @abuf: abuf to set up
168 * @data: New contents of abuf
169 * @size: New size of abuf
170 */
171void abuf_init_const(struct abuf *abuf, const void *data, size_t size);
172
173/**
174 * abuf_uninit() - Free any memory used by an abuf
175 *
176 * The buffer must be inited before this can be called.
177 *
178 * @abuf: abuf to uninit
179 */
180void abuf_uninit(struct abuf *abuf);
181
182/**
183 * abuf_init() - Set up a new abuf
184 *
185 * This initially has no data and alloced is set to false. This is equivalent to
186 * setting all fields to 0, e.g. with memset(), so callers can do that instead
187 * if desired.
188 *
189 * @abuf: abuf to set up
190 */
191void abuf_init(struct abuf *abuf);
192
193#endif