Browse code

core: doxygen documentation for F_MALLOC memory manager

Henning Westerholt authored on 20/07/2011 20:36:41
Showing 2 changed files
... ...
@@ -65,7 +65,7 @@
65 65
 #endif
66 66
 
67 67
 
68
-/*useful macros*/
68
+/* useful macros */
69 69
 
70 70
 #define FRAG_NEXT(f) \
71 71
 	((struct fm_frag*)((char*)(f)+sizeof(struct fm_frag)+(f)->size ))
... ...
@@ -76,14 +76,14 @@
76 76
 
77 77
 
78 78
 
79
-/* ROUNDTO= 2^k so the following works */
79
+/** ROUNDTO= 2^k so the following works */
80 80
 #define ROUNDTO_MASK	(~((unsigned long)ROUNDTO-1))
81 81
 #define ROUNDUP(s)		(((s)+(ROUNDTO-1))&ROUNDTO_MASK)
82 82
 #define ROUNDDOWN(s)	((s)&ROUNDTO_MASK)
83 83
 
84 84
 
85 85
 
86
-	/* finds the hash value for s, s=ROUNDTO multiple*/
86
+/** finds the hash value for s, s=ROUNDTO multiple */
87 87
 #define GET_HASH(s)   ( ((unsigned long)(s)<=F_MALLOC_OPTIMIZE)?\
88 88
 							(unsigned long)(s)/ROUNDTO: \
89 89
 							F_MALLOC_OPTIMIZE/ROUNDTO+big_hash_idx((s))- \
... ...
@@ -95,6 +95,7 @@
95 95
 							F_MALLOC_OPTIMIZE_FACTOR-1)\
96 96
 					)
97 97
 
98
+
98 99
 #ifdef F_MALLOC_HASH_BITMAP
99 100
 
100 101
 #define fm_bmp_set(qm, b) \
... ...
@@ -109,10 +110,20 @@
109 110
 											~(1UL<<((b)%FM_HASH_BMP_BITS)); \
110 111
 	}while(0)
111 112
 
112
-/* returns 0 if not set, !=0 if set */
113
+/** returns 0 if not set, !=0 if set */
113 114
 #define fm_bmp_is_set(qm, b) \
114 115
 	((qm)->free_bitmap[(b)/FM_HASH_BMP_BITS] & (1UL<<((b)%FM_HASH_BMP_BITS)))
115 116
 
117
+
118
+
119
+/**
120
+ * \brief Find the first free fragment in a memory block
121
+ * 
122
+ * Find the first free fragment in a memory block
123
+ * \param qm searched memory block
124
+ * \param start start value
125
+ * \return index for free fragment
126
+ */
116 127
 inline static int fm_bmp_first_set(struct fm_block* qm, int start)
