Before any other operations can be performed, the dosFs file system library, dosFsLib, must be initialized. This happens automatically, triggered by the required dosFs components that were included in the system.

Initializing the file system invokes iosDrvInstall( ), which adds the driver to the I/O system driver table. The driver number assigned to the dosFs file system is recorded in a global variable, dosFsDrvNum. The table specifies the entry points for the dosFs file operations that are accessed by the devices using dosFs.

Next, create one or more block devices. To create the device, call the routine appropriate for that device driver. The format for this routine is xxxDevCreate( ) where xxx represents the device driver type; for example, scsiBlkDevCreate( ) or ataDevCreate( ).

The driver routine returns a pointer to a block device descriptor structure, BLK_DEV. This structure describes the physical attributes of the device and specifies the routines that the device driver provides to a file system. For more information on block devices, see 4.9.4 Block Devices.

If you have included the INCLUDE_DISK_CACHE component in your system, you can use dcacheDevCreate( ) to create a disk cache for each block device. Disk cache is intended to reduce the impact of seek times on rotational media, and is not used for RAM disks or TrueFFS devices. Example 5-1 creates a disk cache.

If you have included the INCLUDE_DISK_PART component in your system, you can create partitions on a disk and mount volumes atop the partitions. Use the usrFdiskPartCreate( ) and dpartDevCreate( ) routines to do this.

The following two examples create and use partitions. The first example creates, partitions, and formats a disk. The second example uses the partitioned disk, from the first example, to create the partition handler.

Create a dosFs device using dosFsDevCreate( ), which calls iosDrvAdd( ) internally. This step simply adds the device to the I/O system; however, it does not invoke any I/O operations and, therefore, does not mount the disk.

This disk is not mounted until the first I/O operation occurs. For more information, see 5.4.4 Mounting Volumes.

If you are using an unformatted disk, format the volume in either of two ways:

• By calling dosFsVolFormat( ) directly, specifying options for both the format of the FAT and the directory format (described below).

• By issuing the ioctl( ) FIODISKINIT command, which invokes the formatting routine with dosFsLib. This method uses the default volume format and parameters.

For more details, see the VxWorks API Reference entries for dosFsVolFormat( ) and ioctl( ).

The MS-DOS and dosFs file systems provide options for the format of the File Allocation Table (FAT) and the format of the directory. These options, described below, are completely independent.

A volume FAT format is set during disk formatting, according to either the volume size (by default), or the per-user defined settings passed to dosFsVolFormat( ). FAT options are summarized in Table 5-1:

There are three options for the directory format. These are:

A disk volume is mounted automatically, generally during the first open( ) or creat( ) operation for a file or directory on the disk. Certain ioctl( ) calls also cause the disk to be mounted.

This section provides examples of the steps discussed in the sections above. These examples use a variety of configurations and device types. They are meant to be relatively generic and applicable to most block devices.

The first example uses an ATA disk, and includes detailed descriptions of the commands run from the shell, displaying both user input and command-line output. The second example lists the required steps to create and format a RAM disk volume. The last example demonstrates how to initialize a pre-formatted SCSI disk.

This section discusses issues related to disks and volumes.

For more information about ioctl( ) support functions, see 5.2.16 I/O Control Functions Supported by dosFsLib.

You can inform dosFsLib that a disk change is taking place by using the ready-change mechanism. A change in the disk's ready-status is interpreted by dosFsLib as indicating that the disk must be remounted before the next I/O operation. To announce a ready-change, use any of the following methods:

• Call ioctl( ) with the FIODISKCHANGE function.

• Have the device driver set the bd_readyChanged field in the BLK_DEV structure to TRUE; this has the same effect as notifying dosFsLib directly.

• Use cbioRdyChgdSet( ) to set the ready-changed bit in the CBIO layer.

The dosFsShow( ) routine can be used to display volume configuration information. The dosFsVolDescGet( ) routine will programmatically obtain or verify a pointer to the DOS_VOLUME_DESC structure. For more information, see the reference entries.

