When using this document, keep the following in mind:ntialGeneral Notice

1. This document is confidential. By accepting this document you acknowledge that you are boundby the terms set forth in the non-disclosure and confidentiality agreement signed separately and /inthe possession of SEGA. If you have not signed such a non-disclosure agreement, please contact
SEGA immediately and return this document to SEGA.

de2. This document may include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new versions of the
document. SEGA may make improvements and/or changes in the product(s) and/or the
program(s) described in this document at any time.

nfi

3. No one is permitted to reproduce or duplicate, in any form, the whole or part of this document
without SEGA’S written permission. Request for copies of this document and for technicalinformation about SEGA products must be made to your authorized SEGA Technical Services
representative.

Co

4. No license is granted by implication or otherwise under any patents, copyrights, trademarks, orother intellectual property rights of SEGA Enterprises, Ltd., SEGA of America, Inc., or any third
party.
5. Software, circuitry, and other examples described herein are meant merely to indicate the characteristics and performance of SEGA’s products. SEGA assumes no responsibility for any intellectual
property claims or other problems that may result from applications based on the examples
describe herein.

GA

6. It is possible that this document may contain reference to, or information about, SEGA products(development hardware/software) or services that are not provided in countries other than Japan.
Such references/information must not be construed to mean that SEGA intends to provide such
SEGA products or services in countries other than Japan. Any reference of a SEGA licensed product/program in this document is not intended to state or simply that you can use only SEGA’slicensed products/programs. Any functionally equivalent hardware/software can be used instead.
7. SEGA will not be held responsible for any damage to the user that may result from accidents or any
other reasons during operation of the user’s equipment, or programs according to this document.

SE

NOTE: A reader's comment/correction form is provided with thisdocument. Please address comments to :(6/27/95- 002)

SEGA of America, Inc., Developer Technical Support (att. Evelyn Merritt)
150 Shoreline Drive, Redwood City, CA 94065
SEGA may use or distribute whatever information you supply in any way
it believes appropriate without incurring any obligation to you.

SE

GA

Co

nfi

de

nti
al

TM

Program Library
User's Guide 1
CD LibraryDoc. # ST-136-R2-093094© 1994 SEGA. All Rights Reserved.

nti
al

READER CORRECTION/COMMENT SHEETKeep us updated!
If you should come across any incorrect or outdated information while reading through the attacheddocument, or come up with any questions or comments, please let us know so that we can make therequired changes in subsequent revisions. Simply fill out all information below and return this form to
the Developer Technical Support Manager at the address below. Please make more copies of this form if
more space is needed. Thank you.
General Information:

Phone

Document number
Document namedeYour Name

Date

ST-136-R2-093094

Program Library User's Guide 1 CD Library

Corrections:
Correction

nfi

pg. #

GA

Co

Chpt.

SE

Questions/comments:

Fax:

Where to send your corrections:(415) 802-1440
Attn: Sr. Coordinator,
Technical Publications Group

Mail:

SEGA OF AMERICA
Attn: Sr. Coordinator,
Technical Publications Group
130 Shoreline Dr.
Redwood City, CA 94065

nti
al

REFERENCES

In translating/creating this document, certain technical words and/or phrases were interpretedwith the assistance of the technical literature listed below.

Dictionary of Science and Engineering, 350,000 words, 3rd Edition
Inter Press
Tokyo, Japan
1990

2.

Computer Dictionary
Kyoritsu Publishing Co., LTD.
Tokyo, Japan
1978

3.

IBM Dictionary of Computing
McGraw-Hill, Inc.
New York, New York
1994

SE

GA

Co

nfi

de

1.

nti
al

SE

GA

Co

nfi

de

(This page was blank in the original Japanese document.)

ii

nti
al

CONTENTS

1.0 Outline ....................................................................................................................................... 1
1.1

Features ......................................................................................................................... 1

1.2

Summary of Functions .................................................................................................... 2

1.3

Module Configuration ..................................................................................................... 4

2.0 Basics .......................................................................................................................................... 5
Glossary ......................................................................................................................... 5

2.2

Notation .......................................................................................................................... 6

2.3

Name Restrictions .......................................................................................................... 6

2.4

Access Macros ............................................................................................................... 6

de

2.1

3.0 Directory Operations .................................................................................................................... 7
Initialization ..................................................................................................................... 7

3.2

File Identifiers ................................................................................................................. 8

3.3

Sub-Directory Operations ............................................................................................... 9

3.4

Conversion Between File Names and File Identifiers ................................................... 11

3.5

CD Block File System ................................................................................................... 12

nfi

3.1

Co

4.0 File Access ................................................................................................................................ 13
4.1

Access Models ............................................................................................................. 13

4.2

Access Pointers ............................................................................................................ 13

4.3

Parameters Controlled for Each File ............................................................................. 14

5.0 Access Modes ........................................................................................................................... 15
5.1

Return-Upon-Completion Access ................................................................................. 15

5.2

Immediate-Return Access............................................................................................. 15

6.1
6.2
6.3

GA

6.0 Other Functions ......................................................................................................................... 19
Development Support Functions .................................................................................. 19
Error Processing Functions .......................................................................................... 21
Multiprocessing ............................................................................................................. 21

7.0 Data Specifications .................................................................................................................... 23
7.1

Constants ..................................................................................................................... 25

SE

7.2

Basic Data .................................................................................................................... 24

7.3

Data Types ................................................................................................................... 29iii

Function Specifications .............................................................................................................. 32

nti
al

8.0

8.1

Directory Control ........................................................................................................... 33

8.2

File Operations ............................................................................................................. 35

8.3

Return-Upon-Completion Read .................................................................................... 37

8.4

Immediate-Return Read ............................................................................................... 38

8.5

Read Parameter Settings ............................................................................................. 41

8.6

Other............................................................................................................................. 42

deAppendix A Utilization of Development Support Functions .................................................................... 43
A.1

Procedure for Using Memory Files ............................................................................... 43

A.2

Procedure for Using DOS Files .................................................................................... 43

A.3

Precautions ................................................................................................................... 44

nfi

Appendix B Error Processing Methods .................................................................................................. 45

Appendix C ............................................................................................................................................. 48
Additional Explanation .................................................................................................. 48

C.2

Changes from the Previous Version ............................................................................. 48

SE

GA

Co

C.1

iv

SE

GA

Co

nfi

de

nti
al

(This page was blank in the original Japanese document.)

v

nti
al

1.0 Outline
Below is an explanation of the libraries for accessing files on a CD.

1.1 Features
This library has the following features.
Compatible CD ROMsde· Capable of accessing ISO9660 level files.
· This library does not cover access that utilizes CD ROM XA sub-header
information.
Data Bufferingnfi· Access is performed that assumes a CD block buffer control mechanism.
· In addition to simply reading files, pre-reads using the buffer are possible.
File IdentifiersCo· Access is based on file identifiers (order in directory).
· Eliminate a drop in speed caused by searching directories.
· Access by file name is possible by using a function that converts from the filename to a file identifier.
Development Support Functions

SE

GA· Memory files and DOS files can be accessed as a development support function.
· In the case of small amounts of data, files on a CD can be interchanged withmemory files.
· DOS files on an IBM PC can be accessed in the same way as memory files via the
SCSI interface. Even data too large to load into SIMM can be replaced by CD
files.
· Two types of libraries are provided: one for building into the product and onethat includes development support functions.

User's Guide 1 CD Library1Directory Operations

nti
al

1.2 Summary of Functions
The functions of the file system library are summarized below, and are categorized
into the following six types.
Library initialization, directory information reads, current directory settings andother functions are provided.
Function performed
Initializes the library and mounts CDs
Reads directory information
Sets the current directory
Converts a file name to a file identifier
Converts a file identifier to a file namedeFunction
GFS_Init
GFS_LoadDir
GFS_SetDir
GFS_NameToId
GFS_IdToName

File Operations

Opens, closes, seeks and performs the other common operations on files listed below.

nfi

ActionOpens a file
Closes a fileMoves the access pointerGets an access pointerChecks if an access pointer is at the end of a file
Converts the unit from byte to sector
Gets the file size
Gets file information

Co

Function
GFS_Open
GFS_Close
GFS_Seek
GFS_Tell
GFS_IsEof
GFS_ByteToSct
GFS_GetFileSize
GFS_GetFileInfo

Return-Upon-Completion Read

Reads data from files. Control does not return from the function until the reading ofdata is complete.
ActionReads data from opened files
Specifies a file identifier and then reads data

SE

GA

Function
GFS_Fread
GFS_Load2

Immediate-Return Read

Read Parameter Setting

ActionIssues a data read request
Issues a read request to the CD buffer
Checks if read processing is complete
Stops read processing
Gets the access status
A server function for one file
A server function for multiple files

deFunction
GFS_NwFread
GFS_NwCdRead
GFS_NwIsComplete
GFS_NwStop
GFS_NwGetStat
GFS_NwExecOne
GFS_NwExecServerntialReads data from files by means of a request function and a server function. The
request issued by the request function is processed by the server function one processing unit at a time. The server function must be recalled repeatedly. By inserting
application processing into the server function call loop, execution of the application
can be continued until completion of the data read.

Other

Function performed
Sets the mode for fetching from the CD buffer
Sets the transfer mode
Sets the unit for reading to the CD buffer
Sets the unit for transferring from the CD buffer

