VxWorks API Reference : OS Libraries

cdromFsLib

NAME

cdromFsLib - ISO 9660 CD-ROM read-only file system library

ROUTINES

cdromFsInit( ) - initialize cdromFsLib
cdromFsVolConfigShow( ) - show the volume configuration information
cdromFsVersionDisplay( ) - display the cdromFs version number
cdromFsVersionNumGet( ) - return the cdromFs version number
cdromFsDevCreate( ) - create a cdromFsLib device

DESCRIPTION

This library defines cdromFsLib, a utility that lets you use standard POSIX I/O calls to read data from a CD-ROM, CD-R, or CD-RW formatted according to the ISO 9660 standard file system.

It provides access to CD file systems using any standard BLOCK_DEV structure (that is, a disk-type driver).

The basic initialization sequence is similar to installing a DOS file system on a SCSI device.

1. Initialize the cdrom file system library (preferably in sysScsiConfig( ) in sysScsi.c): 

    cdromFsInit ();
2. Locate and create a SCSI physical device: 
    pPhysDev=scsiPhysDevCreate (pSysScsiCtrl,0,0,0,NONE,1,0,0);
3. Create a SCSI block device on the physical device: 
    pBlkDev = (SCSI_BLK_DEV *) scsiBlkDevCreate (pPhysDev, 0, 0);
4. Create a CD file system on the block device: 
    cdVolDesc = cdromFsDevCreate ("cdrom:", (BLK_DEV *) pBlkDev);
Call cdromFsDevCreate( ) once for each CD drive attached to your target. After the successful completion of cdromFsDevCreate( ), the CD file system will be available like any DOS file system, and you can access data on the named CD device using open( ), close( ), read( ), ioctl( ), readdir( ), and stat( ). A write( ) always returns an error.

The cdromFsLib utility supports multiple drives, concurrent access from multiple tasks, and multiple open files.

ISO 9660 FILE AND DIRECTORY NAMING

The strict ISO 9660 specification allows only uppercase file names consisting of 8 characters plus a 3 character suffix.

To accommodate users familiar with MS-DOS, cdromFsLib lets you use lowercase name arguments to access files with names consisting entirely of uppercase characters. Mixed-case file and directory names are accessible only if you specify their exact case-correct names.

JOLIET EXTENSIONS FILE AND DIRECTORY NAMING

The Joliet extensions to the ISO 9660 specification are designed to handle long file names up to 340 characters long.

File names must be case correct. The above use of lowercase characters to access files named entirely with uppercase characters is not supported.

cdromFs with Joliet extensions does not support Unicode file names. The file names on the CD are stored in 16 bit Unicode characters. However, they are converted to 8 bit characters inside cdromFs by dropping the most significant byte of each 16 bit character.

FILE AND DIRECTORY NAMING COMMON TO ISO 9660 AND THE JOLIET EXTENSIONS

To support multiple versions of the same file, the ISO 9660 specification also supports version numbers. When specifying a file name in an open( ) call, you can select the file version by appending the file name with a semicolon (;) followed by a decimal number indicating the file version. If you omit the version number, cdromFsLib opens the latest version of the file.

For the time being, cdromFsLib further accommodates MS-DOS users by allowing "\" (backslash) instead of "/" in pathnames. However, the use of the backslash is discouraged because it may not be supported in future versions of cdromFsLib.

Finally, cdromFsLib uses an 8-bit clean implementation of ISO 9660. Thus, cdromFsLib is compatible with CDs using either Latin or Asian characters in the file names.

IOCTL CODES SUPPORTED

FIOGETNAME
Returns the file name for a specific file descriptor.

FIOLABELGET
Retrieves the volume label. This code can be used to verify that a particular volume has been inserted into the drive.

FIOWHERE
Determines the current file position.

FIOWHERE64
Determines the current file position. This is the 64 bit version.

FIOSEEK
Changes the current file position.

FIOSEEK64
Changes the current file position. This is the 64 bit version.

FIONREAD
Tells you the number of bytes between the current location and the end of this file.

FIONREAD64
Tells you the number of bytes between the current location and the end of this file. This is the 64 bit version.

