blob: 78918e726443f838e984098c16c0f08e96c36066 [file] [log] [blame]
Simon Glassb7b65092015-11-08 23:47:47 -07001/*
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 */
33struct 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 */
47void 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 */
68int 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 */
86int 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 */
95bool 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 */
102int 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 */
113int 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 */
126int 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 */
139int 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 */
147bool 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 */
155int 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 */
165int 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 */
176bool 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 */
184int 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 */
199int 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 */
212int 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 */
221void 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 */
228void 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 */
237int 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 */
244void membuff_dispose(struct membuff *mb);
245
246#endif