Co

Function
GFS_SetGmode
GFS_SetTmode
GFS_SetReadPara
GFS_SetTransPara

nfi

Sets the various parameters for the return-upon-completion and immediate-return
functions. Determines how the CD buffer is to be used, the transfer mode (DMA,
CPU, etc.) and the transfer unit.

CD pickup control, registration of error processing functions, and getting the error
status are provided. The error processing function is called when an error occurs.
Function performed
Moves the CD pickup
Registers the error processing function
Gets the error status

SE

GA

Function
GFS_CdMovePickup
GFS_SetErrFunc
GFS_GetErrStat

User's Guide 1 CD Library

3

nti
al

1.3 Module Configuration
The positioning of this library with respect to the hardware and other software isshown below in Figure 1.1. The area enclosed in the dotted line is the module included in the library for debugging.

Application

HardwareSCSI Drivernfi

CD Communiation
I/F LibrarydeFile System

SCSI I/F
IBM PCHD

CD Block

SIMM

Co

Debugging Module

Figure 1.1 Module Configuration

In order to use this library, it is necessary to link the following libraries at the sametime.
Library not compatible with position-independent code forSH7600CD communications interface library
DMA library
Cache libraryGA· SHCNPIC.LIB

SE· SEGA_CDC.LIB· SEGA_DMA.LIB· SEGA_CSH.LIB

4

2.0 Basics

nti
al

2.1 Glossary
The terms used to explain the file system library are defined in Table 2.1.
Table 2.1 Glossary

Memory file
Access pointerCurrent directory
Debug file
Buffer partition
File identifier

Frame address (FAD)

Main process

SE

GA

Co

Interrupt processdeDOS file

Meaning
A buffer that stores data read from the CD in sector units. It has a 200sector capacity.
Files on an IBM PC that can be accessed via a SCSI interface. These canbe used in a debugger library.
A file located on SIMM. These files can be used in the debugger library.
Position at which a file is accessed (unit: sector).
The directory referred to when opening files.
General designation for DOS files and memory files.
One part of a CD buffer divided up into several logical parts. One buffer
partition is dedicated to each file that is opened.
A sequential number in a directory for identifying files. The values usedrange from 0 to (number of directory records - 1). Where, 0 indicates thecurrent directory and 1 indicates the parent directory.
Number continuously assigned in frame units assuming the absolute
time on the CD is 00:00:00. This number has a 1-to-1 correspondence tothe absolute time. The CD is accessed using the frame address as a key,
not the absolute time.
The series of processes that is begun when the CPU is reset. This term
refers to interrupt processing.
Processing that is started by an interrupt. This term refers to the mainprocess.

nfi

Term
CD buffer

User's Guide 1 CD Library

5

nti
al

2.2 Notation
The notation used in explaining the file system is explained below.
Grouping of names“ABC_-” indicates several names beginning with ABC_. For example, ABC_X, ABC_Y
and ABC_Z.
Symbol Specification“!MMM/SSS” indicates the symbol SSS defined by MMM. It is also a notation usedwith E7000 commands.
Hexadecimal NotationdeNumbers with an “H” affixed to them at the end are hexadecimal numbers.

2.3 Name Restrictions
In file system libraries, the following names are used for functions, variables, types,
and macros.
GF- or gfGfGF-

nfi

Functions and variables
Type sMacrosCo

In the applications that use these libraries, be careful not to use designations thatconflict with these naming conventions.

SEGA

2.4 Access Macros
In CD libraries that include file system libraries, members of the structure are referenced using a structure called an access macro. Access macros are capable of getting
and setting the values of members. Using access macros has the following advantages.
· Member access format is uniform.
· Parts accessing specific structure members can be easily extracted.

63.0 Directory Operations

nti
al

3.1 Initialization
Before using this library, GFS_Init must be executed. GFS_Init performs the following
processing:· Initialization of library work area
· Mount processing
Initialization

Sets the work area used by the library and initializes it. The application must provide thework area and the directory information storage area.

deSince the size of the area changes with the number of files opened at the same time, it
should be obtained using the following macro. The statement open_max is the maximum
number of files that can be opened at once.
GFS_WORK_SIZE(open_max)

nfi

Mount Processing

The root directory is read from the CD ROM and this is made the current directory. It also
initializes the CD block and erases all the sector data in the CD buffer. Since the file system
only holds the top address of the directory information storage area, the application must
not change the contents of the area.

#define OPEN_MAX#define MAX_DIRCoThe directory information control structure is initialized and GFS_Init called as shown
below.
20
10/*maximum number of files to be opened at
the same time*//*maximum number of directories*/

GA

Uint32 work[GFS_WORK_SIZE(OPEN_MAX)/4]; /*library work area*/
GfsDirTbl dirtb1;/*directory information control structure */GfsDirId dir[MAX_DIR];/*directory information storage area*/
GFS_DIRTBL_TYPE(&dirtbl) = GFS_DIR_ID;
GFS_DIRTBL_NDIR(&dirtbl) = MAX_DIR;

GFS_DIRTBL_DIRID(&dirtble) = dir;/*directory information storage area type *//*maximum number of elements in directory
information*//*storage area*//*address of directory information storage*//*area*/

GFS_Init(OPEN_MAX, work, &dirtbl);

SE

GFS_Init must be called again when the CD ROM is changed.

User's Guide 1 CD Library

7

Example: Accessing FILE2.DAT below.

nti
al

3.2 File Identifiers
In this library, files that are accessed are specified by file identifiers. If the file nameis used to access a file, then the file name is converted to a file identifier. The file
identifier is valid for the current directory.

Parent

FILE1.DAT

1

FILE2.DAT

2

FILE3.DAT

3
4

Self
Parent

FILE1.DATde0Current directory

FILE2.DAT

File identifier

FILE3.DAT

Program Example

Co

nfi

gfs = GFS_Open (3) ;/** file access is performed here*/
GFS_Close(gfs)SE

GA

Figure 3.1 Access Using File Identifiers

8

nti
al

3.3 Sub-Directory Operations
In order to access files in a sub-directory, it is necessary to set the current directory
information by calling the following functions.
· Read directory information (GFS_LoadDir)· Set current directory (GFS_SetDir)
A method in which the directory information is read in advance and CD ROM
access is lost when the file is opened is allowed.
Read Directory Information (GFS_LoadDir)

This specifies the sub-directory file and reads and saves the directory information.
The following two types of directory information save areas can be selected.

de(a) GFS_DIR_ID· Does not save the file name. Files can only be accessed by means of a file
identifier.

nfi(b) GFS_DIR_NAME· Saves the file name and therefore an area larger than (a) above is required.
· Access by file name is allowed.
Current Directory Setting (GFS_SetDir)

Co

The directory information area read by GFS_LoadDir is used as the current directory.

Root Directory[Logical structure of CD ROM]

0
1
2

Directory
information area3

Sub-directories
0GA

Set current
directorySE

GFS_SetDir

User's Guide 1 CD Library

Directory
information
Read

File

1
2
3

GFS_LoadDir
Directory
information
Read

0
1
2
3

GFS_LoadDir

Figure 3.2 Setting Directory Information

9

The following procedure must be followed to access files in a sub-directory.

ntialRead directory information↓

Set current directory↓
Open file↓
Access file↓

Two examples of this procedure are shown below.

#define MAX_DIR

nfi

Accessing a file in a directory other than the root directory
An example of a procedure program for accessing a file in a sub-directory is shown
below. Here, the file to be accessed is in the directory specified by dir_fid in the current
directory.

10

GfsDirTbl dirtbl;
GfsDirId dirid[MAX_DIR];
Sint32 dir_fid;
Sint32 fid;
GfsHn gfs;/*maximum number of directories*//*Directory information storage area/*Directory information storage area/*enters directory file identifier/*enters accessed file identifier/*file handler of accessed file

*/
*/
*/
*/
*/

Co

Example:deClose file

GFS_DIRTBL_TYPE(&dirtbl) = GFS_DIR_ID;
GFS_DIRTBL_NDIR(&dirtbl) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl) = dirid;
GFS_LoadDir(dir_fid, &dirtbl);/*reads directory information*/

GFS_SetDir(&dirtbl);*//*sets current directorySE

GA/*sets identifier of file accessed in fid */gfs = GFS_Open(fid);/**file access performed here*/
GFS_Close(gfs)10

Simultaneous access of multiple files in different directories
In order to access files in different directories, the target files must be opened whileswitching the current directory. An example is shown in which two files in the two subdirectories directly below the current directory are accessed simultaneously. This file
identifiers of the two sub-directories with the files to be accessed are respectively
specified by dir_fidl and dir_fid2.
/*maximum number of directories*//*current directory at this point*//*control area for directory information *//*storage area for directory information *//*storage area for directory information *//*enters identifiers of directory files *//*enters identifiers of access files*//*file handlers of access files*/*//*loads directory information of current directory dir_fid2
GFS_DIRTBL_TYPE(&dirtbl2) = GFS_DIR_ID;
GFS_DIRTBL_NDIR(&dirtbl2) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl2) = dirid2;
GFS_LoadDir(dir_gfs2, &dirtbl2);*//*opens the file fid1 of the directory dir_fid1
GFS_SetDir(&dirtbl1);
gfs1 = GFS_Open(fid1);

*/

*/

nfi

