****************************************************************************
******************* THE CD-ROM FILING SYSTEM USER GUIDE ********************
****************************************************************************

Copyright © 1990, 1991 Next Technology Corporation Limited. All rights reserved.
Copyright © 1993 Acorn Computers Limited. All rights reserved.
Issue 3, October 1993

                      
                      The CD-ROM Filing System User Guide
                      ===================================


The product described in this manual is subject to continuous development 
and improvement. All information of a technical nature and particulars of 
the product and its use (including the information and particulars in this 
manual) are given by Acorn Computers Limited in good faith. However, 
Acorn Computers Limited cannot accept any liability for any loss or damage 
arising from the use of any information or particulars in this manual.
ACORN, the ACORN logo and ARCHIMEDES are trademarks of Acorn 
Computers Limited.
All other trademarks are acknowledged.
Copyright © 1990, 1991 Next Technology Corporation Limited. All rights 
reserved. Copyright © 1993 Acorn Computers Limited. All rights reserved.
Published by Acorn Computers Limited



Configuring the computer
________________________

The CD-ROM Filing System (CDFS) enables you to access data on a 
CD-ROM from the RISC OS desktop. It is usually resident in a ROM 
on your SCSI expansion card, and is loaded automatically when you 
power on your computer. The CDFS icon bar menu enables you to 
configure your computer to suit the CD-ROM system attached to it.

This section tells you how to configure your computer so that you 
can use CD-ROMs; you only need to do so when adding or removing 
drives.

For details of how to use CDFS once you have configured it, see 
Using CD-ROM discs on page 7.

Configuring your RISC OS computer from the desktop

To ensure the fastest boot up time, the following procedure should 
be followed:

1 Ensure all the peripherals and cables are connected.

2 Switch on the monitor, then the CD-ROM drive. The CD-ROM 
drive should always be switched on before the computer.

3 Switch on the computer. CDFS will look to see if a CD-ROM 
drive is connected.

4 The CDFS CD-ROM icon will be displayed on the Icon Bar.

Click on this icon to determine which type of CD-ROM is 
currently held in the drive drawer - CD-ROM, Photo CD or 
Audio CD.

5 To configure the number of CD-ROM drives you have attached 
to your computer, click Menu on the CD-ROM icon. The CDFS 
icon bar menu will be displayed:

6 Choose Configure, Drives then enter the number of drives 
connected. If only one drive is connected, this step may be left 
out, but the boot-up time will be slower:

7 To configure the CD-ROM buffers, click Menu on the CD-ROM 
icon. Choose Configure, Buffers then click on the required 
buffer size - 16K is normally sufficient, unless you are swapping 
discs a lot, in which case 32K or 64K would be better:

8 Reset the computer to implement the new configuration.

Setting up PC Soft to read CD-ROM discs

Many CD-ROM titles are written in PC format, so to get the best out 
of these, PC Soft should be used in the computer. (PC Soft used to 
be known as the Acorn PC Emulator.) The copy of PC Soft you use 
must be version 1.6 or later.

If you are using MS-DOS, you must have version 3.3 or higher, with 
CD-ROM extensions.

If you are using DR-DOS, you must have a version with CD-ROM 
extensions. At the time of going to press, such versions were not yet 
available - but this is likely to change. You should see your supplier 
for details of DR-DOS compatibility, availability, and installation.

Loading PC Soft

Load PC Soft as instructed in the PC Soft Guide accompanying it. 

Set the configuration of the emulated PC, using the Configure 
option from the PC icon bar menu. Choose EGA and ECD for titles 
using this screen mode, with 128K of memory for computers with 
2MB of RAM, and 256K for those with more RAM. Choose VGA for 
titles using this screen mode. (Versions 1.6 and 1.7 do not support 
VGA, but you can choose EGA+ for a partial emulation of VGA 
mode.)

By default, the CD-ROM drive will be configured as drive F. 
Additional drives will be named G, H and so on. However, if you 
have four hard disc drives configured (drives C-F) then the CD-ROM 
drive will install itself as drive G, and additional drives follow on 
from there.

Now run PC Soft. Switch to Single task mode (from the icon bar 
menu) to be able to display a full screen, and for faster response.

Loading the MS-DOS CD-ROM support software

PC Soft (version 1.6 or later) when sold with MS-DOS is 
accompanied by a CD-ROM Support disc. The software on this disc 
enables you to access the CD-ROM drive while you are running 
DOS. 

The software has its own installation program, to make it easy for 
you to install it on your computer. This program alters your DOS 
AUTOEXEC.BAT and CONFIG.SYS files and copies Microsoft 
MS-DOS CD-ROM extensions and the CD-ROM device driver.

If you usually boot DOS from a floppy disc, you first need to format 
a new system floppy disc on which to install the software. To do this, 
put a floppy disc in the drive and type:

FORMAT A: /S

When the format completes, remove this disc from the drive.

