xref: /openbmc/u-boot/include/membuff.h (revision 626f048b)
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
247