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
|
#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 */
|
