Move include/buffer.h to include/gpxe/buffer.h

1 files changed, 97 insertions, 0 deletions

diff --git a/src/include/gpxe/buffer.h b/src/include/gpxe/buffer.h
new file mode 100644
index 000000000..dba10b889
--- /dev/null
+++ b/src/include/gpxe/buffer.h
@@ -0,0 +1,97 @@
+#ifndef _GPXE_BUFFER_H
+#define _GPXE_BUFFER_H
+
+#include "compiler.h" /* for doxygen */
+#include "stdint.h"
+
+/** @file
+ *
+ * Buffers for loading files.
+ *
+ * This file provides routines for filling a buffer with data received
+ * piecemeal, where the size of the data is not necessarily known in
+ * advance.
+ *
+ * Some protocols do not provide a mechanism for us to know the size
+ * of the file before we happen to receive a particular block
+ * (e.g. the final block in an MTFTP transfer).  In addition, some
+ * protocols (all the multicast protocols plus any TCP-based protocol)
+ * can, in theory, provide the data in any order.
+ *
+ * Rather than requiring each protocol to implement its own equivalent
+ * of "dd" to arrange the data into well-sized pieces before handing
+ * off to the image loader, we provide these generic buffer functions
+ * which assemble a file into a single contiguous block.  The whole
+ * block is then passed to the image loader.
+ *
+ * Example usage:
+ *
+ * @code
+ *
+ *   struct buffer my_buffer;
+ *   void *data;
+ *   off_t offset;
+ *   size_t len;
+ *   
+ *   // We have an area of memory [buf_start,buf_end) into which we want
+ *   // to load a file, where buf_start and buf_end are physical addresses.
+ *   buffer->start = buf_start;
+ *   buffer->end = buf_end;
+ *   init_buffer ( &buffer );
+ *   ...
+ *   while ( get_file_block ( ... ) ) {
+ *     // Downloaded block is stored in [data,data+len), and represents 
+ *     // the portion of the file at offsets [offset,offset+len)
+ *     if ( ! fill_buffer ( &buffer, data, offset, len ) ) {
+ *       // An error occurred
+ *       return 0;
+ *     }
+ *     ...
+ *   }
+ *   ...
+ *   // The whole file is now present at [buf_start,buf_start+filesize),
+ *   // where buf_start is a physical address.  The struct buffer can simply
+ *   // be discarded; there is no done_buffer() call.
+ *
+ * @endcode
+ *
+ * For a description of the internal operation, see buffer.c.
+ *
+ */
+
+/**
+ * A buffer
+ *
+ * #start and #end denote the real boundaries of the buffer, and are
+ * physical addresses.  #fill denotes the offset to the first free
+ * block in the buffer.  (If the buffer is full, #fill will equal
+ * #end-#start.)
+ *
+ */
+struct buffer {
+	physaddr_t	start;		/**< Start of buffer in memory */
+	physaddr_t	end;		/**< End of buffer in memory */
+	off_t		fill;		/**< Offset to first gap in buffer */
+};
+
+/**
+ * A free block descriptor.
+ *
+ * See buffer.c for a full description of the fields.
+ *
+ */
+struct buffer_free_block {
+	char		tail;		/**< Tail byte marker */
+	char		reserved[3];	/**< Padding */
+	physaddr_t	start;		/**< Address of this free block */
+	physaddr_t	next;		/**< Address of next free block */
+	physaddr_t	end;		/**< End of this block */
+} __attribute__ (( packed ));
+
+/* Functions in buffer.c */
+
+extern void init_buffer ( struct buffer *buffer );
+extern int fill_buffer ( struct buffer *buffer, const void *data,
+			 off_t offset, size_t len );
+
+#endif /* _GPXE_BUFFER_H */