When a disk is synchronized, all modified buffered data is physically written to the disk, so that the disk is up to date. This includes data written to files, updated directory information, and the FAT. To avoid loss of data, a disk should be synchronized before it is removed. For more information, see the entries for close( ) and dosFsVolUnmount( ) in the VxWorks Reference Manual.

This section discusses issues related to directories.

For FAT32, subdirectories can be created in any directory at any time. For FAT12 and FAT16, subdirectories can be created in any directory at any time, except in the root directory once it reaches its maximum entry count. Subdirectories can be created in the following ways:

1. Using ioctl( ) with the FIOMKDIR function: The name of the directory to be created is passed as a parameter to ioctl( ).

1. Using open( ): To create a directory, the O_CREAT option must be set in the flags parameter to open, and the FSTAT_DIR option must be set in the mode parameter. The open( ) call returns a file descriptor that describes the new directory. Use this file descriptor for reading only and close it when it is no longer needed.

1. Use mkdir( ), usrFsLib.

When creating a directory using any of the above methods, the new directory name must be specified. This name can be either a full pathname or a pathname relative to the current working directory.

A directory that is to be deleted must be empty (except for the "." and ".." entries). The root directory can never be deleted. Subdirectories can be removed in the following ways:

1. Using ioctl( ) with the FIORMDIR function, specifying the name of the directory. Again, the file descriptor used can refer to any file or directory on the volume, or to the entire volume itself.

1. Using the remove( ) function, specifying the name of the directory.

1. Use rmdir( ), usrFsLib.

You can programmatically search directories on dosFs volumes using the opendir( ), readdir( ), rewinddir( ), and closedir( ) routines.

To obtain more detailed information about a specific file, use the fstat( ) or stat( ) routine. Along with standard file information, the structure used by these routines also returns the file-attribute byte from a directory entry.

For more information, see the entry for dirLib in the VxWorks API Reference.

This section discusses issues related to files.

Files on a dosFs file system device are created, deleted, written, and read using the standard VxWorks I/O routines: creat( ), remove( ), write( ), and read( ). For more information, see 4.3 Basic I/O, and the ioLib entries in the VxWorks API Reference.

The file-attribute byte in a dosFs directory entry consists of a set of flag bits, each indicating a particular file characteristic. The characteristics described by the file-attribute byte are shown in Table 5-2.

If this flag is set, files accessed with open( ) cannot be written to. If the O_WRONLY or O_RDWR flags are set, open( ) returns ERROR, setting errno to S_dosFsLib_READ_ONLY.

This flag is ignored by dosFsLib and produces no special handling. For example, entries with this flag are reported when searching directories.

This flag is ignored by dosFsLib and produces no special handling. For example, entries with this flag are reported when searching directories.

This is a volume label flag, which indicates that a directory entry contains the dosFs volume label for the disk. A label is not required. If used, there can be only one volume label entry per volume, in the root directory. The volume label entry is not reported when reading the contents of a directory (using readdir( )). It can only be determined using the ioctl( ) function FIOLABELGET. The volume label can be set (or reset) to any string of 11 or fewer characters, using the ioctl( ) function FIOLABELSET. Any file descriptor open to the volume can be used during these ioctl( ) calls.

This is a directory flag, which indicates that this entry is a subdirectory, and not a regular file.

This is an archive flag, which is set when a file is created or modified. This flag is intended for use by other programs that search a volume for modified files and selectively archive them. Such a program must clear the archive flag, since VxWorks does not.

All the flags in the attribute byte, except the directory and volume label flags, can be set or cleared using the ioctl( ) function FIOATTRIBSET. This function is called after the opening of the specific file with the attributes to be changed. The attribute-byte value specified in the FIOATTRIBSET call is copied directly; to preserve existing flag settings, determine the current attributes using stat( ) or fstat( ), then change them using bitwise AND and OR operations.

