1 | /** |
---|
2 | * @file |
---|
3 | * |
---|
4 | * @ingroup rtems_bdbuf |
---|
5 | * |
---|
6 | * Block device buffer management. |
---|
7 | */ |
---|
8 | |
---|
9 | /* |
---|
10 | * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia |
---|
11 | * Author: Victor V. Vengerov <vvv@oktet.ru> |
---|
12 | * |
---|
13 | * Copyright (C) 2008,2009 Chris Johns <chrisj@rtems.org> |
---|
14 | * Rewritten to remove score mutex access. Fixes many performance |
---|
15 | * issues. |
---|
16 | * Change to support demand driven variable buffer sizes. |
---|
17 | * |
---|
18 | * Copyright (c) 2009-2012 embedded brains GmbH. |
---|
19 | * |
---|
20 | * @(#) bdbuf.h,v 1.9 2005/02/02 00:06:18 joel Exp |
---|
21 | */ |
---|
22 | |
---|
23 | #ifndef _RTEMS_BDBUF_H |
---|
24 | #define _RTEMS_BDBUF_H |
---|
25 | |
---|
26 | #include <rtems.h> |
---|
27 | #include <rtems/libio.h> |
---|
28 | #include <rtems/chain.h> |
---|
29 | |
---|
30 | #include <rtems/blkdev.h> |
---|
31 | #include <rtems/diskdevs.h> |
---|
32 | |
---|
33 | #ifdef __cplusplus |
---|
34 | extern "C" { |
---|
35 | #endif |
---|
36 | |
---|
37 | /** |
---|
38 | * @defgroup rtems_libblock Block Device Library |
---|
39 | * |
---|
40 | * Block device modules. |
---|
41 | */ |
---|
42 | |
---|
43 | /** |
---|
44 | * @defgroup rtems_bdbuf Block Device Buffer Management |
---|
45 | * |
---|
46 | * @ingroup rtems_libblock |
---|
47 | * |
---|
48 | * The Block Device Buffer Management implements a cache between the disk |
---|
49 | * devices and file systems. The code provides read ahead and write queuing to |
---|
50 | * the drivers and fast cache look-up using an AVL tree. |
---|
51 | * |
---|
52 | * The block size used by a file system can be set at runtime and must be a |
---|
53 | * multiple of the disk device block size. The disk device's physical block |
---|
54 | * size is called the media block size. The file system can set the block size |
---|
55 | * it uses to a larger multiple of the media block size. The driver must be |
---|
56 | * able to handle buffers sizes larger than one media block. |
---|
57 | * |
---|
58 | * The user configures the amount of memory to be used as buffers in the cache, |
---|
59 | * and the minimum and maximum buffer size. The cache will allocate additional |
---|
60 | * memory for the buffer descriptors and groups. There are enough buffer |
---|
61 | * descriptors allocated so all the buffer memory can be used as minimum sized |
---|
62 | * buffers. |
---|
63 | * |
---|
64 | * The cache is a single pool of buffers. The buffer memory is divided into |
---|
65 | * groups where the size of buffer memory allocated to a group is the maximum |
---|
66 | * buffer size. A group's memory can be divided down into small buffer sizes |
---|
67 | * that are a multiple of 2 of the minimum buffer size. A group is the minimum |
---|
68 | * allocation unit for buffers of a specific size. If a buffer of maximum size |
---|
69 | * is request the group will have a single buffer. If a buffer of minimum size |
---|
70 | * is requested the group is divided into minimum sized buffers and the |
---|
71 | * remaining buffers are held ready for use. A group keeps track of which |
---|
72 | * buffers are with a file system or driver and groups who have buffer in use |
---|
73 | * cannot be realloced. Groups with no buffers in use can be taken and |
---|
74 | * realloced to a new size. This is how buffers of different sizes move around |
---|
75 | * the cache. |
---|
76 | |
---|
77 | * The buffers are held in various lists in the cache. All buffers follow this |
---|
78 | * state machine: |
---|
79 | * |
---|
80 | * @dot |
---|
81 | * digraph state { |
---|
82 | * size="16,8"; |
---|
83 | * f [label="FREE",style="filled",fillcolor="aquamarine"]; |
---|
84 | * e [label="EMPTY",style="filled",fillcolor="seagreen"]; |
---|
85 | * c [label="CACHED",style="filled",fillcolor="chartreuse"]; |
---|
86 | * ac [label="ACCESS CACHED",style="filled",fillcolor="royalblue"]; |
---|
87 | * am [label="ACCESS MODIFIED",style="filled",fillcolor="royalblue"]; |
---|
88 | * ae [label="ACCESS EMPTY",style="filled",fillcolor="royalblue"]; |
---|
89 | * ap [label="ACCESS PURGED",style="filled",fillcolor="royalblue"]; |
---|
90 | * t [label="TRANSFER",style="filled",fillcolor="red"]; |
---|
91 | * tp [label="TRANSFER PURGED",style="filled",fillcolor="red"]; |
---|
92 | * s [label="SYNC",style="filled",fillcolor="red"]; |
---|
93 | * m [label="MODIFIED",style="filled",fillcolor="gold"]; |
---|
94 | * i [label="INITIAL"]; |
---|
95 | * |
---|
96 | * legend_transfer [label="Transfer Wake-Up",fontcolor="red",shape="none"]; |
---|
97 | * legend_access [label="Access Wake-Up",fontcolor="royalblue",shape="none"]; |
---|
98 | * |
---|
99 | * i -> f [label="Init"]; |
---|
100 | * f -> e [label="Buffer Recycle"]; |
---|
101 | * e -> ae [label="Get"]; |
---|
102 | * e -> t [label="Read"]; |
---|
103 | * e -> f [label="Nobody Waits"]; |
---|
104 | * c -> ac [label="Get\nRead"]; |
---|
105 | * c -> e [label="Buffer Recycle\nPurge"]; |
---|
106 | * c -> f [label="Reallocate\nBlock Size Changed"]; |
---|
107 | * t -> c [label="Transfer Done",color="red",fontcolor="red"]; |
---|
108 | * t -> e [label="Transfer Error",color="red",fontcolor="red"]; |
---|
109 | * t -> tp [label="Purge"]; |
---|
110 | * tp -> e [label="Transfer Done\nTransfer Error",color="red",fontcolor="red"]; |
---|
111 | * m -> t [label="Swapout"]; |
---|
112 | * m -> s [label="Block Size Changed"]; |
---|
113 | * m -> am [label="Get\nRead"]; |
---|
114 | * m -> e [label="Purge"]; |
---|
115 | * ac -> m [label="Release Modified",color="royalblue",fontcolor="royalblue"]; |
---|
116 | * ac -> s [label="Sync",color="royalblue",fontcolor="royalblue"]; |
---|
117 | * ac -> c [label="Release",color="royalblue",fontcolor="royalblue"]; |
---|
118 | * ac -> ap [label="Purge"]; |
---|
119 | * am -> m [label="Release\nRelease Modified",color="royalblue",fontcolor="royalblue"]; |
---|
120 | * am -> s [label="Sync",color="royalblue",fontcolor="royalblue"]; |
---|
121 | * am -> ap [label="Purge"]; |
---|
122 | * ae -> m [label="Release Modified",color="royalblue",fontcolor="royalblue"]; |
---|
123 | * ae -> s [label="Sync",color="royalblue",fontcolor="royalblue"]; |
---|
124 | * ae -> e [label="Release",color="royalblue",fontcolor="royalblue"]; |
---|
125 | * ae -> ap [label="Purge"]; |
---|
126 | * ap -> e [label="Release\nRelease Modified\nSync",color="royalblue",fontcolor="royalblue"]; |
---|
127 | * s -> t [label="Swapout"]; |
---|
128 | * s -> e [label="Purge",color="red",fontcolor="red"]; |
---|
129 | * } |
---|
130 | * @enddot |
---|
131 | * |
---|
132 | * Empty or cached buffers are added to the LRU list and removed from this |
---|
133 | * queue when a caller requests a buffer. This is referred to as getting a |
---|
134 | * buffer in the code and the event get in the state diagram. The buffer is |
---|
135 | * assigned to a block and inserted to the AVL based on the block/device key. |
---|
136 | * If the block is to be read by the user and not in the cache it is transfered |
---|
137 | * from the disk into memory. If no buffers are on the LRU list the modified |
---|
138 | * list is checked. If buffers are on the modified the swap out task will be |
---|
139 | * woken. The request blocks until a buffer is available for recycle. |
---|
140 | * |
---|
141 | * A block being accessed is given to the file system layer and not accessible |
---|
142 | * to another requester until released back to the cache. The same goes to a |
---|
143 | * buffer in the transfer state. The transfer state means being read or |
---|
144 | * written. If the file system has modifed the block and releases it as |
---|
145 | * modified it placed on the cache's modified list and a hold timer |
---|
146 | * initialised. The buffer is held for the hold time before being written to |
---|
147 | * disk. Buffers are held for a configurable period of time on the modified |
---|
148 | * list as a write sets the state to transfer and this locks the buffer out |
---|
149 | * from the file system until the write completes. Buffers are often accessed |
---|
150 | * and modified in a series of small updates so if sent to the disk when |
---|
151 | * released as modified the user would have to block waiting until it had been |
---|
152 | * written. This would be a performance problem. |
---|
153 | * |
---|
154 | * The code performs multiple block reads and writes. Multiple block reads or |
---|
155 | * read ahead increases performance with hardware that supports it. It also |
---|
156 | * helps with a large cache as the disk head movement is reduced. It however |
---|
157 | * is a speculative operation so excessive use can remove valuable and needed |
---|
158 | * blocks from the cache. |
---|
159 | * |
---|
160 | * The cache has the following lists of buffers: |
---|
161 | * - LRU: Accessed or transfered buffers released in least recently used |
---|
162 | * order. Empty buffers will be placed to the front. |
---|
163 | * - Modified: Buffers waiting to be written to disk. |
---|
164 | * - Sync: Buffers to be synchronized with the disk. |
---|
165 | * |
---|
166 | * A cache look-up will be performed to find a suitable buffer. A suitable |
---|
167 | * buffer is one that matches the same allocation size as the device the buffer |
---|
168 | * is for. The a buffer's group has no buffers in use with the file system or |
---|
169 | * driver the group is reallocated. This means the buffers in the group are |
---|
170 | * invalidated, resized and placed on the LRU queue. There is a performance |
---|
171 | * issue with this design. The reallocation of a group may forced recently |
---|
172 | * accessed buffers out of the cache when they should not. The design should be |
---|
173 | * change to have groups on a LRU list if they have no buffers in use. |
---|
174 | * |
---|
175 | * @{ |
---|
176 | */ |
---|
177 | |
---|
178 | /** |
---|
179 | * @brief State of a buffer of the cache. |
---|
180 | * |
---|
181 | * The state has several implications. Depending on the state a buffer can be |
---|
182 | * in the AVL tree, in a list, in use by an entity and a group user or not. |
---|
183 | * |
---|
184 | * <table> |
---|
185 | * <tr> |
---|
186 | * <th>State</th><th>Valid Data</th><th>AVL Tree</th> |
---|
187 | * <th>LRU List</th><th>Modified List</th><th>Synchronization List</th> |
---|
188 | * <th>Group User</th><th>External User</th> |
---|
189 | * </tr> |
---|
190 | * <tr> |
---|
191 | * <td>FREE</td><td></td><td></td> |
---|
192 | * <td>X</td><td></td><td></td><td></td><td></td> |
---|
193 | * </tr> |
---|
194 | * <tr> |
---|
195 | * <td>EMPTY</td><td></td><td>X</td> |
---|
196 | * <td></td><td></td><td></td><td></td><td></td> |
---|
197 | * </tr> |
---|
198 | * <tr> |
---|
199 | * <td>CACHED</td><td>X</td><td>X</td> |
---|
200 | * <td>X</td><td></td><td></td><td></td><td></td> |
---|
201 | * </tr> |
---|
202 | * <tr> |
---|
203 | * <td>ACCESS CACHED</td><td>X</td><td>X</td> |
---|
204 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
205 | * </tr> |
---|
206 | * <tr> |
---|
207 | * <td>ACCESS MODIFIED</td><td>X</td><td>X</td> |
---|
208 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
209 | * </tr> |
---|
210 | * <tr> |
---|
211 | * <td>ACCESS EMPTY</td><td></td><td>X</td> |
---|
212 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
213 | * </tr> |
---|
214 | * <tr> |
---|
215 | * <td>ACCESS PURGED</td><td></td><td>X</td> |
---|
216 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
217 | * </tr> |
---|
218 | * <tr> |
---|
219 | * <td>MODIFIED</td><td>X</td><td>X</td> |
---|
220 | * <td></td><td>X</td><td></td><td>X</td><td></td> |
---|
221 | * </tr> |
---|
222 | * <tr> |
---|
223 | * <td>SYNC</td><td>X</td><td>X</td> |
---|
224 | * <td></td><td></td><td>X</td><td>X</td><td></td> |
---|
225 | * </tr> |
---|
226 | * <tr> |
---|
227 | * <td>TRANSFER</td><td>X</td><td>X</td> |
---|
228 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
229 | * </tr> |
---|
230 | * <tr> |
---|
231 | * <td>TRANSFER PURGED</td><td></td><td>X</td> |
---|
232 | * <td></td><td></td><td></td><td>X</td><td>X</td> |
---|
233 | * </tr> |
---|
234 | * </table> |
---|
235 | */ |
---|
236 | typedef enum |
---|
237 | { |
---|
238 | /** |
---|
239 | * @brief Free. |
---|
240 | */ |
---|
241 | RTEMS_BDBUF_STATE_FREE = 0, |
---|
242 | |
---|
243 | /** |
---|
244 | * @brief Empty. |
---|
245 | */ |
---|
246 | RTEMS_BDBUF_STATE_EMPTY, |
---|
247 | |
---|
248 | /** |
---|
249 | * @brief Cached. |
---|
250 | */ |
---|
251 | RTEMS_BDBUF_STATE_CACHED, |
---|
252 | |
---|
253 | /** |
---|
254 | * @brief Accessed by upper layer with cached data. |
---|
255 | */ |
---|
256 | RTEMS_BDBUF_STATE_ACCESS_CACHED, |
---|
257 | |
---|
258 | /** |
---|
259 | * @brief Accessed by upper layer with modified data. |
---|
260 | */ |
---|
261 | RTEMS_BDBUF_STATE_ACCESS_MODIFIED, |
---|
262 | |
---|
263 | /** |
---|
264 | * @brief Accessed by upper layer with invalid data. |
---|
265 | */ |
---|
266 | RTEMS_BDBUF_STATE_ACCESS_EMPTY, |
---|
267 | |
---|
268 | /** |
---|
269 | * @brief Accessed by upper layer with purged data. |
---|
270 | */ |
---|
271 | RTEMS_BDBUF_STATE_ACCESS_PURGED, |
---|
272 | |
---|
273 | /** |
---|
274 | * @brief Modified by upper layer. |
---|
275 | */ |
---|
276 | RTEMS_BDBUF_STATE_MODIFIED, |
---|
277 | |
---|
278 | /** |
---|
279 | * @brief Scheduled for synchronization. |
---|
280 | */ |
---|
281 | RTEMS_BDBUF_STATE_SYNC, |
---|
282 | |
---|
283 | /** |
---|
284 | * @brief In transfer by block device driver. |
---|
285 | */ |
---|
286 | RTEMS_BDBUF_STATE_TRANSFER, |
---|
287 | |
---|
288 | /** |
---|
289 | * @brief In transfer by block device driver and purged. |
---|
290 | */ |
---|
291 | RTEMS_BDBUF_STATE_TRANSFER_PURGED |
---|
292 | } rtems_bdbuf_buf_state; |
---|
293 | |
---|
294 | /** |
---|
295 | * Forward reference to the block. |
---|
296 | */ |
---|
297 | struct rtems_bdbuf_group; |
---|
298 | typedef struct rtems_bdbuf_group rtems_bdbuf_group; |
---|
299 | |
---|
300 | /** |
---|
301 | * To manage buffers we using buffer descriptors (BD). A BD holds a buffer plus |
---|
302 | * a range of other information related to managing the buffer in the cache. To |
---|
303 | * speed-up buffer lookup descriptors are organized in AVL-Tree. The fields |
---|
304 | * 'dd' and 'block' are search keys. |
---|
305 | */ |
---|
306 | typedef struct rtems_bdbuf_buffer |
---|
307 | { |
---|
308 | rtems_chain_node link; /**< Link the BD onto a number of lists. */ |
---|
309 | |
---|
310 | struct rtems_bdbuf_avl_node |
---|
311 | { |
---|
312 | struct rtems_bdbuf_buffer* left; /**< Left Child */ |
---|
313 | struct rtems_bdbuf_buffer* right; /**< Right Child */ |
---|
314 | signed char cache; /**< Cache */ |
---|
315 | signed char bal; /**< The balance of the sub-tree */ |
---|
316 | } avl; |
---|
317 | |
---|
318 | const rtems_disk_device *dd; /**< disk device */ |
---|
319 | |
---|
320 | rtems_blkdev_bnum block; /**< block number on the device */ |
---|
321 | |
---|
322 | unsigned char* buffer; /**< Pointer to the buffer memory area */ |
---|
323 | |
---|
324 | rtems_bdbuf_buf_state state; /**< State of the buffer. */ |
---|
325 | |
---|
326 | uint32_t waiters; /**< The number of threads waiting on this |
---|
327 | * buffer. */ |
---|
328 | rtems_bdbuf_group* group; /**< Pointer to the group of BDs this BD is |
---|
329 | * part of. */ |
---|
330 | uint32_t hold_timer; /**< Timer to indicate how long a buffer |
---|
331 | * has been held in the cache modified. */ |
---|
332 | |
---|
333 | int references; /**< Allow reference counting by owner. */ |
---|
334 | void* user; /**< User data. */ |
---|
335 | } rtems_bdbuf_buffer; |
---|
336 | |
---|
337 | /** |
---|
338 | * A group is a continuous block of buffer descriptors. A group covers the |
---|
339 | * maximum configured buffer size and is the allocation size for the buffers to |
---|
340 | * a specific buffer size. If you allocate a buffer to be a specific size, all |
---|
341 | * buffers in the group, if there are more than 1 will also be that size. The |
---|
342 | * number of buffers in a group is a multiple of 2, ie 1, 2, 4, 8, etc. |
---|
343 | */ |
---|
344 | struct rtems_bdbuf_group |
---|
345 | { |
---|
346 | rtems_chain_node link; /**< Link the groups on a LRU list if they |
---|
347 | * have no buffers in use. */ |
---|
348 | size_t bds_per_group; /**< The number of BD allocated to this |
---|
349 | * group. This value must be a multiple of |
---|
350 | * 2. */ |
---|
351 | uint32_t users; /**< How many users the block has. */ |
---|
352 | rtems_bdbuf_buffer* bdbuf; /**< First BD this block covers. */ |
---|
353 | }; |
---|
354 | |
---|
355 | /** |
---|
356 | * Buffering configuration definition. See confdefs.h for support on using this |
---|
357 | * structure. |
---|
358 | */ |
---|
359 | typedef struct rtems_bdbuf_config { |
---|
360 | uint32_t max_read_ahead_blocks; /**< Number of blocks to read |
---|
361 | * ahead. */ |
---|
362 | uint32_t max_write_blocks; /**< Number of blocks to write |
---|
363 | * at once. */ |
---|
364 | rtems_task_priority swapout_priority; /**< Priority of the swap out |
---|
365 | * task. */ |
---|
366 | uint32_t swapout_period; /**< Period swap-out checks buf |
---|
367 | * timers. */ |
---|
368 | uint32_t swap_block_hold; /**< Period a buffer is held. */ |
---|
369 | size_t swapout_workers; /**< The number of worker |
---|
370 | * threads for the swap-out |
---|
371 | * task. */ |
---|
372 | rtems_task_priority swapout_worker_priority; /**< Priority of the swap out |
---|
373 | * task. */ |
---|
374 | size_t task_stack_size; /**< Task stack size for swap-out |
---|
375 | * task and worker threads. */ |
---|
376 | size_t size; /**< Size of memory in the |
---|
377 | * cache */ |
---|
378 | uint32_t buffer_min; /**< Minimum buffer size. */ |
---|
379 | uint32_t buffer_max; /**< Maximum buffer size |
---|
380 | * supported. It is also the |
---|
381 | * allocation size. */ |
---|
382 | } rtems_bdbuf_config; |
---|
383 | |
---|
384 | /** |
---|
385 | * External reference to the configuration. |
---|
386 | * |
---|
387 | * The configuration is provided by the application. |
---|
388 | */ |
---|
389 | extern const rtems_bdbuf_config rtems_bdbuf_configuration; |
---|
390 | |
---|
391 | /** |
---|
392 | * The max_read_ahead_blocks value is altered if there are fewer buffers |
---|
393 | * than this defined max. This stops thrashing in the cache. |
---|
394 | */ |
---|
395 | #define RTEMS_BDBUF_MAX_READ_AHEAD_BLOCKS_DEFAULT 0 |
---|
396 | |
---|
397 | /** |
---|
398 | * Default maximum number of blocks to write at once. |
---|
399 | */ |
---|
400 | #define RTEMS_BDBUF_MAX_WRITE_BLOCKS_DEFAULT 16 |
---|
401 | |
---|
402 | /** |
---|
403 | * Default swap-out task priority. |
---|
404 | */ |
---|
405 | #define RTEMS_BDBUF_SWAPOUT_TASK_PRIORITY_DEFAULT 15 |
---|
406 | |
---|
407 | /** |
---|
408 | * Default swap-out task swap period in milli seconds. |
---|
409 | */ |
---|
410 | #define RTEMS_BDBUF_SWAPOUT_TASK_SWAP_PERIOD_DEFAULT 250 |
---|
411 | |
---|
412 | /** |
---|
413 | * Default swap-out task block hold time in milli seconds. |
---|
414 | */ |
---|
415 | #define RTEMS_BDBUF_SWAPOUT_TASK_BLOCK_HOLD_DEFAULT 1000 |
---|
416 | |
---|
417 | /** |
---|
418 | * Default swap-out worker tasks. Currently disabled. |
---|
419 | */ |
---|
420 | #define RTEMS_BDBUF_SWAPOUT_WORKER_TASKS_DEFAULT 0 |
---|
421 | |
---|
422 | /** |
---|
423 | * Default swap-out worker task priority. The same as the swap-out task. |
---|
424 | */ |
---|
425 | #define RTEMS_BDBUF_SWAPOUT_WORKER_TASK_PRIORITY_DEFAULT \ |
---|
426 | RTEMS_BDBUF_SWAPOUT_TASK_PRIORITY_DEFAULT |
---|
427 | |
---|
428 | /** |
---|
429 | * Default task stack size for swap-out and worker tasks. |
---|
430 | */ |
---|
431 | #define RTEMS_BDBUF_TASK_STACK_SIZE_DEFAULT RTEMS_MINIMUM_STACK_SIZE |
---|
432 | |
---|
433 | /** |
---|
434 | * Default size of memory allocated to the cache. |
---|
435 | */ |
---|
436 | #define RTEMS_BDBUF_CACHE_MEMORY_SIZE_DEFAULT (64 * 512) |
---|
437 | |
---|
438 | /** |
---|
439 | * Default minimum size of buffers. |
---|
440 | */ |
---|
441 | #define RTEMS_BDBUF_BUFFER_MIN_SIZE_DEFAULT (512) |
---|
442 | |
---|
443 | /** |
---|
444 | * Default maximum size of buffers. |
---|
445 | */ |
---|
446 | #define RTEMS_BDBUF_BUFFER_MAX_SIZE_DEFAULT (4096) |
---|
447 | |
---|
448 | /** |
---|
449 | * Prepare buffering layer to work - initialize buffer descritors and (if it is |
---|
450 | * neccessary) buffers. After initialization all blocks is placed into the |
---|
451 | * ready state. |
---|
452 | * |
---|
453 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
454 | * @retval RTEMS_CALLED_FROM_ISR Called from an interrupt context. |
---|
455 | * @retval RTEMS_INVALID_NUMBER The buffer maximum is not an integral multiple |
---|
456 | * of the buffer minimum. |
---|
457 | * @retval RTEMS_RESOURCE_IN_USE Already initialized. |
---|
458 | * @retval RTEMS_UNSATISFIED Not enough resources. |
---|
459 | */ |
---|
460 | rtems_status_code |
---|
461 | rtems_bdbuf_init (void); |
---|
462 | |
---|
463 | /** |
---|
464 | * Get block buffer for data to be written into. The buffers is set to the |
---|
465 | * access or modifed access state. If the buffer is in the cache and modified |
---|
466 | * the state is access modified else the state is access. This buffer contents |
---|
467 | * are not initialised if the buffer is not already in the cache. If the block |
---|
468 | * is already resident in memory it is returned how-ever if not in memory the |
---|
469 | * buffer is not read from disk. This call is used when writing the whole block |
---|
470 | * on a disk rather than just changing a part of it. If there is no buffers |
---|
471 | * available this call will block. A buffer obtained with this call will not be |
---|
472 | * involved in a transfer request and will not be returned to another user |
---|
473 | * until released. If the buffer is already with a user when this call is made |
---|
474 | * the call is blocked until the buffer is returned. The highest priority |
---|
475 | * waiter will obtain the buffer first. |
---|
476 | * |
---|
477 | * The block number is the linear block number. This is relative to the start |
---|
478 | * of the partition on the media. |
---|
479 | * |
---|
480 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
481 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
482 | * occur. |
---|
483 | * |
---|
484 | * @param dd [in] The disk device. |
---|
485 | * @param block [in] Linear media block number. |
---|
486 | * @param bd [out] Reference to the buffer descriptor pointer. |
---|
487 | * |
---|
488 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
489 | * @retval RTEMS_INVALID_ID Invalid block number. |
---|
490 | */ |
---|
491 | rtems_status_code |
---|
492 | rtems_bdbuf_get ( |
---|
493 | const rtems_disk_device *dd, |
---|
494 | rtems_blkdev_bnum block, |
---|
495 | rtems_bdbuf_buffer** bd |
---|
496 | ); |
---|
497 | |
---|
498 | /** |
---|
499 | * Get the block buffer and if not already in the cache read from the disk. If |
---|
500 | * specified block already cached return. The buffer is set to the access or |
---|
501 | * modifed access state. If the buffer is in the cache and modified the state |
---|
502 | * is access modified else the state is access. If block is already being read |
---|
503 | * from disk for being written to disk this call blocks. If the buffer is |
---|
504 | * waiting to be written it is removed from modified queue and returned to the |
---|
505 | * user. If the buffer is not in the cache a new buffer is obtained and the |
---|
506 | * data read from disk. The call may block until these operations complete. A |
---|
507 | * buffer obtained with this call will not be involved in a transfer request |
---|
508 | * and will not be returned to another user until released. If the buffer is |
---|
509 | * already with a user when this call is made the call is blocked until the |
---|
510 | * buffer is returned. The highest priority waiter will obtain the buffer |
---|
511 | * first. |
---|
512 | * |
---|
513 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
514 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
515 | * occur. |
---|
516 | * |
---|
517 | * @param dd [in] The disk device. |
---|
518 | * @param block [in] Linear media block number. |
---|
519 | * @param bd [out] Reference to the buffer descriptor pointer. |
---|
520 | * |
---|
521 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
522 | * @retval RTEMS_INVALID_ID Invalid block number. |
---|
523 | * @retval RTEMS_IO_ERROR IO error. |
---|
524 | */ |
---|
525 | rtems_status_code |
---|
526 | rtems_bdbuf_read ( |
---|
527 | const rtems_disk_device *dd, |
---|
528 | rtems_blkdev_bnum block, |
---|
529 | rtems_bdbuf_buffer** bd |
---|
530 | ); |
---|
531 | |
---|
532 | /** |
---|
533 | * Release the buffer obtained by a read call back to the cache. If the buffer |
---|
534 | * was obtained by a get call and was not already in the cache the release |
---|
535 | * modified call should be used. A buffer released with this call obtained by a |
---|
536 | * get call may not be in sync with the contents on disk. If the buffer was in |
---|
537 | * the cache and modified before this call it will be returned to the modified |
---|
538 | * queue. The buffers is returned to the end of the LRU list. |
---|
539 | * |
---|
540 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
541 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
542 | * occur. |
---|
543 | * |
---|
544 | * @param bd [in] Reference to the buffer descriptor. The buffer descriptor |
---|
545 | * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or |
---|
546 | * rtems_bdbuf_read(). |
---|
547 | * |
---|
548 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
549 | * @retval RTEMS_INVALID_ADDRESS The reference is NULL. |
---|
550 | */ |
---|
551 | rtems_status_code |
---|
552 | rtems_bdbuf_release (rtems_bdbuf_buffer* bd); |
---|
553 | |
---|
554 | /** |
---|
555 | * Release the buffer allocated with a get or read call placing it on the |
---|
556 | * modified list. If the buffer was not released modified before the hold |
---|
557 | * timer is set to the configuration value. If the buffer had been released |
---|
558 | * modified before but not written to disk the hold timer is not updated. The |
---|
559 | * buffer will be written to disk when the hold timer has expired, there are |
---|
560 | * not more buffers available in the cache and a get or read buffer needs one |
---|
561 | * or a sync call has been made. If the buffer is obtained with a get or read |
---|
562 | * before the hold timer has expired the buffer will be returned to the user. |
---|
563 | * |
---|
564 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
565 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
566 | * occur. |
---|
567 | * |
---|
568 | * @param bd [in] Reference to the buffer descriptor. The buffer descriptor |
---|
569 | * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or |
---|
570 | * rtems_bdbuf_read(). |
---|
571 | * |
---|
572 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
573 | * @retval RTEMS_INVALID_ADDRESS The reference is NULL. |
---|
574 | */ |
---|
575 | rtems_status_code |
---|
576 | rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd); |
---|
577 | |
---|
578 | /** |
---|
579 | * Release the buffer as modified and wait until it has been synchronized with |
---|
580 | * the disk by writing it. This buffer will be the first to be transfer to disk |
---|
581 | * and other buffers may also be written if the maximum number of blocks in a |
---|
582 | * requests allows it. |
---|
583 | * |
---|
584 | * @note This code does not lock the sync mutex and stop additions to the |
---|
585 | * modified queue. |
---|
586 | * |
---|
587 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
588 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
589 | * occur. |
---|
590 | * |
---|
591 | * @param bd [in] Reference to the buffer descriptor. The buffer descriptor |
---|
592 | * reference must not be @c NULL and must be obtained via rtems_bdbuf_get() or |
---|
593 | * rtems_bdbuf_read(). |
---|
594 | * |
---|
595 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
596 | * @retval RTEMS_INVALID_ADDRESS The reference is NULL. |
---|
597 | */ |
---|
598 | rtems_status_code |
---|
599 | rtems_bdbuf_sync (rtems_bdbuf_buffer* bd); |
---|
600 | |
---|
601 | /** |
---|
602 | * Synchronize all modified buffers for this device with the disk and wait |
---|
603 | * until the transfers have completed. The sync mutex for the cache is locked |
---|
604 | * stopping the addition of any further modifed buffers. It is only the |
---|
605 | * currently modified buffers that are written. |
---|
606 | * |
---|
607 | * @note Nesting calls to sync multiple devices will be handled sequentially. A |
---|
608 | * nested call will be blocked until the first sync request has complete. |
---|
609 | * |
---|
610 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
611 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
612 | * occur. |
---|
613 | * |
---|
614 | * @param dd [in] The disk device. |
---|
615 | * |
---|
616 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
617 | */ |
---|
618 | rtems_status_code |
---|
619 | rtems_bdbuf_syncdev (const rtems_disk_device *dd); |
---|
620 | |
---|
621 | /** |
---|
622 | * @brief Purges all buffers corresponding to the disk device @a dd. |
---|
623 | * |
---|
624 | * This may result in loss of data. |
---|
625 | * |
---|
626 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
627 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
628 | * occur. |
---|
629 | * |
---|
630 | * @param dd [in] The disk device. |
---|
631 | */ |
---|
632 | void |
---|
633 | rtems_bdbuf_purge_dev (const rtems_disk_device *dd); |
---|
634 | |
---|
635 | /** |
---|
636 | * @brief Sets the block size of a disk device. |
---|
637 | * |
---|
638 | * This will also change the block_to_media_block_shift and bds_per_group |
---|
639 | * fields of the disk device. |
---|
640 | * |
---|
641 | * Before you can use this function, the rtems_bdbuf_init() routine must be |
---|
642 | * called at least once to initialize the cache, otherwise a fatal error will |
---|
643 | * occur. |
---|
644 | * |
---|
645 | * @param dd [in, out] The disk device. |
---|
646 | * @param dd [in] The new block size. |
---|
647 | * |
---|
648 | * @retval RTEMS_SUCCESSFUL Successful operation. |
---|
649 | * @retval RTEMS_INVALID_NUMBER Invalid block size. |
---|
650 | */ |
---|
651 | rtems_status_code |
---|
652 | rtems_bdbuf_set_block_size (rtems_disk_device *dd, uint32_t block_size); |
---|
653 | |
---|
654 | /** @} */ |
---|
655 | |
---|
656 | #ifdef __cplusplus |
---|
657 | } |
---|
658 | #endif |
---|
659 | |
---|
660 | #endif |
---|