VxWorks Reference Manual : Libraries
rt11FsLib - RT-11 media-compatible file system library
rt11FsDevInit( ) - initialize the rt11Fs device descriptor
rt11FsInit( ) - prepare to use the rt11Fs library
rt11FsMkfs( ) - initialize a device and create an rt11Fs file system
rt11FsDateSet( ) - set the rt11Fs file system date
rt11FsReadyChange( ) - notify rt11Fs of a change in ready status
rt11FsModeChange( ) - modify the mode of an rt11Fs volume
This library provides services for file-oriented device drivers which use the RT-11 file standard. This module takes care of all the necessary buffering, directory maintenance, and RT-11-specific details.
The various routines provided by the VxWorks RT-11 file system (rt11Fs) may be separated into three broad groups: general initialization, device initialization, and file system operation.
The rt11FsInit( ) routine is the principal initialization function; it need only be called once, regardless of how many rt11Fs devices will be used.
Other rt11Fs routines are used for device initialization. For each rt11Fs device, either rt11FsDevInit( ) or rt11FsMkfs( ) must be called to install the device and define its configuration.
Several functions are provided to inform the file system of changes in the system environment. The rt11FsDateSet( ) routine is used to set the date. The rt11FsModeChange( ) routine is used to modify the readability or writability of a particular device. The rt11FsReadyChange( ) 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.
Before any other routines in rt11FsLib can be used, rt11FsInit( ) must be called to initialize this library. This call specifies the maximum number of rt11Fs files that can be open simultaneously and allocates memory for that many rt11Fs file descriptors. Attempts to open more files than the specified maximum will result in errors from open( ) or creat( ).
This initialization is enabled when the configuration macro INCLUDE_RT11FS is defined.
To use this library for a particular device, the device structure must contain, as the very first item, a BLK_DEV structure. This must be initialized before calling rt11FsDevInit( ). In the BLK_DEV structure, the driver includes the addresses of five routines which it must supply: one that reads one or more sectors, one that writes one or more sectors, one that performs I/O control on the device (using ioctl( )), one that checks the status of the device, and one that resets the device. This structure also specifies various physical aspects of the device (e.g., number of sectors, sectors per track, whether the media is removable). For more information about defining block devices, see the VxWorks Programmer's Guide: I/O System.
The device is associated with the rt11Fs file system by the rt11FsDevInit( ) call. The arguments to rt11FsDevInit( ) include the name to be used for the rt11Fs volume, a pointer to the BLK_DEV structure, whether the device uses RT-11 standard skew and interleave, and the maximum number of files that can be contained in the device directory.
Thereafter, when the file system receives a request from the I/O system, it simply calls the provided routines in the device driver to fulfill the request.
The RT-11 standard defines a peculiar software interleave and track-to-track skew as part of the format. The rtFmt parameter passed to rt11FsDevInit( ) should be TRUE if this formatting is desired. This should be the case if strict RT-11 compatibility is desired, or if files must be transferred between the development and target machines using the VxWorks-supplied RT-11 tools. Software interleave and skew will automatically be dealt with by rt11FsLib.
When rtFmt has been passed as TRUE and the maximum number of files is specified RT_FILES_FOR_2_BLOCK_SEG, the driver does not need to do anything else to maintain RT-11 compatibility (except to add the track offset as described above).
Note that if the number of files specified is different than RT_FILES_FOR_2_BLOCK_SEG under either a VxWorks system or an RT-11 system, compatibility is lost because VxWorks allocates a contiguous directory, whereas RT-11 systems create chained directories.
The sector number passed to the sector read and write routines is an absolute number, starting from sector 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 device-specific structure of the driver, and adding the proper number of sectors to the sector number passed to the read and write routines.
The RT-11 standard defines the disk to start on track 1. Track 0 is set aside for boot information. Therefore, in order to retain true compatibility with RT-11 systems, a one-track offset (i.e., the number of sectors in one track) needs to be added to the sector numbers passed to the sector read and write routines, and the device size needs to be declared as one track smaller than it actually is. This must be done by the driver using rt11FsLib; the library does not add such an offset automatically.
In the VxWorks RT-11 implementation, the directory is a fixed size, able to contain at least as many files as specified in the call to rt11FsDevInit( ). If the maximum number of files is specified to be RT_FILES_FOR_2_BLOCK_SEG, strict RT-11 compatibility is maintained, because this is the initial allocation in the RT-11 standard.
File names in the RT-11 file system use six characters, followed by a period (.), followed by an optional three-character extension.
An ioctl( ) call with the FIODIRENTRY function returns information about a particular directory entry. A pointer to a REQ_DIR_ENTRY structure is passed as the parameter. The field entryNum in the REQ_DIR_ENTRY structure must be set to the desired entry number. The name of the file, its size (in bytes), and its creation date are returned in the structure. If the specified entry is empty (i.e., if it represents an unallocated section of the disk), the name will be an empty string, the size will be the size of the available disk section, and the date will be meaningless. Typically, the entries are accessed sequentially, starting with entryNum = 0, until the terminating entry is reached, indicated by a return code of ERROR.
A copy of the directory for each volume is kept in memory (in the RT_VOL_DESC structure). This speeds up directory accesses, but requires that rt11FsLib be notified when disks are changed (i.e., floppies are swapped). If the driver can find this out (by interrogating controller status or by receiving an interrupt), the driver simply calls rt11FsReadyChange( ) when a disk is inserted or removed. The library rt11FsLib will automatically try to remount the device next time it needs it.
If the driver does not have access to the information that disk volumes have been changed, the changeNoWarn parameter should be set to TRUE when the device is defined using rt11FsDevInit( ). This will cause the disk to be automatically remounted before each open( ), creat( ), delete( ), and directory listing.
The routine rt11FsReadyChange( ) can also be called by user tasks, by issuing an ioctl( ) call with FIODISKCHANGE as the function code.
As a special case in open( ) and creat( ) calls, rt11FsLib recognizes a NULL file name to indicate access to the entire "raw" disk, as opposed to a file on the disk. Access in raw mode is useful for a disk that has no file system. For example, to initialize a new file system on the disk, use an ioctl( ) call with FIODISKINIT. To read the directory of a disk for which no file names are known, open the raw disk and use an ioctl( ) call with the function FIODIRENTRY.
The RT-11 file system is much simpler than the more common UNIX or MS-DOS file systems. The advantage of RT-11 is its speed; file access is made in at most one seek because all files are contiguous. Some of the most common errors for users with a UNIX background are:
- Only a single create at a time may be active per device.
- File size is set by the first create and close sequence; use lseek( ) to ensure a specific file size; there is no append function to expand a file.
- Files are strictly block oriented; unused portions of a block are filled with NULLs -- there is no end-of-file marker other than the last block.
The rt11Fs file system supports the following ioctl( ) functions. The functions listed are defined in the header ioLib.h. Unless stated otherwise, the file descriptor used for these functions can be any file descriptor open to a file or to the volume itself.
- 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 an rt11Fs file system on the disk volume. This routine does not format the disk; formatting must be done by the driver. The file descriptor should be obtained by opening the entire volume in raw mode:
fd = open ("DEV1:", O_WRONLY); status = ioctl (fd, FIODISKINIT, 0);- FIODISKCHANGE
- Announces a media change. It performs the same function as rt11FsReadyChange( ). This function may be called from interrupt level:
status = ioctl (fd, FIODISKCHANGE, 0);- FIOGETNAME
- Gets the file name of the file descriptor and copies it to the buffer nameBuf:
status = ioctl (fd, FIOGETNAME, &nameBuf);- FIORENAME
- Renames the file to the string newname:
status = ioctl (fd, FIORENAME, "newname");- FIONREAD
- Copies to unreadCount the number of unread bytes in the file:
status = ioctl (fd, FIONREAD, &unreadCount);- FIOFLUSH
- Flushes the file output buffer. It guarantees that any output that has been requested is actually written to the device.
status = ioctl (fd, FIOFLUSH, 0);- FIOSEEK
- Sets the current byte offset in the file to the position specified by newOffset:
status = ioctl (fd, FIOSEEK, newOffset);- FIOWHERE
- Returns the current byte position in the file. This is the byte offset of the next byte to be read or written. It takes no additional argument:
position = ioctl (fd, FIOWHERE, 0);- FIOSQUEEZE
- Coalesces fragmented free space on an rt11Fs volume:
status = ioctl (fd, FIOSQUEEZE, 0);- FIODIRENTRY
- Copies information about the specified directory entries to a REQ_DIR_ENTRY structure that is defined in ioLib.h. The argument req is a pointer to a REQ_DIR_ENTRY structure. On entry, the structure contains the number of the directory entry for which information is requested. On return, the structure contains the information on the requested entry. For example, after the following:
REQ_DIR_ENTRY req; req.entryNum = 0; status = ioctl (fd, FIODIRENTRY, &req);the request structure contains the name, size, and creation date of the file in the first entry (0) of the directory.
- FIOREADDIR
- Reads the next directory entry. The argument dirStruct is a DIR directory descriptor. Normally, readdir( ) is used to read a directory, rather than using the FIOREADDIR function directly. See dirLib.
DIR dirStruct; fd = open ("directory", O_RDONLY); status = ioctl (fd, FIOREADDIR, &dirStruct);- FIOFSTATGET
- Gets file status information (directory entry data). The argument statStruct is a pointer to a stat structure that is filled with data describing the specified file. Normally, the stat( ) or fstat( ) routine is used to obtain file information, rather than using the FIOFSTATGET function directly. See dirLib.
struct stat statStruct; fd = open ("file", O_RDONLY); status = ioctl (fd, FIOFSTATGET, &statStruct);Any other ioctl( ) function codes are passed to the block device driver for handling.
rt11FsLib.h
rt11FsLib, ioLib, iosLib, ramDrv, VxWorks Programmer's Guide: I/O System, Local File Systems
rt11FsDevInit( ) - initialize the rt11Fs device descriptor
RT_VOL_DESC *rt11FsDevInit ( char * devName, /* device name */ BLK_DEV * pBlkDev, /* pointer to block device info */ BOOL rt11Fmt, /* TRUE if RT-11 skew & interleave */ int nEntries, /* no. of dir entries incl term entry */ BOOL changeNoWarn /* TRUE if no disk change warning */ )
This routine initializes the device descriptor. The pBlkDev parameter is a pointer to an already-created BLK_DEV device structure. This structure contains definitions for various aspects of the physical device format, as well as pointers to the sector read, sector write, ioctl( ), status check, and reset functions for the device.
The rt11Fmt parameter is TRUE if the device is to be accessed using standard RT-11 skew and interleave.
The device directory will consist of one segment able to contain at least as many files as specified by nEntries. If nEntries is equal to RT_FILES_FOR_2_BLOCK_SEG, strict RT-11 compatibility is maintained.
The changeNoWarn parameter is TRUE if the disk may be changed without announcing the change via rt11FsReadyChange( ). Setting changeNoWarn to TRUE causes the disk to be regularly remounted, in case it has been changed. This results in a significant performance penalty.
An ERROR is returned if rt11Fmt is TRUE and the bd_blksPerTrack (sectors per track) field in the BLK_DEV structure is odd. This is because an odd number of sectors per track is incompatible with the RT-11 interleaving algorithm.
A pointer to the volume descriptor (RT_VOL_DESC), or NULL if invalid device parameters were specified, or the routine runs out of memory.
rt11FsInit( ) - prepare to use the rt11Fs library
STATUS rt11FsInit ( int maxFiles /* max no. of simultaneously open rt11Fs files */ )
This routine initializes the rt11Fs library. It must be called exactly once, before any other routine in the library. The maxFiles parameter specifies the number of rt11Fs files that may be open at once. This routine initializes the necessary memory structures and semaphores.
This routine is called automatically from the root task, usrRoot( ), in usrConfig.c when the configuration macro INCLUDE_RT11FS is defined.
OK, or ERROR if memory is insufficient.
rt11FsMkfs( ) - initialize a device and create an rt11Fs file system
RT_VOL_DESC *rt11FsMkfs ( char * volName, /* volume name to use */ BLK_DEV * pBlkDev /* pointer to block device struct */ )
This routine provides a quick method of creating an rt11Fs file system on a device. It is used instead of the two-step procedure of calling rt11FsDevInit( ) followed by an ioctl( ) call with an FIODISKINIT function code.
This routine provides defaults for the rt11Fs parameters expected by rt11FsDevInit( ). The directory size is set to RT_FILES_FOR_2_BLOCK_SEG (defined in rt11FsLib.h). No standard disk format is assumed; this allows the use of rt11Fs on block devices with an odd number of sectors per track. The changeNoWarn parameter is defined as FALSE, indicating that the disk will not be replaced without rt11FsReadyChange( ) being called first.
If different values are needed for any of these parameters, the routine rt11FsDevInit( ) must be used instead of this routine, followed by a request for disk initialization using the ioctl( ) function FIODISKINIT.
A pointer to an rt11Fs volume descriptor (RT_VOL_DESC), or NULL if there is an error.
rt11FsDateSet( ) - set the rt11Fs file system date
void rt11FsDateSet ( int year, /* year (72...03 (RT-11's days are numbered)) */ int month, /* month (0, or 1...12) */ int day /* day (0, or 1...31) */ )
This routine sets the date for the rt11Fs file system, which remains in effect until changed. All files created are assigned this creation date.
To set a blank date, invoke the command:
rt11FsDateSet (72, 0, 0); /* a date outside RT-11's epoch */
No automatic incrementing of the date is performed; each new date must be set with a call to this routine.
N/A
rt11FsReadyChange( ) - notify rt11Fs of a change in ready status
void rt11FsReadyChange ( RT_VOL_DESC * vdptr /* pointer to device descriptor */ )
This routine sets the volume descriptor state to RT_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).
N/A
rt11FsModeChange( ) - modify the mode of an rt11Fs volume
void rt11FsModeChange ( RT_VOL_DESC * vdptr, /* pointer to volume descriptor */ int newMode /* O_RDONLY, O_WRONLY, or O_RDWR (both) */ )
This routine sets the volume descriptor mode to newMode. It should be called whenever the read and write capabilities are determined, usually after a ready change. See the manual entry for rt11FsReadyChange( ).
The rt11FsDevInit( ) routine initially sets the mode to O_RDWR, (e.g., both O_RDONLY and O_WRONLY).
N/A
rt11FsLib, rt11FsDevInit( ), rt11FsReadyChange( )