The dosFs file system allocates disk space using one of the following methods. The first two methods are selected based upon the size of the write operation. The last method must be manually specified.

• single cluster allocation.  

Single cluster allocation uses a single cluster, which is the minimum allocation unit. This method is automatically used when the write operation is smaller than the size of a single cluster.

• cluster group allocation (nearly contiguous).  

Cluster group allocation uses adjacent (contiguous) groups of clusters, called extents. Cluster group allocation is nearly contiguous allocation and is the default method used when files are written in units larger than the size of a disk's cluster.

• absolutely contiguous allocation .  

Absolutely contiguous allocation uses only absolutely contiguous clusters. Because this type of allocation is dependent upon the existence of such space, it is specified under only two conditions: immediately after a new file is created and when reading from a file assumed to have been allocated to a contiguous space. Using this method risks disk fragmentation.

For any allocation method, you can deallocate unused reserved bytes by using the POSIX-compatible routine ftruncate( ) or the ioctl( ) function FIOTRUNC.

Under most circumstances, cluster group allocation is preferred to absolutely contiguous file access. Because it is nearly contiguous file access, it achieves a nearly optimal access speed. Cluster group allocation also significantly minimizes the risk of fragmentation posed by absolutely contiguous allocation.

Absolutely contiguous allocation attains raw disk throughput levels, however this speed is only slightly faster than nearly contiguous file access. Moreover, fragmentation is likely to occur over time. This is because after a disk has been in use for some period of time, it becomes impossible to allocate contiguous space. Thus, there is no guarantee that new data, appended to a file created or opened with absolutely continuous allocation, will be contiguous to the initially written data segment.

It is recommended that for a performance-sensitive operation, the application regulate disk space utilization, limiting it to 90% of the total disk space. Fragmentation is unavoidable when filling in the last free space on a disk, which has a serious impact on performance.

The dosFs file system defines the size of a cluster group based on the media's physical characteristics. That size is fixed for each particular media. Since seek operations are an overhead that reduces performance, it is desirable to arrange files so that sequential portions of a file are located in physically contiguous disk clusters. Cluster group allocation occurs when the cluster group size is considered sufficiently large so that the seek time is negligible compared to the read/write time. This technique is sometimes referred to as "nearly contiguous" file access because seek time between consecutive cluster groups is significantly reduced.

Because all large files on a volume are expected to have been written as a group of extents, removing them frees a number of extents to be used for new files subsequently created. Therefore, as long as free space is available for subsequent file storage, there are always extents available for use. Thus, cluster group allocation effectively prevents fragmentation (where a file is allocated in small units spread across distant locations on the disk). Access to fragmented files can be extremely slow, depending upon the degree of fragmentation.

A contiguous file is made up of a series of consecutive disk sectors. Absolutely contiguous allocation is intended to allocate contiguous space to a specified file (or directory) and, by so doing, optimize access to that file. You can specify absolutely contiguous allocation either when creating a file, or when opening a file previously created in this manner.

For more information on the ioctl( ) functions, see 5.2.16 I/O Control Functions Supported by dosFsLib.

The DOS file system is inherently susceptible to data structure inconsistencies that result from interruptions during certain types of disk updates. These types of interruptions include power failures, inadvertent system crashes for fixed disks, and the manual removal of a disk.

The dosFs file system supports the ioctl( ) functions. These functions are defined in the header file ioLib.h along with their associated constants.

For more information, see the manual entries for dosFsLib and for ioctl( ) in ioLib.

VxWorks can be booted from a local SCSI device. Before you can boot from SCSI, you must make a new boot application ROM that contains the SCSI library. Include INCLUDE_SCSI, INCLUDE_SCSI_BOOT, and SYS_SCSI_CONFIG in your boot application project.

After burning the SCSI boot application ROM, you can prepare the dosFs file system for use as a boot device. The simplest way to do this is to partition the SCSI device so that a dosFs file system starts at block 0. You can then make the new system image, place it on your SCSI boot device, and boot the new VxWorks system. These steps are shown in more detail below.