/*loads directory information of current directory dir_fidl
GFS_DIRTBL_TYPE(&dirtbl1) = GFS_DIR_ID;
GFS_DIRTBL_NDIR(&dirtbl1) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl1) = dirid1;
GFS_LoadDir(dir_gfsl, &dirtbll);Code#define MAX_DIR
10
GfsDirTbl curdir;
GfsDirTbl dirtbl1, dirtbl2;
GfsDirId dirid1[MAX_DIR];
GfsDirId dirid2[MAX_DIR];
Sint32 dir_fid2, dir_fid2;
Sint32 fid1, fid2;
GfsHn gfs1, gfs2

nti
alExample:GA/*opens the file fid2 of the directory dir_fid2
GFS_SetDir(&dirtbl2);
gfs2 = GFS_Open(fid2);/**file access is performed here*/
GFS_Close(gfs1);
GFS_Close(gfs2);

3.4 Conversion Between File Names and File Identifiers
When directory information containing file names is set to the current directory,
functions for converting between file names and file identifiers can be used.
If directory information not containing a file name is set to the current directory, anerror results if these functions are called. An example defining a function that uses
this function to open a file by its file name is shown below.

SE

Example:User's Guide 1 CD Library/*opens file specified by file name */GfsHn OpenByName(Uint8 *fname){Sint32 fid = GFS_NameToId(fname);if (fid < 0) {return NULL;}
return GFS_Open(fid);
}

11

nti
al

3.5 CD Block File System
Directories can be controlled using the CD block file system (file system built into
the CD block; CDBFS below).

The processes for initialization, reading directory information and setting the current
directory using the CDBFS are shown below.
Initialization

In order to utilize the functions of the CDBFS, NULL must be specified for the
pointer to the directory control structure and GFS_Init must be called. Upon completion of processing by GFS_Init, the root directory is set by the CDBFS.

deReading Directory Information

In order to read sub-directory information, NULL is specified for the pointer to thedirectory control structure and GFS_LoadDir is called to indicate that the storage
destination of the directory information is in the CD block.
Setting Current Directorynfi

In order to set the directory information set in the CD block to the current directory,
NULL is specified for the pointer to the directory control structure and GFS_SetDiris called.

Co

Even if settings that use the CDBFS are performed, directory control can be partiallyperformed with this library. In that case, always be aware of which directory control
function being utilized. The advantages and disadvantages of using the CDBFS arelisted in Table 3.1.
Table 3.1 Advantages and Disadvantages of Using CDBFSGA

Advantages· Uses small amount of host memory.

Disadvantages· The CD ROM is accessed each time a file in adifferent directory is accessed.
· The amount of CD buffer that can be used byapplications is reduced by one sector.
· File names cannot be used.

The functions GFS_Init and GFS_LoadDir, which read directory information, returnthe number of directories read as the function value. When the CDBFS is used, that
number becomes the number of directories the CDBFS is holding.

SE

An error results if a file name is used when the current directory of the CDBFS is set.

12

4.0 File Access

GFS_NwCdRead

CD ROM

CD Buffer
Read

nti
al

4.1 Access Models
A diagram of a file access model is shown in Figure 4.1.

GFS_Fread
GFS_NwFread

Host Area

de

Fetch

CD Block

Figure 4.1 Access Function Model

nfi

Transferring data from the CD ROM to the CD buffer is called “reading”, and transferring data from the CD buffer to the host area is called “fetching”.

Co

By utilizing GFS_Fread and GFS_NwFread, an application can transfer data from the
CD ROM without being aware of read processing. To control read processing fromthe application, use GFS_NwCdRead.
4.2 Access PointerSince the access pointer is updated by reading, it moves in sector units. Movementof the access pointer when the following expression is executed to read 5000 bytes tothe host area buffer is shown in Figure 4.2. After execution, the access pointer moves
from AP1 to AP2.

GAGFS_FREAD(gfs, 3, buf, 5000);

1 sector

SE

AP1

User's Guide 1 CD Library

AP2

Parts read to host area
Figure 4.2 Movement of access pointer

13

nti
al

Sizes of sectors for each type of file are shown in Table 4.1
Table 4.1 Sector Lengths for Each Type of File
File type
CD ROM mode 1
CD ROM mode 2 form 1 only
CD ROM mode 2 form 2 only
Includes CD ROM mode 2
DOS file
Memory file

Sector length (bytes)
2048
2048
2324
Undefined
2048
2048

de

While reading is performed in sector units, fetching is performed in 4-byte units.

Table 4.2 Parameters for Each File

Fetch mode

Transfer mode
Read parameterGA

Fetch parameter

Description
Offset of file at whichreading is started (unit:
sector)Specifies whether sector
data in CD buffer is erased
or left after fetching
Specifies device that
performs fetching
Maximum number ofsectors transferred in one
read
Number of sectors
transferred in one fetch

Function changed

Initial value

GFS_Seek

0

GFS_SetGmode

GFS_GMODE_ERASE

Co

Parameter
Access pointernfi

4.3 Parameters Controlled for Each FileOf the parameters controlled by the library for each file opened, an application canchange up to five. These parameters are shown in Table 4.2.

GFS_SetTmode

GFS_TMODE_CPU

GFS_SetReadPara

GFS_RPARA_DFL

GFS_SetTransPara

1

SE

The opened file occupies one filter, which is a CD block resource, and one buffer
partition at a time.

145.0 Access Modesntial

The two access modes provided by this library are described below.
· Return-upon-completion accessControl is not returned to the application until completion of access.
· Immediate-return accessControl is returned as soon as an access request is received.

#define BUF_SIZE 2048
GfsHn gfs;
Sint32 fid;
Sint32 nsct = 1;
Uint32 buf[BUF_SIZE]
gfs = GFS_Open(fid);/*file handler/*file identifier/*number of read sectors/*read area

*/
*/
*/
*/

/*opens file

*/

nfi

Example:de

5.1 Return-Upon-Completion Access
Return-upon-completion access is similar to the file access function in the standard
C library. An example return-upon-completion access program is shown below.

GFS_Fread(gfs, nsct, buf, BUF_SIZE); /*nsct sectors read to buf *//*closes file*/Co

GFS_Close(gfs);

GA

5.2 Immediate-Return Access
Immediate-return access is performed by using a request function and a server
function. The request function executes only request acceptance and immediately
returns. Actual access is performed by repeatedly calling the server function while
monitoring the completion status. The application can also be processed in the callloop of the server function.

SE

A file handle that has issued a request cannot issue another request until processingof the first one is completed.

User's Guide 1 CD Library15

Immediate-Return Access for Single Filesntial

The server function for single file access is GFS_NwExecOne. An example of aprogram that accesses one file using immediate-return access is shown below. In thisexample, the request function is GFS_NwFread.
Example:#define BUF_SIZE

2048*2

GfsHn gfs;
Sint32 nsct = 2;
Sint32 stat;
Uint32 buf[BUF_SIZE/4]/*file handler/*number of read sectors/*server status/*read areadegfs = GFS_Open(fid);/*opens file/*request function */GFS_NwFread(gfs, nsct, buf, BUF_SIZE);/*reads nsct sectors into buf/*returns control immediatelynfi

for (;;) {/*server function */stat = GFS_NwExecOne(GFS);/*executes readif (stat == GFS_SVR_COMPLETED) {/*read complete?
break;}
user();/*optional user process}/*closes file

SE

GA

Co

GFS_Close(gfs);

16

*/
*/
*/
*/
*/

*/
*/

*/
*/

*/

*/

Immediate-ReturnAccess for Multiple Filesntial

The server function for continuous access of multiple files is GFS_NwExecServer.
The request function is used in common with access of single files.

The application issues a request for access of multiple files. Following this, access is
executed sequentially by periodically passing control to the server. Access is performed one at a time in the order of the requests.
Here is an example of a program that performs user processing while reading three
files.
Example:nfi/*file handle during access/*server status

gfsl = GFS_Open(fid1);/*opens filegfs2 = GFS_Open(fid2);
gfs3 = GFS_open(fid3);
GFS_NwFread(gfs1, NSCT1, buf1, BSIZE1); /*starts read operation
GFS_NwFread(gfs2, NSCT2, buf2, BSIZE2);
GFS_NwFread(gfs3, NSCT3, buf3, BSIZE3);
for (;;) {stat = GFS_NwExecServer(&now_gfs);/*executes readif (stat == GFS_SVR_COMPLETED {/*is there work to execute?
break;}
user();/*optional user process}
GFS_Close(gfs1);
GFS_Close(gfs2);
GFS_Close(gfs3);

*/

*/
*/
*/

*/

*/
*/

*/

SE

GA

*/

/*file identifier of each file*//*file handle of each file*//*data storage area of each file */Co