To install the software, put the disc labelled CD-ROM Support disc 
into the drive. Type:

A:
INSTALL

This starts the installation program. Follow the instructions given 
on the screen.

When prompted for a drive letter on which to install this software:

* If you boot DOS from a floppy disc, type A. When the 
installation program prompts for your boot disc, insert the 
newly-formatted system disc, and press Space. When you are 
prompted to insert the disc containing MSCDEX.EXE, put the 
CD-ROM Support disc back in the drive.

* If you boot DOS from a hard disc, type the hard disc drive letter 
(typically C).

When the installation program has finished, reboot DOS from your 
hard disc, if you have one, or else put your newly-created system 
disc back in the drive and hold down Ctrl and Alt and press Delete 
to do this. 

During the reboot cycle a message should be displayed on the 
screen similar to the following:

MSCDEX Version 2.20
Copyright ) Microsoft Corp. 1986
Drive F: = Driver CDFSEM unit 0

This indicates that the driver is loaded and the CD-ROM drive has 
been allocated the letter F: for access purposes from DOS.

Your computer will now behave like a PC with a CD-ROM drive 
attached. There is a summary of common PC commands in the 
PC Soft Guide.

Recommended changes to configuration files

We recommend that you check that the following statements exist 
in the CONFIG.SYS and AUTOEXEC.BAT files and amend or add 
them as necessary as some DOS formatted CD-ROM discs require 
these settings before they can be used.

In the CONFIG.SYS file we recommend you add these lines:

FILES=20
BUFFERS=20

In the AUTOEXEC.BAT file your PATH should include the 
pathnames below, in the order given:

PATH=C:\;C:\DOS;F:\    (Hard drive users.)
PATH=A:\;A:\DOS;F:\    (Floppy drive users.)

Of course, your PATH may also include other pathnames you have 
previously added.


Using CD-ROM discs
__________________

You can use CD-ROM drives either with CD-ROM discs formatted for 
use with RISC OS, or with CD-ROM discs produced to run under 
MS-DOS. For the latter, you will need a copy of PC Soft to get full 
benefit.

Using CDFS

CDFS appears to the user very much like ADFS - all the usual 
RISC OS Filer commands are available, although you cannot of 
course save to a CD-ROM. If a write command is made to the 
CD-ROM drive, an error message will be displayed. 

To open a directory display on a CD-ROM which has been inserted 
in the drive, click on the CD-ROM drive icon on the icon bar. The 
contents of the CD-ROM will be displayed by the RISC OS Filer:

RISC OS directory displays can be opened for PC CD-ROMs. PC file 
names are translated to a format compatible with the RISC OS 
environment. You can view text files using Edit in the same way as 
usual, and use ChangeFSI (see page 15) to convert a wide range of 
graphics images to RISC OS sprites, which you can then view using 
Paint. However, to run the programs included on such discs, you will 
need to use PC Soft (see Reading PC-format CD-ROM discs using PC Soft 
below).

If you are not using CDFS

CDFS claims some memory each time you power on your computer. 
If you are not using CDFS and need this extra memory, you can 
disable CDFS by typing

*Unplug CDFS
*Unplug CDFSDriver
*Unplug CDFSFiler

and then resetting your computer. When you need CDFS again, you 
can reinstall the three modules by using *RMReInit for each one 
in a similar way, and then rebooting.

Reading PC-format CD-ROM discs using PC Soft

Place a CD-ROM disc in the drive, and type 

F:

(or whatever drive letter your CD-ROM drive is configured as).

You can now access PC-format discs in the normal way. 

Consult the guide that comes with each title for information on 
playing CD-ROM discs.

Do not try to access a CD-ROM through RISC OS (including via 
CDPlayer) and through PC Soft at the same time.

Performance limitations

VGA images

Version 1.6 and 1.7 of the Acorn PC Emulator (the old name for 
PC Soft) do not fully support the VGA Bios. EGA+ is a partial 
implementation of VGA, but some VGA images on PC format 
CD-ROM discs cannot be displayed fully. The title screens of some 
discs are designed to be displayed in VGA mode, so such discs may 
not start off very well. This does not, however, necessarily mean that 
the rest of the disc cannot be read correctly. Often the application 
will continue of its own accord, or require Space or Return to be 
pressed. In some cases the lack of VGA support will prevent the disc 
from running under the emulator at all.

Version 1.8 of PC Soft does support VGA.

Sound

Titles which attempt to play sound through the computer's own 
sound system can cause program errors, unless you first configure 
sound in the program to be off. Most titles are able to play 
CD-quality sound through a CD-ROM drive, so this problem does 
not often arise.

Titles which attempt to mute one audio channel (left or right), 
whilst playing the other channel, can cause program errors.

Windows 