FIOREADDIR
Reads the next directory entry.

FIODISKCHANGE
Announces that a disk has been replaced (in case the block driver is not able to provide this indication).

FIOUNMOUNT
Announces that the a disk has been removed (all currently open file descriptors are invalidated).

FIOFSTATGET
Gets the file status information (directory entry data).

CDROMFS_DIR_MODE_SET
This is part of the Joliet extensions. It sets the directory mode to the ioctl( ) arg value. That controls whether a file is opened with or without the Joliet extensions. Settings MODE_ISO9660, MODE_JOLIET, and MODE_AUTO do not use Joliet, use Joliet, or try opening the directory first without Joliet and then with Joliet, respectively.

This ioctl( ) unmounts the file system. Thus any open file descriptors are marked obsolete.

CDROMFS_DIR_MODE_GET
This is part of the Joliet extensions. It gets and returns the directory mode set by CDROMFS_DIR_MODE_SET.

CDROMFS_STRIP_SEMICOLON
This sets the readdir( ) strip semicolon setting to FALSE if arg is 0, and TRUE otherwise. If TRUE, readdir( ) removes the semicolon and following version number from the directory entries returned.

CDROMFS_GET_VOL_DESC
This returns the primary or supplementary volume descriptor by which the volume is mouned in arg. arg must be type T_ISO_PVD_SVD_ID as defined in cdromFsLib.h. The result is the volume descriptor adjusted for the endianness of the processor, not the raw volume descriptor from the CD. The result is directly usable by the processor. The result also includes some information not in the volume descriptor, for example which volume descriptor is in-use.

MODIFYING A BSP TO USE CDROMFS IN VXWORKS AE

1. Add the component "INCLUDE_CDROMFS" to your kernel domain project. This will bring in the CDROMFS library modules and initialize them.

2. Continue with step 3 underneath "Modify the definition of sysScsiInit( ) to include the following:" in section MODIFYING A BSP TO USE CDROMFS IN VXWORKS.

MODIFYING A BSP TO USE CDROMFS IN VXWORKS

The following example describes mounting cdromFS on a SCSI device.

Edit your BSP's config.h to make the following changes:
1. Insert the following macro definition: 
    #define INCLUDE_CDROMFS
2. Change FALSE to TRUE in the section under the following comment: 
    /* change FALSE to TRUE for SCSI interface */
Make the following changes in sysScsi.c (or sysLib.c if your BSP has no sysScsi.c):
1. Add the following declaration to the top of the file: 
    #ifdef INCLUDE_CDROMFS
    #include "cdromFsLib.h"
    STATUS cdromFsInit (void);
    #endif
2. Modify the definition of sysScsiInit( ) to include the following: 
    #ifdef INCLUDE_CDROMFS
    cdromFsInit ();
    #endif
The call to cdromFsInit( ) initializes cdromFS. This call must be made only once and must complete successfully before you can call any other cdromFsLib routines, such as cdromFsDevCreate( ). Typically, you make the cdromFSInit( ) call at system startup. Because cdromFS is used with SCSI CD devices, it is natural to call cdromFSInit( ) from within sysScsiInit( ).

3. Modify the definition of sysScsiConfig( ) (if included in your BSP) to include the following: 
/* configure a SCSI CDROM at busId 6, LUN = 0 */

#ifdef INCLUDE_CDROMFS

if ((pSpd60 = scsiPhysDevCreate (pSysScsiCtrl, 6, 0, 0, NONE, 0, 0, 0)) ==
    (SCSI_PHYS_DEV *) NULL)
    {
    SCSI_DEBUG_MSG ("sysScsiConfig: scsiPhysDevCreate failed for CDROM.\n",
                    0, 0, 0, 0, 0, 0);
    return (ERROR);
    }
else if ((pSbdCd = scsiBlkDevCreate (pSpd60, 0, 0) ) == NULL)
    {
    SCSI_DEBUG_MSG ("sysScsiConfig: scsiBlkDevCreate failed for CDROM.\n",
                    0, 0, 0, 0, 0, 0);
    return (ERROR);
    }

