/** * @file rtems/bdbuf.h * * Block Device Buffer Management */ /* * Copyright (C) 2001 OKTET Ltd., St.-Petersburg, Russia * Author: Victor V. Vengerov * * Copyright (C) 2008 Chris Johns * Rewritten to remove score mutex access. Fixes many performance * issues. * * @(#) bdbuf.h,v 1.9 2005/02/02 00:06:18 joel Exp */ #ifndef _RTEMS_BDBUF_H #define _RTEMS_BDBUF_H #include #include #include #include "rtems/blkdev.h" #include "rtems/diskdevs.h" #ifdef __cplusplus extern "C" { #endif /** * State of a buffer in the cache. */ typedef enum { RTEMS_BDBUF_STATE_EMPTY = 0, /*< Not in use. */ RTEMS_BDBUF_STATE_READ_AHEAD = 1, /*< Holds read ahead data only */ RTEMS_BDBUF_STATE_CACHED = 2, /*< In the cache and available */ RTEMS_BDBUF_STATE_ACCESS = 3, /*< The user has the buffer */ RTEMS_BDBUF_STATE_MODIFIED = 4, /*< In the cache but modified */ RTEMS_BDBUF_STATE_ACCESS_MODIFIED = 5, /*< With the user but modified */ RTEMS_BDBUF_STATE_SYNC = 6, /*< Requested to be sync'ed */ RTEMS_BDBUF_STATE_TRANSFER = 7 /*< Being transferred to or from disk */ } rtems_bdbuf_buf_state; /** * To manage buffers we using buffer descriptors (BD). A BD holds a buffer plus * a range of other information related to managing the buffer in the cache. To * speed-up buffer lookup descriptors are organized in AVL-Tree. The fields * 'dev' and 'block' are search keys. */ typedef struct rtems_bdbuf_buffer { rtems_chain_node link; /* Link in the BD onto a number of lists. */ struct rtems_bdbuf_avl_node { signed char cache; /*< Cache */ struct rtems_bdbuf_buffer* left; /*< Left Child */ struct rtems_bdbuf_buffer* right; /*< Right Child */ signed char bal; /*< The balance of the sub-tree */ } avl; dev_t dev; /*< device number */ rtems_blkdev_bnum block; /*< block number on the device */ unsigned char* buffer; /*< Pointer to the buffer memory area */ int error; /*< If not 0 indicate an error value (errno) * which can be used by user later */ volatile rtems_bdbuf_buf_state state; /*< State of the buffer. */ volatile uint32_t waiters; /*< The number of threads waiting on this * buffer. */ rtems_bdpool_id pool; /*< Identifier of buffer pool to which this buffer belongs */ volatile uint32_t hold_timer; /*< Timer to indicate how long a buffer * has been held in the cache modified. */ } rtems_bdbuf_buffer; /** * The groups of the blocks with the same size are collected in a pool. Note * that a several of the buffer's groups with the same size can exists. */ typedef struct rtems_bdbuf_pool { uint32_t blksize; /*< The size of the blocks (in bytes) */ uint32_t nblks; /*< Number of blocks in this pool */ uint32_t flags; /*< Configuration flags */ rtems_id lock; /*< The pool lock. Lock this data and * all BDs. */ rtems_id sync_lock; /*< Sync calls lock writes. */ bool sync_active; /*< True if a sync is active. */ rtems_id sync_requester; /*< The sync requester. */ dev_t sync_device; /*< The device to sync */ rtems_bdbuf_buffer* tree; /*< Buffer descriptor lookup AVL tree * root */ rtems_chain_control ready; /*< Free buffers list (or read-ahead) */ rtems_chain_control lru; /*< Last recently used list */ rtems_chain_control modified; /*< Modified buffers list */ rtems_chain_control sync; /*< Buffers to sync list */ rtems_id access; /*< Obtain if waiting for a buffer in the * ACCESS state. */ volatile uint32_t access_waiters; /*< Count of access blockers. */ rtems_id transfer; /*< Obtain if waiting for a buffer in the * TRANSFER state. */ volatile uint32_t transfer_waiters; /*< Count of transfer blockers. */ rtems_id waiting; /*< Obtain if waiting for a buffer and the * none are available. */ volatile uint32_t wait_waiters; /*< Count of waiting blockers. */ rtems_bdbuf_buffer* bds; /*< Pointer to table of buffer descriptors * allocated for this buffer pool. */ void* buffers; /*< The buffer's memory. */ } rtems_bdbuf_pool; /** * Configuration structure describes block configuration (size, amount, memory * location) for buffering layer pool. */ typedef struct rtems_bdbuf_pool_config { int size; /*< Size of block */ int num; /*< Number of blocks of appropriate size */ unsigned char* mem_area; /*< Pointer to the blocks location or NULL, in this * case memory for blocks will be allocated by * Buffering Layer with the help of RTEMS partition * manager */ } rtems_bdbuf_pool_config; /** * External references provided by the user for each pool in the system. */ extern rtems_bdbuf_pool_config rtems_bdbuf_pool_configuration[]; extern int rtems_bdbuf_pool_configuration_size; /** * Buffering configuration definition. See confdefs.h for support on using this * structure. */ typedef struct rtems_bdbuf_config { uint32_t max_read_ahead_blocks; /*< Number of blocks to read ahead. */ uint32_t max_write_blocks; /*< Number of blocks to write at once. */ rtems_task_priority swapout_priority; /*< Priority of the swap out task. */ uint32_t swapout_period; /*< Period swapout checks buf timers. */ uint32_t swap_block_hold; /*< Period a buffer is held. */ } rtems_bdbuf_config; /** * External referernce to the configuration. The configuration is provided by * the user. */ extern rtems_bdbuf_config rtems_bdbuf_configuration; /** * The max_read_ahead_blocks value is altered if there are fewer buffers * than this defined max. This stops thrashing in the cache. */ #define RTEMS_BDBUF_MAX_READ_AHEAD_BLOCKS_DEFAULT 32 #define RTEMS_BDBUF_MAX_WRITE_BLOCKS_DEFAULT 16 #define RTEMS_BDBUF_SWAPOUT_TASK_PRIORITY_DEFAULT 15 #define RTEMS_BDBUF_SWAPOUT_TASK_SWAP_PERIOD_DEFAULT 250 /* milli-seconds */ #define RTEMS_BDBUF_SWAPOUT_TASK_BLOCK_HOLD_DEFAULT 1000 /* milli-seconds */ /** * Prepare buffering layer to work - initialize buffer descritors and (if it is * neccessary) buffers. Buffers will be allocated accoriding to the * configuration table, each entry describes the size of block and the size of * the pool. After initialization all blocks is placed into the ready state. * lists. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_init (void); /** * Get block buffer for data to be written into. The buffers is set to the * access or modifed access state. If the buffer is in the cache and modified * the state is access modified else the state is access. This buffer contents * are not initialised if the buffer is not already in the cache. If the block * is already resident in memory it is returned how-ever if not in memory the * buffer is not read from disk. This call is used when writing the whole block * on a disk rather than just changing a part of it. If there is no buffers * available this call will block. A buffer obtained with this call will not be * involved in a transfer request and will not be returned to another user * until released. If the buffer is already with a user when this call is made * the call is blocked until the buffer is returned. The highest priority * waiter will obtain the buffer first. * * The block number is the linear block number. This is relative to the start * of the partition on the media. * * @param device Device number (constructed of major and minor device number) * @param block Linear media block number * @param bd Reference to the buffer descriptor pointer. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_get (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd); /** * Get the block buffer and if not already in the cache read from the disk. If * specified block already cached return. The buffer is set to the access or * modifed access state. If the buffer is in the cache and modified the state * is access modified else the state is access. If block is already being read * from disk for being written to disk this call blocks. If the buffer is * waiting to be written it is removed from modified queue and returned to the * user. If the buffer is not in the cache a new buffer is obtained and the * data read from disk. The call may block until these operations complete. A * buffer obtained with this call will not be involved in a transfer request * and will not be returned to another user until released. If the buffer is * already with a user when this call is made the call is blocked until the * buffer is returned. The highest priority waiter will obtain the buffer * first. * * @param device Device number (constructed of major and minor device number) * @param block Linear media block number * @param bd Reference to the buffer descriptor pointer. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_read (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd); /** * Release the buffer obtained by a read call back to the cache. If the buffer * was obtained by a get call and was not already in the cache the release * modified call should be used. A buffer released with this call obtained by a * get call may not be in sync with the contents on disk. If the buffer was in * the cache and modified before this call it will be returned to the modified * queue. The buffers is returned to the end of the LRU list. * * @param bd Reference to the buffer descriptor. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_release (rtems_bdbuf_buffer* bd); /** * Release the buffer allocated with a get or read call placing it on the * modidied list. If the buffer was not released modified before the hold * timer is set to the configuration value. If the buffer had been released * modified before but not written to disk the hold timer is not updated. The * buffer will be written to disk when the hold timer has expired, there are * not more buffers available in the cache and a get or read buffer needs one * or a sync call has been made. If the buffer is obtained with a get or read * before the hold timer has expired the buffer will be returned to the user. * * @param bd Reference to the buffer descriptor. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd); /** * Release the buffer as modified and wait until it has been synchronized with * the disk by writing it. This buffer will be the first to be transfer to disk * and other buffers may also be written if the maximum number of blocks in a * requests allows it. * * @note This code does not lock the sync mutex and stop additions to the * modified queue. * @param bd Reference to the buffer descriptor. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_sync (rtems_bdbuf_buffer* bd); /** * Synchronize all modified buffers for this device with the disk and wait * until the transfers have completed. The sync mutex for the pool is locked * stopping the addition of any further modifed buffers. It is only the * currently modified buffers that are written. * * @note Nesting calls to sync multiple devices attached to a single pool will * be handled sequentially. A nested call will be blocked until the first sync * request has complete. This is only true for device using the same pool. * * @param dev Block device number * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) */ rtems_status_code rtems_bdbuf_syncdev (dev_t dev); /** * Find first appropriate buffer pool. This primitive returns the index of * first buffer pool which block size is greater than or equal to specified * size. * * @param block_size Requested block size * @param pool The pool to use for the requested pool size. * * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) * @retval RTEMS_INVALID_SIZE The specified block size is invalid (not a power * of 2) * @retval RTEMS_NOT_DEFINED The buffer pool for this or greater block size * is not configured. */ rtems_status_code rtems_bdbuf_find_pool (uint32_t block_size, rtems_bdpool_id *pool); /** * Obtain characteristics of buffer pool with specified number. * * @param pool Buffer pool number * @param block_size Block size for which buffer pool is configured returned * there * @param blocks Number of buffers in buffer pool. * * RETURNS: * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed * successfully or error code if error is occured) * @retval RTEMS_INVALID_SIZE The appropriate buffer pool is not configured. * * @note Buffer pools enumerated continuously starting from 0. */ rtems_status_code rtems_bdbuf_get_pool_info (rtems_bdpool_id pool, int *block_size, int *blocks); #ifdef __cplusplus } #endif #endif