Certain CD-ROM applications contain their own version of 
Windows on the CD-ROM itself. These versions have often been 
modified in some way, and do not always work correctly. We 
recommend that you do not use a version of Windows supplied on 
CD-ROM, but an appropriate Windows application available 
separately from a PC dealer. 

Note that Windows 3.1 will not run under PC Soft.


CDPlayer
________

The CDPlayer application allows you to play and control audio CDs 
using your computer and a CD-ROM drive. CDPlayer simulates all 
the functions of a CD audio player with all the normal functions 
such as play, stop, track search, cue and review. It also has a very 
comprehensive programming facility. All the functions, including 
drive select, are controlled using the mouse. 

CDPlayer is supplied on floppy disc. It is already set up to use a 
CD-ROM drive that has a SCSI ID of 6, and that is connected to the 
first SCSI expansion card fitted to your computer. If you wish to use 
a drive with a different SCSI ID, or if you have fitted multiple SCSI 
expansion cards to your computer, you should first read The Setup 
window on page 14.

To start the application, double-click on the CDPlayer icon; this 
loads the program and displays its icon on the icon bar. Click on its 
icon to display the main CD Player window, used to control the CD:

The main CD Player window

The basic set of controls work in the same way as those of a 
conventional audio CD player.

Play starts the audio CD playing.

Pause stops the CD playing, but holds it in its current position.

Stop stops the CD playing, and returns to the start of the CD.

Eject stops the CD and ejects it from the CD player.

Skip backwards and Skip forwards move to the previous or next 
tracks respectively.

Rewind and Fast forward move backwards or forwards through the 
audio track, speeding up as you hold down the button.

Moving the Slider takes you quickly to any point on the CD.

Track number shows the number of the track currently playing, or 
(as above) 00 if nothing is playing.

Playing time gives you three choices of display. It normally shows 
the time the disc has been playing. Clicking on this number changes 
the display to show the time the individual track has been playing; 
clicking again shows the time left on the disc; clicking again returns 
to the original display.

Total tracks/time gives the total number of tracks on the CD, and 
its total playing time.

Display keypad displays the keypad, the use of which is described 
in the next section.

The Keypad window

Clicking on the triangle icon or choosing Keypad from the 
CD Player menu will open the Keypad window. You can use this 
window to select which tracks on the CD you wish to hear and in 
which order you wish to hear them:

To program the player to play a selection of tracks

1 Click on the first track number you wish to hear, and then on 
MEM. The Memory window automatically appears, showing the 
tracks in the program memory:

2 Repeat this for any other tracks you wish to add to the program 
memory.

3 Play the tracks by clicking on Play.

Other program play functions

ALL adds a list of all the audio tracks available on the CD to the 
program memory.

RND clears the program memory, and creates a randomly ordered 
list of all the audio tracks to the program memory. 

RPT continuously repeats the tracks in the program memory until 
you click on the Stop key in the CD Player window. If no program has 
been set, the CD instead repeats continuously from start to finish.

CLR is used to clear the program memory. To clear all tracks from 
the program memory, click Adjust on the CLR button. To clear 
individual tracks, highlight the desired tracks and then click Select 
on the CLR button.

Notes on playing programs

When CDPlayer is set to play a program, the following restrictions 
apply:

* The slider and slider bar cannot be dragged or clicked on.

* The time display will only show the time the disc has been 
playing.

* The main CD Player window must be open to allow the 
programmed tracks to be played.

When playing a mixed mode CD (mixed audio and data tracks), 
using the ALL button guarantees that all the audio tracks will be 
played, otherwise the drive will normally stop when it encounters a 
data track, even if there are subsequent audio tracks.

The Setup window

Each CDPlayer can be used to control a single CD-ROM drive at one 
time, which is selected using the Setup window. CDPlayer is 
supplied already set up to use a CD-ROM drive that has a SCSI ID 
of 6, and that is connected to the first SCSI expansion card fitted to 
your computer. You'll only need to change the Setup if you wish to 
use a drive with a different SCSI ID, or if you have fitted multiple 
SCSI expansion cards to your computer.

To open the Setup window, choose Setup from CDPlayer's icon bar 
menu:

Click on the + and - icons until the correct device, unit and card 
numbers are shown for the CD-ROM drive you wish to use. If you're 
not sure what the numbers should be for a particular drive, you can 
find them out by typing at the command line:

CDFS:CDDevices    (see page 22).

It is not advisable to keep switching CDPlayer from one drive to 
another using the Setup window. This operation should only be 
performed when CDPlayer is first started. If you need to control 
more than one drive, you should start the CDPlayer application as 
many times as you require and change each copy's setup 
individually before use.

Quitting CDPlayer

To quit the CDPlayer application, choose Quit from its icon bar 
menu.


ChangeFSI
_________

ChangeFSI is a useful program for converting and displaying image 
files of various formats. These images can then be converted into 
sprites for viewing with RISC OS applications such as Paint.