VxWorks provides a minimal "file system," rawFs, for use in systems that require only the most basic disk I/O functions. The rawFs file system, implemented in rawFsLib, treats the entire disk volume much like a single large file.

Although the dosFs file system provides this ability to varying degrees, the rawFs file system offers advantages in size and performance if more complex functions are not required.

To use the rawFs file system in a VxWorks-based system, include the INCLUDE_RAWFS component in the kernel, and set the NUM_RAWFS_FILES parameter to the desired maximum open file descriptor count.

The rawFs file system imposes no organization of the data on the disk. It maintains no directory information; thus there is no division of the disk area into specific files. All open( ) operations on rawFs devices specify only the device name; no additional filenames are possible.

The entire disk area is treated as a single file and is available to any file descriptor that is open for the device. All read and write operations to the disk use a byte-offset relative to the start of the first block on the disk.

Before any other operations can be performed, the rawFs library, rawFsLib, must be initialized by calling rawFsInit( ). This routine takes a single parameter, the maximum number of rawFs file descriptors that can be open at one time. This count is used to allocate a set of descriptors; a descriptor is used each time a rawFs device is opened.

The rawFsInit( ) routine also makes an entry for the rawFs file system in the I/O system driver table (with iosDrvInstall( )). This entry specifies the entry points for rawFs file operations, for all devices that use the rawFs file system. The driver number assigned to the rawFs file system is placed in a global variable, rawFsDrvNum.

The rawFsInit( ) routine is normally called by the usrRoot( ) task after starting the VxWorks system.

After the rawFs file system is initialized, the next step is to create one or more devices. Devices are created by the device driver's device creation routine (xxDevCreate( )). The driver routine returns a pointer to a block device descriptor structure (BLK_DEV). The BLK_DEV structure describes the physical aspects of the device and specifies the routines in the device driver that a file system can call. For more information on block devices, see 4.9.4 Block Devices.

Immediately after its creation, the block device has neither a name nor a file system associated with it. To initialize a block device for use with rawFs, the already-created block device must be associated with rawFs and a name must be assigned to it. This is done with the rawFsDevInit( ) routine. Its parameters are the name to be used to identify the device and a pointer to the block device descriptor structure (BLK_DEV):

RAW_VOL_DESC *pVolDesc; 
BLK_DEV      *pBlkDev; 
pVolDesc = rawFsDevInit ("DEV1:", pBlkDev); 

The rawFsDevInit( ) call assigns the specified name to the device and enters the device in the I/O system device table (with iosDevAdd( )). It also allocates and initializes the file system's volume descriptor for the device. It returns a pointer to the volume descriptor to the caller; this pointer is used to identify the volume during certain file system calls.

Note that initializing the device for use with rawFs does not format the disk. That is done using an ioctl( ) call with the FIODISKFORMAT function.

A disk volume is mounted automatically, generally during the first open( ) or creat( ) operation. (Certain ioctl( ) functions also cause the disk to be mounted.) The volume is again mounted automatically on the first disk access following a ready-change operation (see 5.4.6 Changing Disks).

To begin I/O operations upon a rawFs device, first open the device using the standard open( ) function. (The creat( ) function can be used instead, although nothing is actually "created.") Data on the rawFs device is written and read using the standard I/O routines write( ) and read( ). For more information, see 4.3 Basic I/O.

The character pointer associated with a file descriptor (that is, the byte offset where the read and write operations take place) can be set by using ioctl( ) with the FIOSEEK function.

Multiple file descriptors can be open simultaneously for a single device. These must be carefully managed to avoid modifying data that is also being used by another file descriptor. In most cases, such multiple open descriptors use FIOSEEK to set their character pointers to separate disk areas.

The rawFs file system must be notified when removable disks are changed (for example, when floppies are swapped). Two different notification methods are provided: (1) rawFsVolUnmount( ) and (2) the ready-change mechanism.

