VxWorks Reference Manual : Libraries

cdromFsLib

NAME

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

ROUTINES

cdromFsInit( ) - initialize cdromFsLib
cdromFsVolConfigShow( ) - show the volume configuration information
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 formatted according to the ISO 9660 standard file system.

It provides access to CD-ROM 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-ROM file system on the block device:

    cdVolDesc = cdromFsDevCreate ("cdrom:", (BLK_DEV *) pBlkDev);

Call cdromFsDevCreate( ) once for each CD-ROM drive attached to your target. After the successful completion of cdromFsDevCreate( ), the CD-ROM file system will be available like any DOS file system, and you can access data on the named CD-ROM 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.

FILE AND DIRECTORY NAMING

The strict ISO 9660 specification allows only uppercase file names consisting of 8 characters plus a 3 character suffix. 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.

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.

For the time being, cdromFsLib further accommodates MS-DOS users by allowing "stead 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 CD-ROMs 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.

FIOSEEK

Changes the current file position.

FIONREAD

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

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).

MODIFYING A BSP TO USE CDROMFS

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-ROM 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-ROM 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-ROM 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

cdromFsLib, ioLib, ISO 9660 Specification

---

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.

ERRNO

S_cdromFsLib_ALREADY_INIT

RETURNS

OK or ERROR, if cdromFsLib has already been initialized.

SEE ALSO

cdromFsLib, cdromFsDevCreate( ), iosLib.h

---

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

---

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-ROM 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.

SEE ALSO

cdromFsLib, cdromFsInit( )