In case you're wondering, ChangeFSI stands for `Change Floyd 
Steinberg Integer' (ChangeFSI performs Floyd Steinberg error 
diffusion dithering). 

You should make sure that your conversion and subsequent use of 
an image does not infringe on any copyright that the image may be 
under.

ChangeFSI provides the ability to read, scale the data to improve 
the picture, change the x and/or y size, sharpen the picture and write 
the result using error diffusion dithering in one step (so it provides 
the best possible quality). All operations are carried out with 32-bit 
fixed point numbers (three per pixel in the case of a colour picture).

Using ChangeFSI

ChangeFSI is supplied on floppy disc. Before using the application, 
you should copy it either to another floppy disc, or to your 
computer's hard disc - if one is fitted.

Double click on the application to start ChangeFSI. Its icon will be 
loaded onto the icon bar. Display the file icon for the image you 
wish to process, and drag the icon onto the ChangeFSI application 
on the icon bar. ChangeFSI will attempt to interpret the file to give a 
RISC OS sprite, displaying the result. You can then save the 
resultant image as a sprite file.

Picture formats

ChangeFSI will convert many types of images. These include the PC 
graphics formats TIFF, PCX, PIC and IMG, the Amiga format IFF, the 
Compuserv GIF format and the JPEG JFIF file interchange format.

For a full list of image formats explained in greater detail, you 
should read the file FSIInfo provided inside the application (shift 
double-click on !ChangeFSI to display the files).

ChangeFSI in more detail

This section describes the ChangeFSI menu trees in detail. Most 
users won't need to use these options as ChangeFSI is already set 
up to give good results with most types of image files.

If you want to know how ChangeFSI and its options are used in 
greater detail you should read the information file, FSIInfo, provided 
inside the application (shift double-click on !ChangeFSI to display 
the files).

Menu options

Once you have loaded ChangeFSI onto the icon bar, click Menu over 
the icon to display the main options menu.

Scaling options

The Scaling options allow you to choose which scale you wish for 
your image. You can also transform, rotate or mirror the image.

The option Scale 1:1 1:1 will give you a full sized image.

Choosing Custom allows you to specify your own scaling options. If 
you wish the image to `scale to exact pixel size', fill in the left boxes 
only and leave the right boxes blank. The Scale to fill option allows 
you to scale the image so that it covers the entire screen area; this 
may distort the aspect ratio of the image.

The Ignore Source Pixel Size box allows you to ignore any source 
information about the pixel size. This can be useful if you have 
images that use a non-standard pixel size.

The Rotate and Mirror options perform rotations and mirror 
operations on the source image.

Processing options

The Processing options allow you to control the image processing 
used in the conversion and display of the image.

You'll notice that all of these options are `off' by default; you will not 
normally need to change these settings.

Expand Dynamic Range will expand the range of colours in the 
image. This normally brightens the image. It expands the dynamic 
range of a picture to full scale.

Histogram Equalisation will most often result in a worse picture 
but it can be used to recover detail from an otherwise useless 
image. Alternatively you can use it to look at information locked in a 
small part of the input scale.

Disable Dithering will disable Floyd-Steinberg dithering. This will 
usually result in an inferior image.

Invert Input will result in your colour images having their colours 
inverted. Black and white image are also inverted.

Brighten Picture will produce a picture that is slightly brighter than 
it should be. Useful if you have dark pictures.

Black Correction is useful if you want to print the image on a laser 
printer. You should use a number between zero and 128, though 
values between 32 and 64 usually give the best result; experiment. 
Images treated in this way will give a poor result when viewed on 
screen. Only works for 1 bpp (black and white) output.

Gamma Correction is used to correct the image quality as 
displayed on your monitor. Low values of gamma (0 to 1) make 
colours darker and high values (above 1) make them lighter. Gamma 
correction is most often used to correct images that have been 
scanned in with a scanner. Different monitors may need different 
Gamma Corrections. A standard value is 2.2 (TV industry standard).

Pre-sharpening is used to sharpen the edges of objects. This is 
useful if the dithering process has made the image blurred. A value 
of 24 will counteract the general dither blurring. A value of 20 is 
noticeably sharp. Values down to nine can be selected.

Output options

The Output options control the screen mode the picture is created 
for.

The 1, 2, 4, 8 buttons represent the screen colours that you can use. 
The numbers represent bits per pixel. 8 bits represent 256 colours, 4 
bits represent 16 colours, 2 bits represent 4 colours and 1 bit 
represents 2 colours. The square box represents the square pixel 
modes and the oblong box represents the non-square modes. The 
actual output mode chosen is displayed in the mode box.

Use current mode outputs the image for display in the current 
mode.

Ignore pixel aspect disables all pixel size information and assumes 
both source and output pixels are square.

Monochrome and Colour give an image in black and white or 
colour.

Special allows the use of special file suffixes. These are explained 
fully in the on-line documentation file FSIInfo.

