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 */ 32 struct 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 */ 46 void 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 */ 67 int 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 */ 85 int 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 */ 94 bool 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 */ 101 int 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 */ 112 int 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 */ 125 int 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 */ 138 int 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 */ 146 bool 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 */ 154 int 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 */ 164 int 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 */ 175 bool 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 */ 183 int 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 * @return number of bytes read (including terminator) if a line has been 196 * read, 0 if nothing was there 197 */ 198 int membuff_readline(struct membuff *mb, char *str, int maxlen, int minch); 199 200 /** 201 * membuff_extend_by() - expand a membuff 202 * 203 * Extends a membuff by the given number of bytes 204 * 205 * @mb: membuff to adjust 206 * @by: Number of bytes to increase the size by 207 * @max: Maximum size to allow 208 * @return 0 if the expand succeeded, -ENOMEM if not enough memory, -E2BIG 209 * if the the size would exceed @max 210 */ 211 int membuff_extend_by(struct membuff *mb, int by, int max); 212 213 /** 214 * membuff_init() - set up a new membuff using an existing membuff 215 * 216 * @mb: membuff to set up 217 * @buff: Address of buffer 218 * @size: Size of buffer 219 */ 220 void membuff_init(struct membuff *mb, char *buff, int size); 221 222 /** 223 * membuff_uninit() - clear a membuff so it can no longer be used 224 * 225 * @mb: membuff to uninit 226 */ 227 void membuff_uninit(struct membuff *mb); 228 229 /** 230 * membuff_new() - create a new membuff 231 * 232 * @mb: membuff to init 233 * @size: size of membuff to create 234 * @return 0 if OK, -ENOMEM if out of memory 235 */ 236 int membuff_new(struct membuff *mb, int size); 237 238 /** 239 * membuff_dispose() - free memory allocated to a membuff and uninit it 240 * 241 * @mb: membuff to dispose 242 */ 243 void membuff_dispose(struct membuff *mb); 244 245 #endif 246