tapeFsLib

NAME

tapeFsLib - tape sequential device file system library

ROUTINES

tapeFsDevInit( ) - associate a sequential device with tape volume functions
tapeFsInit( ) - initialize the tape volume library
tapeFsReadyChange( ) - notify tapeFsLib of a change in ready status
tapeFsVolUnmount( ) - disable a tape device volume

DESCRIPTION

This library 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 large file. The tape may either be read or written. However, there is no high-level organization of the tape into files or directories, which must be provided by a higher-level layer.

USING THIS LIBRARY

The various routines provided by the VxWorks tape file system, or tapeFs, can be categorized into three broad groupings: general initialization, device initialization, and file system operation.
The tapeFsInit( ) routine is the principal general initialization function; it needs to be called only once, regardless of how many tapeFs devices are used.
To initialize devices, tapeFsDevInit( ) must be called for each tapeFs device.
Use of this library typically occurs through standard use of the I/O system routines open( ), close( ), read( ), write( ) and ioctl( ). Besides these standard I/O system operations, several routines are provided to inform the file system of changes in the system environment. The tapeFsVolUnmount( ) routine informs the file system that a particular device should be unmounted; any synchronization should be done prior to invocation of this routine, in preparation for a tape volume change. The tapeFsReadyChange( ) routine is used to inform the file system that a tape may have been swapped and that the next tape operation should first remount the tape. Information about a ready-change is also obtained from the driver using the SEQ_DEV device structure. Note that tapeFsVolUnmount( ) and tapeFsReadyChange( ) should be called only after a file has been closed.

INITIALIZATION OF THE FILE SYSTEM

Before any other routines in tapeFsLib can be used, tapeFsInit( ) must be called to initialize the library. This implementation of the tape file system assumes only one file descriptor per volume. However, this constraint can be changed in case a future implementation demands multiple file descriptors per volume.
During the tapeFsInit( ) call, the tape 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, tapeFsDrvNum.
To enable this initialization, define INCLUDE_TAPEFS in the BSP, or simply start using the tape file system with a call to tapeFsDevInit( ) and tapeFsInit( ) will be called automatically if it has not been called before.

DEFINING A TAPE DEVICE

To use this library for a particular device, the device structure used by the device driver must contain, as the very first item, a sequential device description structure (SEQ_DEV). The SEQ_DEV must be initialized before calling tapeFsDevInit( ). The driver places in the SEQ_DEV structure the addresses of routines that 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 writes file marks on a tape, one that rewinds the tape volume, one that reserves a tape device for use, one that releases a tape device after use, one that mounts/unmounts a volume, one that spaces forward or backwards by blocks or file marks, one that erases the tape, one that resets the tape device, and one that checks the status of the device. The SEQ_DEV structure also contains fields that describe the physical configuration of the device. For more information about defining sequential devices, see the VxWorks Programmer's Guide: I/O System.

INITIALIZATION OF THE DEVICE

The tapeFsDevInit( ) routine is used to associate a device with the tapeFsLib functions. The volName parameter expected by tapeFsDevInit( ) is a pointer to a name string which identifies the device. This string serves as the pathname for I/O operations which operate on the device and appears in the I/O system device table, which can be displayed using iosDevShow( ).
The pSeqDev parameter expected by tapeFsDevInit( ) is a pointer to the SEQ_DEV structure describing the device and containing the addresses of the required driver functions.
The pTapeConfig parameter is a pointer to a TAPE_CONFIG structure that contains information specifying how the tape device should be configured. The configuration items are fixed/variable block size, rewind/no-rewind device, and number of file marks to be written. For more information about the TAPE_CONFIG structure, look at the header file tapeFsLib.h.
The syntax of the tapeFsDevInit( ) routine is as follows:
    tapeFsDevInit
        (
        char *        volName,     /* name to be used for volume   */
        SEQ_DEV *     pSeqDev,     /* pointer to device descriptor */
        TAPE_CONFIG * pTapeConfig  /* pointer to tape config info  */
        )
When tapeFsLib receives a request from the I/O system, after tapeFsDevInit( ) has been called, it calls the device driver routines (whose addresses were passed in the SEQ_DEV structure) to access the device.

OPENING AND CLOSING A FILE

