VxWorks Reference Manual : Libraries
rawFsLib - raw block device file system library
rawFsDevInit( ) - associate a block device with raw volume functions
rawFsInit( ) - prepare to use the raw volume library
rawFsModeChange( ) - modify the mode of a raw device volume
rawFsReadyChange( ) - notify rawFsLib of a change in ready status
rawFsVolUnmount( ) - disable a raw device volume
This library provides basic services for disk devices that do not use a standard file or directory structure. The disk volume is treated much like a large file. Portions of it may be read, written, or the current position within the disk may be changed. However, there is no high-level organization of the disk into files or directories.
The various routines provided by the VxWorks raw "file system" (rawFs) may be separated into three broad groups: general initialization, device initialization, and file system operation.
The rawFsInit( ) routine is the principal initialization function; it need only be called once, regardless of how many rawFs devices will be used.
A separate rawFs routine is used for device initialization. For each rawFs device, rawFsDevInit( ) must be called to install the device.
Several routines are provided to inform the file system of changes in the system environment. The rawFsModeChange( ) routine may be used to modify the readability or writability of a particular device. The rawFsReadyChange( ) routine is used to inform the file system that a disk may have been swapped and that the next disk operation should first remount the disk. The rawFsVolUnmount( ) routine informs the file system that a particular device should be synchronized and unmounted, generally in preparation for a disk change.
Before any other routines in rawFsLib can be used, rawFsInit( ) must be called to initialize the library. This call specifies the maximum number of raw device file descriptors that can be open simultaneously and allocates memory for that many raw file descriptors. Any attempt to open more raw device file descriptors than the specified maximum will result in errors from open( ) or creat( ).
During the rawFsInit( ) call, the raw device library is installed as a driver in the I/O system driver table. The driver number associated with it is then placed in a global variable, rawFsDrvNum.
This initialization is enabled when the configuration macro INCLUDE_RAWFS is defined; rawFsInit( ) is then called from the root task, usrRoot( ), in usrConfig.c.
To use this library for a particular device, the device structure used by the device driver must contain, as the very first item, a block device description structure (BLK_DEV). This must be initialized before calling rawFsDevInit( ). In the BLK_DEV structure, the driver includes the addresses of five routines it must supply: one that reads one or more blocks, one that writes one or more blocks, one that performs I/O control (ioctl( )) on the device, one that checks the status of the the device, and one that resets the device. The BLK_DEV structure also contains fields that describe the physical configuration of the device. For more information about defining block devices, see the VxWorks Programmer's Guide: I/O System.
The rawFsDevInit( ) routine is used to associate a device with the rawFsLib functions. The volName parameter expected by rawFsDevInit( ) is a pointer to a name string, to be used to identify the device. This will serve as the pathname for I/O operations which operate on the device. This name will appear in the I/O system device table, which may be displayed using iosDevShow( ).
The pBlkDev parameter that rawFsDevInit( ) expects is a pointer to the BLK_DEV structure describing the device and contains the addresses of the required driver functions. The syntax of the rawFsDevInit( ) routine is as follows:
rawFsDevInit ( char *volName, /* name to be used for volume */ BLK_DEV *pBlkDev /* pointer to device descriptor */ )Unlike the VxWorks DOS and RT-11 file systems, raw volumes do not require an FIODISKINIT ioctl( ) function to initialize volume structures. (Such an ioctl( ) call can be made for a raw volume, but it has no effect.) As a result, there is no "make file system" routine for raw volumes (for comparison, see the manual entries for dosFsMkfs( ) and rt11Mkfs( )).When rawFsLib receives a request from the I/O system, after rawFsDevInit( ) has been called, it calls the device driver routines (whose addresses were passed in the BLK_DEV structure) to access the device.
The block number passed to the block read and write routines is an absolute number, starting from block 0 at the beginning of the device. If desired, the driver may add an offset from the beginning of the physical device before the start of the logical device. This would normally be done by keeping an offset parameter in the driver's device-specific structure, and adding the proper number of blocks to the block number passed to the read and write routines. See the ramDrv manual entry for an example.
A disk should be unmounted before it is removed. When unmounted, any modified data that has not been written to the disk will be written out. A disk may be unmounted by either calling rawFsVolUnmount( ) directly or calling ioctl( ) with a FIODISKCHANGE function code.
There may be open file descriptors to a raw device volume when it is unmounted. If this is the case, those file descriptors will be marked as obsolete. Any attempts to use them for further I/O operations will return an S_rawFsLib_FD_OBSOLETE error. To free such file descriptors, use the close( ) call, as usual. This will successfully free the descriptor, but will still return S_rawFsLib_FD_OBSOLETE.
A disk should be "synchronized" before it is unmounted. To synchronize a disk means to write out all buffered data (the write buffers associated with open file descriptors), so that the disk is updated. It may or may not be necessary to explicitly synchronize a disk, depending on how (or if) the driver issues the rawFsVolUnmount( ) call.
When rawFsVolUnmount( ) is called, an attempt will be made to synchronize the device before unmounting. However, if the rawFsVolUnmount( ) call is made by a driver in response to a disk being removed, it is obviously too late to synchronize. Therefore, a separate ioctl( ) call specifying the FIOSYNC function should be made before the disk is removed. (This could be done in response to an operator command.)
If the disk will still be present and writable when rawFsVolUnmount( ) is called, it is not necessary to first synchronize the disk. In all other circumstances, failure to synchronize the volume before unmounting may result in lost data.
The VxWorks raw block device file system supports the following ioctl( ) functions. The functions listed are defined in the header ioLib.h.
- FIODISKFORMAT
- Formats the entire disk with appropriate hardware track and sector marks. No file system is initialized on the disk by this request. Note that this is a driver-provided function:
fd = open ("DEV1:", O_WRONLY); status = ioctl (fd, FIODISKFORMAT, 0);- FIODISKINIT
- Initializes a raw file system on the disk volume. Since there are no file system structures, this functions performs no action. It is provided only for compatibility with other VxWorks file systems.
- FIODISKCHANGE
- Announces a media change. It performs the same function as rawFsReadyChange( ). This function may be called from interrupt level:
status = ioctl (fd, FIODISKCHANGE, 0);- FIOUNMOUNT
- Unmounts a disk volume. It performs the same function as rawFsVolUnmount( ). This function must not be called from interrupt level:
status = ioctl (fd, FIOUNMOUNT, 0);- FIOGETNAME
- Gets the file name of the file descriptor and copies it to the buffer nameBuf:
status = ioctl (fd, FIOGETNAME, &nameBuf);- FIOSEEK
- Sets the current byte offset on the disk to the position specified by newOffset:
status = ioctl (fd, FIOSEEK, newOffset);- FIOWHERE
- Returns the current byte position from the start of the device for the specified file descriptor. This is the byte offset of the next byte to be read or written. It takes no additional argument:
position = ioctl (fd, FIOWHERE, 0);- FIOFLUSH
- Writes all modified file descriptor buffers to the physical device.
status = ioctl (fd, FIOFLUSH, 0);- FIOSYNC
- Performs the same function as FIOFLUSH.
- FIONREAD
- Copies to unreadCount the number of bytes from the current file position to the end of the device:
status = ioctl (fd, FIONREAD, &unreadCount);
rawFsLib.h
rawFsLib, ioLib, iosLib, dosFsLib, rt11FsLib, ramDrv, VxWorks Programmer's Guide: I/O System, Local File Systems
rawFsDevInit( ) - associate a block device with raw volume functions
RAW_VOL_DESC *rawFsDevInit ( char * volName, /* volume name */ BLK_DEV * pBlkDev /* pointer to block device info */ )
This routine takes a block device created by a device driver and defines it as a raw file system volume. As a result, when high-level I/O operations, such as open( ) and write( ), are performed on the device, the calls will be routed through rawFsLib.
This routine associates volName with a device and installs it in the VxWorks I/O System's device table. The driver number used when the device is added to the table is that which was assigned to the raw library during rawFsInit( ). (The driver number is kept in the global variable rawFsDrvNum.)
The BLK_DEV structure specified by pBlkDev contains configuration data describing the device and the addresses of five routines which will be called to read blocks, write blocks, reset the device, check device status, and perform other control functions (ioctl( )). These routines will not be called until they are required by subsequent I/O operations.
A pointer to the volume descriptor (RAW_VOL_DESC), or NULL if there is an error.
rawFsInit( ) - prepare to use the raw volume library
STATUS rawFsInit ( int maxFiles /* max no. of simultaneously open files */ )
This routine initializes the raw volume library. It must be called exactly once, before any other routine in the library. The argument specifies the number of file descriptors that may be open at once. This routine allocates and sets up the necessary memory structures and initializes semaphores.
This routine also installs raw volume library routines in the VxWorks I/O system driver table. The driver number assigned to rawFsLib is placed in the global variable rawFsDrvNum. This number will later be associated with system file descriptors opened to rawFs devices.
This initialization is enabled when the configuration macro INCLUDE_RAWFS is defined; rawFsInit( ) is then called from the root task, usrRoot( ), in usrConfig.c.
OK or ERROR.
rawFsModeChange( ) - modify the mode of a raw device volume
void rawFsModeChange ( RAW_VOL_DESC * vdptr, /* pointer to volume descriptor */ int newMode /* O_RDONLY/O_WRONLY/O_RDWR (both) */ )
This routine sets the device's mode to newMode by setting the mode field in the BLK_DEV structure. This routine should be called whenever the read and write capabilities are determined, usually after a ready change.
The driver's device initialization routine should initially set the mode to O_RDWR (i.e., both O_RDONLY and O_WRONLY).
N/A
rawFsReadyChange( ) - notify rawFsLib of a change in ready status
void rawFsReadyChange ( RAW_VOL_DESC * vdptr /* pointer to volume descriptor */ )
This routine sets the volume descriptor state to RAW_VD_READY_CHANGED. It should be called whenever a driver senses that a device has come on-line or gone off-line, (e.g., a disk has been inserted or removed).
After this routine has been called, the next attempt to use the volume will result in an attempted remount.
N/A
rawFsVolUnmount( ) - disable a raw device volume
STATUS rawFsVolUnmount ( RAW_VOL_DESC * vdptr /* pointer to volume descriptor */ )
This routine is called when I/O operations on a volume are to be discontinued. This is commonly done before changing removable disks. All buffered data for the volume is written to the device (if possible), any open file descriptors are marked as obsolete, and the volume is marked as not mounted.
Because this routine will flush data from memory to the physical device, it should not be used in situations where the disk-change is not recognized until after a new disk has been inserted. In these circumstances, use the ready-change mechanism. (See the manual entry for rawFsReadyChange( ).)
This routine may also be called by issuing an ioctl( ) call using the FIOUNMOUNT function code.
OK, or ERROR if the routine cannot access the volume.