Reprocess

This option reads the file in again and processes it according to any 
new options you have set.

Fast 

This option speeds up the processing of the image by blanking the 
screen during processing.

Save Choices

This option will save any changes you have made to the ChangeFSI 
options so that you can use the options again next time you run 
ChangeFSI.

Quit

This quits the application, removing it from the icon bar.

Image menu

Once your image has been produced you can click Menu over the 
image to display a menu of information about the input and output 
image.

Sprite Info gives the information about the Sprite output file.

Source Info gives the information about the source file.

Range Info gives you information about the dynamic range of the 
image.

Zoom allows you to change the magnification of the image. This is 
not the same as scaling the source image.

Save Sprite allows you to save the image as a Sprite file.

Reprocess allows you to process the image again using any options 
you have changed on the main menu.


Using the command line
______________________

CDFS * Commands

CDFS supports all standard RISC OS filing system * Commands that 
do not try to write to disc; for details of these, see your RISC OS 3 
User Guide. CDFS also provides some new commands of its own, 
detailed below. Many of these commands require an optional drive 
parameter; if you omit this, CDFS defaults to using its current drive 
(initially drive 0).

*CDDevices

*CDDevices displays all the CD devices connected, their product 
name, capacity, SCSI ID (displayed as device, LUN, and card) and 
firmware revision.

*CDDevices

*CDFS

*CDFS selects the CD-ROM filing system as the current filing 
system.

*CDFS

*CDSpeed

*CDSpeed displays or sets the read speed of the given CD-ROM 
drive.

*CDSpeed [drive] [speed]

*Configure CDROMBuffers

*Configure CDROMBuffers sets the configured amount of memory 
reserved for CD-ROM buffering (maximum 512K).

*Configure CDROMBuffers sizeK

*Configure CDROMDrives

*Configure CDROMDrives sets the configured number of CD-ROM 
drives recognised at power on.

*Configure CDROMDrives n

*Eject

*Eject ejects the disc from the given CD-ROM drive.

*Eject [drive]

*Lock

*Lock locks the disc in the given CD-ROM drive, disabling the Eject 
button.

*Lock [drive]

*Play

*Play plays from the specified audio track to the end of the disc in 
the given CD_ROM drive.

*Play track [drive]

*PlayList

*PlayList lists the tracks - whether audio or data - on the disc in the 
given CD-ROM drive, together with their start time and the total CD 
time.

*PlayList [drive]

*PlayMSF

*PlayMSF plays a piece of audio from the disc in the given CD-ROM 
drive. The start and stop times are specified in minutes, seconds 
and frames from the start of the disc.

*PlayMSF mins:secs:frames mins:secs:frames [drive]

*Stop

*Stop stops playing the disc in the given CD-ROM drive.

*Stop [drive]

*Supported

*Supported lists the drive types recognised by CDFS.

*Supported

*Unlock

*Unlock re-enables the Eject button on the given CD-ROM drive, 
reversing the effect of any earlier *Lock command.

*Unlock [drive]

*WhichDisc

*WhichDisc displays the unique ID number for the current CD-ROM 
drive.

*WhichDisc

Configuring CD-ROM drives from the command line

To configure the number of CD-ROM drives, type:

*Configure CDROMDrives n

where n is the number of drives (from 0 to 28). You can set n to 0, 
which obviously sets the configuration to 0 CD-ROM drives.

You may want to configure the size of the CD-ROM buffers, 
especially if you expect to be using a variety of CDs. Type:

*Configure CDROMBuffers sizeK

where size represents the size of the buffers in KB, a number in the 
range 0-512.