The first method of announcing a disk change is to call rawFsVolUnmount( ) prior to removing the disk. This call flushes all modified file descriptor buffers if possible (see Synchronizing Volumes) and also marks any open file descriptors as obsolete. The next I/O operation remounts the disk. Calling ioctl( ) with FIOUNMOUNT is equivalent to using rawFsVolUnmount( ). Any open file descriptor to the device can be used in the ioctl( ) call.

Attempts to use obsolete file descriptors for further I/O operations produce an S_rawFsLib_FD_OBSOLETE error. To free an obsolete descriptor, use close( ), as usual. This frees the descriptor even though it produces the same error.

ISRs must not call rawFsVolUnmount( ) directly, because the call can pend while the device becomes available. The ISR can instead give a semaphore that prompts a task to un-mount the volume. (Note that rawFsReadyChange( ) can be called directly from ISRs; see Announcing Disk Changes with Ready-Change.)

When rawFsVolUnmount( ) is called, it attempts to write buffered data out to the disk. Its use is therefore inappropriate for situations where the disk-change notification does not occur until a new disk is inserted, because the old buffered data would be written to the new disk. In this case, use rawFsReadyChange( ), as described in Announcing Disk Changes with Ready-Change.

If rawFsVolUnmount( ) is called after the disk is physically removed, the data flushing portion of its operation fails. However, the file descriptors are still marked as obsolete, and the disk is marked as requiring remounting. An error is not returned by rawFsVolUnmount( ); to avoid lost data in this situation, explicitly synchronize the disk before removing it (see Synchronizing Volumes).

The second method of announcing that a disk change is taking place is with the ready-change mechanism. A change in the disk's ready-status is interpreted by rawFsLib to indicate that the disk must be remounted during the next I/O call.

There are three ways to announce a ready-change:

• By calling rawFsReadyChange( ) directly.

• By calling ioctl( ) with FIODISKCHANGE.

• By having the device driver set the bd_readyChanged field in the BLK_DEV structure to TRUE; this has the same effect as notifying rawFsLib directly.

The ready-change announcement does not cause buffered data to be flushed to the disk. It merely marks the volume as needing remounting. As a result, data written to files can be lost. This can be avoided by synchronizing the disk before asserting ready-change. The combination of synchronizing and asserting ready-change provides all the functionality of rawFsVolUnmount( ) except for marking file descriptors as obsolete.

Ready-change can be called from an ISR, because it does not attempt to flush data or perform other operations that could cause delay.

The block device driver status-check routine (identified by the bd_statusChk field in the BLK_DEV structure) is useful for asserting ready-change for devices that only detect a disk change after the new disk is inserted. This routine is called at the beginning of each open( ) or creat( ), before the file system checks for ready-change.

If it is not possible for a ready-change to be announced each time the disk is changed, close all file descriptors for the volume before changing the disk.

When a disk is synchronized, all buffered data that is modified is written to the physical device so that the disk is up to date. For the rawFs file system, the only such data is that contained in open file descriptor buffers.

To avoid loss of data, synchronize a disk before removing it. You may need to explicitly synchronize a disk, depending on when (or if) the rawFsVolUnmount( ) call is issued.

When rawFsVolUnmount( ) is called, an attempt is made to synchronize the device before un-mounting. If this disk is still present and writable at the time of the call, synchronization takes place automatically; there is no need to synchronize the disk explicitly.

However, if the rawFsVolUnmount( ) call is made after a disk is removed, it is obviously too late to synchronize, and rawFsVolUnmount( ) discards the buffered data. Therefore, make a separate ioctl( ) call with the FIOSYNC function before removing the disk. (For example, this could be done in response to an operator command.) Any open file descriptor to the device can be used during the ioctl( ) call. This call writes all modified file descriptor buffers for the device out to the disk.

The rawFs file system supports the ioctl( ) functions shown in Table 5-4. The functions listed are defined in the header file ioLib.h. For more information, see the manual entries for rawFsLib and for ioctl( ) in ioLib.

