cbiolib.c

VXWORKS源代码

/* 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 visable
01x,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 cbioBlkDevPtrLimit
01n,19apr00,dat  doc fixup
01m,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 reset
01h,04nov98,lrn  refined error handling with Floppy
01g,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 bug
01d,20oct98,lrn  fixed SPR#22553, SPR#22731
01c,10sep98,lrn  add CBIO_RESET for blk dev replacement, add error handling
01b,03sep98,lrn  add block device wrapper
01a,15jan98,lrn  written, preliminary
*/

/*
DESCRIPTION

This 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 using
minimal memory overhead.  This lean module is known as the basic 
BLK_DEV to CBIO wrapper module.   


CBIO MODULES AND DEVICES

A 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 control
of 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 subordinate
layers.  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 CBIO
API 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 |
              +----------+
.CE


The logical layers of a typical system with a fixed disk
using 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 |
          +-------------------------+
.CE



PUBLIC CBIO API

The 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:
.IP
cbioLibInit() - Library initialization routine 
.IP
cbioBlkRW() - Transfer blocks (sectors) from/to a memory buffer
.IP
cbioBytesRW() - Transfer bytes from/to a memory buffer
.IP
cbioBlkCopy() - Copy directly from block to block (sector to sector)
.IP
cbioIoctl() - Perform I/O control operations on the CBIO device
.IP
cbioModeGet() - Get the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR)
.IP
cbioModeSet() - Set the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR)
.IP
cbioRdyChgdGet() - Determine the CBIO device ready status state
.IP
cbioRdyChgdSet() - Force a change in the CBIO device ready status state 
.IP
cbioLock() - Obtain exclusive ownership of the CBIO device 
.IP
cbioUnlock() - Release exclusive ownership of the CBIO device 
.IP
cbioParamsGet() - Fill a CBIO_PARAMS structure with data from the CBIO device
.IP
cbioDevVerify() - Verify valid CBIO device 
.IP
cbioWrapBlkDev() - Create CBIO wrapper atop a BLK_DEV 
.IP
cbioShow() - Display information about a CBIO device
.LP

These 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 the
the CBIO device is valid and then to perform the requested operation
on 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 MODULE

The 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 with
the 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_DEV
or it can be used with cache and partitioning support. 

The function cbioWrapBlkDev() is used to create the CBIO wrapper atop
a 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 performance
when used.

SEE ALSO
.I "VxWorks Programmers Guide: I/O System"

INCLUDE FILES
cbioLib.h

INTERNAL

CBIO module internal implementation details

This 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 code
returns 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;
.CE

This is used for handle verification of the CBIO device.  
See also handleLibP.h.


.CS
    SEMAPHORE	cbioMutex;		
.CE

This is the semaphore provided by semMLib which will be used 
provide mutual exclusion for the CBIO device.  


Functions

.CS
    CBIO_FUNCS * pFuncs;
.CE

This member of the CBIO_DEV structure is a pointer to a 
CBIO_FUNCS structure.  The CBIO_FUNCS structure is also
a private data structure.   The CBIO_FUNCS structure
contains the following members:


.CS
    STATUS	(* cbioDevBlkRW)
.CE

Address of the block (sector) read and write routine for the CBIO device.


.CS
    STATUS	(* cbioDevBytesRW)	
.CE

Address of the byte oriented read and write routine for the CBIO device.


.CS
    STATUS	(* cbioDevBlkCopy)	
.CE

Address of the block to block copy routine for the CBIO device.


.CS
    STATUS	(* cbioDevIoctl)		
.CE

Address of the ioctl() routine for the CBIO device.

One CBIO_FUNCS structure is typically statically allocated
for each CBIO module.  Refer to ramDiskCbio.c for an example.


Attributes

.CS
    char *	cbioDesc;	
.CE

This member of the CBIO_DEV structure is a pointer to a 
printable descriptive character string for the CBIO device.


.CS
    short	cbioMode;		
.CE

Indicates the access permissions to the CBIO device. 
Valid modes are O_RDONLY, O_WRONLY, and O_RDWR.


.CS
    BOOL	readyChanged;
.CE

TRUE 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;
.CE

The 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;		
.CE

TRUE if the device is removable, FALSE if the device is not removable.


.CS
    block_t	cbioParams.nBlocks;		
.CE

Total number of blocks on this CBIO device


.CS
    size_t	bytesPerBlk;	
.CE

The number of bytes in a block.  512 is a typical value.


.CS
    size_t	blockOffset;		
.CE

The number of blocks offset from block zero on the subordinate device. 


.CS
    short	cbioParams.blocksPerTrack;	
.CE

The number of blocks per track on this device.


.CS
    short	nHeads;		
.CE

The number of heads on this device.


.CS
    short	retryCnt;	
.CE

A counter indicating the total number of retries that
have occurred since creating this device.


.CS
    block_t	cbioParams.lastErrBlk;	
.CE

The block number of the last error that occurred.


.CS
    int		lastErrno;		
.CE

The error code of the last encountered error.

Implementation defined CBIO_DEV attributes

.CS
    caddr_t	cbioMemBase;	
    size_t	cbioMemSize;		
.CE

These 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 @/
.CE

These fields are implementation defined.