|
|
#ifndef BUFFER_H
#define 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 /* BUFFER_H */
|