The tapeFs library, tapeFsLib, provides basic services for tape devices that do not use a standard file or directory structure on tape. The tape volume is treated much like a raw device where the entire volume is a large file. Any data organization on this large file is the responsibility of a higher-level layer.

To configure VxWorks with tapeFs, include the INCLUDE_TAPEFS component in the kernel.

The tapeFs file system imposes no organization of the data on the tape volume. It maintains no directory information; there is no division of the tape area into specific files; and no filenames are used. An open( ) operation on the tapeFs device specifies only the device name; no additional filenames are allowed.

The entire tape area is available to any file descriptor open for the device. All read and write operations to the tape use a location offset relative to the current location of the tape head. When a file is configured as a rewind device and first opened, tape operations begin at the beginning-of-medium (BOM); see Initializing a Device for Use With tapeFs. Thereafter, all operations occur relative to where the tape head is located at that instant of time. No location information, as such, is maintained by tapeFs.

The tapeFs file system must be initialized, and a tape device created, in order to make the physical tape device available to the tape file system. At this point, normal I/O system operations can be performed.

The tapeFs library, tapeFsLib, is initialized by calling tapeFsInit( ). Each tape file system can handle multiple tape devices. However, each tape device is allowed only one file descriptor. Thus, you cannot open two files on the same tape device.

The tapeFsInit( ) routine also makes an entry for the tapeFs file system in the I/O system driver table (with iosDrvInstall( )). This entry specifies function pointers to carry out tapeFs file operations on devices that use the tapeFs file system. The driver number assigned to the tapeFs file system is placed in a global variable, tapeFsDrvNum.

When initializing a tape device, tapeFsInit( ) is called automatically if tapeFsDevInit( ) is called; thus, the tape file system does not require explicit initialization.

Once the tapeFs file system has been initialized, the next step is to create one or more devices that can be used with it. This is done using the sequential device creation routine, scsiSeqDevCreate( ). The driver routine returns a pointer to a sequential device descriptor structure, SEQ_DEV. The SEQ_DEV structure describes the physical aspects of the device and specifies the routines in the device driver that tapeFs can call. For more information on sequential devices, see the manual entry for scsiSeqDevCreate( ), Configuring SCSI Drivers and 4.9.4 Block Devices.

Immediately after its creation, the sequential device has neither a name nor a file system associated with it. To initialize a sequential device for use with tapeFs, call tapeFsDevInit( ) to assign a name and declare a file system. Its parameters are the volume name--for identifying the device; a pointer to SEQ_DEV--the sequential device descriptor structure; and a pointer to an initialized tape configuration structure TAPE_CONFIG. This structure has the following form:

In the preceding definition of TAPE_CONFIG, only two fields, blkSize and rewind, are currently in use. If rewind is TRUE, then a tape device is rewound to the beginning-of-medium (BOM) upon closing a file with close( ). However, if rewind is FALSE, then closing a file has no effect on the position of the read/write head on the tape medium.

The blkSize field specifies the block size of the physical tape device. Having set the block size, each read or write operation has a transfer unit of blkSize. Tape devices can perform fixed or variable block transfers, a distinction also captured in the blkSize field.

For more information on initializing a tapeFs device, see the VxWorks API Reference entry for tapeFsDevInit( ).

A tape file system can be created for fixed block size transfers or variable block size transfers, depending on the capabilities of the underlying physical device. The type of data transfer (fixed block or variable block) is usually decided when the tape device is being created in the file system, that is, before the call to tapeFsDevInit( ). A block size of zero represents variable block size data transfers.

Once the block size has been set for a particular tape device, it is usually not modified. To modify the block size, use the ioctl( ) functions FIOBLKSIZESET and FIOBLKSIZEGET to set and get the block size on the physical device.

Note that for fixed block transfers, the tape file system buffers a block of data. If the block size of the physical device is changed after a file is opened, the file should first be closed and then re-opened in order for the new block size to take effect.

