source: rtems/cpukit/libblock/include/rtems/bdbuf.h @ 47c2327

4.104.11
Last change on this file since 47c2327 was 47c2327, checked in by Thomas Doerfler <Thomas.Doerfler@…>, on Nov 30, 2009 at 12:39:51 PM

documentation fixes
Avoid designated initializers for C++ compatibility
Fixed invalid state transition from FRESH to CACHED
Free memory in case of an error.

  • Property mode set to 100644
File size: 20.1 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 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 *   e [label="EMPTY",style="filled",fillcolor="aquamarine"];
84 *   f [label="FRESH",style="filled",fillcolor="seagreen"];
85 *   c [label="CACHED",style="filled",fillcolor="chartreuse"];
86 *   a [label="ACCESS",style="filled",fillcolor="royalblue"];
87 *   am [label="ACCESS MODIFIED",style="filled",fillcolor="royalblue"];
88 *   t [label="TRANSFER",style="filled",fillcolor="red"];
89 *   s [label="SYNC",style="filled",fillcolor="red"];
90 *   m [label="MODIFIED",style="filled",fillcolor="gold"];
91 *   i [label="INITIAL"];
92 *
93 *   legend_transfer [label="Transfer Wake-Up",fontcolor="red",shape="none"];
94 *   legend_access [label="Access Wake-Up",fontcolor="royalblue",shape="none"];
95 *
96 *   i -> e [label="Init"];
97 *   e -> f [label="Buffer Recycle"];
98 *   f -> a [label="Get"];
99 *   f -> t [label="Read\nRead Ahead"];
100 *   c -> e [label="Reallocate\nBlock Size Changed"];
101 *   c -> a [label="Get\nRead"];
102 *   c -> f [label="Buffer Recycle"];
103 *   t -> c [label="Write Transfer Done\nRead Transfer Done\nRead Ahead Transfer Done",color="red",fontcolor="red"];
104 *   m -> t [label="Swapout"];
105 *   m -> s [label="Block Size Changed"];
106 *   m -> am [label="Get\nRead"];
107 *   a -> m [label="Release Modified",color="royalblue",fontcolor="royalblue"];
108 *   a -> s [label="Sync",color="royalblue",fontcolor="royalblue"];
109 *   a -> c [label="Release",color="royalblue",fontcolor="royalblue"];
110 *   am -> m [label="Release\nRelease Modified",color="royalblue",fontcolor="royalblue"];
111 *   am -> s [label="Sync",color="royalblue",fontcolor="royalblue"];
112 *   s -> t [label="Swapout"];
113 * }
114 * @enddot
115 *
116 * Empty or cached buffers are added to the LRU list and removed from this
117 * queue when a caller requests a buffer.  This is referred to as getting a
118 * buffer in the code and the event get in the state diagram.  The buffer is
119 * assigned to a block and inserted to the AVL based on the block/device key.
120 * If the block is to be read by the user and not in the cache it is transfered
121 * from the disk into memory.  If no buffers are on the LRU list the modified
122 * list is checked.  If buffers are on the modified the swap out task will be
123 * woken.  The request blocks until a buffer is available for recycle.
124 *
125 * A block being accessed is given to the file system layer and not accessible
126 * to another requester until released back to the cache.  The same goes to a
127 * buffer in the transfer state.  The transfer state means being read or
128 * written.  If the file system has modifed the block and releases it as
129 * modified it placed on the cache's modified list and a hold timer
130 * initialised.  The buffer is held for the hold time before being written to
131 * disk.  Buffers are held for a configurable period of time on the modified
132 * list as a write sets the state to transfer and this locks the buffer out
133 * from the file system until the write completes.  Buffers are often accessed
134 * and modified in a series of small updates so if sent to the disk when
135 * released as modified the user would have to block waiting until it had been
136 * written.  This would be a performance problem.
137 *
138 * The code performs multiple block reads and writes.  Multiple block reads or
139 * read ahead increases performance with hardware that supports it.  It also
140 * helps with a large cache as the disk head movement is reduced.  It however
141 * is a speculative operation so excessive use can remove valuable and needed
142 * blocks from the cache.
143 *
144 * The cache has the following lists of buffers:
145 *  - LRU: Accessed or transfered buffers released in least recently used
146 *  order.  Empty buffers will be placed to the front.
147 *  - Modified: Buffers waiting to be written to disk.
148 *  - Sync: Buffers to be synchronized with the disk.
149 *
150 * A cache look-up will be performed to find a suitable buffer.  A suitable
151 * buffer is one that matches the same allocation size as the device the buffer
152 * is for.  The a buffer's group has no buffers in use with the file system or
153 * driver the group is reallocated.  This means the buffers in the group are
154 * invalidated, resized and placed on the LRU queue.  There is a performance
155 * issue with this design.  The reallocation of a group may forced recently
156 * accessed buffers out of the cache when they should not.  The design should be
157 * change to have groups on a LRU list if they have no buffers in use.
158 *
159 * @{
160 */
161
162/**
163 * @brief State of a buffer of the cache.
164 *
165 * The state has several implications.  Depending on the state a buffer can be
166 * in the AVL tree, in a list, in use by an entity and a group user or not.
167 */
168typedef enum
169{
170  /**
171   * @brief Empty.
172   *
173   * Not in the AVL tree.  Not in a list.  Not in use.  Not a user of its
174   * group.
175   */
176  RTEMS_BDBUF_STATE_EMPTY = 0,
177
178  /**
179   * @brief Fresh.
180   *
181   * In the AVL tree.  Not in a list.  In use by a get or read request.  A user
182   * of its group.
183   */
184  RTEMS_BDBUF_STATE_FRESH,
185
186  /**
187   * @brief Cached.
188   *
189   * In the AVL tree.  In the LRU list.  Not in use.  Not a user of its group.
190   */
191  RTEMS_BDBUF_STATE_CACHED,
192
193  /**
194   * @brief Accessed by upper layer.
195   *
196   * In the AVL tree.  Not in a list.  In use by an upper layer.  A user of its
197   * group.
198   */
199  RTEMS_BDBUF_STATE_ACCESS,
200
201  /**
202   * @brief Accessed and modified by upper layer.
203   *
204   * In the AVL tree.  Not in a list.  In use by an upper layer.  A user of its
205   * group.
206   */
207  RTEMS_BDBUF_STATE_ACCESS_MODIFIED,
208
209  /**
210   * @brief Modified by upper layer.
211   *
212   * In the AVL tree.  In the modified list.  In use by swapout mechanic.  A
213   * user of its group.
214   */
215  RTEMS_BDBUF_STATE_MODIFIED,
216
217  /**
218   * @brief Scheduled for synchronization.
219   *
220   * In the AVL tree.  In the sync list.  In use by swapout mechanic.  A user
221   * of its group.
222   */
223  RTEMS_BDBUF_STATE_SYNC,
224
225  /**
226   * @brief In transfer by block device driver.
227   *
228   * In the AVL tree.  Not in a list.  In use by the block device driver.  A
229   * user of its group.
230   */
231  RTEMS_BDBUF_STATE_TRANSFER
232} rtems_bdbuf_buf_state;
233
234/**
235 * Forward reference to the block.
236 */
237struct rtems_bdbuf_group;
238typedef struct rtems_bdbuf_group rtems_bdbuf_group;
239
240/**
241 * To manage buffers we using buffer descriptors (BD). A BD holds a buffer plus
242 * a range of other information related to managing the buffer in the cache. To
243 * speed-up buffer lookup descriptors are organized in AVL-Tree. The fields
244 * 'dev' and 'block' are search keys.
245 */
246typedef struct rtems_bdbuf_buffer
247{
248  rtems_chain_node link;       /**< Link the BD onto a number of lists. */
249
250  struct rtems_bdbuf_avl_node
251  {
252    struct rtems_bdbuf_buffer* left;   /**< Left Child */
253    struct rtems_bdbuf_buffer* right;  /**< Right Child */
254    signed char                cache;  /**< Cache */
255    signed char                bal;    /**< The balance of the sub-tree */
256  } avl;
257
258  dev_t             dev;        /**< device number */
259
260  rtems_blkdev_bnum block;      /**< block number on the device */
261
262  unsigned char*    buffer;     /**< Pointer to the buffer memory area */
263  int               error;      /**< If not 0 indicate an error value (errno)
264                                 * which can be used by user later */
265
266  volatile rtems_bdbuf_buf_state state;  /**< State of the buffer. */
267
268  volatile uint32_t  waiters;    /**< The number of threads waiting on this
269                                  * buffer. */
270  rtems_bdbuf_group* group;      /**< Pointer to the group of BDs this BD is
271                                  * part of. */
272  volatile uint32_t  hold_timer; /**< Timer to indicate how long a buffer
273                                  * has been held in the cache modified. */
274
275  int   references;              /**< Allow reference counting by owner. */
276  void* user;                    /**< User data. */
277} rtems_bdbuf_buffer;
278
279/**
280 * A group is a continuous block of buffer descriptors. A group covers the
281 * maximum configured buffer size and is the allocation size for the buffers to
282 * a specific buffer size. If you allocate a buffer to be a specific size, all
283 * buffers in the group, if there are more than 1 will also be that size. The
284 * number of buffers in a group is a multiple of 2, ie 1, 2, 4, 8, etc.
285 */
286struct rtems_bdbuf_group
287{
288  rtems_chain_node    link;          /**< Link the groups on a LRU list if they
289                                      * have no buffers in use. */
290  size_t              bds_per_group; /**< The number of BD allocated to this
291                                      * group. This value must be a multiple of
292                                      * 2. */
293  uint32_t            users;         /**< How many users the block has. */
294  rtems_bdbuf_buffer* bdbuf;         /**< First BD this block covers. */
295};
296
297/**
298 * Buffering configuration definition. See confdefs.h for support on using this
299 * structure.
300 */
301typedef struct rtems_bdbuf_config {
302  uint32_t            max_read_ahead_blocks;   /**< Number of blocks to read
303                                                * ahead. */
304  uint32_t            max_write_blocks;        /**< Number of blocks to write
305                                                * at once. */
306  rtems_task_priority swapout_priority;        /**< Priority of the swap out
307                                                * task. */
308  uint32_t            swapout_period;          /**< Period swapout checks buf
309                                                * timers. */
310  uint32_t            swap_block_hold;         /**< Period a buffer is held. */
311  size_t              swapout_workers;         /**< The number of worker
312                                                * threads for the swapout
313                                                * task. */
314  rtems_task_priority swapout_worker_priority; /**< Priority of the swap out
315                                                * task. */
316  size_t              size;                    /**< Size of memory in the
317                                                * cache */
318  uint32_t            buffer_min;              /**< Minimum buffer size. */
319  uint32_t            buffer_max;              /**< Maximum buffer size
320                                                * supported. It is also the
321                                                * allocation size. */
322} rtems_bdbuf_config;
323
324/**
325 * External reference to the configuration.
326 *
327 * The configuration is provided by the application.
328 */
329extern const rtems_bdbuf_config rtems_bdbuf_configuration;
330
331/**
332 * The max_read_ahead_blocks value is altered if there are fewer buffers
333 * than this defined max. This stops thrashing in the cache.
334 */
335#define RTEMS_BDBUF_MAX_READ_AHEAD_BLOCKS_DEFAULT    0
336
337/**
338 * Default maximum number of blocks to write at once.
339 */
340#define RTEMS_BDBUF_MAX_WRITE_BLOCKS_DEFAULT         16
341
342/**
343 * Default swap-out task priority.
344 */
345#define RTEMS_BDBUF_SWAPOUT_TASK_PRIORITY_DEFAULT    15
346
347/**
348 * Default swap-out task swap period in milli seconds.
349 */
350#define RTEMS_BDBUF_SWAPOUT_TASK_SWAP_PERIOD_DEFAULT 250
351
352/**
353 * Default swap-out task block hold time in milli seconds.
354 */
355#define RTEMS_BDBUF_SWAPOUT_TASK_BLOCK_HOLD_DEFAULT  1000
356
357/**
358 * Default swap-out worker tasks. Currently disabled.
359 */
360#define RTEMS_BDBUF_SWAPOUT_WORKER_TASKS_DEFAULT     0
361
362/**
363 * Default swap-out worker task priority. The same as the swapout task.
364 */
365#define RTEMS_BDBUF_SWAPOUT_WORKER_TASK_PRIORITY_DEFAULT \
366                             RTEMS_BDBUF_SWAPOUT_TASK_PRIORITY_DEFAULT
367
368/**
369 * Default size of memory allocated to the cache.
370 */
371#define RTEMS_BDBUF_CACHE_MEMORY_SIZE_DEFAULT (64 * 512)
372
373/**
374 * Default minimum size of buffers.
375 */
376#define RTEMS_BDBUF_BUFFER_MIN_SIZE_DEFAULT (512)
377
378/**
379 * Default maximum size of buffers.
380 */
381#define RTEMS_BDBUF_BUFFER_MAX_SIZE_DEFAULT (4096)
382
383/**
384 * Prepare buffering layer to work - initialize buffer descritors and (if it is
385 * neccessary) buffers. After initialization all blocks is placed into the
386 * ready state.
387 *
388 * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed
389 *         successfully or error code if error is occured)
390 */
391rtems_status_code
392rtems_bdbuf_init (void);
393
394/**
395 * Get block buffer for data to be written into. The buffers is set to the
396 * access or modifed access state. If the buffer is in the cache and modified
397 * the state is access modified else the state is access. This buffer contents
398 * are not initialised if the buffer is not already in the cache. If the block
399 * is already resident in memory it is returned how-ever if not in memory the
400 * buffer is not read from disk. This call is used when writing the whole block
401 * on a disk rather than just changing a part of it. If there is no buffers
402 * available this call will block. A buffer obtained with this call will not be
403 * involved in a transfer request and will not be returned to another user
404 * until released. If the buffer is already with a user when this call is made
405 * the call is blocked until the buffer is returned. The highest priority
406 * waiter will obtain the buffer first.
407 *
408 * The block number is the linear block number. This is relative to the start
409 * of the partition on the media.
410 *
411 * @param device Device number (constructed of major and minor device number)
412 * @param block  Linear media block number
413 * @param bd     Reference to the buffer descriptor pointer.
414 *
415 * @return       RTEMS status code (RTEMS_SUCCESSFUL if operation completed
416 *               successfully or error code if error is occured)
417 */
418rtems_status_code
419rtems_bdbuf_get (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd);
420
421/**
422 * Get the block buffer and if not already in the cache read from the disk. If
423 * specified block already cached return. The buffer is set to the access or
424 * modifed access state. If the buffer is in the cache and modified the state
425 * is access modified else the state is access. If block is already being read
426 * from disk for being written to disk this call blocks. If the buffer is
427 * waiting to be written it is removed from modified queue and returned to the
428 * user. If the buffer is not in the cache a new buffer is obtained and the
429 * data read from disk. The call may block until these operations complete. A
430 * buffer obtained with this call will not be involved in a transfer request
431 * and will not be returned to another user until released. If the buffer is
432 * already with a user when this call is made the call is blocked until the
433 * buffer is returned. The highest priority waiter will obtain the buffer
434 * first.
435 *
436 * @param device Device number (constructed of major and minor device number)
437 * @param block  Linear media block number
438 * @param bd     Reference to the buffer descriptor pointer.
439 *
440 * @return       RTEMS status code (RTEMS_SUCCESSFUL if operation completed
441 *               successfully or error code if error is occured)
442 */
443rtems_status_code
444rtems_bdbuf_read (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd);
445
446/**
447 * Release the buffer obtained by a read call back to the cache. If the buffer
448 * was obtained by a get call and was not already in the cache the release
449 * modified call should be used. A buffer released with this call obtained by a
450 * get call may not be in sync with the contents on disk. If the buffer was in
451 * the cache and modified before this call it will be returned to the modified
452 * queue. The buffers is returned to the end of the LRU list.
453 *
454 * @param bd Reference to the buffer descriptor.
455 *
456 * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed
457 *         successfully or error code if error is occured)
458 */
459rtems_status_code
460rtems_bdbuf_release (rtems_bdbuf_buffer* bd);
461
462/**
463 * Release the buffer allocated with a get or read call placing it on the
464 * modidied list.  If the buffer was not released modified before the hold
465 * timer is set to the configuration value. If the buffer had been released
466 * modified before but not written to disk the hold timer is not updated. The
467 * buffer will be written to disk when the hold timer has expired, there are
468 * not more buffers available in the cache and a get or read buffer needs one
469 * or a sync call has been made. If the buffer is obtained with a get or read
470 * before the hold timer has expired the buffer will be returned to the user.
471 *
472 * @param bd Reference to the buffer descriptor.
473 *
474 * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed
475 *         successfully or error code if error is occured)
476 */
477rtems_status_code
478rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd);
479
480/**
481 * Release the buffer as modified and wait until it has been synchronized with
482 * the disk by writing it. This buffer will be the first to be transfer to disk
483 * and other buffers may also be written if the maximum number of blocks in a
484 * requests allows it.
485 *
486 * @note This code does not lock the sync mutex and stop additions to the
487 *       modified queue.
488
489 * @param bd Reference to the buffer descriptor.
490 *
491 * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed
492 *         successfully or error code if error is occured)
493 */
494rtems_status_code
495rtems_bdbuf_sync (rtems_bdbuf_buffer* bd);
496
497/**
498 * Synchronize all modified buffers for this device with the disk and wait
499 * until the transfers have completed. The sync mutex for the cache is locked
500 * stopping the addition of any further modifed buffers. It is only the
501 * currently modified buffers that are written.
502 *
503 * @note Nesting calls to sync multiple devices will be handled sequentially. A
504 * nested call will be blocked until the first sync request has complete.
505 *
506 * @param dev Block device number
507 *
508 * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed
509 *         successfully or error code if error is occured)
510 */
511rtems_status_code
512rtems_bdbuf_syncdev (dev_t dev);
513
514/** @} */
515
516#ifdef __cplusplus
517}
518#endif
519
520#endif
Note: See TracBrowser for help on using the repository browser.