Sint32 fid1, fid2, fid3;
GfsHn gfsl, gfs2, gfs3;
Uint32 buf1[BSIZE1/4];
Uint32 buf2[BSIZE2/4];
Uint32 buf3[BSIZE3/4];
GfsHn now_gfs;
Sint32 stat;de/*number of sectors read from each file#define NSCT1 1#define NSCT2 2#define NSCT3 3/*size of data storage area of each file (unit: byte)#define BSIZE1 2048*NSCT1#define BSIZE2 2048*NSCT2#define BSIZE3 2048*NSCT3

User's Guide 1 CD Library17Pre-loading to CD Bufferntial

If pre-reading to the CD buffer is specified by GFS_NwCdRead when a large file iscontinuously loaded a little at a time, then full advantage can be taken of the read
speed of the CD.

In the program example shown below, a 1000 sector file is continuously read 10
sectors at a time. GFS_NwCdRead specifies to look ahead 1000 sector pre-reads, andtherefore the 1000 sectors of the target file are continuously played and stored in thebuffer. Since data is fetched from the buffer at the same time this processing is performed, the buffer does not get full and playback is not interrupted.

deIf this processing is performed without pre-reading, then playback of the CD isinterrupted every 10 sectors and time is wasted.

Example:#define SECT_SIZE#define FILE_ SIZE
#define RD_UNIT

2048
10000*SECT_SIZE
10

Uint8 *rd_bp, *proc_bp;
Uint32 buf1[RD_UNIT*SECT_SIZE/4];
Uint32 buf2[RD_UNIT*SECT_SIZE/4];
GfsHn gfs;
Sint32 i, stat, nbyte;

nfi

An example of a program that pre-reads to the CD buffer is shown.

/*read buffer and processing buffer/*data storage area 1/*data storage area 2

SE

GA

Co

gfs = GFS_Open(fid);
GFS_NwCdRead(gfs, FILE_SIZE);/*pre-read specification for CD buffer
GFS_SetTransPara(gfs, RD_UNIT);/*maximum RD_UNIT sector fetched oncefor (i = 0; i < FILE_SIZE / RD_UNIT; ++I){/*read and processing buffer settings*/
if (i & 1) {rd_bp = buf1;
proc_bp = buf2;} else {rd_bp = buf2;
proc_bp = buf1;}/*executes fetch from CD buffer */GFS_NwFread(gfs, RD_UNIT, rd-bp, RD_UNIT * SECT_SIZE);
do {if (i > 0) {user_process(proc_bp);/*processing of read data*/
} else {user_process0();/*processing before data is read */}GFS_NwExecOne(gfs);
GFS_NwGetStat(gfs, &stat, &nbyte);} while (nbyte < RD_UNIT * SECT_SIZE);
}

18

*/
*/
*/

*/
*/

6.0 Other Functions

nti
al

6.1 Development Support Functions
The file system provides a function to access memory files and DOS files to support
debugging. This function makes it possible to access files that have not been preparedon the CD ROM yet or files that have been changed since the CD ROM was made in
the same way files on the CD ROM are accessed. However, this function cannot be
used together with the CDBFS.
The mechanism that facilitates access of debugging files in the same way as files on
the CD ROM lies in the directory information read process.

deWhen directory information is read from the CD ROM, directory information is also
read form the debugger file. The information in the debugger file is processed either
in place of or in addition to the information in the CD ROM file.

nfi

After reading directory information from a directory, the following processing is
performed.
1) Substitution
The directory information from a debugger file of the same name as the CD ROM
file is set to the directory information area in place of the corresponding CD ROM
file.

Co

2) Addition
A debugger file for which substitution was not performed is added to the directory
information storage area.
In the substitution of the debugger file, the memory file takes precedence over the
DOS file. An example in which these processes are performed is shown below.
Figure 6.1 shows the file configuration.

GA

CD ROM
DIR1

SE

DIR2

User's Guide 1 CD Library

.
..
FILE1
FILE2
FILE3
.
..
FILE4
FILE5
FILE6

DOS

SIMM

FILE1
FILE4
DOS_FILE

FILE1
SIMMFILE

Figure 6.1 File Configuration Example

19

Table 6.1 Directory Information of DIR1
Directory information
obtained

.
..
FILE1
FILE2
FILE3

DOS

FILE1

SIMM

FILE1

FILE4
DOS_FILE

de

.
..
FILE1
FILE2
FILE3
FILE4
DOS_FILE
SIMMFILE

CD ROMnti
al

The results of obtaining the directory information of DIR1 with this file configuration are shown in Table 6.1 and the results of obtaining the directory information of
DIR2 are shown in Table 6.2

SIMMFILE

The files with lines through them indicate that they have been replaced.

.
..
FILE4
FILE5
FILE6
FILE1
DOS_FILE
SIMMFILE

CD ROM
.
..
FILE4
FILE5
FILE6

DOS

SIMM

FILE4

Co

Directory information
obtained

nfi

Table 6.1 Directory Information of DIR2

FILE1
DOS_FILE

FILE1
SIMMFILE

The files with lines through them indicate that they have been replaced.

SEGA

As shown in the examples above, substitution and addition by a debugger file canbe performed on all directories of a CD ROM.

20

nti
al

6.2 Error Processing Functions
By registering error processing functions, it is possible to specify that an error processing function be called in the event an error should occur during execution of alibrary function. Error processing functions are not registered in the initial state.
When an error does occur, the error processing function is executed using the following call format.
void *(func)(void *obj, Sint32 err); /*error processing function
void *obj;/*pointer to registered object
Sint32 err_code;/*generated error code

*/
*/
*/