The configuration chosen will be stored in the CMOS RAM; reset the 
computer to implement it. The computer should boot up into the 
desktop. A `CD-ROM' icon should appear in the icon bar, the 
number of icons representing the number of CD-ROM drives 
attached.

Important: Incorrectly setting the number of drives causes the boot 
up procedure to take longer.

Altering the default configuration of your system under 
PC Soft

The device driver

The DOS device driver CDFS_DRV.SYS is configured by entering a 
statement such as this in CONFIG.SYS:

DEVICE = C:\DRIVERS\CDFS_DRV.SYS /D:MSCD001 /N:1

Parameter switches are:

Parameter

Use

/N:

This restricts the number of drives that can be 
used from PC Soft, for example, if you have 4 
CD-ROM drives and you use the switch /N:2, 
then only the first two drives will be usable 
from PC Soft. If this switch is not specified 
then all of the drives will be accessible.

/D:

This switch allows the device driver name to 
be changed. You are advised not to change 
this switch as it must then also be changed 
for MSCDEX.EXE.

MS-DOS CD-ROM Extensions

The file containing the MS-DOS CD-ROM extensions is called 
MSCDEX.EXE. This is configured by entering a statement such as 
this in AUTOEXEC.BAT:

C:\DRIVERS\MSCDEX /D:MSCD001 /L:F

Parameter switches are:

Parameter

Use

/D:

Specifies the CD-ROM device driver name - 
for example MSCD001 - which must match 
that used in CONFIG.SYS.

/L:

Specifies the drive letter of the first CD-ROM 
drive

/M:

Specifies the number of cache buffers for 
MSCDEX.EXE (8 - 15), the default being 8.

/V:

Displays verbose message during boot-up, 
detailing memory usage and diagnostic 
information.

/S:

Instructs MSCDEX.EXE to patch DOS to allow 
CD-ROM drive sharing on an MS-NET based 
network server.

This parameter is not used by PC Soft.

/E:

Instructs MSCDEX.EXE to use extended 
memory if available.


Interfacing CDs and RISC OS
___________________________

Introduction

CDFS is made up from three modules: the CDFS module itself, the 
CDFSDriver module, and the CDFSFiler module. In general, the 
SWIs provided by these modules are reserved for internal use, and 
you must not use them in your own code, otherwise unpredictable 
results may occur. You should access files stored on CD-ROMs 
using the same * Commands and SWI calls with which you would 
access any other filing system; see the FileSwitch chapter of the 
RISC OS 3 Programmer's Reference Manual.

However, RISC OS itself does not provide any facilities for you to 
use the audio facilities of a CD-ROM drive; these facilities are 
instead provided by the CDFS and CDFSDriver SWIs detailed below. 
You should only use these SWIs for accessing audio, and you must 
not use any other CDFS or CDFSDriver SWIs.

The SWI calls

All SWIs conform to the RISC OS standard insofar as:

* Any registers not explicitly defined as result parameters are 
preserved.

* The processor flags N, Z and C are preserved.

* Errors are indicated by setting V and returning with R0 pointing 
at an error block. (If the bit 17 clear version is called, control 
passes to the error handler instead.)

* The SWI cannot be called from the background unless this is 
specifically documented.

* All SWIs may be called from interrupt and event routines.

but:

* No CDFSDriver SWIs preserve the interrupt state.

* No CDFSDriver SWIs are re-entrant.

CDFS SWI calls

CDFS_ConvertDriveToDevice (SWI &41E80)

Converts a logical drive number to a physical drive number.

On entry

R0 = logical drive number

On exit

R0 preserved
R1 = physical drive number

Use

This call converts a logical drive number to a physical drive number. 
You can then use the physical drive number to produce a CDFS 
control block, which you have to pass when calling CDFSDriver 
SWIs. For details of how to construct the block, see below.

This call returns an error if the logical drive is not known.

CDFSDriver SWI calls

CDFS control blocks

Before you can access a CD-ROM drive using any of the CDFSDriver 
SWIs, you need to set up a CDFS control block, as described below. 
When you call any of the SWIs, you pass a pointer to the block in R7.

A CDFS control block describes a physical device to the 
CDFS_Driver module, so that it can use the correct routines. 
Consequently there must be one block for each CD-ROM drive to be 
accessed. Once set up, the block remains valid until the next CDFS 
initialisation. CDFS may alter a block's contents, but you must not 
do so yourself, nor must you save a block and use it in another 
session.

Each CDFS control block is five words long. To construct a block for 
a particular logical drive, you must:

1 Allocate memory for the block.

2 Call CDFS_ConvertDriveToDevice to convert that drive's logical 
number to a physical drive number.

3 Copy the returned physical drive number into the block as 
follows:

Bits from         Place   Word   Bits   of CDFS control block 
physical drive    in:                        
number


0 - 2                      0     0-2
3 - 4                      1     0-1
5 - 7                      2     0-2
8 - 15                     3     0-7
16 - 31                    4     0-15

All bits of the control block not mentioned above must be 
initialised to zero. The whole process can be done as follows:

word 0 = (drive_number AND 7)
word 1 = (drive_number AND &18) >> 3
word 2 = (drive_number AND &E0) >> 5
word 3 = (drive_number AND &FF00) >> 8
word 4 = (drive_number AND &FFFF0000) >> 16

Addressing modes

Locations on a CD are specified as one word addresses. You can use 
three different addressing modes:

Addressing mode     Meaning

0                 Logical block addressing
1                 Red Book addressing
2                 Physical block addressing

Logical block addressing

A logical block address gives an offset in blocks from the start of the 
CD's data area.

Red Book addressing

A Red Book address gives a time offset from the CD's first frame, 
made up as follows from the MM:SS:FF location defined in the Red 
Book:

Byte    Mnemonic    Meaning

0         FF     Frame number (0 - 74)
1         SS     Seconds (0 - 59)
2         MM     Minutes (0 - 99)
3                Undefined

There are 75 frames per second.

Physical Block Addressing

A physical block address gives an offset in blocks from the first block 
on the CD.

CD_OpenDrawer (SWI &41247)

Stops the CD spinning, opens the drawer and ejects the caddy

On entry

R7 = pointer to CDFS control block

On exit

R7 preserved

Use

This call stops the CD spinning, opens the drawer and ejects the 
caddy. The call fails and returns an error if the drawer has previously 
been locked using CD_EjectButton or *Lock.

CD_EjectButton (SWI &41248)

Enables or disables CD ejection

On entry

R0 = 0 (to enable ejection) or 1 (to disable ejection)
R7 = pointer to CDFS control block

On exit

R0, R7 preserved

Use

This call enables or disables CD ejection. It is used by the *Lock 
command.

CD_EnquireAddress (SWI &41249)

Returns the current address of the head

On entry

R0 = addressing mode, for returned head location
R7 = pointer to CDFS control block

On exit

R0 = head address
R7 preserved

Use

This call returns the current address of the head. You can use it 
while playing audio to determine which section of audio is playing.

CD_PlayAudio (SWI &4124B)

Attempts to play a section of a CD as audio, specified by address

On entry

R0 = addressing mode, of parameters
R1 = start address of play section
R2 = end address of play section
R7 = pointer to CDFS control block

On exit

R0-R2, R7 preserved

Use

This call attempts to play a section of a CD as audio, specified by 
address. If the section contains non-audio information, the results 
are drive-dependent; you will not necessarily get an error returned, 
and some drives may still attempt to play the data. We therefore 
recommend you first use calls to CD_EnquireTrack to find if the 
section you wish to play consists entirely of audio.

CD_PlayTrack (SWI &4124C)

Attempts to play a section of a CD as audio, specified by track

On entry

R0 = track number at which to start playing (1 - 99)
R1 = 255 to play to end of CD, or 254 to play to end of track
R7 = pointer to CDFS control block

On exit

R0, R1, R7 preserved

Use

This call attempts to play a section of a CD as audio, specified by 
track. If the section contains non-audio information, an error is 
returned.

CD_AudioPause (SWI &4124D)

Controls pausing of audio playing

On entry

R0 = 0 to turn off pausing, if pause was in effect, or 1 to turn on
 pausing, if audio was playing
R7 = pointer to CDFS control block

On exit

R0, R7 preserved

Use

This call controls pausing of audio playing.

CD_EnquireTrack (SWI &4124E)

Returns the track range of a CD, or information on a specified track

On entry

R0 = 0 to return track range, or a valid track number
R1 = pointer to 5 byte block
R7 = pointer to CDFS control block

On exit

R0, R1, R7 preserved

Use

This call returns the track range of a CD, or information on a 
specified track. The information is returned in the block pointed to 
by R1.

If R0 = 0 on entry, the track range is returned in the block as follows:

Byte      Contents

0     First track on CD (1-99)
1     Last track on CD (1-99)
2-4   Corrupted

Track numbers do not necessarily start at 1.

If R0 is a valid track number on entry, then information about that 
track is returned in the block:

Byte       Contents

0-3   Logical block address of track start (ie Mode 0 
      address)
4     Audio control bits specifying the type of 
      information the track holds:

      Bits      Meaning
       0      0 -> audio information, 1 -> data information
       1      0 -> 4 channel sound,   1 -> 2 channel sound
       2-7    Reserved

CD_StopDisc (SWI &41252)

Stops a CD playing

On entry

R7 = pointer to CDFS control block

On exit

R7 preserved

Use

This call stops a CD playing. You can use it to stop prematurely an 
audio play request.

CD_DiscUsed (SWI &41253)

Returns the size of the CD currently in the drive

On entry

R0 = addressing mode, for returned size
R1 = pointer to 8 byte block
R7 = pointer to CDFS control block

On exit

R0 preserved
R1 corrupted
R7 preserved

Use

This call returns the size of the CD currently in the drive. The call 
works with audio CDs as well as with CD-ROMs. The size is returned 
in the block pointed to by R1 on entry:

Bytes    Contents

0-3      Size of CD
4-7      Size of blocks on CD, in bytes (usually 2048)

Note that R1 may be corrupted on exit.

CD_AudioStatus (SWI &41254)

Returns the current audio status of the drive

On entry

R7 = pointer to CDFS control block

On exit

R0 = audio status
R7 preserved

Use

This call returns the current audio status of the drive, which may 
have one of the following values:

Value   Meaning

0       Currently playing audio
1       Currently paused
2       Reserved (has no meaning at present)
3       Audio play successfully completed
4       Error occurred during last audio play
5       Audio play has not been requested

To maintain drive independence, you should always treat values 3 
and 5 in the same way.

Soft-loadable Drivers

A soft-loadable driver must register itself with the CDFS_Driver 
module before it can be used. Once the driver has been registered, 
CDFS will make a SCSI_Inquiry command to obtain information 
about a SCSI device at a specific SCSI address (i.e. device id, LUN, 
card). The results of this Inquiry command are then passed to the 
soft-loaded driver to check if it recognises the drive. If the 
soft-loaded driver does recognise the drive, then it must return 
without an error, in which case CDFS will allocate this soft-loaded 
driver as the code which is called each time information is required 
from the device.

For soft-loadable drivers which are not SCSI, the same procedure 
must be followed. In this case however, CDFS, when passing the 
Inquiry command, will pass an error block pointed to by R0 instead 
for any SCSI address which is not occupied by a device. The 
soft-loaded driver will check for this error block, and when seen will 
return a non-error as above. CDFS will then allocate the driver as 
before. Thus the non-SCSI soft-loaded CD-ROM device driver is 
effectively allocated a SCSI address which is not occupied by any 
other device. CDFS will then access the driver in the usual manner, 
passing the SCSI address in the control block to the specific driver 
which can handle the command in the most appropriate way for the 
specific hardware regardless of its type. 

SWI handler entry conditions

When the soft-loadable driver registers itself with the CDFSDriver, it 
passes the address of a handler for SWI calls. CDFSDriver passes 
`CD_' SWIs to this handler with the following entry conditions:

On entry

R0 - R6 = Whatever values the various CD_ SWIs use 

R7 = pointer to a control block   

 Offset         Meaning

  0        SCSI device id (0-7)
  4        SCSI card number (0-3, usually 0)
  8        Logical Unit Number (0-7, usually 0)
  12       Drive type for this module 

R11= the number of the CD_SWI, i.e.     0 -> CD _ReadData, 
                                        1 -> CD_SeekTo etc
R12 = pointer to the workspace for this module 
R13 = pointer to a full descending stack, approx. 1024 bytes 
R14 = address to return to

On exit

R0 - R12 and R14 corrupted

CD_Register  (SWI & 41260)

Registers the soft-loadable driver with the CDFSDriver module.

On entry

R0 = pointer to a block

Offset  Meaning

  0    Information word for CDFSDriver module:
       Bits  Meaning
       0 - 5  The number of CD commands recognised, 
       currently 31, maximum 63 
       6  If set then use the SCSI 1 read data 
       command 
       7  If set then use the SCSI 1 seek command 
       9 - 31  Reserved   (must be zero)

  4    Number of times registered (should be set to zero             
       and will be updated by CDFSDriver)
  8    Number of drive types recognised by this driver
  12   Unused (must be zero)
  16   Unused (must be zero)

R1 = pointer to a 1-word special tag (&EE5OEE50), followed by 
handler code     

