CD-ROM File System

for VxWorks 5.5.1

Programmer’s Supplement
Copyright  2003 Wind River Systems, Inc.
ALL RIGHTS RESERVED. No part of this publication may be copied in any form, by
photocopy, microfilm, retrieval system, or by any other means now known or hereafter
invented without the prior written permission of Wind River Systems, Inc.
Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of
Wind River Systems, Inc. Any third-party trademarks referenced are the property of their
respective owners. For further information regarding Wind River trademarks, please see:
http://www.windriver.com/company/terms/trademark.html

Corporate Headquarters
Wind River Systems, Inc.
500 Wind River Way
Alameda, CA 94501-1153
U.S.A.

toll free (U.S.): (800) 545-WIND

telephone: (510) 748-4100
facsimile: (510) 749-2010

For additional contact information, please visit the Wind River URL:
http://www.windriver.com
For information on how to contact Customer Support, please visit the following URL:
http://www.windriver.com/support

CD-ROM File System for VxWorks 5.5.1 Programmer’s Supplement

21 Apr 03
Part #: DOC-15053-ND-00
 Contents

1 Introduction .............................................................................................................. 1

2 cdromFsLib ............................................................................................................... 1

3 Creating and Using a CD Block Device .................................................................. 3

4 Changing Disks ........................................................................................................ 7

Unmounting Volumes ....................................................................... 7
Announcing Disk Changes with the Ready-Change Mechanism 7

5 I/O Control Functions Supported by cdromFsLib ................................................. 8

6 Version Numbers ...................................................................................................... 9

iii
CD-ROM File System for VxWorks 5.5.1
Programmer’s Supplement

iv
 CD-ROM File System
for VxWorks 5.5.1 ®

Programmer’s Supplement

1. Introduction
VxWorks uses a standard I/O interface between the file system and the device
driver. This allows multiple file systems, of the same or different types, to operate
within a single VxWorks system. By following these standard interfaces, you can
write your own file system for VxWorks, and freely mix file systems and device
drivers.
This document discusses the VxWorks CD-ROM file system, cdromFs. cdromFs
allows applications to read data from CDs formatted according to the ISO 9660
standard file system with or without the Joliet extensions. This document describes
how cdromFs is organized, configured, and used.

2. cdromFsLib
The cdromFs library, cdromFsLib, lets applications read any CD-ROMs, CD-Rs, or
CD-RWs (collectively called CDs) that are formatted in accordance with the ISO
9660 file system standard, with or without the Joliet extensions. ISO 9660
interchange level 3, implementation level 2, is supported. Note that multi-extent
files, interleaved files, and files with extended attribute records are supported.

1
 CD-ROM File System for VxWorks 5.5.1
Programmer’s Supplement

The following CD features and ISO 9660 features are not supported:
■ Multi-volume sets
■ Record format files
■ CDs with a sector size that is not a power of two1
■ Multi-session CD-R or CD-RW2
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 file systems using any standard BLK_DEV
structure. The basic initialization sequence is similar to installing a dosFs file
system on a SCSI or ATA device, with a few significant differences: Create the CD
file system device directly on the BLK_DEV. CBIO drivers are not used. After you
have created the CD file system device, use ioctl( ) to set file system options. The
files system options are described below:
■ CDROMFS_DIR_MODE_SET/GET. These options set and get the directory
mode. The directory mode controls whether a file is opened with the Joliet
extensions, or without them. The directory mode can be set to any of the
following:
■ MODE_ISO9660. Do not use the Joliet extensions.
■ MODE_JOLIET. Use the Joliet extensions.
■ MODE_AUTO. Try opening the directory first without Joliet, and then with
Joliet.

1. Therefore, mode 2/form 2 sectors are not supported, as they have 2324 bytes of user data
per sector. Both mode 1/form 1 and mode 2/form 1 sectors are supported, as they have 2048
bytes of user data per sector.
2. The first session (that is, the earliest session) is always read. The most commonly desired
behavior is to read the last session (that is, the latest session).

2
 3
Creating and Using a CD Block Device

! WARNING: Changing the directory mode unmounts the file system. Therefore,
any open file descriptors are marked as obsolete.

■
CDROMFS_STRIP_SEMICOLON. This option sets the readdir( ) strip semicolon
setting to FALSE if arg is 0, and to TRUE otherwise. If TRUE, readdir( ) removes
the semicolon and following version number from the directory entries
retrieved.
■ CDROMFS_GET_VOL_DESC. This option returns, in arg, the primary or
supplementary volume descriptor by which the volume is mounted. arg must
be of 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). This result can be used directly by the
processor. The result also includes some information not in the volume
descriptor, such as which volume descriptor is in use.
For information on using cdromFs( ), see the VxWorks API Reference entry for
cdromFsLib.

