VxWorks API Reference : OS Libraries
cbioLib - Cached Block I/O library
cbioLibInit( ) - Initialize CBIO Library
cbioBlkRW( ) - transfer blocks to or from memory
cbioBytesRW( ) - transfer bytes to or from memory
cbioBlkCopy( ) - block to block (sector to sector) tranfer routine
cbioIoctl( ) - perform ioctl operation on device
cbioModeGet( ) - return the mode setting for CBIO device
cbioModeSet( ) - set mode for CBIO device
cbioRdyChgdGet( ) - determine ready status of CBIO device
cbioRdyChgdSet( ) - force a change in ready status of CBIO device
cbioLock( ) - obtain CBIO device semaphore.
cbioUnlock( ) - release CBIO device semaphore.
cbioParamsGet( ) - fill in CBIO_PARAMS structure with CBIO device parameters
cbioShow( ) - print information about a CBIO device
cbioDevVerify( ) - verify CBIO_DEV_ID
cbioWrapBlkDev( ) - create CBIO wrapper atop a BLK_DEV device
cbioDevCreate( ) - Initialize a CBIO device (Generic)
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.
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.
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:
+--------------------+ | 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 | +----------+The logical layers of a typical system with a fixed disk using CBIO partitioning layer and a CBIO caching layer appears:
+--------------------+ | 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 | +-------------------------+
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:
cbioLibInit( ) - Library initialization routine cbioBlkRW( ) - Transfer blocks (sectors) from/to a memory buffer cbioBytesRW( ) - Transfer bytes from/to a memory buffer cbioBlkCopy( ) - Copy directly from block to block (sector to sector) cbioIoctl( ) - Perform I/O control operations on the CBIO device cbioModeGet( ) - Get the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR) cbioModeSet( ) - Set the CBIO device mode (O_RDONLY, O_WRONLY, or O_RDWR) cbioRdyChgdGet( ) - Determine the CBIO device ready status state cbioRdyChgdSet( ) - Force a change in the CBIO device ready status state cbioLock( ) - Obtain exclusive ownership of the CBIO device cbioUnlock( ) - Release exclusive ownership of the CBIO device cbioParamsGet( ) - Fill a CBIO_PARAMS structure with data from the CBIO device cbioDevVerify( ) - Verify valid CBIO device cbioWrapBlkDev( ) - Create CBIO wrapper atop a BLK_DEV cbioShow( ) - Display information about a CBIO device
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.
VxWorks Programmers Guide: I/O System
cbioLib.h
cbioLibInit( ) - Initialize CBIO Library
STATUS cbioLibInit (void)
This function initializes the CBIO library, and will be called when the first CBIO device is created, hence it does not need to be called during system initialization. It can be called mulitple times, but will do nothing after the first call.
OK or ERROR
cbioBlkRW( ) - transfer blocks to or from memory
STATUS cbioBlkRW ( CBIO_DEV_ID dev, /* CBIO handle */ block_t startBlock, /* starting block of transfer */ block_t numBlocks, /* number of blocks to transfer */ addr_t buffer, /* address of the memory buffer */ CBIO_RW rw, /* direction of transfer R/W */ cookie_t * pCookie /* pointer to cookie */ )
This routine verifies the CBIO device is valid and if so calls the devices block transfer routine. The CBIO device performs block transfers between the device and memory.
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
RETURNS OK if sucessful or ERROR if the handle is invalid, or if the CBIO device routine returns ERROR.
cbioBytesRW( ) - transfer bytes to or from memory
STATUS cbioBytesRW ( CBIO_DEV_ID dev, /* CBIO handle */ block_t startBlock, /* starting block of the transfer */ off_t offset, /* offset into block in bytes */ addr_t buffer, /* address of data buffer */ size_t nBytes, /* number of bytes to transfer */ CBIO_RW rw, /* direction of transfer R/W */ cookie_t * pCookie /* pointer to cookie */ )
This routine verifies the CBIO device is valid and if so calls the devices byte tranfer routine which transfers between a user buffer and the lower layer (hardware, subordinate CBIO, or BLK_DEV). It is optimized for byte transfers.
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
RETURNS OK if sucessful or ERROR if the handle is invalid, or if the CBIO device routine returns ERROR.
cbioBlkCopy( ) - block to block (sector to sector) tranfer routine
STATUS cbioBlkCopy ( CBIO_DEV_ID dev, /* CBIO handle */ block_t srcBlock, /* source start block */ block_t dstBlock, /* destination start block */ block_t numBlocks /* number of blocks to copy */ )
This routine verifies the CBIO device is valid and if so calls the devices block to block tranfer routine which makes copies of one or more blocks on the lower layer (hardware, subordinate CBIO, or BLK_DEV). It is optimized for block to block copies on the subordinate layer.
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
RETURNS OK if sucessful or ERROR if the handle is invalid, or if the CBIO device routine returns ERROR.
cbioIoctl( ) - perform ioctl operation on device
STATUS cbioIoctl ( CBIO_DEV_ID dev, /* CBIO handle */ int command, /* ioctl command to be issued */ addr_t arg /* arg - specific to ioctl */ )
This routine verifies the CBIO device is valid and if so calls the devices I/O control operation routine.
CBIO modules expect the following ioctl( ) codes:
- CBIO_RESET - reset the CBIO device. When the third argument to the ioctl
call accompaning CBIO_RESET is NULL, the code verifies that the disk is inserted and is ready, after getting it to a known state. When the 3rd argument is a non-zero, it is assumed to be a BLK_DEV pointer and CBIO_RESET will install a new subordinate block device. This work is performed at the BLK_DEV to CBIO layer, and all layers shall account for it. A CBIO_RESET indicates a possible change in device geometry, and the CBIO_PARAMS members will be reinitialized after a CBIO_RESET.- CBIO_STATUS_CHK - check device status of CBIO device and lower layer
- CBIO_DEVICE_LOCK - Prevent disk removal
- CBIO_DEVICE_UNLOCK - Allow disk removal
- CBIO_DEVICE_EJECT - Unmount and eject device
- CBIO_CACHE_FLUSH - Flush any dirty cached data
- CBIO_CACHE_INVAL - Flush & Invalidate all cached data
- CBIO_CACHE_NEWBLK - Allocate scratch block
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
RETURNS OK if sucessful or ERROR if the handle is invalid, or if the CBIO device routine returns ERROR.
cbioModeGet( ) - return the mode setting for CBIO device
int cbioModeGet ( CBIO_DEV_ID dev /* CBIO handle */ )
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID This routine is not protected by a semaphore.
This routine confirms if the current layer is a CBIO to BLKDEV wrapper or a CBIO to CBIO layer. Depending on the current layer it either returns the mode from BLK_DEV or calls cbioModeGet( ) recursively.
RETURNS O_RDONLY, O_WRONLY, or O_RDWR or ERROR
cbioModeSet( ) - set mode for CBIO device
STATUS cbioModeSet ( CBIO_DEV_ID dev, /* CBIO handle */ int mode /* O_RDONLY, O_WRONLY, or O_RDWR */ )
Valid modes are O_RDONLY, O_WRONLY, or O_RDWR.
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID This routine is not protected by a semaphore.
This routine confirms if the current layer is a CBIO to BLKDEV wrapper or a CBIO to CBIO layer. Depending on the current layer it either sets the mode of the BLK_DEV or calls cbioModeSet( ) recursively.
RETURNS OK or ERROR if mode is not set.
cbioRdyChgdGet( ) - determine ready status of CBIO device
int cbioRdyChgdGet ( CBIO_DEV_ID dev /* CBIO handle */ )
For example
switch (cbioRdyChgdGet (cbioDeviceId)) { case TRUE: printf ("Disk changed.\n"); break; case FALSE: printf ("Disk has not changed.\n"); break; case ERROR: printf ("Not a valid CBIO device.\n"); break; default: break; }If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID This routine is not protected by a semaphore.This routine will check down to the driver layer to see if any lower layer has its ready changed bit set to TRUE. If so, this routine returns TRUE. If no lower layer has its ready changed bit set to TRUE, this layer returns FALSE.
RETURNS TRUE if device ready status has changed, else FALSE if the ready status has not changed, else ERROR if the CBIO_DEV_ID is invalid.
cbioRdyChgdSet( ) - force a change in ready status of CBIO device
STATUS cbioRdyChgdSet ( CBIO_DEV_ID dev, /* CBIO handle */ BOOL status /* TRUE/FALSE */ )
Pass TRUE in status to force READY status change.
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID If status is not passed as TRUE or FALSE, ERROR is returned. This routine is not protected by a semaphore.
This routine sets readyChanged bit of passed CBIO_DEV.
RETURNS OK or ERROR if the device is invalid or status is not TRUE or FALSE.
cbioLock( ) - obtain CBIO device semaphore.
STATUS cbioLock ( CBIO_DEV_ID dev, /* CBIO handle */ int timeout /* timeout in ticks */ )
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
OK or ERROR if the CBIO handle is invalid or semTake fails.
cbioUnlock( ) - release CBIO device semaphore.
STATUS cbioUnlock ( CBIO_DEV_ID dev /* CBIO handle */ )
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
OK or ERROR if the CBIO handle is invalid or the semGive fails.
cbioParamsGet( ) - fill in CBIO_PARAMS structure with CBIO device parameters
STATUS cbioParamsGet ( CBIO_DEV_ID dev, /* CBIO handle */ CBIO_PARAMS * pCbioParams /* pointer to CBIO_PARAMS */ )
If the CBIO_DEV_ID passed to this routine is not a valid CBIO handle, ERROR will be returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
OK or ERROR if the CBIO handle is invalid.
cbioShow( ) - print information about a CBIO device
STATUS cbioShow ( CBIO_DEV_ID dev /* CBIO handle */ )
This function will display on standard output all information which is generic for all CBIO devices. See the CBIO modules particular device show routines for displaying implementation-specific information.
It takes two arguments:
A CBIO_DEV_ID which is the CBIO handle to display or NULL for the most recent device.
RETURNS OK or ERROR if no valid CBIO_DEV is found.
cbioLib, dcacheShow( ), dpartShow( )
cbioDevVerify( ) - verify CBIO_DEV_ID
STATUS cbioDevVerify ( CBIO_DEV_ID device /* CBIO_DEV_ID to be verified */ )
The purpose of this function is to determine if the device complies with the CBIO interface. It can be used to verify a CBIO handle before it is passed to dosFsLib, rawFsLib, usrFdiskPartLib, or other CBIO modules which expect a valid CBIO interface.
The device handle provided to this function, device is verified to be a CBIO device. If device is not a CBIO device ERROR is returned with errno set to S_cbioLib_INVALID_CBIO_DEV_ID
The dcacheCbio and dpartCbio CBIO modules (and dosFsLib) use this function internally, and therefore this function need not be otherwise invoked when using compliant CBIO modules.
OK or ERROR if not a CBIO device, if passed a NULL address, or if the check could cause an unaligned access.
cbioLib, dosFsLib, dcacheCbio, dpartCbio
cbioWrapBlkDev( ) - create CBIO wrapper atop a BLK_DEV device
CBIO_DEV_ID cbioWrapBlkDev ( BLK_DEV * pDevice /* BLK_DEV * device pointer */ )
The purpose of this function is to make a blkIo (BLK_DEV) device comply with the CBIO interface via a wrapper.
The device handle provided to this function, device is verified to be a blkIo device. A lean CBIO to BLK_DEV wrapper is then created for a valid blkIo device. The returned CBIO_DEV_ID device handle may be used with dosFsDevCreate( ), dcacheDevCreate( ), and any other routine expecting a valid CBIO_DEV_ID handle.
To verify a blkIo pointer we see that all mandatory functions are not NULL.
Note that if a valid CBIO_DEV_ID is passed to this function, it will simply be returned without modification.
The dosFsLib, dcacheCbio, and dpartCbio CBIO modules use this function internally, and therefore this function need not be otherwise invoked when using those CBIO modules.
a CBIO device pointer, or NULL if not a blkIo device
cbioLib, dosFsLib, dcacheCbio, dpartCbio
cbioDevCreate( ) - Initialize a CBIO device (Generic)
CBIO_DEV_ID cbioDevCreate ( caddr_t ramAddr, /* where it is in memory (0 = KHEAP_ALLOC) */ size_t ramSize /* pool size */ )
This routine will create an empty CBIO_DEV structure and return a handle to that structure (CBIO_DEV_ID).
This routine is intended to be used by CBIO modules only. See cbioLibP.h
RETURNS CBIO_DEV_ID or NULL if ERROR.