117 128
 {
118 129
 	int bmp_idx;
... ...
@@ -163,18 +174,27 @@ inline static int fm_bmp_first_set(struct fm_block* qm, int start)
163 174
 #define MEM_FRAG_AVOIDANCE
164 175
 
165 176
 
166
-/* computes hash number for big buckets*/
177
+/** computes hash number for big buckets */
167 178
 #define big_hash_idx(s) ((unsigned long)bit_scan_reverse((unsigned long)(s)))
168 179
 
169 180
 
181
+/**
182
+ * \name Memory manager boundary check pattern
183
+ */
184
+/*@{ */
170 185
 #ifdef DBG_F_MALLOC
171
-#define ST_CHECK_PATTERN   0xf0f0f0f0
172
-#define END_CHECK_PATTERN1 0xc0c0c0c0
173
-#define END_CHECK_PATTERN2 0xabcdefed
186
+#define ST_CHECK_PATTERN   0xf0f0f0f0 /** inserted at the beginning */
187
+#define END_CHECK_PATTERN1 0xc0c0c0c0 /** inserted at the end       */
188
+#define END_CHECK_PATTERN2 0xabcdefed /** inserted at the end       */
189
+/*@} */
174 190
 #endif
175 191
 
176 192
 
177
-
193
+/**
194
+ * \brief Insert a memory fragment in a memory block
195
+ * \param qm memory block
196
+ * \param frag memory fragment
197
+ */
178 198
 static inline void fm_insert_free(struct fm_block* qm, struct fm_frag* frag)
179 199
 {
180 200
 	struct fm_frag** f;
... ...
@@ -200,8 +220,14 @@ static inline void fm_insert_free(struct fm_block* qm, struct fm_frag* frag)
200 220
 }
201 221
 
202 222
 
203
-
204
- /* size should be already rounded-up */
223
+/**
224
+ *\brief Split a memory fragement
225
+ *
226
+ * Split a memory fragement, size should be already rounded-up
227
+ * \param qm memory block
228
+ * \param frag memory fragment
229
+ * \param size fragement size
230
+ */
205 231
 static inline
206 232
 #ifdef DBG_F_MALLOC 
207 233
 void fm_split_frag(struct fm_block* qm, struct fm_frag* frag,
... ...
@@ -248,8 +274,12 @@ void fm_split_frag(struct fm_block* qm, struct fm_frag* frag,
248 274
 }
249 275
 
250 276
 
251
-
252
-/* init malloc and return a fm_block*/
277
+/**
278
+ * \brief Initialize memory manager malloc
279
+ * \param address start address for memory block
280
+ * \param size Size of allocation
281
+ * \return return the fm_block
282
+ */
253 283
 struct fm_block* fm_malloc_init(char* address, unsigned long size)
254 284
 {
255 285
 	char* start;
... ...
@@ -308,7 +338,14 @@ struct fm_block* fm_malloc_init(char* address, unsigned long size)
308 338
 }
309 339
 
310 340
 
311
-
341
+/**
342
+ * \brief Main memory manager allocation function
343
+ * 
344
+ * Main memory manager allocation function, provide functionality necessary for pkg_malloc
345
+ * \param qm memory block
346
+ * \param size memory allocation size
347
+ * \return address of allocated memory
348
+ */
312 349
 #ifdef DBG_F_MALLOC
313 350
 void* fm_malloc(struct fm_block* qm, unsigned long size,
314 351
 					const char* file, const char* func, unsigned int line)
... ...
@@ -408,7 +445,13 @@ found:
408 445
 }
409 446
 
410 447
 
411
-
448
+/**
449
+ * \brief Main memory manager free function
450
+ * 
451
+ * Main memory manager free function, provide functionality necessary for pkg_free
452
+ * \param qm memory block
453
+ * \param p freed memory
454
+ */
412 455
 #ifdef DBG_F_MALLOC
413 456
 void fm_free(struct fm_block* qm, void* p, const char* file, const char* func, 
414 457
 				unsigned int line)
... ...
@@ -454,6 +497,15 @@ void fm_free(struct fm_block* qm, void* p)
454 497
 }
455 498
 
456 499
 
500
+/**
501
+ * \brief Main memory manager realloc function
502
+ * 
503
+ * Main memory manager realloc function, provide functionality for pkg_realloc
504
+ * \param qm memory block
505
+ * \param p reallocated memory block
506
+ * \param size
507
+ * \return reallocated memory block
508
+ */
457 509
 #ifdef DBG_F_MALLOC
458 510
 void* fm_realloc(struct fm_block* qm, void* p, unsigned long size,
459 511
 					const char* file, const char* func, unsigned int line)
... ...
@@ -603,7 +655,10 @@ void* fm_realloc(struct fm_block* qm, void* p, unsigned long size)
603 655
 }
604 656
 
605 657
 
606
-
658
+/**
659
+ * \brief Report internal memory manager status
660
+ * \param qm memory block
661
+ */
607 662
 void fm_status(struct fm_block* qm)
