Просмотр исходного кода

Move API docs to buffer.h, implementation to buffer.c.

tags/v0.9.3
Michael Brown 19 лет назад
Родитель
Сommit
2ddbac101e
2 измененных файлов: 58 добавлений и 57 удалений
  1. 2
    54
      src/core/buffer.c
  2. 56
    3
      src/include/buffer.h

+ 2
- 54
src/core/buffer.c Просмотреть файл

@@ -1,59 +1,7 @@
1
+
1 2
 /** @file
2 3
  *
3
- * Buffers for loading files.
4
- *
5
- * This file provides routines for filling a buffer with data received
6
- * piecemeal, where the size of the data is not necessarily known in
7
- * advance.
8
- *
9
- * Some protocols do not provide a mechanism for us to know the size
10
- * of the file before we happen to receive a particular block
11
- * (e.g. the final block in an MTFTP transfer).  In addition, some
12
- * protocols (all the multicast protocols plus any TCP-based protocol)
13
- * can, in theory, provide the data in any order.
14
- *
15
- * Rather than requiring each protocol to implement its own equivalent
16
- * of "dd" to arrange the data into well-sized pieces before handing
17
- * off to the image loader, we provide these generic buffer functions
18
- * which assemble a file into a single contiguous block.  The whole
19
- * block is then passed to the image loader.
20
- *
21
- * Example usage:
22
- *
23
- * @code
24
- *
25
- *   struct buffer my_buffer;
26
- *   void *data;
27
- *   off_t offset;
28
- *   size_t len;
29
- *   
30
- *   // We have an area of memory [buf_start,buf_end) into which we want
31
- *   // to load a file, where buf_start and buf_end are physical addresses.
32
- *   buffer->start = buf_start;
33
- *   buffer->end = buf_end;
34
- *   init_buffer ( &buffer );
35
- *   ...
36
- *   while ( get_file_block ( ... ) ) {
37
- *     // Downloaded block is stored in [data,data+len), and represents 
38
- *     // the portion of the file at offsets [offset,offset+len)
39
- *     if ( ! fill_buffer ( &buffer, data, offset, len ) ) {
40
- *       // An error occurred
41
- *       return 0;
42
- *     }
43
- *     ...
44
- *   }
45
- *   ...
46
- *   // The whole file is now present at [buf_start,buf_start+filesize),
47
- *   // where buf_start is a physical address.  The struct buffer can simply
48
- *   // be discarded; there is no done_buffer() call.
49
- *
50
- * @endcode
51
- *
52
- * For a description of the internal operation, see \ref buffer_int.
53
- *
54
- */
55
-
56
-/** @page buffer_int Buffer internals
4
+ * Buffer internals.
57 5
  *
58 6
  * A buffer consists of a single, contiguous area of memory, some of
59 7
  * which is "filled" and the remainder of which is "free".  The

+ 56
- 3
src/include/buffer.h Просмотреть файл

@@ -1,9 +1,62 @@
1 1
 #ifndef BUFFER_H
2 2
 #define BUFFER_H
3 3
 
4
-#include "stdint.h"
4
+#include "etherboot.h"
5 5
 
6
-/* @file */
6
+/** @file
7
+ *
8
+ * Buffers for loading files.
9
+ *
10
+ * This file provides routines for filling a buffer with data received
11
+ * piecemeal, where the size of the data is not necessarily known in
12
+ * advance.
13
+ *
14
+ * Some protocols do not provide a mechanism for us to know the size
15
+ * of the file before we happen to receive a particular block
16
+ * (e.g. the final block in an MTFTP transfer).  In addition, some
17
+ * protocols (all the multicast protocols plus any TCP-based protocol)
18
+ * can, in theory, provide the data in any order.
19
+ *
20
+ * Rather than requiring each protocol to implement its own equivalent
21
+ * of "dd" to arrange the data into well-sized pieces before handing
22
+ * off to the image loader, we provide these generic buffer functions
23
+ * which assemble a file into a single contiguous block.  The whole
24
+ * block is then passed to the image loader.
25
+ *
26
+ * Example usage:
27
+ *
28
+ * @code
29
+ *
30
+ *   struct buffer my_buffer;
31
+ *   void *data;
32
+ *   off_t offset;
33
+ *   size_t len;
34
+ *   
35
+ *   // We have an area of memory [buf_start,buf_end) into which we want
36
+ *   // to load a file, where buf_start and buf_end are physical addresses.
37
+ *   buffer->start = buf_start;
38
+ *   buffer->end = buf_end;
39
+ *   init_buffer ( &buffer );
40
+ *   ...
41
+ *   while ( get_file_block ( ... ) ) {
42
+ *     // Downloaded block is stored in [data,data+len), and represents 
43
+ *     // the portion of the file at offsets [offset,offset+len)
44
+ *     if ( ! fill_buffer ( &buffer, data, offset, len ) ) {
45
+ *       // An error occurred
46
+ *       return 0;
47
+ *     }
48
+ *     ...
49
+ *   }
50
+ *   ...
51
+ *   // The whole file is now present at [buf_start,buf_start+filesize),
52
+ *   // where buf_start is a physical address.  The struct buffer can simply
53
+ *   // be discarded; there is no done_buffer() call.
54
+ *
55
+ * @endcode
56
+ *
57
+ * For a description of the internal operation, see buffer.c.
58
+ *
59
+ */
7 60
 
8 61
 /**
9 62
  * A buffer
@@ -23,7 +76,7 @@ struct buffer {
23 76
 /**
24 77
  * A free block descriptor.
25 78
  *
26
- * See \ref buffer_int for a full description of the fields.
79
+ * See buffer.c for a full description of the fields.
27 80
  *
28 81
  */
29 82
 struct buffer_free_block {

Загрузка…
Отмена
Сохранить