include/membuff.h

   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