608 663
 {
609 664
 	struct fm_frag* f;
... ...
@@ -689,9 +744,14 @@ void fm_status(struct fm_block* qm)
689 744
 }
690 745
 
691 746
 
692
-
693
-/* fills a malloc info structure with info about the block
694
- * if a parameter is not supported, it will be filled with 0 */
747
+/**
748
+ * \brief Fills a malloc info structure with info about the block
749
+ *
750
+ * Fills a malloc info structure with info about the block, if a
751
+ * parameter is not supported, it will be filled with 0
752
+ * \param qm memory block
753
+ * \param memory information
754
+ */
695 755
 void fm_info(struct fm_block* qm, struct mem_info* info)
696 756
 {
697 757
 	int r;
... ...
@@ -734,9 +794,12 @@ void fm_info(struct fm_block* qm, struct mem_info* info)
734 794
 }
735 795
 
736 796
 
737
-
738
-/* returns how much free memory is available
739
- * on error (not compiled with bookkeeping code) returns (unsigned long)(-1) */
797
+/**
798
+ * \brief Helper function for available memory report
799
+ * \param qm memory block
800
+ * \return Returns how much free memory is available, on error (not compiled
801
+ * with bookkeeping code) returns (unsigned long)(-1)
802
+ */
740 803
 unsigned long fm_available(struct fm_block* qm)
741 804
 {
742 805
 
... ...
@@ -784,7 +847,10 @@ make_new:
784 847
 }
785 848
 
786 849
 
787
-
850
+/**
851
+ * \brief Debugging helper, summary and logs all allocated memory blocks
852
+ * \param qm memory block
853
+ */
788 854
 void fm_sums(struct fm_block* qm)
789 855
 {
790 856
 	struct fm_frag* f;
... ...
@@ -45,10 +45,11 @@
45 45
 
46 46
 #include "meminfo.h"
47 47
 
48
-/* defs*/
49 48
 
50
-/* use a bitmap to quickly find free fragments, should speed up
51
- * especially startup (non-warmed-up malloc) */
49
+/**
50
+ * Use a bitmap to quickly find free fragments, should speed up
51
+ * especially startup (non-warmed-up malloc) 
52
+ */
52 53
 #define F_MALLOC_HASH_BITMAP
53 54
 
54 55
 #ifdef DBG_F_MALLOC
... ...
@@ -68,11 +69,10 @@
68 69
 
69 70
 
70 71
 
71
-#define F_MALLOC_OPTIMIZE_FACTOR 14UL /*used below */
72
+#define F_MALLOC_OPTIMIZE_FACTOR 14UL /* used below */
73
+/** Size to optimize for, (most allocs <= this size), must be 2^k */
72 74
 #define F_MALLOC_OPTIMIZE  (1UL<<F_MALLOC_OPTIMIZE_FACTOR)
73
-								/* size to optimize for,
74
-									(most allocs <= this size),
75
-									must be 2^k */
75
+
76 76
 
77 77
 #define F_HASH_SIZE (F_MALLOC_OPTIMIZE/ROUNDTO + \
78 78
 		(sizeof(long)*8-F_MALLOC_OPTIMIZE_FACTOR)+1)
... ...
@@ -84,11 +84,12 @@ typedef unsigned long fm_hash_bitmap_t;
84 84
 	((F_HASH_SIZE+FM_HASH_BMP_BITS-1)/FM_HASH_BMP_BITS)
85 85
 #endif
86 86
 
