include/membuff.h

   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