/*
 * Create an instance of a CD device in the I/O system.
 * A block device must already have been created.  Internally,
 * cdromFsDevCreate() calls iosDrvInstall(), which enters the
 * appropriate driver routines in the I/O driver table.
 */

if ((cdVolDesc = cdromFsDevCreate ("cdrom:", (BLK_DEV *) pSbdCd )) == NULL)
    {
    return (ERROR);
    }

#endif /* end of #ifdef INCLUDE_CDROMFS */
4. Before the definition of sysScsiConfig( ), declare the following global variables used in the above code fragment: 
    SCSI_PHYS_DEV *pSpd60;
    BLK_DEV *pSbdCd;
    CDROM_VOL_DESC_ID cdVolDesc;
The main goal of the above code fragment is to call cdromFsDevCreate( ). As input, cdromFsDevCreate( ) expects a pointer to a block device. In the example above, the scsiPhysDevCreate( ) and scsiBlkDevCreate( ) calls set up a block device interface for a SCSI CD device.

After the successful completion of cdromFsDevCreate( ), the device called "cdrom" is accessible using the standard open( ), close( ), read( ), ioctl( ), readdir( ), and stat( ) calls.

INCLUDE FILES

cdromFsLib.h

CAVEATS

The cdromFsLib utility does not support CD sets containing multiple disks.

SEE ALSO

ioLib, ISO 9660 Specification, Joliet extension Specification

OS Libraries : Routines

cdromFsInit( )

NAME

cdromFsInit( ) - initialize cdromFsLib

SYNOPSIS

STATUS cdromFsInit (void)

DESCRIPTION

This routine initializes cdromFsLib. It must be called exactly once before calling any other routine in cdromFsLib.

RETURNS

OK or ERROR, if driver can not be installed.

ERRNO

S_iosLib_DRIVER_GLUT

SEE ALSO

cdromFsLib, cdromFsDevCreate( ), iosLib.h

OS Libraries : Routines

cdromFsVolConfigShow( )

NAME

cdromFsVolConfigShow( ) - show the volume configuration information

SYNOPSIS

VOID cdromFsVolConfigShow
    (
    void * arg                /* device name or CDROM_VOL_DESC * */
    )

DESCRIPTION

This routine retrieves the volume configuration for the named cdromFsLib device and prints it to standard output. The information displayed is retrieved from the BLK_DEV structure for the specified device.

RETURNS

N/A

SEE ALSO

cdromFsLib, cdromFsVersionDisplay( )

OS Libraries : Routines

cdromFsVersionDisplay( )

NAME

cdromFsVersionDisplay( ) - display the cdromFs version number

SYNOPSIS

void cdromFsVersionDisplay /* SPR#78687 */
    (
    int level                 /* level of display, not used */
    )

DESCRIPTION

This routine displays the cdromFs version number.

RETURNS

N/A

SEE ALSO

cdromFsLib, cdromFsVersionNumGet( ), cdromFsVolConfigShow( )

OS Libraries : Routines

cdromFsVersionNumGet( )

NAME

cdromFsVersionNumGet( ) - return the cdromFs version number

SYNOPSIS

uint32_t cdromFsVersionNumGet (void)

DESCRIPTION

This routine returns the cdromFs version number.

RETURNS

the cdromFs version number.

SEE ALSO

cdromFsLib, cdromFsVersionDisplay( )

OS Libraries : Routines

cdromFsDevCreate( )

NAME

cdromFsDevCreate( ) - create a cdromFsLib device

SYNOPSIS

CDROM_VOL_DESC_ID cdromFsDevCreate
    (
    char *    devName,        /* device name */
    BLK_DEV * pBlkDev         /* ptr to block device */
    )

DESCRIPTION

This routine creates an instance of a cdromFsLib device in the I/O system. As input, this function requires a pointer to a BLK_DEV structure for the CD drive on which you want to create a cdromFsLib device. Thus, you should already have called scsiBlkDevCreate( ) prior to calling cdfromFsDevCreate( ).

RETURNS

CDROM_VOL_DESC_ID, or NULL if error.

ERRNO

S_memLib_NOT_ENOUGH_MEMORY

SEE ALSO

cdromFsLib, cdromFsInit( )