R2 = pointer to workspace for the soft-loadable module (passed in 
R12 to the handler)

On exit

  Offset  Meaning

    12    A pointer to a routine to convert logical blocks to 
          minutes, seconds, frames
    16    A pointer to a routine to convert minutes, seconds, 
          frames to logical blocks 

Use

This call registers the soft-loadable driver with the CDFSDriver 
module. The block pointed to by R0 on entry must be in RAM, 
whereas anything else, i.e. the code for each CD _SWI, can be in 
ROM. The block must stay put in the memory so that CDFSDriver 
can check it when detecting drive types. 

CD_Unregister       (SWI &41261)

Removes the soft-loadable driver from the CDFSDriver module.

On entry

R0 = pointer to a block                   

   Offset   Meaning

      0     Information word for CDFSDriver module block 

            Bits      Meaning
            0-5   The number of CD commands recognised, 
                  currently 31, maximum 63 
            6     If set then use all SCSI 2 commands and 
                  ignore bits 7 and 8 
            7     If set then use the SCSI 2 read data 
                  command 
            8     If set then use the SCSI 2 seek command 
            9-31 RESERVED (must be zero)

      4     Number of times registered (should be sent to 1 to 
            indicate that it has been registered already)
      8     UNUSED

R1 = pointer to a special tag (&EE5OEE50 = 1 word) followed by the 
handler code.

On exit

-

Use

Removes the soft-loadable driver from the CDFSDriver module. The 
block pointed to by R0 on entry must be in RAM, whereas anything 
else, i.e. the code for each CD _ SWI, can be in the ROM.

CD_ByteCopy       (SWI &41262)

Fast memory copy routine.

On entry      

R1 = pointer to the source             
R2 = pointer to the destination
R3 = number of bytes to copy

On exit

All registers preserved 

Use

Fast memory copy routine which provides an efficient way of 
copying any number of bytes, word-aligned or not.

CD_Identify (SWI & 41263) 

Identifies the drive type of a CD-ROM drive.

On entry

R7 = pointer to CDFS control block
     (as obtained from SWI CDFS_ConvertDriveToDevice)


On exit

R0 - Rl preserved       
R2 = drive type given by CDFS driver, or - 1 if type not recognised

Use

This call gets the drive type of a CD-ROM drive, so that other 
CD_SWIs can be made. It can be made by CDFS, the PCEmulator 
driver or !CDPlayer.