3. Creating and Using a CD Block Device

This section describes the steps for creating a block device for the CD-ROM,
creating a cdromFsLib device, mounting the file system, and accessing the media
in the device.

Step 1: Configure Your Environment for the CD-ROM Device

Add the component INCLUDE_CDROMFS in your project. Add other required
components (like SCSI/ATA depending on the type of device). For more
information, see the VxWorks Programmer’s Guide: Local File Systems.
If you are using an ATAPI device, make appropriate modifications to the ataDrv,
ataResources[ ] structure array (if needed). This must be configured appropriately
for your hardware platform.

3
 CD-ROM File System for VxWorks 5.5.1
Programmer’s Supplement

Step 2: Create a Block Device

Based on the type of device, use the appropriate create routine and create a block
device. Following is an example for an ATAPI master device upon the secondary
ATA controller:
-> pBlkd = ataDevCreate(1, 0, 0, 0)
new symbol "pBlkd" added to symbol table.
pBlkd = 0x3fff334: value = 67105604 = 0x3fff344 = pBlkd + 0x10

Step 3: Create an Instance of a CD-ROM Device in the I/O System

A block device must already have been created. Call cdromFsDevCreate( ), which
calls iosDrvInstall( ) internally. This enters the appropriate driver routines in the
I/O driver table.
-> cdromFsDevCreate("/cd", pBlkd)
value = 67105456 = 0x3fff2b0

-> devs
drv name
0 /null
1 /tyCo/0
1 /tyCo/1
5 ala-petrient:
6 /vio
7 /cd
value = 25 = 0x19

-> cd "/cd"
value = 0 = 0x0

The cd command changes the current working directory, without performing I/O,
and, therefore, can be called before the media is mounted.

Step 4: Open the Root Directory

This step is optional. It is only required if you plan to execute Step 8 or Step 9.
-> fd = open ("/cd", 0, 0)

In the command-line sequence above, the first 0 is the value of O_RDONLY in

fcntl.h.

Step 5: Set readdir( ) To Omit Version Numbers from Its Output

This step is optional.
The strip semicolon mode controls whether readdir( ) returns version numbers.
After mounting, the strip semicolon mode defaults to FALSE, meaning that version

4
 3
Creating and Using a CD Block Device

numbers will be returned. If you do not want version numbers, enter the
following:
-> ioctl (fd, 0x740002, 1)

In the command-line sequence above, 0x740002 is the value of

CDROMFS_STRIP_SEMICOLON in cdromFsLib.h.

Step 6: Set Which Volume Descriptor To Use

This step is optional.
The directory mode controls which volume descriptor is used to open a file or
directory. After mounting, the directory mode defaults to MODE_AUTO, meaning
that all volume descriptors will be tried. The directory mode can be changed to
MODE_ISO9660 to use only the ISO 9660 volume descriptors, or to MODE_JOLIET
to use only the Joliet volume descriptors. If either of these modes is selected, and
if the CD does not contain the selected volume descriptor, an
S_cdromFsLib_UNKNOWN_FILE_SYSTEM error is recorded.

-> ioctl (fd, 0x740000, 0)

In the command-line sequence above, 0x740000 is the value of

CDROMFS_DIR_MODE_SET, and 0 is the value of MODE_ISO9660. Both are located
in cdromFsLib.h.

Step 7: Close the Root Directory

This step is optional. It is only required if you plan to execute Step 8 or Step 9.
-> close (fd)

Step 8: Mount the Device

Now, run cdromFsVolConfigShow( ) to indicate whether the device (created
above) is mounted. Executing this command shows that the device is not mounted.
-> cdromFsVolConfigShow "/cd"

device name /cd

bytes per blkDevDrv sector 2048
no volume mounted
value = 18 = 0x12

Mount the device in order to access it. Because cdromFs is mounted during the first
open( ) operation, a call to open( ) or any function that uses open( ) will mount the
device. The ls command below both mounts the device and lists its contents.

5
 CD-ROM File System for VxWorks 5.5.1
Programmer’s Supplement

-> ls "/cd"
/cd/.
/cd/..
/cd/INDEX.HTML;1
/cd/INSTRUCT.HTML;1
/cd/MPF
/cd/README.TXT;1
value = 0 = 0x0

Step 9: Check the Configuration

You can check the CD-ROM configuration using cdromFsVolConfigShow( ):
-> cdromFsVolConfigShow "/cd"

device config structure ptr 0x3fff2b0

device name /cd
bytes per blkDevDrv sector 2048

Primary directory hierarchy:

volume descriptor number :1

