membuff.h 7.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246
/*
 * Copyright (c) 2015 Google, Inc
 * Written by Simon Glass <sjg@chromium.org>
 *
 * Copyright (c) 1992 Simon Glass
 *
 * SPDX-License-Identifier:	GPL-2.0+
 */

#ifndef _MEMBUFF_H
#define _MEMBUFF_H

/**
 * @struct membuff: holds the state of a membuff - it is used for input and
 * output buffers. The buffer extends from @start to (@start + @size - 1).
 * Data in the buffer extends from @tail to @head: it is written in at
 * @head and read out from @tail. The membuff is empty when @head == @tail
 * and full when adding another character would make @head == @tail. We
 * therefore waste one character in the membuff to avoid having an extra flag
 * to determine whether (when @head == @tail) the membuff is empty or full.
 *
 * xxxxxx  data
 * ......  empty
 *
 * .............xxxxxxxxxxxxxxxx.........................
 *		^		^
 *		tail		head
 *
 * xxxxxxxxxxxxx................xxxxxxxxxxxxxxxxxxxxxxxxx
 *		^		^
 *		head		tail
 */
struct membuff {
	char *start;		/** the start of the buffer */
	char *end;		/** the end of the buffer (start + length) */
	char *head;		/** current buffer head */
	char *tail;		/** current buffer tail */
};

/**
 * membuff_purge() - reset a membuff to the empty state
 *
 * Initialise head and tail pointers so that the membuff becomes empty.
 *
 * @mb: membuff to purge
 */
void membuff_purge(struct membuff *mb);

/**
 * membuff_putraw() - find out where bytes can be written
 *
 * Work out where in the membuff some data could be written. Return a pointer
 * to the address and the number of bytes which can be written there. If
 * @update is true, the caller must then write the data immediately, since
 * the membuff is updated as if the write has been done,
 *
 * Note that because the spare space in a membuff may not be contiguous, this
 * function may not return @maxlen even if there is enough space in the
 * membuff. However, by calling this function twice (with @update == true),
 * you will get access to all the spare space.
 *
 * @mb: membuff to adjust
 * @maxlen: the number of bytes we want to write
 * @update: true to update the membuff as if the write happened, false to not
 * @data: the address data can be written to
 * @return number of bytes which can be written
 */
int membuff_putraw(struct membuff *mb, int maxlen, bool update, char **data);

/**
 * membuff_getraw() - find and return a pointer to available bytes
 *
 * Returns a pointer to any valid input data in the given membuff and
 * optionally marks it as read. Note that not all input data may not be
 * returned, since data is not necessarily contiguous in the membuff. However,
 * if you call this function twice (with @update == true) you are guaranteed
 * to get all available data, in at most two installments.
 *
 * @mb: membuff to adjust
 * @maxlen: maximum number of bytes to get
 * @update: true to update the membuff as if the bytes have been read (use
 * false to check bytes without reading them)
 * @data: returns address of data in input membuff
 * @return the number of bytes available at *@data
 */
int membuff_getraw(struct membuff *mb, int maxlen, bool update, char **data);

/**
 * membuff_putbyte() - Writes a byte to a membuff
 *
 * @mb: membuff to adjust
 * @ch: byte to write
 * @return true on success, false if membuff is full
 */
bool membuff_putbyte(struct membuff *mb, int ch);

/**
 * @mb: membuff to adjust
 * membuff_getbyte() - Read a byte from the membuff
 * @return the byte read, or -1 if the membuff is empty
 */
int membuff_getbyte(struct membuff *mb);

/**
 * membuff_peekbyte() - check the next available byte
 *
 * Return the next byte which membuff_getbyte() would return, without
 * removing it from the membuff.
 *
 * @mb: membuff to adjust
 * @return the byte peeked, or -1 if the membuff is empty
 */
int membuff_peekbyte(struct membuff *mb);

/**
 * membuff_get() - get data from a membuff
 *
 * Copies any available data (up to @maxlen bytes) to @buff and removes it
 * from the membuff.
 *
 * @mb: membuff to adjust
 * @Buff: address of membuff to transfer bytes to
 * @maxlen: maximum number of bytes to read
 * @return the number of bytes read
 */
int membuff_get(struct membuff *mb, char *buff, int maxlen);

/**
 * membuff_put() - write data to a membuff
 *
 * Writes some data to a membuff. Returns the number of bytes added. If this
 * is less than @lnehgt, then the membuff got full
 *
 * @mb: membuff to adjust
 * @data: the data to write
 * @length: number of bytes to write from 'data'
 * @return the number of bytes added
 */
int membuff_put(struct membuff *mb, const char *buff, int length);

/**
 * membuff_isempty() - check if a membuff is empty
 *
 * @mb: membuff to check
 * @return true if empty, else false
 */
bool membuff_isempty(struct membuff *mb);

/**
 * membuff_avail() - check available data in a membuff
 *
 * @mb: membuff to check
 * @return number of bytes of data available
 */
int membuff_avail(struct membuff *mb);

/**
 * membuff_size() - get the size of a membuff
 *
 * Note that a membuff can only old data up to one byte less than its size.
 *
 * @mb: membuff to check
 * @return total size
 */
int membuff_size(struct membuff *mb);

/**
 * membuff_makecontig() - adjust all membuff data to be contiguous
 *
 * This places all data in a membuff into a single contiguous lump, if
 * possible
 *
 * @mb: membuff to adjust
 * @return true on success
 */
bool membuff_makecontig(struct membuff *mb);

/**
 * membuff_free() - find the number of bytes that can be written to a membuff
 *
 * @mb: membuff to check
 * @return returns the number of bytes free in a membuff
 */
int membuff_free(struct membuff *mb);

/**
 * membuff_readline() - read a line of text from a membuff
 *
 * Reads a line of text of up to 'maxlen' characters from a membuff and puts
 * it in @str. Any character less than @minch is assumed to be the end of
 * line character
 *
 * @mb: membuff to adjust
 * @str: Place to put the line
 * @maxlen: Maximum line length (excluding terminator)
 * @return number of bytes read (including terminator) if a line has been
 *	   read, 0 if nothing was there
 */
int membuff_readline(struct membuff *mb, char *str, int maxlen, int minch);

/**
 * membuff_extend_by() - expand a membuff
 *
 * Extends a membuff by the given number of bytes
 *
 * @mb: membuff to adjust
 * @by: Number of bytes to increase the size by
 * @max: Maximum size to allow
 * @return 0 if the expand succeeded, -ENOMEM if not enough memory, -E2BIG
 * if the the size would exceed @max
 */
int membuff_extend_by(struct membuff *mb, int by, int max);

/**
 * membuff_init() - set up a new membuff using an existing membuff
 *
 * @mb: membuff to set up
 * @buff: Address of buffer
 * @size: Size of buffer
 */
void membuff_init(struct membuff *mb, char *buff, int size);

/**
 * membuff_uninit() - clear a membuff so it can no longer be used
 *
 * @mb: membuff to uninit
 */
void membuff_uninit(struct membuff *mb);

/**
 * membuff_new() - create a new membuff
 *
 * @mb: membuff to init
 * @size: size of membuff to create
 * @return 0 if OK, -ENOMEM if out of memory
 */
int membuff_new(struct membuff *mb, int size);

/**
 * membuff_dispose() - free memory allocated to a membuff and uninit it
 *
 * @mb: membuff to dispose
 */
void membuff_dispose(struct membuff *mb);

#endif