浏览代码

More documentation

tags/v0.9.3
Michael Brown 19 年前
父节点
当前提交
e911a74724
共有 2 个文件被更改,包括 52 次插入25 次删除
  1. 34
    6
      src/core/buffer.c
  2. 18
    19
      src/include/buffer.h

+ 34
- 6
src/core/buffer.c 查看文件

@@ -49,15 +49,44 @@
49 49
  *
50 50
  * @endcode
51 51
  *
52
+ * For a description of the internal operation, see \ref buffer_int.
53
+ *
52 54
  */
53 55
 
54
-/** @package Internals
56
+/** @page buffer_int Buffer internals
57
+ *
58
+ * A buffer consists of a single, contiguous area of memory, some of
59
+ * which is "filled" and the remainder of which is "free".  The
60
+ * "filled" and "free" spaces are not necessarily contiguous.
61
+ *
62
+ * When a buffer is initialised via init_buffer(), it consists of a
63
+ * single free space.  As data is added to the buffer via
64
+ * fill_buffer(), this free space decreases and can become fragmented.
65
+ *
66
+ * Each free block within a buffer starts with a "tail byte".  If the
67
+ * tail byte is non-zero, this indicates that the free block is the
68
+ * tail of the buffer, i.e. occupies all the remaining space up to the
69
+ * end of the buffer.  When the tail byte is non-zero, it indicates
70
+ * that a descriptor (a @c struct @c buffer_free_block) follows the
71
+ * tail byte.  The descriptor describes the size of the free block and
72
+ * the address of the next free block.
73
+ *
74
+ * We cannot simply always start a free block with a descriptor,
75
+ * because it is conceivable that we will, at some point, encounter a
76
+ * situation in which the final free block of a buffer is too small to
77
+ * contain a descriptor.  Consider a protocol with a blocksize of 512
78
+ * downloading a 1025-byte file into a 1025-byte buffer.  Suppose that
79
+ * the first two blocks are received; we have now filled 1024 of the
80
+ * 1025 bytes in the buffer, and our only free block consists of the
81
+ * 1025th byte.  Using a "tail byte" solves this problem.
55 82
  *
83
+ * 
56 84
  * Note that the rather convoluted way of manipulating the buffer
57 85
  * descriptors (using copy_{to,from}_phys rather than straightforward
58 86
  * pointers) is needed to cope with operation as a PXE stack, when we
59 87
  * may be running in real mode or 16-bit protected mode, and therefore
60
- * cannot directly access arbitrary areas of memory.
88
+ * cannot directly access arbitrary areas of memory using simple
89
+ * pointers.
61 90
  *
62 91
  */
63 92
 
@@ -203,10 +232,9 @@ static inline void unfree_block ( struct buffer *buffer,
203 232
  * buffer_free_block) apart.  If this condition is not satisfied, data
204 233
  * corruption will occur.  (See split_free_block() for details.)
205 234
  *
206
- * @att In practice this is not a problem.  Callers of fill_buffer()
207
- * will be download protocols such as TFTP, and very few protocols
208
- * have a block size smaller than @c sizeof(struct @c
209
- * buffer_free_block).
235
+ * In practice this is not a problem.  Callers of fill_buffer() will
236
+ * be download protocols such as TFTP, and very few protocols have a
237
+ * block size smaller than @c sizeof(struct @c buffer_free_block).
210 238
  *
211 239
  */
212 240
 int fill_buffer ( struct buffer *buffer, const void *data,

+ 18
- 19
src/include/buffer.h 查看文件

@@ -3,34 +3,33 @@
3 3
 
4 4
 #include "stdint.h"
5 5
 
6
-/*
7
- * "start" and "end" denote the real boundaries of the buffer.  "fill"
8
- * denotes the offset to the first free block in the buffer.  (If the
9
- * buffer is full, "fill" will equal ( end - start ) ).
6
+/* @file */
7
+
8
+/**
9
+ * A buffer
10
+ *
11
+ * @c start and @c end denote the real boundaries of the buffer, and
12
+ * are physical addresses.  @c fill denotes the offset to the first
13
+ * free block in the buffer.  (If the buffer is full, @c fill will
14
+ * equal @c end-start.)
10 15
  *
11 16
  */
12 17
 struct buffer {
13
-	physaddr_t	start;
14
-	physaddr_t	end;
15
-	off_t		fill;
18
+	physaddr_t	start;		/**< Start of buffer in memory */
19
+	physaddr_t	end;		/**< End of buffer in memory */
20
+	off_t		fill;		/**< Offset to first gap in buffer */
16 21
 };
17 22
 
18
-/*
19
- * Free blocks in the buffer start with a "tail byte".  If non-zero,
20
- * this byte indicates that the free block is the tail of the buffer,
21
- * i.e. occupies all the remaining space up to the end of the buffer.
22
- * When the tail byte is non-zero, it indicates that the remainder of
23
- * the descriptor (the struct buffer_free_block) follows the tail
24
- * byte.
23
+/**
24
+ * A free block descriptor.
25 25
  *
26
- * This scheme is necessary because we may end up with a tail that is
27
- * smaller than a struct buffer_free_block.
26
+ * See \ref buffer_int for a full description of the fields.
28 27
  *
29 28
  */
30 29
 struct buffer_free_block {
31
-	char		tail;
32
-	physaddr_t	next_free;
33
-	physaddr_t	end;
30
+	char		tail;		/**< Tail byte marker */
31
+	physaddr_t	next_free;	/**< Address of next free block */
32
+	physaddr_t	end;		/**< End of this block */
34 33
 } __attribute__ (( packed ));
35 34
 
36 35
 /* Functions in buffer.c */

正在加载...
取消
保存