descriptor logical sector :16
descriptor offset in sector :0
standard ID :CD001
volume descriptor version :1
UCS unicode level (0=ISO9660) :0
system ID :LINUX
volume ID :MPF_CD
volume size :611622912 = 583 MB
number of logical blocks :298644 = 0x48e94
volume set size :1
volume sequence number :1
logical block size :2048
path table size (bytes) :3476
path table size on CD (bytes) :3476
path table entries :238
volume set ID :

volume publisher ID :WorldWide Technologies

volume data preparer ID :Kelly Corday

volume application ID :mkisofs v1.04

copyright file name :mkisofs v1.04

abstract file name :mkisofs v1.04
bibliographic file name :mkisofs v1.04
creation date :13.11.1998 14:36:49:00
modification date :13.11.1998 14:36:49:00
expiration date :00.00.0000 00:00:00:00
effective date :13.11.1998 14:36:49:00
value = 0 = 0x0

6
 4
Changing Disks

4. Changing Disks
The cdromFs file system must be notified when removable disks are changed (for
example, when CDs are swapped). Two different notification methods are
provided:
■ ioctl( ) FIOUNMOUNT
■ the ready-change mechanism

Unmounting Volumes

The first method of announcing a disk change is to call the ioctl( ) function
FIOUNMOUNT. This call marks any open file descriptors as obsolete. The next I/O
operation remounts the disk. 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_cdromFsLib_VOL_UNMOUNTED error. To free an obsolete descriptor, use close( )
as usual. This call frees the descriptor, although it produces the same error.
ISRs should not call ioctl( ) FIOUNMOUNT directly because the call can pend while
the device becomes available. The ISR can instead give a semaphore that prompts
a task to unmount the volume. Note that ioctl( ) FIODISKCHANGE can be called
directly from an ISR; see Announcing Disk Changes with the Ready-Change
Mechanism, p.7.

Announcing Disk Changes with the Ready-Change Mechanism

The second method of announcing that a disk change is taking place is with the
ready-change mechanism. cdromFsLib interprets a change in the disk’s ready
status to indicate that the disk must be remounted during the next I/O call.
There are two ways to announce a ready-change action:
■ 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 cdromFsLib directly.
The ready-change announcement does not unmount the disk; therefore, it does not
mark file descriptors as obsolete. It merely marks the volume as needing to be
remounted.

7
 CD-ROM File System for VxWorks 5.5.1
Programmer’s Supplement

A ready-change can be called from an ISR, as it does not perform actions that could
cause delay.
The block device driver status-checking 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( ) call, before the file system checks for a
ready-change.
If it is not possible to announce a ready-change each time the disk is changed, close
all file descriptors for the volume before changing the disk.

5. I/O Control Functions Supported by cdromFsLib

The cdromFs file system supports the ioctl( ) functions. These functions, and their
associated constants, are defined in the header files ioLib.h and cdromFsLib.h.
Table 1 describes the ioctl( ) functions that cdromFsLib supports. For more
information, see the reference entries for cdromFsLib and for ioctl( ) in ioLib.

Table 1 ioctl( ) Functions Supported by cdromFsLib

Function Constant Decimal Description

CDROMFS_DIR_MODE_GET 7602176 Gets the volume descriptor(s) used to open files.

CDROMFS_DIR_MODE_SET 7602177 Sets the volume descriptor(s) used to open files.

CDROMFS_GET_VOL_DESC 7602179 Gets the volume descriptor that is currently in use.

CDROMFS_STRIP_SEMICOLON 7602178 Sets the readdir( ) strip version number setting.

FIODISKCHANGE 13 Announces a media change.

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

FIOGETNAME 18 Gets the filename of the file descriptor.

FIOLABELGET 33 Gets the volume label.

FIONREAD 1 Gets the number of unread bytes in a file.

FIONREAD64 6401 Gets the number of unread bytes in a file (64-bit version).

8
 6
Version Numbers

Table 1 ioctl( ) Functions Supported by cdromFsLib

Function Constant Decimal Description

FIOREADDIR 37 Reads the next directory entry.

FIOSEEK 7 Sets the current byte offset in a file.

FIOSEEK64 6407 Sets the current byte offset in a file (64-bit version).

FIOUNMOUNT 39 Unmounts a disk volume.

FIOWHERE 8 Returns the current byte position in a file.

FIOWHERE64 6408 Returns the current byte position in a file (64-bit version).

6. Version Numbers
cdromFsLib has a 4-byte version number. The version number is composed of four
parts, from most significant byte to least significant byte:
■ major number
■ minor number
■ patch level
■ build
The version number is returned by cdromFsVersionNumGet( ) and displayed by
cdromFsVersionNumDisplay( ).3

3. This function name uses Display rather Show in order not to clutter the output of lkup
"Show". Other VxWorks modules will include similar version number support in the future.