A tape volume is opened by calling the I/O system routine open( ). A file can be opened only with the O_RDONLY or O_WRONLY flags. The O_RDWR mode is not used by this library. A call to open( ) initializes the file descriptor buffer and state information, reserves the tape device, rewinds the tape device if it was configured as a rewind device, and mounts a volume. Once a tape volume has been opened, that tape device is reserved, disallowing any other system from accessing that device until the tape volume is closed. Also, the single file descriptor is marked "in use" until the file is closed, making sure that a file descriptor is not opened multiple times.
A tape device is closed by calling the I/O system routine close( ). Upon a close( ) request, any unwritten buffers are flushed, the device is rewound (if it is a rewind device), and, finally, the device is released.

UNMOUNTING VOLUMES (CHANGING TAPES)

A tape volume should be unmounted before it is removed. When unmounting a volume, make sure that any open file is closed first. A tape may be unmounted by calling tapeFsVolUnmount( ) directly.
If a file is open, it is not correct to change the medium and continue with the same file descriptor still open. Since tapeFs assumes only one file descriptor per device, to reuse that device, the file must be closed and opened later for the new tape volume.
Before tapeFsVolUnmount( ) is called, the device should be synchronized by invoking the ioctl( ) FIOSYNC or FIOFLUSH. It is the responsibility of the higher-level layer to synchronize the tape file system before unmounting. Failure to synchronize the volume before unmounting may result in loss of data.

IOCTL FUNCTIONS

The VxWorks tape sequential device file system supports the following ioctl( ) functions. The functions listed are defined in the header files ioLib.h and tapeFsLib.h.
FIOFLUSH
Writes all modified file descriptor buffers to the physical device.
    status = ioctl (fd, FIOFLUSH, 0);
FIOSYNC
Performs the same function as FIOFLUSH.

FIOBLKSIZEGET
Returns the value of the block size set on the physical device. This value is compared against the sd_blkSize value set in the SEQ_DEV device structure.

FIOBLKSIZESET
Sets a specified block size value on the physical device and also updates the value in the SEQ_DEV and TAPE_VOL_DESC structures, unless the supplied value is zero, in which case the device structures are updated but the device is not set to zero. This is because zero implies variable block operations, therefore the device block size is ignored.

MTIOCTOP
Allows use of the standard UNIX MTIO ioctl operations by means of the MTOP structure. The MTOP structure appears as follows:
typedef struct mtop
    {
    short       mt_op;                  /* operation */
    int         mt_count;               /* number of operations */
    } MTOP;
Use these ioctl( ) operations as follows:
    MTOP mtop;

    mtop.mt_op    = MTWEOF;
    mtop.mt_count = 1;
    status = ioctl (fd, MTIOCTOP, (int) &mtop);
The permissable values for mt_op are:

MTWEOF
Writes an end-of-file record to tape. An end-of-file record is a file mark.

MTFSF
Forward space over a file mark and position the tape head in the gap between the file mark just skipped and the next data block. Any buffered data is flushed out to the tape if the tape is in write mode.

MTBSF
Backward space over a file mark and position the tape head in the gap preceeding the file mark, that is, right before the file mark. Any buffered data is flushed out to the tape if the tape is in write mode.

MTFSR
Forward space over a data block and position the tape head in the gap between the block just skipped and the next block. Any buffered data is flushed out to the tape if the tape is in write mode.

MTBSR
Backward space over a data block and position the tape head right before the block just skipped. Any buffered data is flushed out to the tape if the tape is in write mode.

MTREW
Rewind the tape to the beginning of the medium. Any buffered data is flushed out to the tape if the tape is in write mode.

MTOFFL
Rewind and unload the tape. Any buffered data is flushed out to the tape if the tape is in write mode.

MTNOP
No operation, but check the status of the device, thus setting the appropriate SEQ_DEV fields.

MTRETEN
Retension the tape. This command usually sets tape tension and can be used in either read or write mode. Any buffered data is flushed out to tape if the tape is in write mode.

MTERASE
Erase the entire tape and rewind it.

MTEOM
Position the tape at the end of the medium and unload the tape. Any buffered data is flushed out to the tape if the tape is in write mode.

INCLUDE FILES

tapeFsLib.h

tapeFsDevInit( )

NAME

tapeFsDevInit( ) - associate a sequential device with tape volume functions

SYNOPSIS

