/* dcacheCbio.c - Disk Cache Driver *//* Copyright 1999-2002 Wind River Systems, Inc. *//*modification history--------------------01z,03mar02,jkf  SPR#32277, adding dcacheDevEnable and Disable(), orig by chn01y,21dec01,chn  SPRs 30130, 22463, 21975 (partial). Disabled defaulting                 tuneable parameters after they are explicitly set by user.01x,12dec01,jkf  fixing diab build warnings.01w,09dec01,jkf  SPR#71637, fix for SPR#68387 caused ready changed bugs.01v,09nov01,jkf  SPR#71633, dont set errno when DevCreate is called w/BLK_DEV                 SPR#65431, fixing typo in man page01u,29aug01,jkf  SPR#69031, common code for both AE & 5.x.01t,01aug01,jyo  Fixed SPR#68387: readyChanged bit is not correctly checked to                 verify the change in the media, SPR#69411: Change in media's                 readyChanged bit is not being propogated appropriately to the                 layers above.01s,13jun01,jyo  SPR#67729: Updating blkSubDev, cbioSubDev and isDriver in                 dcacheDevCreate().01r,19apr00,dat  doc fixup01q,09mar00,jkf  removed taskUndelay & taskPrioritySet from CBIO_FLUSH                 now forcing ioctl flushes inline.01p,29feb00,jkf  T3 changes01o,31aug99,jkf  changes for new CBIO API.01n,31jul99,jkf  T2 merge, tidiness & spelling.01i,17nov98,lrn  zero-fill blocks allocated with CBIO_CACHE_NEWBLK01h,29oct98,lrn  pass along 3rd arg on CBIO_RESET, removed old mod history01g,20oct98,lrn  fixed SPR#22553, SPR#2273101f,14sep98,lrn  refined error handling, made updTask unconditional01e,08sep98,lrn  add hash for speed (SPR#21972), size change (SPR#21975)01d,06sep98,lrn  modify to work on top of CBIO (SPR#21974), and use                 wrapper for block devices b.c.01c,30jul98,wlf  partial doc cleanup01b,01jul98,lrn  written.01a,28jan98,lrn  written, preliminary*//*DESCRIPTIONThis module implements a disk cache mechanism via the CBIO API.This is intended for use by the VxWorks DOS file system, to storefrequently used disk blocks in memory.  The disk cache is unaware of the particular file system format on the disk, and handles thedisk as a collection of blocks of a fixed size, typically the sectorsize of 512 bytes.  The disk cache may be used with SCSI, IDE, ATA, Floppy or any othertype of disk controllers.  The underlying device driver may be eithercomply with the CBIO API or with the older block device API.  This library interfaces to device drivers implementing the block device API via the basic CBIO BLK_DEV wrapper provided by cbioLib.Because the disk cache complies with the CBIO programming interface onboth its upper and lower layers, it is both an optional and a stackablemodule.   It can be used or omitted depending on resources available and performance required.The disk cache module implements the CBIO API, which is used by the filesystem module to access the disk blocks, or to access bytes within a particular disk block.  This allows the file system to use the disk cacheto store file data as well as Directory and File Allocation Table blocks, on a Most Recently Used basis, thus keeping a controllable subset of thesedisk structures in memory.  This results in minimized memory requirements for the file system, while avoiding any significant performance degradation.The size of the disk cache, and thus the memory consumption of the disksubsystem, is configured at the time of initialization (see dcacheDevCreate()), allowing the user to trade-off memory consumptionversus performance.  Additional performance tuning capabilities areavailable through dcacheDevTune().Briefly, here are the main techniques deployed by the disk cache:.IPLeast Recently Used block re-use policy.IPRead-ahead.IPWrite-behind with sorting and grouping.IPHidden writes.IPDisk cache bypass for large requests.IPBackground disk updating (flushing changes to disk) with an adjustableupdate period (ioctl flushes occur without delay.).LPSome of these techniques are discussed in more detail below; others are described in varrious professional and academic publications.DISK CACHE ALGORITHMThe disk cache is composed internally of a number cache blocks, ofthe same size as the disk physical block (sector). These cache blocksare maintained in a list in "Most Recently Used" order, that is, blockswhich are used are moved to the top of this list. When a block needs tobe relinquished, and made available to contain a new disk block, theLeast Recently Used block will be used for this purpose.In addition to the regular cache blocks, some of the memory allocatedfor cache is set aside for a "big buffer", which may range from 1/4 ofthe overall cache size up to 64KB.  This buffer is used for:.IPCombining cache blocks with adjacent disk block numbers, in order towrite them to disk in groups, and save on latency and overhead .IPReading ahead a group of blocks, and then converting them to normalcache blocks..LPBecause there is significant overhead involved in accessing the diskdrive, read-ahead improves performance significantly by reading groupsof blocks at once.TUNABLE PARAMETERSThere are certain operational parameters that control the disk cacheoperation which are tunable. A number of.I presetparameter sets is provided, dependent on the size of the cache. Theseshould suffice for most purposes, but under certain types of workload,it may be desirable to tune these parameters to better suite theparticular workload patterns.See dcacheDevTune() for description of the tunable parameters. It isrecommended to call dcacheShow() after calling dcacheTune() in order to verify that the parameters where set as requested, and to inspect the cache statistics which may change dramatically. Note that the hit ratio is a principal indicator of cache efficiency, and should be inspectedduring such tuning.BACKGROUND UPDATINGA dedicated task will be created to take care of updating the disk withblocks that have been modified in cache. The time period between updatesis controlled with the tunable parameter syncInterval. Its priorityshould be set above the priority of any CPU-bound tasks so as to assureit can wake up frequently enough to keep the disk synchronized with thecache.   There is only one such task for all cache devices configured.  The task name is tDcacheUpdThe updating task also has the responsibility to invalidate disk cacheblocks for removable devices which have not been used for 2 seconds or more.There are a few global variables which control the parameters of thistask, namely:.IP <dcacheUpdTaskPriority>controls the default priority of the update task, and is set by default to 250..IP <dcacheUpdTaskStack>is used to set the update task stack size..IP <dcacheUpdTaskOptions>controls the task options for the update task..LPAll the above global parameters must be set prior to callingdcacheDevCreate() for the first time, with the exception ofdcacheUpdTaskPriority, which may be modified in run-time, and takeseffect almost immediately. It should be noted that this priority is notentirely fixed, at times when critical disk operations are performed,and FIOFLUSH ioctl is called, the caller task will temporarily.I loanits priority to the update task, to insure the completion of the flushingoperation.REMOVABLE DEVICESFor removable devices, disk cache provides these additional features:.IP "disk updating"is performed such that modified blocks will be written to disk withinone second, so as to minimize the risk of losing data in case of afailure or disk removal..IP "error handling"includes a test for disk removal, so that if a disk is removed from thedrive while an I/O operation is in progress, the disk removal event willbe set immediately..IP "disk signature"which is a checksum of the disk's boot block, is maintained by the cachecontrol structure, and it will be verified against the disk if it wasidle for 2 seconds or more. Hence if during that idle time a disk wasreplaced, the change will be detected on the next disk access, and thecondition will be flagged to the file system..IP NOTEIt is very important that removable disks should all have a uniquevolume label, or volume serial number, which are stored in the disk'sboot sector during formatting. Changing disks which have an identicalboot sector may result in failure to detect the change, resulting inunpredictable behavior, possible file system corruption..LPCACHE IMPLEMENTATIONMost Recently Used (MRU) disk blocks are stored in a collection of memorybuffers called the disk cache.  The purpose of the disk cache is to reduce the number of disk accesses and to accelerate disk read and write operations, by means of the following techniques:.IPMost Recently Used blocks are stored in RAM, which results in the mostfrequently accessed data being retrieved from memory rather than from disk..IPReading data from disk is performed in large units, relying on the read-aheadfeature, one of the disk cache