/* cbioLib.c - Cached Block I/O library *//* Copyright 1999-2002 Wind River Systems, Inc. */#include "copyright_wrs.h"/*modification history--------------------01y,03jun02,jkf  fixed SPR#78162, cbioLib has INTERNAL comment visable01x,29apr02,jkf  SPR#76013, blkWrapBlkRWbuf() shall semGive what it semTake's,                 also removed cbioWrapBlkDev check for bytesPerBlk since the                  media may not be present at cdromFs mount time; improved                  error message to mention the BLK_DEV * value that fails.01w,14jan02,jkf  SPR#72533, added cbioRdyChk(), which is used in cbioShow().01v,12dec01,jkf  fixing diab build warnings.01u,10dec01,jkf  SPR#72039, cbioShow should use strcmp.01t,09dec01,jkf  SPR#71637, fix for SPR#68387 caused ready changed bugs.01s,15nov01,jkf  SPR#71720, avoid unaligned pointer access.01r,20sep01,jkf  SPR#69031, common code for both AE & 5.x.01q,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.01p,14jun01,jyo  Fixed SPR#67729 and SPR#68150: Media's state information is                 read correctly from the lowest layer and tidied the code to                 use the new member subDev instead of pDc of CBIO_DEV                 structure.01o,08sep00,nrj  Fixed SPR#33934,33925: avoid using cbioBlkDevPtrLimit01n,19apr00,dat  doc fixup01m,07dec99,jkf  changed OBJ_CORE to HANDLE, KHEAP_ALLOC, made mode int                 changes for cbioDevVerify(), cbioWrapBlkDev().01l,15sep99,jkf  changes for public CBIO API.01k,31jul99,jkf  T2 merge, tidiness, & spelling.01j,14dec98,lrn  make pointer range limit configurable (SPR#23977)01i,22nov98,lrn  added statusChk verification after reset01h,04nov98,lrn  refined error handling with Floppy01g,29oct98,lrn  fixed BLK_DEV replacement for PCMCIA, w/ CBIO_RESET 3rd arg   01f,20oct98,lrn  removed the previous mode because of non-ATA block drivers.01e,20oct98,lrn  added capacity adjustment to work around ATA driver bug01d,20oct98,lrn  fixed SPR#22553, SPR#2273101c,10sep98,lrn  add CBIO_RESET for blk dev replacement, add error handling01b,03sep98,lrn  add block device wrapper01a,15jan98,lrn  written, preliminary*//*DESCRIPTIONThis library provides the Cached Block Input Output Application Programmers Interface (CBIO API).  Libraries such as dosFsLib, rawFsLib, and usrFdiskPartLib use the CBIO API for I/O operations to underlying devices.This library also provides generic services for CBIO modules.  The libraries dpartCbio, dcacheCbio, and ramDiskCbio are examples of CBIO modules that make use of these generic services.This library also provides a CBIO module that converts blkIo driver BLK_DEV (blkIo.h) interface into CBIO API compliant interface usingminimal memory overhead.  This lean module is known as the basic BLK_DEV to CBIO wrapper module.   CBIO MODULES AND DEVICESA CBIO module contains code for supporting CBIO devices.  The libraries cbioLib, dcacheCbio, dpartCbio, and ramDiskCbio are examples of CBIO modules.   A CBIO device is a software layer that provide its master controlof I/O to it subordinate.  CBIO device layers typicaly reside logically below a file system and above a storage device.  CBIO devices conform to the CBIO API on their master (upper) interface.CBIO modules provide a CBIO device creation routine used to instantiate a CBIO device.  The CBIO modules device creation routine returns a CBIO_DEV_ID handle.  The CBIO_DEV_ID handle is used to uniquely identify the CBIO device layer instance.  The user of the CBIO device passes this handle to the CBIO API routines when accessing the device.The libraries dosFsLib, rawFsLib, and usrFdiskPartLib are considered users of CBIO devices because they use the CBIO API on their subordinate(lower) interface.  They do not conform to the CBIO API on their master interface, therefore they are not CBIO modules.  They are users of CBIO devices and always reside above CBIO devices in the logical stack.TYPES OF CBIO DEVICES A "CBIO to CBIO device" uses the CBIO API for both its master and its subordinate interface.  Typically, some type of module specific I/O processing occurs during the interface between the master and subordinatelayers.  The libraries dpartCbio and dcacheCbio are examples of CBIO to CBIO devices.   CBIO to CBIO device layers are stackable.   Care should be taken to assemble the stack properly.  Refer to each modules reference manual entry for recommendations about the optimum stacking order. A "CBIO API device driver" is a device driver which provides the CBIOAPI as the interface between the hardware and its upper layer.  The ramDiskCbio.c RAM DISK driver is an example of a simple CBIO API device driver.A "basic BLK_DEV to CBIO wrapper device" wraps a subordinate BLK_DEV layer with a CBIO API compatible layer.  The wrapper is provided via the cbioWrapBlkDev() function.The logical layers of a typical system using a CBIO RAM DISK appear:.CS         +--------------------+         | Application module |          +--------------------+ <-- read(), write(), ioctl()                   |         +--------------------+         | VxWorks I/O System |          +--------------------+ <-- IOS layer iosRead,Write,ioctl                   |                (iosDrvInstall rtns from dosFsLib)      +--------------- -----------+      | File System (DOSFS/RAWFS) |       +---------------------------+ <-- CBIO API (cbioBlkRW, cbioIoctl, etc.)                   |+----------------------------------------------+| CBIO API device driver module (ramDiskCbio.c)|+----------------------------------------------+                   |              +----------+              | Hardware |              +----------+.CEThe logical layers of a typical system with a fixed diskusing CBIO partitioning layer and a CBIO caching layer appears:.CS            +--------------------+            | Application module |            +--------------------+ <-- read(), write(), ioctl()                      |            +-------------------+            | VxWorks IO System |            +-------------------+ <-- IOS layer Read,Write, ioctl                      |               (iosDrvInstall rtns from dosFsLib)         +---------------------------+         | File System (DOSFS/RAWFS) |         +---------------------------+ <-- CBIO API RTNS (cbioLib.h)                      |      +---------------------------------+      | CBIO to CBIO device (dpartCbio) |      +---------------------------------+ <-- CBIO API RTNS                      |     +----------------------------------+     | CBIO to CBIO device (dcacheCbio) |     +----------------------------------+ <-- CBIO API RTNS                       |  +------------------------------------------------+  | basic CBIO to BLK_DEV wrapper device (cbioLib) |  +------------------------------------------------+ <-- BLK_DEV (blkIo.h)                      |+-------------------------------------------------------+| BLK_DEV API device driver. scsiLib, ataDrv, fdDrv,etc | +-------------------------------------------------------+                      |          +-------------------------+          | Storage Device Hardware |          +-------------------------+.CEPUBLIC CBIO APIThe CBIO API provides user access to CBIO devices.  Users of CBIO devices are typically either file systems or other CBIO devices.  The CBIO API is exposed via cbioLib.h.  Users of CBIO modules include the cbioLib.h header file.  The libraries dosFsLib, dosFsFat, dosVDirLib, dosDirOldLib, usrFdiskPartLib, and rawFsLib all use the CBIO API to access CBIO modules beneath them.    The following functions make up the public CBIO API:.IPcbioLibInit() - Library initialization routine .IPcbioBlkRW() - Transfer blocks (sectors) from/to a memory buffer.IPcbioBytesRW() - Transfer bytes from/to a memory buffer.IPcbioBlkCopy() - Copy directly from block to block (sector to sector).IPcbioIoctl() - Perform I/O control operations on the CBIO device.IPcbioModeGet() - Get the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR).IPcbioModeSet() - Set the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR).IPcbioRdyChgdGet() - Determine the CBIO device ready status state.IPcbioRdyChgdSet() - Force a change in the CBIO device ready status state .IPcbioLock() - Obtain exclusive ownership of the CBIO device .IPcbioUnlock() - Release exclusive ownership of the CBIO device .IPcbioParamsGet() - Fill a CBIO_PARAMS structure with data from the CBIO device.IPcbioDevVerify() - Verify valid CBIO device .IPcbioWrapBlkDev() - Create CBIO wrapper atop a BLK_DEV .IPcbioShow() - Display information about a CBIO device.LPThese CBIO API functions (except cbioLibInit()) are passed a CBIO_DEV_ID handle in the first argument.   This handle (obtained from the subordinate CBIO modules device creation routine) is used by the routine to verify thethe CBIO device is valid and then to perform the requested operationon the specific CBIO device.When the CBIO_DEV_ID passed to the CBIO API routine is not a valid CBIO handle, ERROR will be returned with the errno set to S_cbioLib_INVALID_CBIO_DEV_ID (cbioLib.h).   Refer to the individual manual entries for each function for a complete description.THE BASIC CBIO TO BLK_DEV WRAPPER MODULEThe basic CBIO to BLK_DEV wrapper is a minimized disk cache using simplified algorithms.   It is used to convert a legacy BLK_DEV device into as CBIO device.  It may be used standalone with solid state disks which do not have mechanical seek and rotational latency delays, such flash cards.  It may also be used in conjunction withthe dpartCbio and dcacheCbio libraries.  The DOS file system dosFsDevCreate routine will call cbioWrapBlkDev() internally, so the file system may be installed directly on top of a block driver BLK_DEVor it can be used with cache and partitioning support. The function cbioWrapBlkDev() is used to create the CBIO wrapper atopa BLK_DEV device.The functions dcacheDevCreate and dpartDevCreate also both interally use cbioDevVerify() and cbioWrapBlkDev() to either stack the new CBIO device atop a validated CBIO device or to create a basic CBIO to BLK_DEV wrapper as needed.  The user typically never needs to manually invoke the cbioWrapBlkDev() or cbioDevVerify() functions.Please note that the basic CBIO BLK_DEV wrapper is inappropriate for rotational media without the disk caching layer.  The services provided by the dcacheCbio module are more appropriate for use on rotational disk devices and will yeild superior performancewhen used.SEE ALSO.I "VxWorks Programmers Guide: I/O System"INCLUDE FILEScbioLib.hINTERNALCBIO module internal implementation detailsThis section describes information concerning CBIO modules themselves.Users of CBIO modules use only the public CBIO API.  It is not recommend that the information presented in this section be used to circumvent the public CBIO API.  All the private data structures presented herein are private and are indeed subject to change without notice.Refer to the source file src/usr/ramDiskCbio.c for an implementation example of a CBIO module.  The CBIO_DEV structure (PRIVATE)The common fundamental component of every CBIO device is its CBIO_DEV structure.   The CBIO_DEV_ID is a pointer to a CBIO_DEV structure.  The CBIO_DEV is defined in the WRS private cbioLibP.h header file.Every instance of a CBIO device has its own CBIO_DEV structure.Every CBIO module has code for creating a CBIO device.  This codereturns a pointer to the CBIO_DEV structure, ie a CBIO_DEV_ID handle.A CBIO_DEV structure contains the following members:VxWorks objects.CS    HANDLE	cbioHandle;.CEThis is used for handle verification of the CBIO device.  See also handleLibP.h..CS    SEMAPHORE	cbioMutex;		.CEThis is the semaphore provided by semMLib which will be used provide mutual exclusion for the CBIO device.  Functions.CS    CBIO_FUNCS * pFuncs;.CEThis member of the CBIO_DEV structure is a pointer to a CBIO_FUNCS structure.  The CBIO_FUNCS structure is alsoa private data structure.   The CBIO_FUNCS structurecontains the following members:.CS    STATUS	(* cbioDevBlkRW).CEAddress of the block (sector) read and write routine for the CBIO device..CS    STATUS	(* cbioDevBytesRW)	.CEAddress of the byte oriented read and write routine for the CBIO device..CS    STATUS	(* cbioDevBlkCopy)	.CEAddress of the block to block copy routine for the CBIO device..CS    STATUS	(* cbioDevIoctl)		.CEAddress of the ioctl() routine for the CBIO device.One CBIO_FUNCS structure is typically statically allocatedfor each CBIO module.  Refer to ramDiskCbio.c for an example.Attributes.CS    char *	cbioDesc;	.CEThis member of the CBIO_DEV structure is a pointer to a printable descriptive character string for the CBIO device..CS    short	cbioMode;		.CEIndicates the access permissions to the CBIO device. Valid modes are O_RDONLY, O_WRONLY, and O_RDWR..CS    BOOL	readyChanged;.CETRUE if the device ready status has changed, and the device needs to be remounted (disk insertion).  FALSE if the device ready status has not changed..CS    CBIO_PARAMS     cbioParams;.CEThe next CBIO_DEV member is a CBIO_PARAMS (cbioLib.h) structure.   This contains physical information about the device.  The members of the CBIO_PARAMS structure are:.CS    BOOL	cbioParams.cbioRemovable;		.CETRUE if the device is removable, FALSE if the device is not removable..CS    block_t	cbioParams.nBlocks;		.CETotal number of blocks on this CBIO device.CS    size_t	bytesPerBlk;	.CEThe number of bytes in a block.  512 is a typical value..CS    size_t	blockOffset;		.CEThe number of blocks offset from block zero on the subordinate device. .CS    short	cbioParams.blocksPerTrack;	.CEThe number of blocks per track on this device..CS    short	nHeads;		.CEThe number of heads on this device..CS    short	retryCnt;	.CEA counter indicating the total number of retries thathave occurred since creating this device..CS    block_t	cbioParams.lastErrBlk;	.CEThe block number of the last error that occurred..CS    int		lastErrno;		.CEThe error code of the last encountered error.Implementation defined CBIO_DEV attributes.CS    caddr_t	cbioMemBase;	    size_t	cbioMemSize;		.CEThese represent the base address and size of any memory pool supplied to the CBIO module..CS    u_long	cbioPriv0;		/@ Implementation defined @/    u_long	cbioPriv1;		/@ Implementation defined @/    u_long	cbioPriv2;		/@ Implementation defined @/    u_long	cbioPriv3;		/@ Implementation defined @/    u_long	cbioPriv4;		/@ Implementation defined @/    u_long	cbioPriv5;		/@ Implementation defined @/    u_long	cbioPriv6;		/@ Implementation defined @/    u_long	cbioPriv7;		/@ Implementation defined @/    CBIO_DEV_EXTRA * pDc ;		/@ Implementation defined structure @/.CEThese fields are implementation defined.