A tape volume is mounted automatically during the open( ) operation. There is no specific mount operation, that is, the mount is implicit in the open( ) operation.

To begin I/O to a tapeFs device, the device is first opened using open( ). Data on the tapeFs device is written and read using the standard I/O routines write( ) and read( ). For more information, see 4.7.7 Block Devices.

End-of-file markers can be written using ioctl( ) with the MTWEOF function. For more information, see 5.5.6 I/O Control Functions Supported by tapeFsLib.

The tapeFs file system should be notified when removable media are changed (for example, when tapes are swapped). The tapeFsVolUnmount( ) routine controls the mechanism to un-mount a tape volume.

A tape should be un-mounted before it is removed. Prior to un-mounting a tape volume, an open file descriptor must be closed. Closing an open file flushes any buffered data to the tape, thus synchronizing the file system with the data on the tape. To flush or synchronize data before closing the file, call ioctl( ) with the FIOFLUSH or FIOSYNC functions.

After closing any open file, call tapeFsVolUnmount( ) before removing the tape. Once a tape has been un-mounted, the next I/O operation must remount the tape using open( ).

Interrupt handlers must not call tapeFsVolUnmount( ) directly, because it is possible for the call to pend while the device becomes available. The interrupt handler can instead give a semaphore that prompts a task to un-mount the volume.

The tapeFs file system supports the ioctl( ) functions shown in Table 5-5. The functions listed are defined in the header files ioLib.h, seqIo.h, and tapeFsLib.h. For more information, see the VxWorks API Reference entries for tapeFsLib, ioLib, and ioctl( ).

The MTIOCTOP operation is compatible with the UNIX MTIOCTOP operation. The argument passed to ioctl( ) with MTIOCTOP is a pointer to an MTOP structure that contains the following two fields:

typedef struct mtop  
    { 
    short mt_op;       /* operation */ 
    int  mt_count;     /* number of operations */ 
    } MTOP;

The mt_op field contains the type of MTIOCTOP operation to perform. These operations are defined in Table 5-6. The mt_count field contains the number of times the operation defined in mt_op should be performed.  

The cdromFs library, cdromFsLib, lets applications read any CD-ROM that is formatted in accordance with ISO 9660 file system standards. To configure VxWorks with cdromFs, add the INCLUDE_CDROMFS component to the kernel.

After initializing cdromFs and mounting it on a CD-ROM block device, you can access data on that device using the standard POSIX I/O calls: open( ), close( ), read( ), ioctl( ), readdir( ), and stat( ). The write( ) call always returns an error.

The cdromFs utility supports multiple drives, multiple open files, and concurrent file access. When you specify a pathname, cdromFS accepts both "/" and "\". However, the backslash is not recommended because it might not be supported in future releases.

CdromFs provides access to CD-ROM file systems using any standard BLK_DEV structure. The basic initialization sequence is similar to installing a dosFs file system on a SCSI device.

For information on using cdromFs( ), see the VxWorks API Reference entry for cdromFsLib.

The Target Server File System (TSFS) is designed for development and diagnostic purposes. It is a full-featured VxWorks file system, but the files are actually located on the host system.

The TSFS provides all of the I/O features of the network driver for remote file access (netDrv), without requiring any target resources (except those required for communication between the target system and the target server on the host). The TSFS uses a WDB driver to transfer requests from the VxWorks I/O system to the target server. The target server reads the request and executes it using the host file system. When you open a file with TSFS, the file being opened is actually on the host. Subsequent read( ) and write( ) calls on the file descriptor obtained from the open( ) call read from and write to the opened host file.

The TSFS VIO driver is oriented toward file I/O rather than toward console operations as is the Tornado 1.0 VIO driver. TSFS provides all the I/O features that netDrv provides, without requiring any target resource beyond what is already configured to support communication between target and target server. It is possible to access host files randomly without copying the entire file to the target, to load an object module from a virtual file source, and to supply the filename to routines such as moduleLoad( ) and copy( ).