(*func)(obj, err_code);*/de/*calls error processing function

When control returns from the error processing function, the library function returns
control to the application using the error code as the function value.

nfi

6.3 Multiple Processing
This is the processing required when the functions of this library are used (multiple
processing) for both the main processing and the interrupt processing.

Co

When an example is made to execute the functions of this library simultaneously formain processing and interrupt processing, the function value called last becomes
error code GFS_ERR_BUSY. In that case, the following measures must be taken
depending on whether this occurs during main processing or interrupt processing.
During Main Processing

Wait until the called function stops returning GFS_ERR_BUSY or postpone calling of
this library function until the next opportunity.
During Interrupt Processing

SE

GA

Postpone calling of this library function until the next opportunity.

User's Guide 1 CD Library

21

SE

GA

Co

nfi

de

nti
al

(This page was blank in the original Japanese document.)22

A list of file system data is shown in Table 7.1.
Table 7.1 Data Table

Data NamedeGFS_ATR_GFS_NWSTAT_GFS_SVR_GFS_SEEK_GFS_GMODE_GFS_TRANS_GFS_ERR_-

GfsHn
GfsDirTbl
GfsDirId
GfsDirName
GfsErrFunc
GfsErrStat

No.
1.0
2.0
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8
3.0
3.1
3.2
3.3
3.4
3.5
3.6

SE

GA

Co

nfi

Data
Basic data
Constants
File attribute
Access status
Access Server status
Seek modeGet (fetch) mode
Transfer mode
Error code
Other
Data types
File handle
Directory information control
Directory information with no file name
Directory information with file name
Error processing function
Error statusnti
al

7.0 Data Specifications

User's Guide 1 CD Library23

7.1 Basic Data
Data
Basic data

Data Name

1) Basic Data Types
A table of the basic data structure is shown below.

Explanation
1-byte integer without sign
1-byte integer with sign
2-byte integer without sign
2-byte integer with sign
4-byte integer without sign
4-byte integer with sign
logic type 4-byte integer

Constant name
FALSE
TRUE

Value
0
1

3) NULL PointerSE
24

Explanation

Null pointer

Co

Value
(void *)0

GA

Constant name
NULL

Explanation
False logical value
True logical valuenfi2) Logical Constants
These are used as logical (Boo1) values.

deType name
Uint8
Sint8
Uint16
Sint16
Uint32
Sint32
Boo1

No.
1.0

nti
al

Title
Data specification

7.2 Constants
Data
File attribute

Data Name
GFS_ATR_-

No.
2.1

nti
al

Title
Data specification

The constants shown below indicate the presence or absence of their respective
attributes. These constants are used for attributes in directory information read by
GFS_Init and GFS_LoadDir and for attributes output by GFS_GetFileInfo.
The bits not shown here are undefined.
Bit

7

6

5

4

3

2

1

0

GFS_ATR_END_TBL 1:

Data
Access status

GFS_ATR_FORM2

1: Includes FORM2 sectors

GFS_ATR_INTLV

1: Includes interleave sectors

GFS_ATR_DIR

1: Directory file

nfi

Title
Data specification

1: Includes FORM1 sectors

de

GFS_ATR_FORM1

End of directory information table

Data Name
GFS_NWSTAT_-

No.
2.2

The constants shown below indicate the access status of the server. Therefore, output
using GFS_NwGetStat.
Explanation
No action
GFS_NwFread is being executed
GFS_NwCdRead is being executed

SE

GA

Co

Constant name
GFS_NWSTAT_NOACTGFS_NWSTAT_FREAD
GFS_NWSTAT_CDREAD

User's Guide 1 CD Library

25

Data
Access Server status

Data NameGFS_SVR_-

No.
2.3

nti
al

Title
Data specification

The constants shown below are functions of GFS_NwExecOne and GFS_NwExecServer.
Their execution status is shown.

Title
Data specification

Data
Seek mode

Explanation
Processing complete
Processing in progress
Temporary pause because CD buffer fullError has occurred during access

Data NameGFS_SEEK_-deConstant name
GFS_SVR_COMPLETED
GFS_SVR_BUSY
GFS_SVR_CDPAUSEGFS_SVR_ERROR

No.
2.4

The constants below indicate the reference when moving an access pointer. These areused as arguments for GFS_Seek.

Data
Fetch mode

Data Name
GFS_GMODE_-

Co

Title
Data specification

Explanation

Top of file
Current position
End of filenfi

Constant name
GFS_SEEK_SET
GFS_SEEK_CUR
GFS_SEEK END

No.
2.5

The constants below indicate the method by which data are fetched from the CD ROM
buffer. These are used as arguments for GFS_SetGmode.

SE

GA

Constant name
GFS_GMODE_ERASE
GFS_GMODE_RESIDENT

26

Explanation
Delete from buffer after transferring
Leave in CD buffer after transferringData
Transfer mode

Data Name
GFS_TRANS_-

No.
2.6

nti
al

Title
Data specification

The constants below indicate the device that executes transfer from the CD buffer. These
are used as arguments of GFS_SetTmode.
Explanation
DMA transfer by SCU
DMA cycle steal transfer channel 0
DMA cycle steal transfer channel channel 1
Software transfer

SE

GA

Co

nfi

de

Constant name
GFS_TMODE_SCU
GFS_TMODE_SDMA0
GFS_TMODE_SDMA1
GFS_TMODE_CPU

User's Guide 1 CD Library

27

Data
Error codes

Data Name
GFS_ERR_-

No.
2.7

nti
al

Title
Data specification

The value of GFS_ERR_OK is "0". Other error codes have negative values.

Title
Data specification

Data
Other

de

Co

GFS_ERR_DIR
GFS_ERR_CDBFSGFS_ERR_NONAME
GFS_ERR_NEXISTGFS_ERR_FID
GFS_ERR_HNDL
GFS_ERR_SEEK
GFS_ERR_ORG
GFS_ERR_NUM
GFS_ERR_OFS
GFS_ERR_FBUSY
GFS_ERR_PARA
GFS_ERR_BUSY
GFS_ERR_NOHNDLGFS_ERR_PUINUSE
GFS_ERR_ALIGNGFS_ERR_TMOUT
GFS_ERR_CDOPEN
GFS_ERR_BFULExplanation
Normal end
CD read error
No CD is set in the player
A non-CD ROM disc is set in the player
Contents of directory control table are incorrect
The value for the maximum number of opens isincorrect
The specified file is not a directory
CD block file system error
File names cannot be used in the current directory
File name does not exist
Incorrect file identifier
File handle is incorrect
Seek position is incorrect
Reference position is incorrect
Byte number is negative
Incorrect offset
Processing of specified file handle not complete
Incorrect mode
Library function is being executed
No open file handle
Pickup is being used
Data read area is not in 4-byte boundary
Internal processing time out
Tray is open
Read stopped because buffer is full

nfi

Constant name
GFS_ERR_OK
GFS_ERR_CDRD
GFS_ERR_CDNODISC
GFS_ERR_CDROM
GFS_ERR_DIRTBL
GFS_ERR_OPENMAX

Data Name

No.
2.8

GA

Other constants used in this library are shown below.

SE

Constant name
GFS_RPARA_DFL
GFS_BUFSIZ_INF

28

Explanation
Initial value of read parameter
Specifies read regardless of the size of the read area
in GFS_Load7.3 Data Types
Data
File handle

Data Name
GfsHn

No.
3.1

nti
al

Title
Data specification

Holds information regarding file access for each file. The information is generated by
GFS_Open. Most functions that access files reference this data.
Title
Data specification

Data
Directory information control

Data Name
GfsDirTbl

No.
3.2

Constant name
GFS_DIR_ID
GFS_DIR_NAMEdeDirectory information control structures can control directory information without filenames and directory information with files names. The following constants specify
which is controlled.
Explanation
Does not have file name information
Has file name information

Type
Sint32
Sint32Co

GfsDirTbl *dirtbl
Access macro
GFS_DIRTBL_TYPE(dirtbl)
GFS_DIRTBL_NDIR(dirtbl)

nfi

These are data types for controlling directory information. The directory informationtable classification and its size and substance are held.

GFS_DIRTBL_DIRID(dirtbl)

GfsDirId *GFS_DIR_NAME(dirtbl)

GfsDirName *Explanation
Directory information table classification
Maximum number of elements in directory
information table
Pointer to directory information table withno file names
Pointer to directory information table withfile names(a) When directory information with no file names is usedGA

GfsDirTbl dirtbl;
GfsDirId dir_id[MAX_DIR_ID]
GFS_DIRTBL_TYPE(&dirtbl) = GFS_DIR_ID; /*specifies directory information with no *//*file name*/
GFS_DIRTBL_NDIR(&dirtbl) = MAX_DIR_ID; /*maximum number of elements*/
GFS_DIRTBL_DIRID(&dirtbl) = dir_id;/*directory information table with no file *//*name*/(b) When directory information with file names is usedSE

GfsDirTbl dirtbl;
GfsDirName dir_name[MAX_DIR_NAME]
GFS_DIRTBL_TYPE(&dirtbl) = GFS_DIR_NAME; /*specifies directory information with/*file name
GFS_DIRTBL_NDIR(&dirtbl) = MAX_DIR_NAME; /*maximum number of elements
GFS_DIRTBL_DIRNAME(&dirtbl) = dir_name; /*directory information table with file/*nameUser's Guide 1 CD Library

29

*/
*/
*/
*/
*/

Data
Directory information without file names

Data Name
GfsDirId

No.
3.3

nti
al

Title
Data specification

These are directory information structures with no file names. GFS_DIR_ID is used to
specify the type of directory information table (GFS_DIRTBL_TYPE).

Title
Data specification

Type
Sint32
Sint32
Uint8
Uint8
Uint8
Uint8

Explanation
Top FAD of file
Size of file (unit: byte)
File number
File attribute
Unit size of file (unit: sector)
Gap size of file (unit: sector)

deGfsDirId *dir
Access macro
GFS_DIR_FAD(dir)GFS_DIR_SIZE(dir)GFS_DIR_FN(dir)GFS_DIR_ATR(dir)GFS_DIR_UNIT(dir)GFS_DIR_GAP(dir)Data
Directory information with file names

Data Name
GfsDirName

No.
3.4

nfi

These are directory information structures which include file names. GFS_DIR_NAME
is used to specify the type of directory information table (GFS_DIRTBL_TYPE).

SE

GA

Co

GfsDirId *dir
Access macro
Type
Explanation
GFS_DIR_FAD(dir)Sint32Top FAD of file
GFS_DIR_SIZE(dir)Sint32Size of file (unit: byte)
GFS_DIR_FN(dir)Uint8File number
GFS_DIR_ATR(dir)Uint8File attribute
GFS_DIR_UNIT(dir)Uint8
Unit size of file (unit: sector)
GFS_DIR_GAP(dir)Uint8
Gap size of file (unit: sector)
GFS_DIR_FNAME(dir) Uint8[]
File name *1*1: The area size is 12 bytes. When the file name length is 12 bytes, the character string
does not end with '¥0.'

30

Data
Error processing function

These are functions set with GFS_SetErrFunc.
Syntax:Input:
Output:Data Name
GfsErrFunc

No.
3.5

nti
al

Title
Data specification

void (*GfsErrFunc) (void *obj, Sint32 ec)
obj: Object required for error processingec: Error code
none

Title
Data specification

Data
Erro status

Data Name
GfsErrStat

Type
GFSErrFunc
void *
Sint32

Explanation
Pointer to error processing function
First argument of error processing function
Error code

SE

GA

Co

nfi

GfsErrStat *stat
Access macro
GFS_ERR_FUNC(err)
GFS_ERR_OBJ(err)
GFS_ERR_CODE(err)deData output by GFS_GetErrStat.

No.
3.6

User's Guide 1 CD Library31

A list of file system library functions is shown in Table 8.1.
Table 8.1 File System Library Function Table

Function NamedeGFS_Init
GFS_LoadDir
GFS_SetDir
GFS_ToId
GFS_IdToName

1.1
1.2
1.3
1.4
1.5

2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8

GFS_Load
GFS_Fread

3.1
3.2

GFS_Load
GFS_NwCdRead
GFS_NwIsComplete
GFS_NwStop
GFS_NwGetStat
GFS_NwExecOne
GFS_NwExecServer

4.1
4.2
4.3
4.4
4.5
4.6
4.7

GFS_SetGmode
GFS_SetTmode
GFS_SetReadPara
GFS_SetTransPara

5.1
5.2
5.3
5.4

GFS_CdMovePickup
GFS_SetErrFunc
GFS_GetErrStat

6.1
6.2
6.3

Co

GA

SE
32

No.

GFS_Open
GFS_Close
GFS_Seek
GFS_Tell
GFS_IsEof
GFS_ByteToSct
GFS_GetFileSize
GFS_GetFileInfo

nfi

ActionDirectory operations
Initialization of file system
Read directory information
Set current directory
Convert from file names to file identifiers
Convert from identifiers to file names
File operations
Open file
Close fileMove access pointerGet access pointerCheck file end
Convert from byte length to sector length
Get file size
Get file information
Return-Upon-Completion Loading
File batch read
Read data
Immediate-Return Reading
Start reading data
Start pre-read to CD buffer
Check completion of access operation
Stop access operation
Get current access status
Execute access in file units
Execute multiple file access operation
Read Parameter Settings
Get (fetch) mode setting (resident/destructive)
Transfer mode setting (software, DMA, etc.)
Amount read to CD buffer setting
Amount transferred from CD buffer setting
Other
Move the CD pickup
Error processing function settings
Get error statusnti
al

8.0 Function Specifications

8.1 Directory Control