TAPE_VOL_DESC *tapeFsDevInit
    (
    char *        volName,    /* volume name */
    SEQ_DEV *     pSeqDev,    /* pointer to sequential device info */
    TAPE_CONFIG * pTapeConfig /* pointer to tape config info */
    )

DESCRIPTION

This routine takes a sequential device created by a device driver and defines it as a tape 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 tapeFsLib.
This routine associates volName with a device and installs it in the VxWorks I/O system-device table. The driver number used when the device is added to the table is that which was assigned to the tape library during tapeFsInit( ). (The driver number is kept in the global variable tapeFsDrvNum.)
The SEQ_DEV structure specified by pSeqDev contains configuration data describing the device and the addresses of the routines which are called to read blocks, write blocks, write file marks, reset the device, check device status, perform other I/O control functions (ioctl( )), reserve and release devices, load and unload devices, and rewind devices. These routines are not called until they are required by subsequent I/O operations. The TAPE_CONFIG structure is used to define configuration parameters for the TAPE_VOL_DESC. The configuration parameters are defined and described in tapeFsLib.h.

RETURNS

A pointer to the volume descriptor (TAPE_VOL_DESC), or NULL if there is an error.

ERRNO

S_tapeFsLib_NO_SEQ_DEV, S_tapeFsLib_ILLEGAL_TAPE_CONFIG_PARM

tapeFsInit( )

NAME

tapeFsInit( ) - initialize the tape volume library

SYNOPSIS


STATUS tapeFsInit ()

DESCRIPTION

This routine initializes the tape volume library. It must be called exactly once, before any other routine in the library. Only one file descriptor per volume is assumed.
This routine also installs tape volume library routines in the VxWorks I/O system driver table. The driver number assigned to tapeFsLib is placed in the global variable tapeFsDrvNum. This number is later associated with system file descriptors opened to tapeFs devices.
To enable this initialization, simply call the routine tapeFsDevInit( ), which automatically calls tapeFsInit( ) in order to initialize the tape file system.

RETURNS

OK or ERROR.

tapeFsReadyChange( )

NAME

tapeFsReadyChange( ) - notify tapeFsLib of a change in ready status

SYNOPSIS

STATUS tapeFsReadyChange
    (
    TAPE_VOL_DESC * pTapeVol /* pointer to volume descriptor */
    )

DESCRIPTION

This routine sets the volume descriptor state to TAPE_VD_READY_CHANGED. It should be called whenever a driver senses that a device has come on-line or gone off-line (for example, that a tape has been inserted or removed).
After this routine has been called, the next attempt to use the volume results in an attempted remount.

RETURNS

OK if the read change status is set, or ERROR if the file descriptor is in use.

ERRNO

S_tapeFsLib_FILE_DESCRIPTOR_BUSY

tapeFsVolUnmount( )

NAME

tapeFsVolUnmount( ) - disable a tape device volume

SYNOPSIS

STATUS tapeFsVolUnmount
    (
    TAPE_VOL_DESC * pTapeVol /* pointer to volume descriptor */
    )

DESCRIPTION

This routine is called when I/O operations on a volume are to be discontinued. This is commonly done before changing removable tape. All buffered data for the volume is written to the device (if possible), any open file descriptors are marked obsolete, and the volume is marked not mounted.
Because this routine flushes data from memory to the physical device, it should not be used in situations where the tape-change is not recognized until after a new tape has been inserted. In these circumstances, use the ready-change mechanism. (See the manual entry for tapeFsReadyChange( ).)
This routine may also be called by issuing an ioctl( ) call using the FIOUNMOUNT function code.

RETURNS

OK, or ERROR if the routine cannot access the volume.

ERRNO

S_tapeFsLib_VOLUME_NOT_AVAILABLE, S_tapeFsLib_FILE_DESCRIPTOR_BUSY, S_tapeFsLib_SERVICE_NOT_AVAILABLE

tapeFsLib

NAME

ROUTINES

DESCRIPTION

USING THIS LIBRARY

INITIALIZATION OF THE FILE SYSTEM

DEFINING A TAPE DEVICE

INITIALIZATION OF THE DEVICE

OPENING AND CLOSING A FILE

UNMOUNTING VOLUMES (CHANGING TAPES)

IOCTL FUNCTIONS

INCLUDE FILES

SEE ALSO

tapeFsDevInit( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

tapeFsInit( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

SEE ALSO

tapeFsReadyChange( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO

tapeFsVolUnmount( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO