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