cbiolib.c

vxworks源码源码解读是学习vxworks的最佳途径

/* cbioLib.c - Cached Block I/O class library */

/* Copyright 1999 Wind River Systems, Inc. */

/*
modification history
--------------------
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 cbioDevVerify() 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 RTNS (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 or create CBIO to BLK_DEV wrapper
.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_objLib_OBJ_ID_ERROR
One exception is cbioDevVerify(), which instead returns NULL on failure.

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 cbioDevVerify 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 cbioDevVerify() is used to create the wrapper atop
a BLK_DEV device.

The functions dcacheDevCreate and dpartDevCreate both interally use 
cbioDevVerify 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 this wrapper.

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.


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.  


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
    OBJ_CORE	objCore;
.CE

This is the traditional VxWorks object core.  This is used for object
control and verification of the CBIO device.  Because class libraries 
and object management libraries are private to VxWorks, the CBIO 
module developer should not deviate from this fields usage in the 
ramDiskCbio.c implementation.  See also objLib.h and classLib.h .  


.CS
    SEMAPHORE	cbio_mutex;		
.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	(* cbio_blkRW)
.CE

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


.CS
    STATUS	(* cbio_BytesRW)	
.CE

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


.CS
    STATUS	(* cbio_blkCopy)	
.CE

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


.CS
    STATUS	(* cbio_ioctl)		
.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 *	cbio_description;	
.CE

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


.CS
    short	cbio_mode;		
.CE

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


.CS
    BOOL	cbio_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     params;
.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	params.cbio_removable;		
.CE

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


.CS
    block_t	params.cbio_nBlocks;		
.CE

Total number of blocks on this CBIO device


.CS
    size_t	cbio_bytesPerBlk;	
.CE

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


.CS
    size_t	cbio_offset;		
.CE

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


.CS
    short	params.cbio_blksPerTrack;	
.CE

The number of blocks per track on this device.


.CS
    short	cbio_nHeads;		
.CE

The number of heads on this device.


.CS
    short	cbio_retry;	
.CE

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


.CS
    block_t	params.cbio_lastErrBlk;	
.CE

The block number of the last error that occurred.


.CS
    int		cbio_lastErrno;		
.CE

The error code of the last encountered error.


IMPLEMENTATION DEFINED CBIO_DEV ATTRIBUTES

.CS
    caddr_t	cbio_memBase;	
    size_t	cbio_memSize;		
.CE

These represent the base address and size of any memory 
pool supplied to the CBIO module.

.CS
    u_long	cbio_Priv0;		/@ Implementation defined @/
    u_long	cbio_Priv1;		/@ Implementation defined @/
    u_long	cbio_Priv2;		/@ Implementation defined @/
    u_long	cbio_Priv3;		/@ Implementation defined @/
    u_long	cbio_Priv4;		/@ Implementation defined @/
    u_long	cbio_Priv5;		/@ Implementation defined @/
    u_long	cbio_Priv6;		/@ Implementation defined @/
    u_long	cbio_Priv7;		/@ Implementation defined @/
    CBIO_DEV_EXTRA * pDc ;		/@ Implementation defined structure @/
.CE

These fields are implementation defined.


Some developers may wish to create their own modules using the CBIO API.  
The guidelines herein should be followed regardless of CBIO module type
being designed.  The source file ramDiskCbio.c may be used as an 
implementation example.

CBIO modules have a CBIO device creation routine.   The routine 
creates a CBIO_DEV structure and initializes all its fields.  
Un-used function members are initialized to NULL.  CBIO modules 
do not perform an iosDevAdd() call, and are akin to block device 
drivers in that respect.  The creation routine returns a CBIO 
handle of type CBIO_DEV_ID.

CBIO modules have a block transfer routine. This routine transfers 
between a user buffer and the lower layer (hardware, subordinate 
CBIO, or BLK_DEV).  It is optimized for block transfers.  This 
routine returns OK or ERROR and may otherwise set errno.

This routine is declared:

.CS
STATUS	xxCbioBlkRW		/@ Read/Write blocks @/
    (
    CBIO_DEV_ID     dev,
    block_t         start_block,
    block_t         num_blocks,