Each I/O request, including open( ), is synchronous; the calling target task is blocked until the operation is complete. This provides flow control not available in the console VIO implementation. In addition, there is no need for WTX protocol requests to be issued to associate the VIO channel with a particular host file; the information is contained in the name of the file.

Consider a read( ) call. The driver transmits the ID of the file (previously established by an open( ) call), the address of the buffer to receive the file data, and the desired length of the read to the target server. The target server responds by issuing the equivalent read( ) call on the host and transfers the data read to the target program. The return value of read( ) and any errno that might arise are also relayed to the target, so that the file appears to be local in every way.

For detailed information, see the VxWorks API Reference entry for wdbTsfsDrv.

TSFS sockets are operated on in a similar way to other TSFS files, using open( ), close( ), read( ), write( ), and ioctl( ). To open a TSFS socket, use one of the following forms of filename:

"TCP:hostIP:port" 
"TCP:hostname:port"

The flags and permissions arguments are ignored. The following examples show how to use these filenames:

fd = open("/tgtsvr/TCP:phobos:6164"0,0)    /* open socket and connect  */ 
                                           /* to server phobos         */ 
 
fd = open("/tgtsvr/TCP:150.50.50.50:6164",0,0)  /* open socket and     */ 
                                                /*connect to server    */ 
                                                /* 150.50.50.50        */

The result of this open( ) call is to open a TCP socket on the host and connect it to the target server socket at hostname or hostIP awaiting connections on port. The resultant socket is non-blocking. Use read( ) and write( ) to read and write to the TSFS socket. Because the socket is non-blocking, the read( ) call returns immediately with an error and the appropriate errno if there is no data available to read from the socket. The ioctl( ) usage specific to TSFS sockets is discussed in the VxWorks API Reference entry for wdbTsfsDrv. This socket configuration allows VxWorks to use the socket facility without requiring sockLib and the networking modules on the target.

Errors can arise at various points within TSFS and are reported back to the original caller on the target, along with an appropriate error code. The error code returned is the VxWorks errno which most closely matches the error experienced on the host. If a WDB error is encountered, a WDB error message is returned rather than a VxWorks errno.

To use the TSFS, your VxWorks-based system must be configured with the INCLUDE_WDB_TSFS component in the kernel. This creates the /tgtsvr file system.

The target server on the host system must also be configured for TSFS. This involves assigning a root directory on your host to TSFS (see the discussion of the target server -R option in Security Considerations). For example, on a PC host you could set the TSFS root to c:\myTarget\logs.

Having done so, opening the file /tgtsvr/logFoo on the target causes c:\myTarget\logs\logFoo to be opened on the host by the target server. A new file descriptor representing that file is returned to the caller on the target.

While TSFS has much in common with netDrv, the security considerations are different. With TSFS, the host file operations are done on behalf of the user that launched the target server. The user name given to the target as a boot parameter has no effect. In fact, none of the boot parameters have any effect on the access privileges of TSFS.

In this environment, it is less clear to the user what the privilege restrictions to TSFS actually are, since the user ID and host machine that start the target server may vary from invocation to invocation. By default, any Tornado tool that connects to a target server which is supporting TSFS has access to any file with the same authorizations as the user that started that target server. However, the target server can be locked (with the -L option) to restrict access to the TSFS.

The options which have been added to the target server startup routine to control target access to host files using TSFS include:

This option restricts access to the server to processes running under the same user ID for UNIX, or the same WIND_UID for Windows.

For example, specifying -R /tftpboot prepends this string to all TSFS filenames received by the target server, so that /tgtsvr/etc/passwd maps to /tftpboot/etc/passwd. If -R is not specified, TSFS is not activated and no TSFS requests from the target will succeed. Restarting the target server without specifying -R disables TSFS.

The target server interprets this option to mean that modifying operations (including file create and delete or write) are authorized. If -RW is not specified, the default is read only and no file modifications are allowed.