Syntax
Input

Function
Initialize file system: mountSint32Function Name
GFS_Init

No.
1.1

nti
al

Title
Function specification

GFS_Init(Sint32 open_max, void *work, GfsDirTbl *dirtbl)

dirtblDirectory control structure
NULL

Directory control functions used
Directory control by this library
Directory control of CD block file system

Work must be positioned in 4-byte boundaries. The CD block initialization flag,
standby time, ECC time and number of retries do not change.

Title
Function specification

nfi

Note:

de

open_max : maximum number of files that can be opened at one
time (1 to 24)
work: work area for library
dirtbl: directory information control structure
Outputdirtbl: directory information control structure (directory
information storage area)
Function value Number of directories read. A negative error code is returned when an error occurs.
Function
Initializes the file system and mounts CD ROM's. The directory control function is
specified by dirtbl.

Function
Read directory information

No.
1.2

GFS_LoadDir(Sint32 fid, GfsDirTbl *dirtbl): directory file identifier: directory information control structure
Output: directory information control structure (directory
information storage area)
Function value Number of directories read. A negative error code is returned when an error occurs.
FunctionReads directory information from the specified directory file. The storage destinationof the directory information will change according to the specification by dirtbl.

Co

Syntax
Input

Sint32fid
dirtbldirtblFunction NameGFS_LoadDir

SE

GA

dirtblDirectory information storage area
Directory control structure
Directory information storage area of dirtbl
NULL
File control information area in CD block
When NULL is specified for dirtbl, an error will result if use of the CD block filesystem is not declared with GFS_Init.
However, it is always possible to pass a pointer to an appropriate directory
information control structure other than NULL to dirtbl.

User's Guide 1 CD Library33

Function
Set current directory

Function NameGFS_SetDir

No.
1.3

nti
al

Title
Function specification

SyntaxSint32 GFS_SetDir(GfsDirTbl *dirtbl)
Input
dirtbl: directory information control structure
Outputnone
Function value Error code
Function
Sets the specified directory information to the current directory. The directory
information used by the dirtbl specification changes.
dirtblDirectory control structure
NULL

Directory information used
Contents of dirtbl
File control information in CD block

Function
Convert from name to file identifier

Function Name
GFS_NameToId

nfi

Title
Function specification

deWhen NULL is specified for dirtbl, an error will result if use of the CD block filesystem is not declared with GFS_Init.
However, it is always possible to pass a pointer to an appropriate directory
information control structure other than NULL to dirtbl.

No.
1.4

Title
Function specification

Co

SyntaxSint32 GFS_NameToId(Uint8 *fname)
Input
fname
: file nameOutputnone
Function value File identifier. A negative error code is returned when an error occurs.
Function
Returns a file identifier corresponding to the file name.

Function
Convert from identifier to file name

Function Name
GFS_IdToName

No.
1.5

SE

GA

Syntaxconst Uint8 *GFS_IdToName(Sint32 fid)
Input
fname
: file identifier
Outputnone
Function value Pointer to file name. NULL when an error occurs.
Function
Returns a pointer to the file name corresponding to the file identifier. This point
specifies the conversion table area used by this library.

34

8.2 File Operations
FunctionOpen file

Function NameGFS_OpenNo.
2.1

Function Name
GFS_Close

No.
2.2

nti
al

Title
Function specification

SyntaxGfsHn GFS_Open(Sint32 fid)
Input
fid
file identifier
Outputnone
Function value File handler. NULL is returned in the case of an error.
Function
Opens the specified file and returns the file handler.

Function
Close file

de

Title
Function specification

nfi

