]>
Commit | Line | Data |
---|---|---|
b7b65090 SG |
1 | /* |
2 | * Copyright (c) 2015 Google, Inc | |
3 | * Written by Simon Glass <sjg@chromium.org> | |
4 | * | |
5 | * Copyright (c) 1992 Simon Glass | |
6 | * | |
7 | * SPDX-License-Identifier: GPL-2.0+ | |
8 | */ | |
9 | ||
10 | #ifndef _MEMBUFF_H | |
11 | #define _MEMBUFF_H | |
12 | ||
13 | /** | |
14 | * @struct membuff: holds the state of a membuff - it is used for input and | |
15 | * output buffers. The buffer extends from @start to (@start + @size - 1). | |
16 | * Data in the buffer extends from @tail to @head: it is written in at | |
17 | * @head and read out from @tail. The membuff is empty when @head == @tail | |
18 | * and full when adding another character would make @head == @tail. We | |
19 | * therefore waste one character in the membuff to avoid having an extra flag | |
20 | * to determine whether (when @head == @tail) the membuff is empty or full. | |
21 | * | |
22 | * xxxxxx data | |
23 | * ...... empty | |
24 | * | |
25 | * .............xxxxxxxxxxxxxxxx......................... | |
26 | * ^ ^ | |
27 | * tail head | |
28 | * | |
29 | * xxxxxxxxxxxxx................xxxxxxxxxxxxxxxxxxxxxxxxx | |
30 | * ^ ^ | |
31 | * head tail | |
32 | */ | |
33 | struct membuff { | |
34 | char *start; /** the start of the buffer */ | |
35 | char *end; /** the end of the buffer (start + length) */ | |
36 | char *head; /** current buffer head */ | |
37 | char *tail; /** current buffer tail */ | |
38 | }; | |
39 | ||
40 | /** | |
41 | * membuff_purge() - reset a membuff to the empty state | |
42 | * | |
43 | * Initialise head and tail pointers so that the membuff becomes empty. | |
44 | * | |
45 | * @mb: membuff to purge | |
46 | */ | |
47 | void membuff_purge(struct membuff *mb); | |
48 | ||
49 | /** | |
50 | * membuff_putraw() - find out where bytes can be written | |
51 | * | |
52 | * Work out where in the membuff some data could be written. Return a pointer | |
53 | * to the address and the number of bytes which can be written there. If | |
54 | * @update is true, the caller must then write the data immediately, since | |
55 | * the membuff is updated as if the write has been done, | |
56 | * | |
57 | * Note that because the spare space in a membuff may not be contiguous, this | |
58 | * function may not return @maxlen even if there is enough space in the | |
59 | * membuff. However, by calling this function twice (with @update == true), | |
60 | * you will get access to all the spare space. | |
61 | * | |
62 | * @mb: membuff to adjust | |
63 | * @maxlen: the number of bytes we want to write | |
64 | * @update: true to update the membuff as if the write happened, false to not | |
65 | * @data: the address data can be written to | |
66 | * @return number of bytes which can be written | |
67 | */ | |
68 | int membuff_putraw(struct membuff *mb, int maxlen, bool update, char **data); | |
69 | ||
70 | /** | |
71 | * membuff_getraw() - find and return a pointer to available bytes | |
72 | * | |
73 | * Returns a pointer to any valid input data in the given membuff and | |
74 | * optionally marks it as read. Note that not all input data may not be | |
75 | * returned, since data is not necessarily contiguous in the membuff. However, | |
76 | * if you call this function twice (with @update == true) you are guaranteed | |
77 | * to get all available data, in at most two installments. | |
78 | * | |
79 | * @mb: membuff to adjust | |
80 | * @maxlen: maximum number of bytes to get | |
81 | * @update: true to update the membuff as if the bytes have been read (use | |
82 | * false to check bytes without reading them) | |
83 | * @data: returns address of data in input membuff | |
84 | * @return the number of bytes available at *@data | |
85 | */ | |
86 | int membuff_getraw(struct membuff *mb, int maxlen, bool update, char **data); | |
87 | ||
88 | /** | |
89 | * membuff_putbyte() - Writes a byte to a membuff | |
90 | * | |
91 | * @mb: membuff to adjust | |
92 | * @ch: byte to write | |
93 | * @return true on success, false if membuff is full | |
94 | */ | |
95 | bool membuff_putbyte(struct membuff *mb, int ch); | |
96 | ||
97 | /** | |
98 | * @mb: membuff to adjust | |
99 | * membuff_getbyte() - Read a byte from the membuff | |
100 | * @return the byte read, or -1 if the membuff is empty | |
101 | */ | |
102 | int membuff_getbyte(struct membuff *mb); | |
103 | ||
104 | /** | |
105 | * membuff_peekbyte() - check the next available byte | |
106 | * | |
107 | * Return the next byte which membuff_getbyte() would return, without | |
108 | * removing it from the membuff. | |
109 | * | |
110 | * @mb: membuff to adjust | |
111 | * @return the byte peeked, or -1 if the membuff is empty | |
112 | */ | |
113 | int membuff_peekbyte(struct membuff *mb); | |
114 | ||
115 | /** | |
116 | * membuff_get() - get data from a membuff | |
117 | * | |
118 | * Copies any available data (up to @maxlen bytes) to @buff and removes it | |
119 | * from the membuff. | |
120 | * | |
121 | * @mb: membuff to adjust | |
122 | * @Buff: address of membuff to transfer bytes to | |
123 | * @maxlen: maximum number of bytes to read | |
124 | * @return the number of bytes read | |
125 | */ | |
126 | int membuff_get(struct membuff *mb, char *buff, int maxlen); | |
127 | ||
128 | /** | |
129 | * membuff_put() - write data to a membuff | |
130 | * | |
131 | * Writes some data to a membuff. Returns the number of bytes added. If this | |
132 | * is less than @lnehgt, then the membuff got full | |
133 | * | |
134 | * @mb: membuff to adjust | |
135 | * @data: the data to write | |
136 | * @length: number of bytes to write from 'data' | |
137 | * @return the number of bytes added | |
138 | */ | |
139 | int membuff_put(struct membuff *mb, const char *buff, int length); | |
140 | ||
141 | /** | |
142 | * membuff_isempty() - check if a membuff is empty | |
143 | * | |
144 | * @mb: membuff to check | |
145 | * @return true if empty, else false | |
146 | */ | |
147 | bool membuff_isempty(struct membuff *mb); | |
148 | ||
149 | /** | |
150 | * membuff_avail() - check available data in a membuff | |
151 | * | |
152 | * @mb: membuff to check | |
153 | * @return number of bytes of data available | |
154 | */ | |
155 | int membuff_avail(struct membuff *mb); | |
156 | ||
157 | /** | |
158 | * membuff_size() - get the size of a membuff | |
159 | * | |
160 | * Note that a membuff can only old data up to one byte less than its size. | |
161 | * | |
162 | * @mb: membuff to check | |
163 | * @return total size | |
164 | */ | |
165 | int membuff_size(struct membuff *mb); | |
166 | ||
167 | /** | |
168 | * membuff_makecontig() - adjust all membuff data to be contiguous | |
169 | * | |
170 | * This places all data in a membuff into a single contiguous lump, if | |
171 | * possible | |
172 | * | |
173 | * @mb: membuff to adjust | |
174 | * @return true on success | |
175 | */ | |
176 | bool membuff_makecontig(struct membuff *mb); | |
177 | ||
178 | /** | |
179 | * membuff_free() - find the number of bytes that can be written to a membuff | |
180 | * | |
181 | * @mb: membuff to check | |
182 | * @return returns the number of bytes free in a membuff | |
183 | */ | |
184 | int membuff_free(struct membuff *mb); | |
185 | ||
186 | /** | |
187 | * membuff_readline() - read a line of text from a membuff | |
188 | * | |
189 | * Reads a line of text of up to 'maxlen' characters from a membuff and puts | |
190 | * it in @str. Any character less than @minch is assumed to be the end of | |
191 | * line character | |
192 | * | |
193 | * @mb: membuff to adjust | |
194 | * @str: Place to put the line | |
195 | * @maxlen: Maximum line length (excluding terminator) | |
196 | * @return number of bytes read (including terminator) if a line has been | |
197 | * read, 0 if nothing was there | |
198 | */ | |
199 | int membuff_readline(struct membuff *mb, char *str, int maxlen, int minch); | |
200 | ||
201 | /** | |
202 | * membuff_extend_by() - expand a membuff | |
203 | * | |
204 | * Extends a membuff by the given number of bytes | |
205 | * | |
206 | * @mb: membuff to adjust | |
207 | * @by: Number of bytes to increase the size by | |
208 | * @max: Maximum size to allow | |
209 | * @return 0 if the expand succeeded, -ENOMEM if not enough memory, -E2BIG | |
210 | * if the the size would exceed @max | |
211 | */ | |
212 | int membuff_extend_by(struct membuff *mb, int by, int max); | |
213 | ||
214 | /** | |
215 | * membuff_init() - set up a new membuff using an existing membuff | |
216 | * | |
217 | * @mb: membuff to set up | |
218 | * @buff: Address of buffer | |
219 | * @size: Size of buffer | |
220 | */ | |
221 | void membuff_init(struct membuff *mb, char *buff, int size); | |
222 | ||
223 | /** | |
224 | * membuff_uninit() - clear a membuff so it can no longer be used | |
225 | * | |
226 | * @mb: membuff to uninit | |
227 | */ | |
228 | void membuff_uninit(struct membuff *mb); | |
229 | ||
230 | /** | |
231 | * membuff_new() - create a new membuff | |
232 | * | |
233 | * @mb: membuff to init | |
234 | * @size: size of membuff to create | |
235 | * @return 0 if OK, -ENOMEM if out of memory | |
236 | */ | |
237 | int membuff_new(struct membuff *mb, int size); | |
238 | ||
239 | /** | |
240 | * membuff_dispose() - free memory allocated to a membuff and uninit it | |
241 | * | |
242 | * @mb: membuff to dispose | |
243 | */ | |
244 | void membuff_dispose(struct membuff *mb); | |
245 | ||
246 | #endif |