87
-/* hash structure:
88
- * 0 .... F_MALLOC_OPTIMIZE/ROUNDTO  - small buckets, size increases with
89
- *                            ROUNDTO from bucket to bucket
90
- * +1 .... end -  size = 2^k, big buckets */
91
-
87
+/**
88
+ * \name Hash structure
89
+ * - 0 .... F_MALLOC_OPTIMIZE/ROUNDTO  - small buckets, size increases with
90
+ * ROUNDTO from bucket to bucket
91
+ * - +1 .... end -  size = 2^k, big buckets
92
+ */
92 93
 struct fm_frag{
93 94
 	unsigned long size;
94 95
 	union{
... ...
@@ -129,9 +130,21 @@ struct fm_block{
129 130
 };
130 131
 
131 132
 
132
-
133
+/**
134
+ * \brief Initialize memory manager malloc
135
+ * \param address start address for memory block
136
+ * \param size Size of allocation
137
+ * \return return the fm_block
138
+ */
133 139
 struct fm_block* fm_malloc_init(char* address, unsigned long size);
134 140
 
141
+
142
+/**
143
+ * \brief Main memory manager allocation function
144
+ * \param qm memory block
145
+ * \param size memory allocation size
146
+ * \return address of allocated memory
147
+ */
135 148
 #ifdef DBG_F_MALLOC
136 149
 void* fm_malloc(struct fm_block*, unsigned long size,
137 150
 					const char* file, const char* func, unsigned int line);
... ...
@@ -139,6 +152,14 @@ void* fm_malloc(struct fm_block*, unsigned long size,
139 152
 void* fm_malloc(struct fm_block*, unsigned long size);
140 153
 #endif
141 154
 
155
+
156
+/**
157
+ * \brief Main memory manager free function
158
+ * 
159
+ * Main memory manager free function, provide functionality necessary for pkg_free
160
+ * \param qm memory block
161
+ * \param p freed memory
162
+ */
142 163
 #ifdef DBG_F_MALLOC
143 164
 void  fm_free(struct fm_block*, void* p, const char* file, const char* func, 
144 165
 				unsigned int line);
... ...
@@ -146,6 +167,16 @@ void  fm_free(struct fm_block*, void* p, const char* file, const char* func,
146 167
 void  fm_free(struct fm_block*, void* p);
147 168
 #endif
148 169
 
170
+
171
+/**
172
+ * \brief Main memory manager realloc function
173
+ * 
174
+ * Main memory manager realloc function, provide functionality for pkg_realloc
175
+ * \param qm memory block
176
+ * \param p reallocated memory block
177
+ * \param size
178
+ * \return reallocated memory block
179
+ */
149 180
 #ifdef DBG_F_MALLOC
150 181
 void*  fm_realloc(struct fm_block*, void* p, unsigned long size, 
151 182
 					const char* file, const char* func, unsigned int line);
... ...
@@ -153,11 +184,38 @@ void*  fm_realloc(struct fm_block*, void* p, unsigned long size,
153 184
 void*  fm_realloc(struct fm_block*, void* p, unsigned long size);
154 185
 #endif
155 186
 
187
+
188
+/**
189
+ * \brief Report internal memory manager status
190
+ * \param qm memory block
191
+ */
156 192
 void  fm_status(struct fm_block*);
193
+
194
+
195
+/**
196
+ * \brief Fills a malloc info structure with info about the block
197
+ *
198
+ * Fills a malloc info structure with info about the block, if a
199
+ * parameter is not supported, it will be filled with 0
200
+ * \param qm memory block
201
+ * \param memory information
202
+ */
157 203
 void  fm_info(struct fm_block*, struct mem_info*);
158 204
 
205
+
206
+/**
207
+ * \brief Helper function for available memory report
208
+ * \param qm memory block
209
+ * \return Returns how much free memory is available, on error (not compiled
210
+ * with bookkeeping code) returns (unsigned long)(-1)
211
+ */
159 212
 unsigned long fm_available(struct fm_block*);
160 213
 
214
+
215
+/**
216
+ * \brief Debugging helper, summary and logs all allocated memory blocks
217
+ * \param qm memory block
218
+ */
161 219
 #ifdef DBG_F_MALLOC
162 220
 void fm_sums(struct fm_block*);
163 221
 #else