Syntaxvoid GFS_Close(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value none
Function
Closes the specified file handle.

Title
Function specification

Function
Move access pointer

Function NameGFS_SeekNo.
2.3

Sint32 GFS_Seek(GfsHn gfs, Sint32 off, Sint32 org)
gfs
: file handle
off: amount access point is moved (unit: sector)org: reference for moving (seek mode: GFS_SEEK_-)
Outputnone
Function value Position of access point after moving. A negative error code is returned if there is anerror.
Function
The access pointer is moved to a position off sectors from org. If movement to a
position past the file end is specified, the access pointer is moved on the assumptionthat the file exists up to that position.

Co

Syntax
Input

Function
Get access pointer

GA

Title
Function specification

Function Name
GFS_Tell

No.
2.4

SE

SyntaxSint32 GFS_Tell(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value Position of access pointer. A negative error code is returned if there is an error.
Function
Gets the position of the access pointer.

User's Guide 1 CD Library35

Function
Check file end

Function Name
GFS_IsEof

No.
2.5

nti
al

Title
Function specification

Title
Function specificationdeSyntax
Bool GFS_IsEof(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value file end flag
Function
Checks whether or not the access pointer has reached the end of a file. The function
values have the following meanings.
TRUE:
reached file end
FALSE: has not reached file end
If an incorrect file handle is entered, then it is considered that the file end has beenreached.

Function
Convert from byte size to sector length

Function NameGFS_ByteToSct

No.
2.6

nbyte + sector length of file - 1
file sector lengthCo

nsct =

nfi

Sint32 GFS_ByteToSct(GfsHn gfs, Sint32 nbyte)
gfs: file handle
nbyte: number of bytes
Outputnone
Function value Number of sectors; returns a negative error code when an error occurs.
Function
Converts the unit from byte to sector (nsct). The length nsct of the sector unit isobtained by the following equation.

SyntaxInput

In cases in which the sector length is not defined (Form1 and Form2 are mixed), then"0" is returned.

Title
Function specification

Function
Get file size

Function Name
GFS_GetFileSize

No.
2.7

void GFS_GetFileSize(GfsHn gfs, Sint32 *sctsize, Sint32 *nsct,
Sint32 *lastsize)
Input
gfs
: file handle
Outputsctsize: number of sectors
nsct: number of sectors (does not include last sector)
Function value none
Function
Gets information for seeking the file size. If NULL is specified for sctsize, nsct andlastsize, the output of the information can be suppressed. The file size is obtained by
the following equation.

GA

Syntaxfsize = sctsize * (nsct - 1) + lastsize:

When lastsize for the file of form2 is 2048 bytes, then it must be processed as the last
sector having 2324 bytes of data.

SE

Note:

36

Function
Get file information

Function Name
GFS_GetFileInfo

No.
2.8

nti
al

Title
Function specification

void GFS_GetFileInfo(GfsHn gfs, Sint32 *fid, Sint32 *fn,)
Sint32 *fsize, Sint32 *atr
Input
gfs
: file handle
Outputfid: file identifierfn: file number
fsize: file size (unit: byte)
atr: attribute
Function value none
Function
Gets file information. If NULL is specified for fid, fn, fsize and atr, the output of theinformation can be suppressed. The file size is recorded in the directory information,and therefore the size of one sector is calculated as 2048 bytes.

8.3 Return-Upon-Completion Read

Syntax
Input

Function
Batch load a file

Sint32Function NameGFS_Load

No.
3.1

nfi

Title
Function specificationdeSyntaxGFS_Load(Sint32 fid, Sint32 off, void *buf, Sint32 bsize)

SE

GA

Co

fid
: file identifier
off: offset (unit: sector)
bsize: top limit of number of data to be loaded (unit: byte)
Outputbuf: data load area
Function value Number of loaded data (unit: byte); negative error code is returned in case of error.
Function
Specifies file identifier and loads data from file. Open and close are performed within
the function.
If the file size is less than bsize, then data is loaded up to the end of the file. When
GFS_BUFSIZ_INF is specified for bsize, then data from the specified position up to
the end of the file is loaded
Note:
Buf must be located at 4-byte boundaries.
The default values for the fetch mode, transfer mode, load parameters and fetch
parameters are used.

User's Guide 1 CD Library37

Syntax
Input

Sint32Function
Load data

Function Name
GFS_Fread

No.
3.2

nti
al

Title
Function specification

GFS_Fread(GfsHn gfs, Sint32 nsct, void *buf, Sint32 bsize)

8.4 Immediate-Return Read

Syntax
Input

Sint32FunctionStart data loading

Co

Title
Function specification

nfi

de

gfs
: file handle
nsct: number of sector loaded
bsize: top limit of number of data to be loaded (unit: byte)
Outputbuf: data load area
Function value Number of bytes actually loaded.
Function
Specifies an opened file handle and loads data from the file.
Loads nsct sectors of data from the access pointer. Of the data loaded, the data up to
the maximum bsize byte are written to buf.
The access pointer advances nsct sectors.
Note:
There are restrictions on the address boundaries of buf depending on the transfer
mode.
· GFS_TMODE_SCU: no restriction· Other than above: locate at 4-byte boundaries
Even if the access pointer is outside the file range specified by the file handle, it
undergoes read processing as part of the file. Even if the number of sectors specified
straddles the file end, the specified number of sectors undergo read processing.
Regardless of the value specified by GFS_SetReadPara, the default value is used forthe read parameter.

Function Name
GFS_NwFread

No.
4.1

GFS_NwFread(GfsHn gfs, Sint32 nsct, void *buf, Sint32 bsize)

SE

GA

fid
: file handle
nsct: number of sectors loadedbsize: size of load area (unit: number of bytes)
Outputbuf: data load area
Function value error code
FunctionIssues a request for data load in response to a server function. Upon completion of
the requested access operation, the access pointer advances nsct sectors.
Note:
The same precaution as noted for GFS_Fread applies to the address boundary of buf.
Even if the access pointer is outside the file range specified by the file handle, it
undergoes read processing as part of the file. Even if the number of sectors specified
straddles the file end, the specified number of sectors undergo read processing.

38

Function
Start pre-read to CD buffer

Function Name
GFS_NwCdRead

No.
4.2

nti
al

Title
Function specification

Sint32 GFS_NwCDread(GfsHn gfs, Sint32 nsct)
gfs: file handle
nsct: number of sectors loaded
Outputnone
Function value error code
FunctionIssues requests to server function for pre-reads to the CD buffer. Completion of therequested read operation does not cause the access pointer to change.
If the following conditions are not met, the access operation for the specified filehandle is not terminated.
· The nsct sector data are transferred to the host area by the GFS_Fread function or
the GFS_NwFread function.
· The access operation is stopped by the GFS_NwStop function.
Note:
Perform the following operation to find out whether transfer to the host area by the
GFS_NwFread function after the start of a pre-read has been completed.
· Use GFS_NwGetStat to get the number of bytes transferred.
· Check if the number of bytes transferred is equal to the target number of bytes.
(If equal to the target number of bytes, then transfer is complete.)
If a pre-read is performed by the GFS_NwRead function, please take note thatcompletion of the GFS_NwFread function cannot be checked by the
GFS_NwIsCompleted function.

nfi

de

Syntax
Input

Title
Function specification

Function
Check completion of access operation

Function Name
GFS_NwIsComplete

No.
4.3

Function
Stop access operation

Function Name
GFS_NwStop

No.
4.4

GA

Title
Function specification

Co

Syntax
Bool GFS_NwIsComplete(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value status of access operation
Function
Check whether the access operation of the server function is complete. The function
values have the following meanings.
TRUE: access complete
FALSE: operation in progress

SE

SyntaxSint32 GFS_NwStop(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value Stop Point access pointer. Negative error code if an error occurs.
Function
Stops the access operation of a server function. GFS_NwExecServer continues theaccess operation on the next file.

User's Guide 1 CD Library39

Function
Get current access status

Function Name
GFS_NwGetStat

No.
4.5

nti
al

Title
Function specification

void GFS_NwGetStat(GfsHn gfs, Sint32 *stat, Sint32 *ndata)gfs: file handle
stat: current access statusndata: number of data
Function value none
Function
Used to get the access status of a server function. The meaning of data for each accessstatus is shown in the table below.
Access status
Processing
Meaning of data number
GFS_NWSTAT_NOACTNone
No meaning
GFS_NWSTAT-FREAD
Read from CD to Number of bytes read into host
host area
area
GFS_NWSTAT_CDREAD
Pre-read to CD
Number of sectors read to CD
bufferbuffer

Title
Function specificationdeSyntax
Input
OutputFunction
Execute access operation in file units

Function Name
GFS_NwExecOne

No.
4.6

Title
Function specification

Co

nfi

SyntaxSint32 GFS_NwExecOne(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value execution status (GFS_EXEC_-)
Function
This is an access server function for single files. It performs the following access tothe file handle in accordance with the access operation called immediately prior to it.
· GFS_NwFread: reads to CD buffer and transfers to host.
· GFS_NwCdRead: reads to CD buffer.

Function
Function Name
Execute access operation for multiple files GFS_NwExecServer

No.
4.7

SE

GA

SyntaxSint32 GFS_NwExecServer(GfsHn *now_gfs)
Input
none
Outputnow_gfs : file handle to be executed
Function value access server status (GFS_SVR_-)
Function
This is an access server function for multiple files. It performs the actual access(GFS_NwExecOne function) in the order in which requests were issued.
Upon completion of the access operation for one file, processing moves to the next
file.

40

8.5 Read Parameter Settings
Function
Function Name
Set get (fetch) mode (resident/destructive) GFS_SetGmode

No.
5.1

nti
al

Title
Function specification

Sint32 GFS_SetGmode(GfsHn gfs, Sint32 gmode)gfs: file handle
gmode : get (fetch) mode (GFS_GMODE_-)
Outputnone
Function value Get (fetch) mode before setting. Negative error code in the case of an error.
Function
Sets the get (fetch) mode.
Syntax
Input

FunctionSet transfer mode (software/DMA, etc.)

Function NameGFS_SetTmode

de

Title
Function specification

No.
5.2

Sint32 GFS_SetTmode(GfsHn gfs, Sint32 gmode)gfs: file handle
tmode: transfer mode (GFS_TMODE_-)
Outputnone
Function value Transfer mode before setting; a negative error code in the case of an error.
Function
Sets the method of transfer from the CD buffer.

Title
Function specification

nfi

Syntax
Input

Function NameGFS_SetReadPara

FunctionSet amount transferred from CD buffer

Function NameGFS_SetTransPara

FunctionSet amount read to CD buffer

No.
5.3

No.
5.4

GA

Title
Function specification

Co

Sint32 GFS_SetReadPara(GfsHn gfs, Sint32 cdrsize)
gfs: file handle
cdrsize : maximum amount read at one time to CD buffer(unit: sector)
Outputnone
Function value Read amount before setting; a negative error code in the case of an error.
Function
Sets the maximum value for the amount read at one time to the CD buffer.
Syntax
Input

Sint32 GFS_SetTransPara(GfsHn gfs, Sint32 tsize)
gfs: file handletsize: amount transferred at one time to a specified area
(unit: sector)
Outputnone
Function value Transfer amount before setting. Negative error code in the case of an error.
Function
Sets the amount of data transferred to the destination area in one get (fetch)
operation.

SE

Syntax
Input

User's Guide 1 CD Library41

8.6 Other
Function
Move CD pickup

Function Name
GFS_CdMovePickup

No.
6.1

nti
al

Title
Function specification

SyntaxSint32 GFS_CdMovePickup(GfsHn gfs)
Input
gfs
: file handle
Outputnone
Function value Error code
Function
Moves the CD pickup to the position of the access pointer. This is used to shorten
pickup seek time when reading from the CD with the GFS_Fread, GFS_NwFread or
GFS_NwCdRead functions.

FunctionSet error processing function

Function NameGFS_SetErrFunc

de

Title
Function specification

No.
6.2

Function
Get error status

Co

Title
Function specification

nfi

void GFS_SetErrFunc(void (*func)(GfsErrFunc func), void *obj)
func: function called when error occurs
obj: first argument of func function
Outputnone
Function value none
Function
Records the function called when an error occurs. When NULL is set to func, then noerror processing function is registered.
Syntax
Input

Function Name
GFS_GetErrStat

SE

GA

Syntaxvoid GFS_GetErrStat(GfsErrStat *stat)
Input
none
Outputstat: error
Function value none
Function
Gets the error status of the library function executed last.

42

No.
6.3

nti
al

AppendixA Utilization of Development Support Functions
A.1 Procedure for Using Memory Files
The following operations must be followed in the order shown here to use memory
files.
• Write file data

Make a file that will become the memory file and convert it to a memory file. Use
the MFCAT.EXE application to convert it to a memory file.
• Load memory file

• Load the target programde

Set the memory file in the memory area. This is done using the ICE command.
This must be done each time the contents of the memory area are destroyed.

• Declare use of the memory filenfi

Load the program file being developed to the target.

Before executing GFS_Init, the top address in memory is set to !gfsd_mmc/
GFMC_base. By doing this, the SIMM directory information is obtained with
GFS_Init. Since the initial value of !gfsd_mmc/GFMC_base is “0”, the SIMM
directory information is not referenced in this state.

Co

GFMC_base is defined as follows:
Sint8 *GFMC_base = 0;
Refer to the CD Tool Manual regarding MFCAT.EXE.

GA

A.2 Procedure for Using DOS Files
The following operations must be followed in the order shown here to use a DOS
file.
• Write corresponding table file

Make a file that becomes the DOS file and make a corresponding table file for the
filenames on the CD ROM and the file names in DOS.
• BootConfirm that the DIP switches are set to allow use of SCSI and boot the target.
• Load the target program

SE

After confirming that the IBM PC has recognized the target as a SCSI device,break the target and load the target program.

• Execute CDSIM.EXE

Execute CDSIM.EXE on the IBM PC.
See the CD Tool Manual regarding corresponding table files and CDSIM.EXE.

User's Guide 1 CD Library

43

nti
al

A.3 Precautions
The precautions that should be taken when using the development support tools arelisted below.
• When the CD ROM is not used

In order to prevent differences in programs between when they are all CD ROM
files and when they are all debugger files, information for the parent directory
and the current directory is added even when the CD ROM is not used. This
directory information which is automatically added is set as files on the CD ROM.
• Temporarily restricting access• File name access recommendeddeNormally, when both memory files and DOS files are accessed, the DIP switchesof the target are set so that the SCSI is not used in order to temporarily stop DOS
file access, and the computer is rebooted. In order to access only DOS files,
however, “0" is set in !gfsd_mmc/GFMC_base.

• Debugger file directory information

nfi

During use of debugger files, the file identifier may change due to a change in thefile structure. Therefore, the use of access by file name is recommended.
Debugger file directory information is set as follows:Co: file identifier in debugger file
:0
:0
:0

SE

GA

FAD
File number
Gap size
Unit size

44Appendix B Error Processing Methods

GFS_ERR_CDRD

ntialThe causes and remedies of the following error codes is shown below.
Cause: Read error in CD block.
Remedy: Check CD ROM hardware and CD ROM media.
GFS_ERR_CDNODISC

Cause: The CD ROM is not set in place.
Remedy: Reset the CD ROM in place.

deGFS_ERR_CDROM

Cause: A disc that is not a CD ROM has been inserted.
Remedy: Insert a disc that is a CD ROM.
GFS_ERR_DIRTBL

GFS_ERR_OPENMAX

nfi

Cause: The contents of the directory control structure are not correct.
Remedy: Check whether a value or a correct value has been set in each member of the directory control structure and whether that value iscorrect before calling GFS_Init and GFS_LoadDir.

GFS_ERR_DIR

Co

Cause: The value for the maximum number of open files is incorrect.
Remedy: Check if the specification for the maximum number of files opened
by calling GFS_Init exceeds the range of 1 to 24.
Cause: The specified file is not a directory.
Remedy: Check correspondence between file identifiers and files.
GFS_ERR_CDBFSGA

Cause: An attempt to use the CD block file system was made even though
there was no use declaration.
Remedy: If the CD block file system is to be used, then specify NULL for the
directory control area address and call GFS_Init.
If the CD block file system is not going to be used, do not specify
NULL for GFS_LoadDir and GFS_SetDir.

GFS_ERR_NONAME

SE

Cause: File names cannot be handled by the current directory.
Remedy: Specify a directory control area in which GFS_DIR_NAME has been
set to GFS_DIRTBL_TYPE and call GFS_Init or GFS_LoadDir.

GFS_ERR_NEXIST

Cause: The specified file name does not exist.
Remedy: Check if the current directory setting or the file name specification
is incorrect.

User's Guide 1 CD Library45

GFS_ERR_FID

ntial

Cause: The file identifier specification is incorrect.
Remedy: Check if the specified file identifier has exceeded the range of
GFS_DIR_NDIR of the directory control structure set in the current
directory.
GFS_ERR_HNDL

Cause: File handle is incorrect.
Remedy: Check if the function value is set of GFS_Open in the variable inwhich the file handle is stored, or that the contents of the variable
have not been destroyed.

de

GFS_ERR_SEEK

Cause: The seek location is incorrect.
Remedy: Check the seek position calculated from the reference position andthe offset.
GFS_ERR_ORG

nfi

Cause: The reference position of GFS_Seek is incorrect.
Remedy: Check to be sure the reference position is at one of GFS_SEEK_SET,
GFS_SEEK_CUR or GFS_SEEK_END.
GFS_ERR_NUM

GFS_ERR_OFS

Co

Cause: A negative number of bytes was specified.
Remedy: Check the number of bytes specified by GFS_ByteToSct.
Cause: The offset is incorrect.
Remedy: Check the read start sector position specified by GFS_Load.
GFS_ERR_FBUSY

GA

Cause: Processing of specified file handle remains to be performed.
Remedy: Correct the program so that it accesses again after completing
access of the target file, or reconsider the file structure.
GFS_ERR_PARA

Cause: Incorrect mode.
Remedy: Make sure that correct arguments are given to GFS_SetGMode,
GFS_SetTmode, GFS_SetReadPara and GFS_SetTransPara.
GFS_ERR_BUSY

SE

Cause: Multiplex processing was attempted.
Remedy: Refer to “6.3 Multiple Processing”.

46

GFS_ERR_NOHNDL

ntial

Cause: No open file handles.
Remedy: Either increase the specification for the maximum number of files
that can be opened at the same time by GFS_Init or reduce thenumber of files opened at the same time.
GFS_ERR_PUINUSE

Cause: GFS_CdMovePickup was called while the pickup was in use.
Remedy: Call GFS_CdMovePickup in a state in which file access is not being
performed.
GFS_ERR_ALIGNdeCause: The read destination of a file is not located at a word boundary.
Remedy: Position the read area at a word boundary.
GFS_ERR_TMOUT

nfi

Cause: A response was not received from the CD block in the prescribedtime period.
Remedy: Something may be wrong with the hardware.
GFS_ERR_CDOPEN

GFS_ERR_BFULCo

Cause: The tray on the CD drive is open.
Remedy: Close the tray and then continue.

SE

GA

Cause: The CD buffer becomes full and reading is stopped when the fetch
mode is GFS_GMODE_RESIDENT.
Remedy: Adjust the order of access and the amount read to prevent the CD
buffer from becoming full , when the fetch mode is
GFS_GMODE_RESIDENT.

User's Guide 1 CD Library

47

nti
al

Appendix C
This is an addition to the main part of the manual.
C.1

Additional Explanation

DOS File Parameters

C.2

Changes from the Previous Versionde

The initial value of the fetch parameters for DOS files is “1”. Since only one sector canbe transferred at a time, settings other than “1” for the fetch parameters are invalid.

1) Changes in CD Pre-read Processing• Change in how GFS_NwCdRead is used
Even if GFS_NwExecOne is not called after calling GFS_NwCdRead, pre-readfrom the CD is enabled.

nfi

When look ahead from the CD is used, either all of the specified number ofsectors is transferred to the host, or it is not terminated until access is stopped(GFS_NwIsComplete does not return TRUE).

Co• Access Complete Check (Important)Since GFS_NwCdRead is not terminated until either data transfer ends oraccess is stopped (except access of CDDA files), do not wait for termination.
As is shown in the example in the old manual, an endless loop will result if
waiting for termination of GFS_NwExecOne, so use caution.

GA

If GFS_NwFread does not perform pre-read with NwCdRead, then termination can be checked using the same procedure as in the previous version. If
pre-read from the CD is being used, then use GFS_NwGetStat to check fortermination while also monitoring the number of bytes transferred. An
example is shown below.
GfsHn
gfs;
Sint32 fid, stat, nbyte;
Uint32 buf[10*2048/4];

SE

gfs = GFS_Open(fid);
GFS_NwRead(gfs, 100)for (i = 0, i < 10; ++i) {GFSNwFread(gfs, 10, buf, 10*2048);
while (GFS_NwExecOne (gfs) != GFS_SVR_COMPLETE) {GFS_NwGetStat(gfs, &stat, &nbyte);/*checks whether number of bytes specified by GFS_NwFread has been read */if (nbyte >= 10*2048) {break;}
user();/*application processing
*/
}
}

48

nti
al

2) Addition of CDDA File Processing Function
A CDDA file processing function has been added. When a CDDA file is read, themusic track specified by that file is played. However, in order to output sound,
SCSP must be set by the application. CDDA files and regular files have thefollowing differences.
• Control of files
The only controls the file system performs on CDDA files are playback andplayback range. The playback mode is an omitted value (no repeat, moves
pickup).

de• Pre-read
Since the data from CDDA files does not enter the CD buffer, when they areaccessed, pre-read processing and normal access are equivalent.

• Parameters relating to file operation
The fetch mode, transfer mode, read parameters and fetch parameters cannot
be changed for CDDA files. An error is returned when the following functions
are called for CDDA files.

nfi

GFS_SetGmode
GFS_SetTmode
GFS_SetReadPara
GFS_SetTransPara

Co3) File attributes
The following changes were made to make the values of file attributes output by
GFS_GetFileInfo conform with the CD-ROM XA standard.
GFS_ATR_DIR
GFS_ATR_CDDA
GFS_ATR_INTLV
GFS_ATR_FORM2
GFS_ATR_FORM1
GFS_ATR_END_TBL

0x80
0x40
0x20
0x10
0x80
0x01

GA

GFS_ATR_CDD was added because of the addition of CDDA file processing
functions. Its bit are “1” in the CDDA files. Other constant names and meanings
are unchanged.

SE4) Function values of GFS_Init and GFS_LoadDir
When NULL is specified for the pointer to the directory information control
structure of an argument, the number of directories being held by the CD block
file system is returned as a function value.

User's Guide 1 CD Library

49

nti
al

5) Addition of error codes
The following error codes were added.
• GFS_ERR_BFULThis error code is generated if the CD buffer becomes full while a resident
mode (GFS_GMODE_RESIDENT) file is being read. Adjust the order ofaccess, etc., to prevent a buffer full condition during resident mode file access.

de• GFS_ERR_FATALThis error code serves notice that the CD drive is in a fatal condition. When thefile system detects this condition, CD playback is stopped (seek home position)and recovery from the error condition is attempted. If this error condition isdetected, try processing again.
6) Recognition of tray open condition
A “1” value for the DCHG bit (bit 5) of the interrupt factor register (HIRQREQ)of the CD block is also treated as a tray open condition.

nfi7) Precautions when using SCU-DMA
When the transfer mode is GFS_TMODE_SCU, the file system library uses a SCU
level 0DMA end interrupt (vector number 4B). Upon completion of transfer, theinterrupt vector and interrupt mask used are restored to their original state.

Co8) Debug file-related items• GFMC_base
The variable GFMC_base which sets the top address of the SIMM file is defined in both sega_gfs.lib and segadgfs.lib.
GFMC_base in sega-gfs.lib exists only to establish compatibility withsegadgfs.lib. It does not affect the operation of the file system.

SE

GA• File identifiers
We eliminated the function that automatically added “.” and “..” (current
directory and parent directory) when a CD file is not used. Because of this, file
identifiers agree at the time of boot up.

50