source: rtems/cpukit/libblock/include/rtems/bdbuf.h @ b6911069

4.115
Last change on this file since b6911069 was b6911069, checked in by Sebastian Huber <sebastian.huber@…>, on 05/29/12 at 16:02:52

libblock: Add task stack size bdbuf configuration

The task stack size for the swap-out and worker tasks is now
configurable. The bdbuf task resources are now included in the work
space size estimate.

  • Property mode set to 100644
File size: 24.6 KB
Line 
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
34extern "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 */
236typedef 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 */
297struct rtems_bdbuf_group;
298typedef 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 */
306typedef 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 */
344struct 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 */
359typedef 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 */
389extern 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 */
460rtems_status_code
461rtems_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 */
491rtems_status_code
492rtems_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 */
525rtems_status_code
526rtems_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 */
551rtems_status_code
552rtems_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 */
575rtems_status_code
576rtems_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 */
598rtems_status_code
599rtems_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 */
618rtems_status_code
619rtems_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 */
632void
633rtems_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 */
651rtems_status_code
652rtems_bdbuf_set_block_size (rtems_disk_device *dd, uint32_t block_size);
653
654/** @} */
655
656#ifdef __cplusplus
657}
658#endif
659
660#endif
Note: See TracBrowser for help on using the repository browser.