When using this document, keep the following in mind:

tialGeneral Noticeden

1. This document is confidential. By accepting this document you acknowledge that you are boundby the terms set forth in the nondisclosure and confidentiality agreement signed separately and in
the possession of SEGA. If you have not signed such a nondisclosure agreement, please contact
SEGA immediately and return this document to SEGA.
2. 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.
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.

Co

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
described 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 imply 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 :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.

(11/2/94- 002)

SE

GA

Co

nfi

de
n

tia
l

TM

Program Library
User's Guide 3
Doc. # ST-135-R4-092295© 1995-96 SEGA. All Rights Reserved.

tial

READER CORRECTION/COMMENT SHEETGeneral Information:
Your Name

Phone

Document number

ST-135-R4-092295

Document name

Program Library User's Guide 3

Date

Corrections:pg. #Correction

GA

Co

nfi

Chpt.

de
n

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

SE

Questions/comments:

Fax:

Where to send your corrections:(415) 802-1717
Attn: Evelyn Merritt,
Developer Technical Support

Mail:

SEGA OF AMERICA
Attn: Evelyn Merritt,
Developer Technical Support
150 Shoreline Dr.
Redwood City, CA 94065

tialTable of Contents
Sound Interface Library......................................................................................

2.0

6
Guide .................................................................................................................................................6
1.1 Objective .................................................................................................................................. 6
1.2 Overview .................................................................................................................................. 6
1.3 Sound System Startup .............................................................................................................6
1.4 Performance Setup .................................................................................................................. 7
1.5 Sound Control .......................................................................................................................... 7
1.6 Status Acquisition .................................................................................................................... 8
Reference ..........................................................................................................................................9
2.1 Data List ................................................................................................................................... 9
2.2 Data Specifications ................................................................................................................ 10
2.3 List of Functions ..................................................................................................................... 20
2.4 Function Specifications .......................................................................................................... 21

de
n

1.0

DMA Library......................................................................................................

nfi

2.0

32
Guide ...............................................................................................................................................32
1.1 Objective ................................................................................................................................ 32
1.3 Precautions ............................................................................................................................ 32
1.4 Calling Sequence ................................................................................................................... 33
Reference ........................................................................................................................................34
2.1 Data List ................................................................................................................................. 34
2.2 Data Specifications ................................................................................................................ 35
2.3 List of Functions ..................................................................................................................... 41
2.4 Function Specifications .......................................................................................................... 42

Co

1.0

Cache Library....................................................................................................

2.0

50
Guide ...............................................................................................................................................50
1.1 Objective ................................................................................................................................ 50
1.2 Overview ................................................................................................................................ 50
Reference ........................................................................................................................................51
2.1 List of Functions ..................................................................................................................... 51
2.2 Function Specifications .......................................................................................................... 51
2.3 List of Function Format Macros ............................................................................................. 52
2.4 Function Format Macro Specification .................................................................................... 52

GA

1.0

Interrupt Management Library............................................................................
1.0

SE

2.0

55
Guide ...............................................................................................................................................55
1.1 Objective ................................................................................................................................ 55
1.2 Overview ................................................................................................................................ 55
1.3 Overview of Functions ........................................................................................................... 55
1.4 Usage Conditions .................................................................................................................. 55
1.5 Calling Sequence ................................................................................................................... 56
Reference ........................................................................................................................................57
2.1 Data List ................................................................................................................................. 57
2.2 Data Specifications ................................................................................................................ 58
2.3 List of Functions ..................................................................................................................... 61
2.4 Function Specifications .......................................................................................................... 62

4

Memory Management Library.............................................................................

2.0

66
Guide ...............................................................................................................................................66
1.1 Objective ................................................................................................................................66
1.2 Overview ................................................................................................................................66
1.3 Calling Sequence ...................................................................................................................66
Reference ........................................................................................................................................67
2.1 List of Functions .....................................................................................................................67
2.2 Function Specifications ..........................................................................................................67

tia
l

1.0

Timer Library.....................................................................................................

2.0

69
Guide ...............................................................................................................................................69
1.1 Objective ................................................................................................................................69
1.2 Overview ................................................................................................................................69
1.3 Detailed Information ...............................................................................................................70
Reference ........................................................................................................................................72
2.1 List of Function Format Macros .............................................................................................72
2.2 Function Specifications ..........................................................................................................73

de
n

1.0

Debug Support Library......................................................................................

2.0

81
Guide ...............................................................................................................................................81
1.1 Objective ................................................................................................................................81
1.2 Description .............................................................................................................................81
1.3 Coding Example .................................................................................................................... 81
Reference ........................................................................................................................................82
2.1 List of Functions .....................................................................................................................82
2.2 Function Specifications ..........................................................................................................82

nfi

1.0

Compression Decompression Library................................................................

GA

Co

86
Terminology ................................................................................................................................................86
1.0
Guide ...............................................................................................................................................87
1.1 Application .............................................................................................................................87
1.2 Compression Method .............................................................................................................87
1.3 Decompression Library ..........................................................................................................92
2.0
Reference ........................................................................................................................................96
2.1 Data Specifications ................................................................................................................ 96
2.2 List of Functions .....................................................................................................................97
2.3 Function Specifications ..........................................................................................................98

PCM-ADPCM Playback Library.........................................................................
1.0

SE

2.0
3.0
4.0
5.0

102
Overview ........................................................................................................................................102
1.1 Objective ..............................................................................................................................102
1.2 Features ...............................................................................................................................102
1.3 System Image ......................................................................................................................103
Specifications ................................................................................................................................ 104
Playback Sequence ....................................................................................................................... 107
Programming Precautions .............................................................................................................109
Data Specifications ........................................................................................................................ 111
5.1 List of Data ........................................................................................................................... 111
5.2 Data Details ......................................................................................................................... 112
Functions Specifications ................................................................................................................ 118
6.1 List of Functions ................................................................................................................... 118
6.2 Function Details ...................................................................................................................120

6.0

INDEX .............................................................................................................

Program Library User's Guide 3

131
5

tia
l

Sound Interface Library
1.0 Guideden

1.1 Objective
The Sound Interface Library interfaces the sound sub-system and the main hardware
system (including the CD system), and enables control over sound playback and related
processes.
1.2 Overview

Co• Sound system startup• Performance setup• Sound control• Status acquisitionnfi

The sound sub-system controls the playback of song sequences, PCM audio and CD
audio. The sound system must be activated before the sound playback can be controlled. Sound data must then be transferred to the sound memory as a performance
setup for song sequences and PCM audio. The resulting sound control is monitored bystatus information provided by the library. This chapter explains the details of theSound Interface Library in the order shown in the following list. For more information,
see also the sound driver system interface in the Sound Development Manual (ST-081-R5062894).

1.3 Sound System Startup

The sound system must be started at power on. The calling sequence is as follows.

data area for system startup

GAvoid sndStart (){SndIniDt sys_ini; /**/SE

SND_INI_PRG_ADR(sys_ini) = (Uint16 *) 0x22002400 ;/* set 68K program area start address*/
SND_INI_PRG_SZ(sys_ini) = (Uint16 *) 0x4fc8 ;/* set 68K program size*/
SND_INI_ARA_ADR(sys_ini) = (Uint16 *) 0x22004400 ;/* set sound area map area start address*/
SND_INI_ARA_SZ(sys_ini) = 0x0550 ;/* set sound area map size (word specified) */SND_Init (&sys_ini) ; /* startup sound system
*/
. . .

}

6

tia
l

1.4 Performance Setup
SequencedenSequence data (song data, sound effect data), executed by sound control functions, mustbe transferred to the sound memory. Transfers must be performed according to thecurrent sound area map. (For more information about the sound area map, see theSound Development Manual.) The calling sequence is shown in the Sound Control section
below.
PCM

Refer to the information on the sound driver system interface in the Sound Development
Manual for setting up PCM performances.
1.5 Sound Control
Functions

Enables control such as playback start/end and volume settings over song sequences.
Enables playback start and end of PCM data.
Enables control such as volume/pan settings, volume analysis, and effect changes overCD audio data.

Calling SequenceCo• Sequence:• PCM:• CD:

nfi

The sound control function writes commands to the sound memory. There are eightcommand buffers. The sound control function can be used without the need to monitor
the command buffer.

The following calling sequence is used until the start of a song sequence.

*/
*/
*/
*/
*/
*/

SE

GA

void sndCnt(){
sndStart;/* sound system startup (see item above)
SND_ChgMap (2) ;/* change sound area map
SND_MoveData((Uint16 *)0x22005000, 0xffff, SND_KD_SEQ, 2);/* sound data transfer(sequence)
SND_MoveData((Uint16 *)0x22005500, 0xffff, SND_KD_TONE, 2);/* transfer sound data (tone)
SND_SetT1V1(15) ;/* Set master volume
SND_StartSeq(0, 2, 5, 0) ;/* start sequence. . .
}Program Library User's Guide 3

7

tia
l

1.6 Status Acquisition
Functions

The following provides an overview of functions by sound data type:
Enables acquisition of current status (play, pause, etc.).
Enables acquisition of current PCM data address being used.
Enables acquisition of volume analysis results.

den• Sequence:• PCM:• CD:

Calling Sequence

The following calling sequence starts another sequence under sound control number 0 if
a sound control number 0 sequence has stopped.

SE

GA

Co

nfi

void sndHantei(){
SndSeqStat status;/* define sequence status area*/
. . .
SND_GetSeqStat (&status, 0);/* get sequence status*/
if(SND_SEQ_STAT_MODE(status) == SND_MD_STOP){/* is sequence under sound control number 0 stopped? */SND_StartSeq (0, 2, 6, 0) ;/* start sequence
*/
}
}

8

tia
l

2.0 Reference
2.1 Data List
Data TypeSndIniDt

1

Sound area map number data type

SndAreaMap

2

Total volume data type

SndTlVl3

SndEfctBnkNum

4

SndToneBnkNum

5

SndMixBnkNum

6

SndEfctOut

7

SndLev

8

Effect bank number data type
Tone bank number data type
Mixer number data type
Effect out select data typeLevel data type

9

SndRet10

Hardware check parameter data type

SndHardPrm

11

Hardware check status data type

SndHardStat

12

Sound control number data type

SndSeqNum

13

Sequence bank number data type

SndSeqBnkNum

14

Sequence song number data type

SndSeqSongNum

15

Priority level data type

SndSeqPri

16

Sequence volume data type

SndSeqVl

17

Fade rate data type

SndFade18

Tempo data type

SndTempo

19

Sequence status data type

SndSeqStat

20

Sound control no. play position data type

SndSeqPlayPos

21

PCM start parameter data type

SndPcmStPrm

22

PCM change parameter data type

SndPcmChgPrm

23

PCM play address data typeCo

SndPcmPlayAdr

24

PCM address update interrupt status data SndPcmIntStat
type

25

Volume analysis data type

SndCdVlAnl

26

Discrete frequency band stereo volume
analysis data type

SndCdHzSrVl

27

SE

GA

PCM

CD

SndPanCommand execution status data typenfi

Pan data type

Sequence

Number

System startup data typedenCommonData Name

Program Library User's Guide 3

9

tia
l

2.2 Data Specifications• Common
Title

Data

Data NameNo.

Data Specifications

System start data typeSndIniDt1denThis data type indicates the transfer source of data required by the sound system.
The transfer destination is the sound memory (fixed). Set each of the following:• Address
Refer to the link map file and set the address.
• SizeSet the size of the 68K program object file and the sound area map object file.
Access Macro
SndIniDt sys_ini
TypeUint16*

68K program start address

Description

SND_INI_PRG_SZ (sys_ini)

Uint16

68K program start size

SND_INI_ARA_ADR (sys_ini)

Uint16*

Sound area map start address

SND_INI_ARA_SZ (sys_ini)

Uint16

Sound area map size (word specified)

Co

nfi

Access Macro

SND_INI_PRG_ADR (sys_ini)

Title

Data

Data Specifications

Sound area map data type

Data NameNo.

SndAreaMap

2This data type displays the sound area map.
Description of V
alues

Description

GA

Value

SE

0 ~ 255

10

ArbitraryData

Data Name

Data Specifications

Total volume data type

SndTlVl

This data type denotes the total volume.
Description of Values
Value

Description

0 is OFF, 15 is the maximum

Title

Data

Data Specifications

Effect bank number data typeThis data type indicates the effect bank number.
Description of Values

Data NameNo.

SndEfctBnkNum

4

Description

0 ~15

Arbitrary

nfi

Value

3

de
n

0 ~15

No.

tia
l

Title

Data

Data Specifications

Sound tone bank number data type

Data NameNo.

SndToneBnkNum

5

Co

Title

This data type denotes the tone bank number.
Description of Values
Value

Description

Title

Arbitrary

GA

0 ~15

Data Specifications

Data

Data NameNo.

Mixer number data type

SndMixBnkNum

6This data type shows the mixer number.
Description of Values
Value

ArbitrarySE

0 ~127

Description

Program Library User's Guide 3

11

Data

Data Name

Data Specifications

Effect out select data type

SndEfctOut

This data type denotes the effect out selection setting.
Description of Values
Value

Description

Arbitrary

Title

Data

Data Specifications

7

de
n

0 ~15

No.

tia
l

Title

Level data typeThis data type denotes the level.
Description of Values

No.

SndLev

8

Description

0~7

Arbitrary

Data

Data Specifications

Pan data type

Data NameNo.

SndPan

9

Co

Title

nfi

Value

Data Name

This data type shows pan. To pan the sound from left to right, increment up from - 15.
Description of Values↑, ↓ : Adjust the volume in the direction of the arrow.
Value

Description

Left

MaximumOFF-14 to -1

Maximum↓

0

Maximum

Maximum

0 to 14↑

Maximum

15

OFF

Maximum

GA

- 15

SE
12

Right

Data

Data Name

Data Specifications

Command execution status data type

SndRetThis data type indicates the command execution condition.
Constant

Description

No.

tia
l

Title

Command normal end (command was set)

SND_RET_NSET

Command abnormal end (command was not set)den

SND_RET_SET

10

Title

Data

Data Specifications

Hardware check parameter data type

Data NameNo.

SndHardPrm

11

This data type denotes the hardware check parameters.
Constant

Description

DRAM 4 Mbit read/write

SND_DRAM8DRAM 8 Mbit read/write

SND_SCSP_MIDISCSP MIDI

SND_SOUND_SRC_LR

Sound generator output (L/R)

SND_SOUND_SRC_L

Sound generator output (L)

SND_SOUND_SRC_R

Sound generator output (R)

Co

nfi

SND_DRAM4

Title

Data

Data Specifications

Hardware check status data type

Data NameNo.

SndHardStat

12

This data type denotes the hardware check status.

GA

Constant

NormalSND_HARD_ERR

AbnormalDescriptionSE

SND_HARD_OK

Program Library User's Guide 313Sequence

tia
l

•

Title

Data

Data NameNo.

Data Specifications

Sound control number data type

SndSeqNum

13

This data type indicates the sound control number.
Description of Values
Description

de
n

Value

0 ~7

Arbitrary

Title

Data

Data Specifications

Sequence bank number data type

Data NameNo.

SndSeqBnkNum

14

Description of Values
Value

nfi

This data type denotes the sequence bank number.

Description

0 ~15

Arbitrary

Data

Data Specifications

Sequence song number data type

Co

Title

Data NameNo.

SndSeqSongNum

15

This data type denotes the sequence song number.
Description of Values
Value

Description

Title

ArbitraryGA

0 ~255

Data Specifications

Data

Data Name

No.

Priority level data type

SndSeqPri

16

This data type denotes the priority level.
Description of Values

SE

Value

0 ~7

14

Description

0 is the highest priority level and 7 is the minimumData

Data NameNo.

Data Specifications

Sequence volume data type

SndSeqVI

17

This data type denotes the sequence volume.
Description of Values
Value

Description

0 is off, 127 is the maximum (source sound level)

Title

Data

Data Specifications

Fade rate data typeThis data type denotes the fade rate.
Description of Values
Value

de
n

0 ~127

tia
l

Title

Data NameNo.

SndFade18

Description

Fade rate is disabled

1 ~255Longest at 1, shortest at 255

Data

Data Specifications

Tempo data type

Data NameNo.

SndTempo

19

Co

Title

nfi

0

This data type denotes the tempo.
Description of Values
Value

Relative value in terms of the present value+ is Up and - is Down
Up 2X at +4096, Down 2X at -4096

SEGA+32767 ~ -32768

Description

Program Library User's Guide 3

15

Data

Data NameNo.

Data Specifications

Sequence status data type

SndSeqStat

20

This data type indicates the sequence status.
SndSeqStat

StatusType

Uint16Song mode

SND_SEQ_STAT_STAT(status)

Uint16Song status

SND_SEQ_STAT_MODE(status)
Constant

DescriptiondenAccess Macro

SND_SEQ_STAT_MODE(status)

tia
l

Title

Description

Stop

SND_MD_PLAY

Play

SND_MD_FADE

Fade

SND_MD_PLAY_PS

Play pause

SND_MD_FADE_PS

Fade pause

SND_SEQ_STAT_STAT(status)
Value (Hexadecimal)

nfi

SND_MD_STOP

Description

Normal01 ~ 7F

Error code

80 ~ FF

Timing flag

Co

00

Title

Data

Data Name

Data Specifications

Sound control number play position data SndSeqPlayPos
type

This data type denotes the sound control number play position.

GA

Description of Values
Value (Hexadecimal)SE

0 ~FFFF

16

0 ~FFFF

Description

No.

21

tia
l

• PCM
Title

Data

Data Name

Data Specifications

PCM start parameter data type

SndPcmStartPrm 22

This data type denotes the PCM start parameters.
prm

Access MacroType

Descriptionden

SndPcmStPrm

No.

SND_PRM_MODE(prm)

Uint8

Stereo and mono + sampling rate

SND_PRM_SADR(prm)Uint16

PCM stream buffer start address

SND_PRM_SIZE(prm)Uint16

PCM stream buffer size

SND_PRM_OFSET(prm)

Uint8

PCM stream play start offset

SND_PRM_MODE(prm)Specify the following constants by logical OR.
Constant

SND_MD_MONO

Mono

SND_MD_STEREO

Stereo

SND_MD_16

16-bit PCM

SND_MD_8

8-bit PCM

Co

Sampling rate selection bit

SND_PRM_SADR(prm)Value (Hexadecimal)

0000 ~ FFFF

SND_PRM_SIZE(prm)Description

PCM stream buffer start address(upper 16 bits of 20 bit data)

Value (Hexadecimal)

Description

PCM stream buffer size
(number of samples for 1 channel)

GA0000 ~ FFFF

Description

nfi

Bit Position

Mono/stereo select bit

SND_PRM_OFSET(prm)Value (Hexadecimal)

PCM stream play start offset (0000 ~ F000)

SE

0~F(1000 [4k sample] units)

Description

Program Library User's Guide 3

17

Data

Data NameNo.

Data Specifications

PCM change parameter data type

SndPcmChgPrm

23This data type denotes the PCM change parameters.
SndPcmChgPrm prm
Access MacroType

Description

tia
l

Title

SndPcmNum

PCM stream play number

SND_PRM_LEV(prm)

SndLev

Direct sound level

SND_PRM_PAN(prm)SndPanDirect sound pan

SND_PRM_PICH(prm)

Uint8

PICH word

SND_R_EFCT_IN(prm)

SndEfctIn

Effect in selectSND_R_EFCT_LEV(prm)

SndLev

Effect send level

SND_L_EFCT_IN(prm)

SndEfctIn

Effect in selectLeft output

SND_L_EFCT_LEV(prm)

SndLev

Effect send level(invalid for mono)den

SND_PRM_NUM(prm)nfiRight output (mono)

The following constants and values can be used by each access macro.
SND_PRM_NUM(prm)Value

Description

PCM stream play number

SND_PRM_PICH(prm)

Co

0 ~7

Refer to the PICH register section in the Saturn SCSP User’s Manual(ST-077-R2-052594).
Title

Data

Data Specifications

PCM play address data type

Data NameNo.

SndPcmPlayAdr

24

GA

This data type denotes the PCM play address.
SndPcmPlayAdr(prm)

Access Macro

Description

SND_PCM_RADR(prm)

Uint8

Right output (mono)

SND_PCM_LADR(prm)

Uint8

Left output

SE
18

Type

Data Specifications

Data

Data NameNo.

PCM address update interrupt status
data type

SndPcmIntStat

25

tia
l

Title

This data type indicates the PCM address update interrupt status. The following
bit position constants can be specified by OR.
Bit Position Constant

Description

PCM playback number 0

SND_PCM_PLAY1

PCM playback number 1

SND_PCM_PLAY2

PCM playback number 2

SND_PCM_PLAY3

PCM playback number 3

SND_PCM_PLAY4

PCM playback number 4

SND_PCM_PLAY5

PCM playback number 5

SND_PCM_PLAY6

PCM playback number 6

SND_PCM_PLAY7

PCM playback number 7den

SND_PCM_PLAY0

Title

nfi

• CD
Data

Data Specifications

Volume analysis volume data type

Data NameNo.

SndCdVlAnl

26

Description of Values
Value

Description

0 ~32767
Title

0 is OFF, 32767 is maximum

Data

Data Specifications

Co

This data type denotes the analysis volume.

Discrete frequency band stereo volume
analysis data type

Data NameNo.

SndCdHzSrVl

27

GA

This data type denotes the discrete frequency band stereo volume analysis data.
In the case of monaural, the same values are entered in left and right outputs.
SndCdHzSrVl

hz_vl

Access MacroType

Description

SND_CD_LHIGH (hz_vl) SndCdVlAnl

Treble analysis volume

SND_CD_LMID (hz_vl)

SndCdVlAnl

Midrange analysis volume

SND_CD_LLOW (hz_vl)

Bass analysis volume
Treble analysis volume

SND_CD_RMID (hz_vl)

SndCdVlAnl

Midrange analysis volume

SND_CD_RLOW (hz_vl)

SndCdVlAnl

Bass analysis volume

SE

SndCdVlAnl

SND_CD_RHIGH (hz_vl) SndCdVlAnl

Program Library User's Guide 3

Left output

Right output

19

Function

Name

No.

Start sound system

SND_Init

1

Interrupt

Set interrupt enable

SND_SET_ENA_INT

2

Get interrupt enable

SND_GET_ENA_INT

3

Set interrupt source

SND_SET_FCT_INT

4

Reset interrupt

SND_RESET_INT

5Transfer sound data

SND_MoveData

6

Change sound area map

SND_ChgMap

7

Set total volume

SND_SetTlVl

8

SND_ChgEfct

9

SND_ChgMix

10

Change mixer parameters

SND_ChgMixPrm

11

Check hardware

SND_ChkHard

12

Start sequence

SND_StartSeq

13

Stop sequence

SND_StopSeq

14

Pause sequence

SND_PauseSeq

15

Continue sequence

SND_ContSeq

16

Set sequence volume

SND_SetSeqVl

17

Change tempo

SND_ChgTempo

18

Direct MIDI control

SND_CtrlDirMidi

19

Start PCM

SND_StartPcm

20

Stop PCM

SND_StopPcm

21

PCM change

SND_ChgPcm

22

Start volume analysis

SND_StartVlAnl

23

Stop volume analysis

SND_StopVlAnl

24

Set CD-DA level

SND_SetCdDaLev

25

Set CD-DA pan

SND_SetCdDaPan

26

Get sequence status

SND_GetSeqStat

27

Get sound control number playposition

SND_GetSeqPlayPos 28

Get PCM execute address

SND_GetPcmPlayAdr 29

Get PCM address update
interrupt status

SND_GET_INT_STAT30

Get total stereo volume analysis

SND_GetAnlTlVl

31

Get discrete frequency bandstereo volume analysis

SND_GetAnlHzVl

32

Sound control

CommonChange effectCo

Sequencenfi

Change mixerdenStart sound system

Performance setup

PCM

GA

CD

Status Acquisition

Sequence

SE

PCM

20

tia
l

2.3 List of Functions

CD• Start Sound Systemtial

2.4 Function Specifications

Title

Function

Function Name

No.

Function Specifications

Start sound system

SND_Init

1

Remarks:

void SND_Init(SndIniDt *sys_ini)
sys_ini : Data for system startup
None
None
The sound system is started up based on the specified system startup data. Startup
occurs after the program and sound area map data are transferred and the hardware
registers are initialized. For more details, see the Sound Driver System Interface
section of the Sound Development Manual.
SCU DMA transfer is used for these transfers.

denFormat:Input:
Output:Function Value:
Functionnfi• Interrupt
Title

Function

Function Specifications

Set interrupt enable

No.

SND_SET_ENA_INT

2void SND_SET_ENA_INT(Uint8 data)
data:
Interrupt enable bit (1= enabled, 0= disabled)
Constant

Co

Format:Input:

Function Name

Bit Position Constant

Description

SND_INT_PCM_ADR

PCM address interrupt

SE

GA

Output:None
Function Value: None
Function:
Enables interrupts. This setting enables or disables the interrupt signal from thesound system. This setting does not mask SCU interrupts.

Program Library User's Guide 3

21

tia
l

Title

Function

Function Name

No.

Function Specifications

Get interrupt enable

SND_GET_ENA_INT

3

Format:Input:
Output:Uint8 SND_GET_ENA_INT(void)
None
Interrupt enable bit (1= enabled, 0= disabled)denConstant
Bit Position Constant

Description

SND_INT_PCM_ADR

PCM address interrupt

Function Value: None
Function:
Gets interrupt enable.

Function

Function Specifications

Set interrupt source

Format:Input:
Output:Function Name

nfi

Title

SND_SET_FCT_INT

No.

4

Constant

Co

Uint8 SND_SET_FCT_INT(void)
None
Interrupt enable bit

Bit Position Constant

Description

SND_FCT_PCM_ADR

PCM address update

Title

GA

Function Value: None
Function:
Sets the interrupt source.

Function Specifications

22

Function Name

No.

Reset interrupt

SND_RESET_INT

5void SND_RESET_INT(void)
None
None
None
Resets interrupt. Execute after a sound interrupt occurs. If this function is not
executed, the interrupt remains asserted.

SE

Format:Input:
Output:Function Value:
Function:

Functiontial• Performance Setup
Title

Function

Function Name

No.

Function Specifications

Transfer sound data

SND_MoveData

6

Format:Input:

Constant
Description

SND_KD_TONE

Tone bank data

SND_KD_SEQ

Sequence data

SND_KD_DSP_PRG

DSP program

SND_KD_DSP_RAM

DSP work RAM

nfi

Bit Position Constantdenvoid SND_MoveData(Uint16 *source, Uint32 size, Uint16
data_kind, Uint16 data_no)source: Sound data transfer source address
size: Transfer size (byte units)
data_kind: Data type
data_no: Data number

SE

GA

Co

Output:None
Function Value: None
Function:Transfers sound data to the sound memory according to the map information that
corresponds to the specified data type and number.
Remarks:
SCU DMA transfer is used in transferring data.

Program Library User's Guide 3

23

tia
l

• Sound Control
CommonTitle

Function

Function Name

No.

Function Specifications

Change sound area map

SND_ChgMap

7

SndRet SND_ChgMap(SndAreaMap area_no)area_no : Sound area map number
None
Command execution status
Changes the current sound area map to the sound area map indicated by
the sound area map number.

Title

Function

Function Specifications

Set total volume

Function NameNo.

SND_SetTlVl8

nfi

SndRet SND_SetVlTl(SndTlVl vol)vol: Total volume
None
Command execution status
Changes the total volume.
Affects only sequence and PCM.

Co

Format:Input:
Output:Function Value:
Function:
Remarks:denFormat:Input:
Output:Function Value:
Function:

Title

Function

Function Name

No.

Function Specifications

Change effect

SND_ChgEfct

9

Title

SndRet SND_ChgEfct(SndEfctBnkNum efct_no)
efct_no : Effect bank number
None
Command execution status
Executes the DSP program denoted by the effect bank number.

GA

Format:Input:
Output:Function Value:
Function:

Function Specifications

Format:Function

Function Name

No.

Change mixer

SND_ChgMix

10

SE

SndRet SND_ChgMix(SndToneBnkNum tone_no, SndMixBnkNum
mix_no)Input:
tone_no : Tone bank number
mix_no: Mixer number
Output:None
Function Value: Command execution status
Function:
Changes mixers.

24

Function

Function Name

Function Specifications

Change mixer parameters

SND_ChgMixPrm

No.

tia
l

Title

Format:11

Title

Function

Function Specifications

Check hardware

Function NameNo.

SND_ChkHard

12

nfi

SndRet SndChkHard(SndHardStat *stat, SndHardChk prm)prm
: Hardware check parameters
stat: Hardware check status
Command execution status
Checks hardware according to hardware parameters.

SE

GA

Co

Format:Input:
Output:Function Value:
Function:den

SndRet SND_ChgMixPrm(SndEfctOut efct_out SndLev level,
SndPan pan)
Input:
efct_out : Effect out selectlevel: Effect return levelpan: Effect PAN
Output:None
Function Value: Command execution status
Function:
Changes mixer parameters.

Program Library User's Guide 3

25

tia
l

Sequence
Title

Function

Function Name

No.

Function Specifications

Start sequence

SND_StartSeq

13

Format:Title

Function

Function Specifications

Stop sequenceNo.

SND_StopSeq

14

nfi

Title

Function

Function Name

No.

Function Specifications

Pause sequence

SND_PauseSeq

15

Title

SndRet SND_PauseSeq(SndSeqNum seq_no)
seq_no: Sound control number
None
Command execution status
Pauses the selected sequence.

GA

Format:Input:
Output:Function Value:
Function:

Function Specifications

Function

Function NameNo.

Continue sequence

SND_ContSeq

16

SndRet SND_ContSeq(SndSeqNum seq_no)
seq_no: Sound control number
None
None
Cancels pause of the selected sequence.

SE

Format:Input:
Output:Function Value:
Function:26

Function Name

SndRet SND_StopSeq(SndSeqNum seq_no)
seq_no: Sound control number
None
Command execution status
Stops the specified sequence.

Co

Format:Input:
Output:Function Value:
Function:den

SndRet SND_StartSeq(SndSeqNum seq_no, SndSeqBnkNum seq_bk_no,
SndSeqSongNum song_no, SndSeqPri pri_lev)
Input:
seq_no: Sound control number
seq_bk_no: Sequence bank number
song_no: Sequence song number
pri_lev: Priority level
Output:none
Function Value: Command execution status
Function:Starts the specified sequence.

Function

Function Name

Function Specifications

Set sequence volume

SND_SetSeqVl

No.

tia
l

Title

Format:17

Title

Function

Function Specifications

Change tempodenSndRet SND_SetSeqVl(SndSeqNum seq_no, SndSeqVl seq_vl,
SndFade fade)
Input:
seq_no: Sound control number
seq_lev : Fade level
fade: Fade rate
Output:None
Function Value: Command execution status
Function:
Sets the sequence volume.

Format:Input:

Function NameNo.

SND_ChgTempo

18

nfi

SndRet SND_ChgTempo(SndSeqNum seq_no, SndTempo tempo)
seq_no : Sound control number
tempo: TempoOutput:None
Function Value: Command execution status
Function:
Sets the tempo of the selected sequence.

Function

Function Specifications

Direct MIDI control

Format:Co

Title

Function NameNo.

SND_CtrlDirMidi 19SE

GA

SndRet SND_CtrlDirMidi(SndSeqNum seq_no, SndSeqPri seq_pri,
Uint8 md_com, Uint8 ch, Uint8 dtl, Uint8 dt2)
Input:
seq_no: Sound control number
seq_pri: MIDI command (0H~7H)
ch: MIDI channel (0H~1FH)
dt1: MIDI data1 (00H~7FH)
dt2: MIDI data2 (00H~7FH)
Output:None
Function Value: Command execution conditions
Function:
MIDI is controlled directly according to the selected parameters.

Program Library User's Guide 3

27

tia
l

PCM

Title

Function

Function Name

No.

Function Specifications

Start PCM

SND_StartPcm

20

Format:Input:

Title

Function

Function Specifications

Stop PCM

Function Specifications

PCM Change

Co

Function

SND_StopPcm

21

Function NameNo.

SND_ChgPcm

22

GA

SndRet SND_ChgPcm(SndPcmChgPrm *cpcm)
cpcm: PCM change parameter pointerNone
Command execution status
Changes the playback status of PCM data.

SE
28

No.

SndRet SND_StopPcm(SndPcmNum pcm_num)
pcm_num : Play stop PCM stream play number
None
Command execution status
Stops play of PCM data.

Title

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Format:Input:
Output:Function Value:
Function:den

SndRet SND_StartPcm(SndPcmStartPrm *sprm, SndPcmChgPrm *cprm)
sprm: PCM start parameter pointercprm: PCM change parameter pointerOutput:None
Function Value: Command execution status
Function:
Plays PCM data according to the specified parameters.

tia
l

CD
Title

Function

Function Name

Function Specifications

Start Volume Analysis

SND_StartVlAnl 23

Remarks:

SndRet SND_StartVlAnl(void)
None
None
Command execution status
Starts analysis of the frequency band volume and total volume. Volume analysis
continues until it is stopped by the volume analysis stop function. Before analyzing
the frequency band volumes with this function, the special DSP program for this task
must be executed by effect change. The DSP program is not required when analyzing
the total volume.
Other DSP programs cannot be executed while the frequency band volume analysis
DSP program is being executed.

Function

Function Specifications

Stop Volume Analysis

No.

SND_StopVlAnl

24

SndRet SND_StopVlAnl(void)
None
None
Command execution status
Stops volume analysis.

Co

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Title

de
n

Format:Input:
Output:Function Value:
Function:

No.

Title

Function

Function Name

No.

Function Specifications

Set CD-DA Level

SND_SetCdDaLev

25

Format:Input:Title

GA

SndRet SND_SetCdDaLev(SndLev left, SndLev right)
left: Volume of left output
right: Volume of right output
Output:None
Function Value: Command execution status
Function:
Changes the current stereo volume.

Function Specifications

Format:Input:

Function

Function Name

Set CD-DA Pan

SND_SetCdDaPan 26

No.

SE

SndRet SND_SetCdDaPan(SndPan left, SndPan right)
left: Pan of left output
right: Pan of right output
Output:None
Function Value: Command execution status
Function:
Changes the current stereo pan.

Program Library User's Guide 3

29

tia
l

• Status Acquisition
Sequence
Title

Function

Function Name

No.

Function Specifications

Get sequence status

SND_GetSeqStat

27

void SND_GetSeqStat(SndSeqStat *status, SndSeqNum seq_no)
seq_no: Sound control number
status: Sequence status pointerNone
Gets the sequence status of the selected sound control number.

Title

Function

Function Specifications

Get sound control number playposition

Function NameNo.

SND_GetSeqPlayPos

28

nfi

void SND_GetSeqPlayPos(SndSeqPlayPos *pos, SndSeqNum seq_no)
seq_no: Sound control number
pos: Sound control number play position
None
Gets the play position of the specified sound control number.

PCM

Co

Format:Input:
Output:Function Value:
Function:

Title

Function

Function Name

Function Specifications

Get PCM execute address

SND_GetPcmPlayAdr 29

Title

Function Specifications

Function

Function NameNo.

Get PCM address update interrupt
statusSND_GET_INT_STAT

30

SndPcmIntStat SND_GET_INT_STAT(void)
None
None
PCM address update interrupt status
Gets the PCM address update interrupt status. Valid when the interrupt source isinterrupted by the PCM address update. The PCM playback number address thatwas updated can be the determined with this information.

SE

Format:Input:
Output:Function Value:
Function:No.

void SND_GetPcmPlayAdr(SndPcmPlayAdr *adr, SndPcmNum num)num
: PCM play numberadr: PCM execute address
None
Gets the PCM data address being played back.

GA

Format:Input:
Output:Function Value:
Function:

30

de
n

Format:Input:
Output:Function Value:
Function:

tia
l

CD
Title

Function

Function Name

No.

Function Specifications

Get total stereo volume analysis

SND_GetAnlTlVl

31

Format:Input:
Output:denvoid SND_GetAnlTlVl(SndChVlAnl *left, SndCdAnl *right)
None
left
: Total volume of left output
right: Total volume of right output
Function Value: None
Function:
Gets the analysis of the total stereo volume. Execute the volume analysis start
function before executing this function.
Remarks:
Volume is updated at 16 msec intervals.

Title

Function

Function Specifications

Get discrete frequency band stereo
volume analysis

SND_GetAnlHzVl 32

void SND_GetAnlHzVl(SndCdHzSrV1 *hz_vl)
none
hz_vl
: Frequency band stereo volume
None
Gets the stereo volume based on sound frequency bands. Execute the volume
analysis start function before executing this function.
Volume is updated at 16 msec intervals.

SE

GA

Co

Remarks:No.

nfi

Format:Input:
Output:Function Value:
Function:

Function Name

Program Library User's Guide 3

31

tia
l

DMA Library
1.0 Guide
1.1 Objective

1.2

de
n

Direct Memory Access (DMA) functions decrease the overhead on the Main CPU’s
processing time by enabling it to perform work other than the transfer of data. Thislibrary provides basic DMA data transfer functions.
Overview

The DMA Library supports both the SH2 (CPU) and SCU-based DMA transfers. Highlevel and low-level library functions are provided for each device.
Descriptions of the high-level and low-level functions are as follows.

nfi• High-level functions
Provides basic functionality for byte, word, and longword transfers through easy-to-use functions.
• Low-level functions
Provides functions that enable the detailed setup of device modes, interrupts, and status communication.

Co

The main differences between the SH2 (CPU) and SCU DMA functions are explained
next. For more detailed information, refer back to the hardware manual for each device.
• CPU
Capable of transfers between the same bus (e.g., between work RAM areas). This is not possible with
the SCU.
• SCU
Because parallel operations by the CPU can be performed during data transfers, the SCU is effective intransfers that do not involve the CPU bus. The SCU is capable of high-speed transfers compared with
the CPU.

GA

1.3 Precautions• Select the suitable function after examining the source and destination access units used for thetransfer. See the appropriate hardware manual for information about access units.
• High-level DMA transfers purge the destination area after a transfer under the following condition.
Condition:
Reason:When the destination area is the work RAM.
An assumption is made that the RAM area read using the cache is work RAM.

SE

• Burst mode transfers cannot be used by the CPU.

32

tia
l

1.4 Calling Sequence
The following example shows the DMA transfer calling sequence.
#define SCLA_CFRAME ((void *)0x5e60000)#define K_NUM(424)
Uint32 scl_k_data[512];/* VDP2 VRAM scroll coefficient address *//* Scroll coefficient data size*//* Work RAM scroll coefficient data area */

SE

GA

Co

nfi

de
n

. . .
void copyToData(){
DMA_ScuCopyMem(SCLA_CFRAME, scl_k_data, K-NUM);/* data transfer to VDP2 VRAM fromWork RAM */. . .
if(DMA_ScuResult() == DMA_SCU_BUSY){ /* DMA_ScuCopyMem() completion check
*/
. . .
}
}

Program Library User's Guide 333

2.1 Data List

Data

SCU

CPU

DMA channel

NoneTransfer parameters

DmaScuPrm

DMA channel
Common transfer parameters

Co
GA
SE
34

1

2

None

3

DmaCpuComPrm

4

DmaCpuPrm

5

nfi

Transfer parameters

No.

de
n

Low-level

Data Nametial

2.0 Reference• Low-level SCU Transferstial

2.2 Data Specifications

Title

Data

Data NameNo.

Data Specifications

DMA Channel

none

1

Use the following constants when specifying an SCU DMA channel.
Description

DMA_SCU_CH0

Channel 0

DMA_SCU_CH1

Channel 1

DMA_SCU_CH2

Channel 2

Title

Data

Data Specifications

Transfer parametersdenName of Constant

Data NameNo.

DmaScuPrm

2/* Read address/* Write address/* Number of transfer bytes/* Read address add value/* Write address add value/* Mode bit/* Read address update bit/* Write address update bit/* Start source selection bit/* Mask bit

Costruct{Uint32dxr;
Uint32
dxw;
Uint32
dxc;
Uint32dxad_r;Uint32dxad_w;
Uint32
dxmod;
Uint32
dxrup;
Uint32
dxwup;
Uint32dxft;
Uint32msk;} DmaScuPrm;

nfi

Transfer parameters have the following structure.

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

GA

The following tables show constants that can be used by each member.
dxad_r/*read address add value

Name of Constant*/

Description

Don’t add

DMA_SCU_R4

Add 4 bytes

SE

DMA_SCU_R0

Program Library User's Guide 3

35

/*

write address add value

Name of Constant

Description

Don’t add

DMA_SCU_W2

Add 2 bytes

DMA_SCU_W4

Add 4 bytes

DMA_SCU_W8

Add 8 bytes

DMA_SCU_W16

Add 16 bytes

DMA_SCU_W32

Add 32 bytes

DMA_SCU_W64

Add 64 bytes

DMA_SCU_W128

Add 128 bytes

/*

de
n

DMA_SCU_W0

dxmod

mode bit*/

Name of Constantnfi

DMA_SCU_IN_DIR

Indirect mode

read address update bit
write address update bit

Co

/*
/*

Description

Direct mode

DMA_SCU_DIR

dxrup
dxwup

Name of Constant

DMA_SCU_KEEP

Hold

DMA_SCU_REN

Update

dxft

/*

*/
*/

Description

start source select bit*/

Description

DMA_SCU_F_VBLK_IN

Receive V-blank-IN signal

DMA_SCU_F_VBLK_OUT

Receive V-blank-OUT signal

DMA_SCU_F_HBLK_OUT

Receive H-blank-IN signal

DMA_SCU_F_TIM0

Receive Timer 0 signal

DMA_SCU_F_TIM1

Receive Timer 1 signal

DMA_SCU_F_SND

Receive Sound-Req signal

DMA_SCU_F_SPR

Receive Sprite draw end signal

DMA_SCU_F_DMA

Set DMA start source bit

SE

GA

Name of Constant

36

*/

tia
l

dxad_w

tia
l

mask
/* mask bit*/(This is a write mask bit for the members above. Bits specified by the following
constants are not written. Multiple specifications are possible by using logical OR)
Name of Constant

Description

Read address

DMA_SCU_M_DXW

Write address

DMA_SCU_M_DXC

Number of transfer bytes

DMA_SCU_M_DXAD_R

Read address add value

DMA_SCU_M_DXAD_W

Write address add value

DMA_SCU_M_DXMOD

Mode bit

DMA_SCU_M_DXRUP

Read address update bit

DMA_SCU_M_DXWUP

Write address update bit

DMA_SCU_M_DXFT

Start source selection bit

SE

GA

Co

nfi

de
n

DMA_SCU_M_DXR

Program Library User's Guide 3

37

tia
l

• Low-Level CPU Transfers
Title

Data

Data NameNo.

Data Specifications

DMA channel

None

3

Use the following constants when specifying a CPU DMA channel.
Description

DMA_CPU_CH0

Channel 0

DMA_CPU_CH1

Channel 1

Title

Data

Data Specifications

Common transfer parametersdenName of Constant

Data NameNo.

DmaCpuComPrm

4

Common transfer parameters have the following structure.

nfi

struct{Uint32
pr;
Uint32
dme;
Uint32
msk;}DmaCpuComPrm;/* priority mode/* DMA master enable/* mask bit

*/
*/
*/

pr

Co

The following tables show constants that can be used by each of these members.
/*

priority mode

Name of Constant*/
Description

DMA_CPU_FIX

Priority sequence is fixed

DMA_CPU_ROR

Priority sequence based on round robin

dme

/*

DMA master enableGA

Name of Constant*/
Description

DMA_CPU_DIS

DMA transfer on all channels disabled

DMA_CPU_ENA

DMA transfer on all channels disabled

msk

/*

mask bit*/

SE

This is a write mask bit for the members. Bits specified by the following constants are not written. Multiple specifications are possible byusing logical OR.
Name of Constant

DMA_CPU_M_PR
DMA_CPU_M_AE
DMA_CPU_M_NMIFDMA_CPU_M_DME

38

Description

Priority mode
Address error flag
NMI flag
DMA master enable

Data

Data Name

Data Specifications

Transfer parameters

DmaCpuPrm

Transfer parameters have the following structure.
struct{Uint32 sar;
Uint32 dar;Uint32 tcr;
Uint32 dm;
Uint32 sm;
Uint32 ts;
Uint32 ar;
Uint32 ie;
Uint32 drcr;
Uint32 msk;
} DmaCpuPrm;

No.

tia
l

Title

*/
*/
*/
*/
*/
*/
*/
*/
*/
*/

de
n

/* DMA source address/* DMA destination address/* DMA transfer count/* destination address mode/* source address mode bit/* transfer size/* auto request mode/* interrupt enable/* DMA request/response select control/* mask bit

5

dm
sm

/*
/*

destination address mode
source address mode bit

Name of Constant

Description

transfer size

Name of ConstantGA

DMA_CPU_1
DMA_CPU_2
DMA_CPU_4
DMA_CPU_16
ar

/*

SE

/*

*/
Description

Module request
Auto request

interrupt enable

Name of Constant

DMA_CPU_INT_ENA
DMA_CPU_INT_DIS

Program Library User's Guide 3

Description

Byte unit
Word (2 byte) unit
Long word (4 byte) unit
16 byte unit

Name of Constantie*/auto request mode

DMA_CPU_MOD
DMA_CPU_AUTO

*/
*/

Fixed
Add
Subtract

Co

DMA_CPU_AM_NOM
DMA_CPU_AM_ADD
DMA_CPU_AM_SUB
ts /*

nfi

The following tables show constants that can be used by each member.

*/
Description

Enable interrupt request
Disable interrupt request

39

/*

DMA request/response select control

Name of Constant

msk /*

mask bit

Name of Constant

DMA_CPU_M_SAR
DMA_CPU_M_DAR
DMA_CPU_M_TCR
DMA_CPU_M_DM
DMA_CPU_M_SM
DMA_CPU_M_TS
DMA_CPU_M_AR
DMA_CPU_M_IE
DMA_CPU_M_DRCR
DMA_CPU_M_TE

*/

de
n

DMA_CPU_TXIDescription

DREQ (external request)
RXI (built-in SCI receive data full interrupt
transfer request)
TXI (built-in SCI send data empty interrupt
transfer request)

Description

DMA source address
DMA destination address
DMA transfer countDestination address mode
Source address mode bit
Transfer size
Auto request mode
Interrupt enable
DMA request/response select control
Transfer end flag

nfi

DMA_CPU_DREQ
DMA_CPU_RXI

*/

tia
l

drcr

SE

GA

Co

This is a member write mask bit. Bits specified by the following constants are not written. Multiple settings are possible by using logicalOR.

40

High-level

SCU

CPU

DMA_ScuMemCopy

1

DMA data transfer result check

DMA_ScuResult

2

DMA byte data transfer

DMA_CpuMemCopy1

3

DMA word data transfer

DMA_CpuMemCopy2

4

DMA_CpuMemCopy4

5

DMA_CpuMemCopy16

6

DMA_CpuResult

7

Set DMA transfer parameters

DMA_ScuSetPrm

8Start DMA transfer

DMA_ScuStart

9

DMA_ScuStop

10

Stop DMA transfer on all channels

DMA_ScuAllStop

11

Set common DMA transfer
parameters

DMA_CpuSetComPrm

12

Set DMA transfer parameters

DMA_CpuSetPrm

13

Start DMA transfer

DMA_CpuStart

14

Stop DMA transfer

DMA_CpuStop

15

Stop DMA transfer on all channels

DMA_CpuAllStop

16

Get common DMA status

DMA_CpuGetComStatus 17

Get DMA status

DMA_CpuGetStatus

DMA 16-byte data transfer
DMA data transfer end check
SCU

18

SE

GA

Co

nfi

Stop DMA transfer

CPU

No.

DMA data transfer

DMA long word data transfer

Low-level

Function NamedenFunctiontial

2.3 List of Functions

Program Library User's Guide 3

41

tia
l

2.4 Function Specifications• High-level SCU Transfers
Title

Function

Function Name

No.

Function Specifications

DMA data transfer

DMA_ScuMemCopy

1

Format:Input:

denvoid DMA_ScuMemCopy(void *dst, void *src, Uint32 cnt)
*dst : Destination address*src : Source address
cnt: Transfer byte countOutput:None
Function Value: None
Function:
DMA transfer is done by the direct mode of the SCU DMA mode 0. For more information, see the SCU User’s Manual (ST-097-R5-072694). Operation of this transfer
differs depending on whether the destination address is in work RAM or not. The
differences are explained below.
• Work RAM

nfi

The destination area is purged after transfer in order to eliminate conflict withthe cache. In addition, because the CPU bus is used, control does not return to
the CPU until DMA execution ends.
• Areas other than the Work RAM

Co

After transfer begins, control returns to the CPU immediately because the CPU
bus is not used. In this case, a check of the transfer result is done by
DMA_ScuResult().

SE

GA

Although transfer units are basically long word units, but the source and destination addresses can be specified in byte units. However, when the device requests
data in word boundary units, make sure to do so. For more information, see the
SCU User’s Manual.

42

Function

Function Name

Function Specifications

DMA data transfer result check

Dma_ScuResult

2

Uint 32 DMA_ScuResult(void)
None
None
Result of DMA_ScuMemCopy()
Checks the results of DMA_ScuMemCopy(). The following table lists the return
values.
Execution Result Constant Names
Name of Constant

DMA_SCU_END
DMA_SCU_FAIL
DMA_SCU_BUSYdenFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Description

Normal end
Abnormal end
Busy

When the CPU_Bus is specified as the transfer source or destination with
DMA_ScuMemCopy(), the CPU cannot run while the DMA is executing.
Accordingly, the execution results in that case cannot be “busy" (DMA_SCU_BUSY).

SE

GA

Co

nfi

Remarks:

Program Library User's Guide 3

43

tia
l

• High-level CPU Transfers
Title

Function

Function Name

No.

Function Specifications

DMA byte data transfer

DMA_CpuMemCopy1

3

Format:Input:nfi

denvoid DMA_CpuMemCopy1(void *dst, void *src, Uint32 cnt)
*dst : Destination address*src : Source address
cnt: Transfer count (0 - 16777215)
0x00000001
1 time0x00ffffff
16777215 times
0x00000000
16777216 times
Output:None
Function Value: None
Function:Transfers byte data cnt times from the src address to the dst address. The transfer
amount is cnt bytes. Data is transferred without the use of channel 0, cycle steal
mode, and completion interrupt. When the destination address is the work RAM,the destination area is purged after transfer in order to eliminate conflicts with thecache. There are no restrictions on addressing.

Title

Function

Function Specifications

DMA word data transfer

Format:Input:

Function NameNo.

DMA_CpuMemCopy2

4

SE

GA

Co

void DMA_CpuMemCopy2(void *dst, void *src, Uint32 cnt)
*dst : Destination address*src : Source address
cnt: Transfer count (0 - 16777215)
0x000000001
1 time0x00ffffff
16777215 times
0x00000000
16777216 times
Output:None
Function Value: None
Function:Transfers byte data cnt times from the src address to the dst address. The transfer
amount is cnt*2 bytes. Data is transferred without the use of channel 0, cycle steal
mode, and completion interrupt. When the destination address is the work RAM,the destination area is purged after transfer in order to eliminate conflicts with thecache. The addressing must be word boundary-based.

44

Function

Function Name

Function Specifications

DMA long word Data Transfer

DMA_CpuMemCopy4

No.

tia
l

Title

Format:Input:

5

nfi

de
n

void DMA_CpuMemCopy4(void *dst, void *src, Uint32 cnt)
*dst : Destination address*src : Source address
cnt: Transfer count (0 - 16777215)
0x00000001
1 time0x00ffffff
16777215 times
0x00000000
16777216 times
Output:None
Function Value: None
Function:Transfers long word data cnt times from the src address to the dst address.
The transfer amount is cnt*4 bytes. Data is transferred without the use of channel
0, cycle steal mode, and completion interrupt. Whenthe destination address is thework RAM, the destination area is purged after transfer in order to eliminate conflicts
with the cache. Addressing must be long word boundary-based.

Title

Function

Function Specifications

DMA 1-byte data transfer

Format:Input:

Function NameNo.

DMA_CpuMemCopy16

6

SE

GA

Co

void DMA_CpuMemCopy16(void *dst, void *src, Uint32 cnt)
*dst : Destination address*src : Source address
cnt: Transfer count (0 - 16777215) (long word units)
0x00000001
1 time0x00ffffff
16777215 times
0x00000000
16777216 times
Output:None
Function Value: None
Function:Transfers long word data of data cnt times from the src address to the dst address.
The transfer amount is cnt*4 bytes. Data is transferred without the use of channel
0, the cycle steal mode, and completion interrupt. When the destination address isthe work RAM, the destination area is purged after transfer in order to eliminate
conflicts with the cache. Addressing must be long word boundary-based.

Program Library User's Guide 3

45

Function

Function Name

Function Specifications

DMA data transfer end check

DMA_CpuResult

Execution Result Constant Names
Name of Constant

Description

Normal end
Busy

SE

GA

Co

nfi

DMA_CPU_END
DMA_CPU_BUSY

46

7

Uint 32 DMA_CpuResult(void)
None
None
Results of DMA_CpuMemCopy 1, 2, 4, 16 ()Checks the results of DMA_CpuMemCopy 1, 2, 4, 16 (). The following tableshows returned values.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Low-level SCU Transfers

tia
l

•

Title

Function

Function Name

No.

Function Specifications

Set DMA transfer parameters

DMA_ScuSetPrm

8

Format:Input:

Title

Function

Function Specifications

Start DMA transfer

Stop DMA transfer

10

9

GA

void DMA_ScuStop(Uint32 ch)ch: DMA channel
None
None
Stops DMA transfer on the specified DMA channel.

Function Specifications

Function

Function Name

No.

Stop DMA transfer on all channels

DMA_ScuAllStop

11

void DMA_ScuAllStop(void)
None
None
None
Stops DMA transfer on all DMA channels.

SE

Format:Input:
Output:Function Value:
Function:No.

DMA_ScuStop

Co

Function

Function Specifications

Title

Function NameDMA_ScuStart

void DMA_ScuStart(Uint32 ch)ch: DMA channel
None
None
Starts DMA transfer on the specified DMA channel.

Title

Format:Input:
Output:Function Value:
Function:

No.

Function Name

nfi

Format:Input:
Output:Function Value:
Function:denvoid DMA_ScuSetPrm(DmaScuPrm *prm, Uint32 ch)prm: Transfer parametersch: DMA channel
Output:None
Function Value: None
Function:
Sets the values of transfer parameters to the specified DMA channel.

Program Library User's Guide 3

47

tia
l

Low-level CPU Transfers
Title

Function

Function Name

No.

Function Specifications

Set common DMA transfer
parameters

DMA_CpuSetComPrm

12

Format:Input:
Output:Function Value:
Function:
Remarks:

void DMA_CpuSetComPrm(DmaCpuComPrm *com_prm)
com_prm: Common transfer parameters
None
None
Sets specified common DMA transfer parameters, but does not set parametersmasked by DmaCpuComPrm.msk.
When DMA_CPU_M_AE is not masked byDmaCpuComPrm.msk, the address error flagis cleared. When DMA_CPU_M_NMIF is not masked, the NMI flag is cleared.

Function

Function Specifications

Set DMA transfer parameters

Function NameNo.

DMA_CpuSetPrm

13

nfi

Title

de
n

•

Format:Input:

Co

void DMA_CpuSetPrm(DmaCpuPrm *prm Uint32 ch, )prm: Transfer parametersch: DMA channel
Output:None
Function Value: None
Function:
Sets specified channel transfer parameters, but does not set parameters masked by
DmaCpuPrm.msk.
Remarks:
When DMA_CPU_TE is not masked by DmaCpuPrm.msk, the transfer end flag bit iscleared.

Title

Function

Function Name

No.

Function Specifications

Start DMA transfer

DMA_CpuStart

14

Uint32 DMA_CpuStart(Uint32 ch)ch: DMA channel
None
None
Starts DMA transfer on the specified DMA channel.

SE

GA

Format:Input:
Output:Function Value:
Function:48

Function

Function Name

Function Specifications

Stop DMA transfer

DMA_CpuStop

void DMA_CpuStop(Uint32 ch)ch: DMA channel
None
None
Stops DMA transfer on the specified DMA channel.

denFormat:Input:
Output:Function Value:
Function:

Title

Function

Function Specifications

Stop DMA transfer on all channels

No.

DMA_CpuAllStop

16

void DMA_CpuAllStop(void)
None
None
None
Stops DMA transfer on all DMA channels.

Title

Function

Function Specifications

Get common DMA status

Function NameNo.

DMA_CpuGetComStatus 17

void DMA_CpuGetComStatus(DmaCpuComStatus *status)
Nonestatus : status pointerNone
Gets the specified common status.

Co

Format:Input:
Output:Function Value:
Function:

15

Function Name

nfi

Format:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Function

Function Name

No.

Function Specifications

Get DMA status

DMA_CpuGetStatus

18

GA

Title

void DMA_CpuGetStatus(DmaCpuStatus *status, Uint32 ch)ch: DMA channel
status : Status pointerNone
Gets the status on specified DMA channel.

SE

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 3

49

tia
l

Cache Library
1.0 Guide
1.1 Objectiveden

The Cache Library provides functions that are required after the execution of a DMA as
well as function-format macros for cache register operations.
1.2 Overview

The main purpose of this library is to provide functions that purge the cache after DMA
transfers.

nfi

When the CPU accesses RAM memory space via a cache address, a conflict occurs
between the RAM and cache memory contents if the RAM is used as a destination for
DMA transfers.

SE

GA

Co

For more details on SH2 cache operations, refer to the SH2 hardware manual.

50

2.1 List of Functions
Function

Initialize cache

CSH_Init

Clear all caches

CSH_AllClr

Associative purge of target area

CSH_Purge

2.2 Function Specifications• High-level
Title

Function

Function Specifications

Initialize cache

Format:Input:

1

2
3

Function NameNo.

CSH_Init1

nfi

void CSH_Init(Uint16 sw)
sw: Way mode

No.

de
n

High-level

Function Nametial

2.0 Reference

Way Mode Constant Names
Name of Constant

Description

4-way set associative
2-way set associativeCo

CSH_4WAY
CSH_2WAY

Output:None
Function Value: None
Function:
Initializes the cache. Clears valid bits of all cache lines, enables instruction fill anddata fill, and enables the cache.

Function Specifications

Format:Input:
Output:Function Value:
Function:

Function NameNo.

Clear all caches

CSH_AllClr2

void CSH_AllClr(void)
None
None
None
Clears valid bits of all caches of all ways. This function executes internally after
disabling the cache and re-enables the cache after cache clear.
Address array is updated, however, the data array is not updated.

SE

Remarks:

Function

GA

Title

Program Library User's Guide 3

51

Function

Function Name

No.

Function Specifications

Associative purge of target area

CSH_Purge

3

tia
l

Title

Format:Input:

2.3 List of Function Format Macros
Function

Function Format Macro
Name

No.

Get cache register

CSH_GET_CCR

1

Set cache register

CSH_SET_CCR

2

Cache enable control
Instruction fill control
Data fill control

nfi

Low-leveldenvoid CSH_Purge(void *address, Uint32 p_size))*address : Start address
p_size: Purge byte size
Output:None
Function Value: None
Function:
Purges the area specified by address and p_size.

3

CSH_SET_CODE_FILL

4

CSH_SET_DATA_FILL

5

CSH_SET_WAY_MODE

6

Co

2, 4-way set associative modeswitch

CSH_SET_ENABLE

Select address array access way

CSH_SET_ACS_WAY

7

2.4 Function Format Macro Specification
Low-level

Function

GA

Title

Function Specifications

52

No.

CSH_GetCcr

1

Uint16 CSH_GetCcr(void)
None
None
Cache register contents
Gets the CCR contents and returns as a function value.

SE

Format:Input:
Output:Function Value:
Function:

Get cache register

Function Name

Function

Function Name

Function Specifications

Set cache register

CSH_SetCcr

Title

Function

Function Specifications

Cache enable control

Format:Input:

2

Uint16 CSH_SetCcr(Uint16 reg)reg
: Cache register value
none
Returns contents of register
Sets reg to CCR. Can set each state of the cache in one setting.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Function NameNo.

CSH_SetEnable3

void CSH_SetEnable(Uint16 sw)
sw: Cache enable switch

Cache Enable Switch Constant Names

CSH_DISABLE
CSH_ENABLE

Description

nfi

Name of Constant

Disable cache
Enable cacheCo

Output:None
Function Value: None
Function:Controls operation of the cache by the specified cache enable switch.

Title

Function

Function Name

No.

Function Specifications

Instruction fill control

CSH_SetCodeFill

4

Format:Input:

void CSH_SetCodeFill(Uint16 sw)
sw: Instruction fill disable switch

GA

Command Fill Disable Switch Constant Names
Name of Constant

CSH_CODE_ENABLE
CSH_CODE_DISABLE

Description

Enable instruction fill
Disable instruction fillSE

Output:none
Function Value: none
Function:Controls the cache fill operation during instruction fetches.

Program Library User's Guide 3

53

Function

Function Name

Function Specifications

Data fill control

CSH_SetDataFill

Format:Input:

void CSH_SetDataFill(Uint16 sw)
sw: Data fill disable switch
Disable Switch Constant Names
Name of Constant

No.

tia
l

Title

5

Description

Enable data fill
Disable data fillden

CSH_DATA_ENABLE
CSH_DATA_DISABLE

nfi

Output:None
Function Value: None
Function:Controls the cache fill operation when reading data.

Title

Function

Function Specifications

2, 4-way set associative mode switch CSH_SetWayMode

Format:Input:

Function Name

No.

6void CSH_SetWayMode(Uint16 sw)
sw: Way ModeCo

Way Mode Constant Names
Name of Constant

CSH_4WAY
CSH_2WAY

Description

4-way set associative mode
2-way set associative mode

Title

GA

Output:None
Function Value: None
Function:
Selects 2-way or 4-way mode.

Function Specifications

54

Function Name

No.

Select access way of address array

CSH_SetAcsWay

7

void CSH_SetAcsWay(Uint16 way)way
: Way (0~3)
None
None
Used in selecting the access way when reading or writing an address array.

SE

Format:Input:
Output:Function Value:
Function:

Function1.0 Guide
1.1 Objective

1.2 Overview

den

The Interrupt Management Library controls interrupts.

tialInterrupt Management Library

The library manages access to interrupt registers and interrupt processing routines.
1.3 Overview of Functions
Interrupt RegisterAccess Control

Co

nfi

Because the interrupt mask register is write-only, its value cannot be read. Therefore,
values written to the interrupt mask register are held by the library. Specifically, thefollowing methods are used.
(1) The interrupt mask register state is always held in memory (mask state memory
hereafter).
(2) The same data is written to the mask state memory when a write occurs to theinterrupt mask register.
(3) The contents of the mask state memory are read when there is a need to read theinterrupt mask register.
Interrupt Processing Routine
AccessGA

The library may be used to set the interrupt function or SCU function to the interrupt
vector table. In addition, the current interrupt vector settings can be checked. The SCU
interrupt function is set as the initial value in the SCU interrupt vector table. The SCU
interrupt function has a feature that enables a set SCU function to be called as a subroutine. The SCU function is executed each time the SCU interrupt function is executed.
As default initial settings, a dummy function (which executes only the return process) is
set as the interrupt function, and a SCU dummy function (which executes only the
return process) is set as the SCU interrupt function.
1.4 Usage Conditions

SE

Interrupt RegisterAccess Control

Because the value of the interrupt mask register is held by the library, the library should
be used to set the interrupt mask register. If the register is written directly, the interrupt
mask register will not correspond with the mask state memory. As a result, correct
processing will not occur.

Program Library User's Guide 3

55

tia
l

1.5 Calling SequencedenInterrupt RegisterAccess Control
void sysInit(){
INT_SetMsk((INT_MSK_HBLK_IN | INT_MSK_VBLK_OUT),(INT_MSK_SPR | INT_MSK_DMA1));/* Enable “H-Blank-IN” and “V-Blank-OUT”*//* Disable “Sprite draw complete” and “Level 0-DMA”
*/
. . .
}
void anyPrg(){
Uint32 status_bit;
status_bit = INT_GET_STAT();/* Get status*/if(INT_JudgeStat(status_bit, INT_ST_VBLK_OUT, INT_ST_VBLK_IN) == TRUE) {nfi/* When V-Blank-OUT interrupt occurs, and/* V-Blank-IN interrupt does not occur
. . .
}

Co

}

*/
*/

Interrupt Processing Routine
AccessFile A#pragma interrupt (vblkIn)/* vblkIn function is specified as theinterrupt function */SEGAvoid vblkIn(void)
{
. . .
}

56

*/
*/

*/
*/

nfi

de
n

tia
l

File B
void systemInit(void){
INT_SetFunc(INT_SCU_VBLK_IN, vblkIn);/* vblkIn interrupt function is set to the/* V-Blank-IN interrupt vector table.
INT_SetScuFunc(INT_SCU_VBLK_OUT, vblkOut);/* vblkOut function is set to the SCU interrupt/* function of the V-Blank-OUT interrupt vector.
. . .
}void vblkOut(void)
{
. . .
}

2.0 ReferenceCo

2.1 Data List
Data

Data Name

NumberInterrupt Register Access Control

Interrupt mask bit value constant

None

1

Interrupt status bit value constant

None

2

None

3

Interrupt Processing Routine Access

SE

GA

Vector number constantProgram Library User's Guide 357

Interrupt RegisterAccess Control
Title

Data

Data Name

Data Specifications

Interrupt mask bit value constant

None

tia
l

2.2 Data SpecificationsNo.

1

Constant

Description

No specification

INT_MSK_ALL

Set all (specifies all bits described below)

INT_MSK_ABUS

A-Bus

INT_MSK_SPR

Sprite draw complete

INT_MSK_DMAI

Illegal DMA

INT_MSK_DMA0

Level 0 DMA

INT_MSK_DMA1

Level 1 DMA

INT_MSK_DMA2

Level 2 DMA

INT_MSK_PAD

PAD

INT_MSK_SYS

System manager

INT_MSK_SND

Sound request

INT_MSK_TIM0
INT_MSK_HBLK_IN
INT_MSK_VBLK_OUT

DSP endTimer 1
Timer 0H-Blank-IN

V-Blank-OUT
V-Blank-IN

SEGA

INT_MSK_VBLK_IN

Co

INT_MSK_TIM1

nfi

INT_MSK_NULL

INT_MSK_DSP

58

de
n

The following table shows constants that can be set as the interrupt mask bit value. The
value of each constant is 1 for the 1 bit that the constant represents, and everything else
is set as 0. Multiple numbers can be set once by using logical OR.

Data

Data Name

Data Specifications

Interrupt Status Bit Value Constant

None

No.

tia
l

Title

2

Constantden

The following table shows the constants that can be set as the interrupt status bit value.
The value of each constant is 1 for the 1 bit that the constant represents, and everythingelse is set as 0. Multiple numbers can be set once by using logical OR.

Description

No specification

INT_ST_ALL

Specify all (specifies all bits described below)

INT_ST_ABUS

A-Bus (specifies A-Bus 01 ~ 16 bits)

INT_ST_ABUS 01 ~ ABUS 16

A-Bus 01 ~ 16

INT_ST_SPR

Sprite draw complete

INT_ST_DMAI

Illegal DMA

INT_ST_DMA0

Level 0 DMA

INT_ST_DMA1

Level 1 DMA

INT_ST_DMA2

Level 2 DMA

INT_ST_PAD

PAD

INT_ST_SYS

System manager

INT_ST_SND

Sound request

INT_ST_DSP

DSP end

INT_ST_TIM0
INT_ST_HBLK_IN
INT_ST_VBLK_OUT

Timer 1
Timer 0H-Blank-IN

V-Blank-OUT
V-Blank-IN

SEGA

INT_ST_VBLK_IN

Co

INT_ST_TIM1

nfi

INT_ST_NULL

Program Library User's Guide 359

TitleData

Data Name

Data Specifications

Vector number constant

None

tia
l

Interrupt Processing Routine
AccessNo.

3Interrupt Types

SCU

Constant Name

INT_SCU_ABUS
INT_SCU_SPR
INT_SCU_DMAI
INT_SCU_DMA0
INT_SCU_DMA1

Description

A-Bus

Sprite draw complete
Illegal DMA

Level 0 DMA
Level 1 DMA
Level 2 DMA

nfi

INT_SCU_DMA2

den

The following table shows the constants that can be set as the vector number.
The SCU constant name can be set only by the master SH2. The CPU constant namecan be set by the master and slave SH2.

NT_SCU_SYS

System manager

NT_SCU_SND

Sound request

NT_SCU_DSP

DSP end

NT_SCU_TIM1

Timer 1

NT_SCU_TIM0

Timer 0NT_SCU_HBLK_IN

H-Blank-IN

NT_SCU_VBLK_OUT

V-Blank-OUT

Co

PAD

NT_SCU_VBLK_IN

V-Blank-IN

INT_CPU_DIVUDivider

NT_CPU_DMAC0DMAC channel 0

NT_CPU_DMAC1DMAC channel 1

NT_CPU_WDT

WDT interval

NT_CPU_BSC

BSC compare match

NT_CPU_SCI_ERISCI receive error

NT_CPU_SCI_RXI

SCI receive data fill

NT_CPU_SCI_TXISCI receive data empty

NT_CPU_SCI_TEISCI send end

NT_CPU_FRT_ICI

FRT input capture

NT_CPU_FRT_OCI

FRT output compare

NT_CPU_FRT_OVI

FRT overflow

SE

GA

CPU

INT_SCU_PAD

60

Function

Function Name

Interrupt Register Access Control

tial

2.3 List of Functions
NumberGet interrupt mask register

INT_GetMsk

Set interrupt mask register

INT_SetMsk

Change interrupt mask register

INT_ChgMsk

Get interrupt status register

INT_GetStat

Reset interrupt status register

INT_ResStat

5

Set A-Bus interrupt acknowledge

INT_SetAck

6

Get A-Bus interrupt acknowledge

INT_GetAck

7

Set interrupt function

INT_SetFunc

8

Set SCU function

INT_SetScuFunc

9

Get interrupt function address

INT_GetFunc

10

Get SCU function address

INT_GetScuFunc

11

2
3

nfi

de
n

4

SE

GA

Co

Interrupt Processing Routine Access

1

Program Library User's Guide 3

61

tia
l

2.4 Function Specifications
Interrupt RegisterAccess Control
Title

Function

Function Name

No.

Function Specifications

Get interrupt mask register

INT_GetMsk

1

Uint32 INT_GetMsk(void)
None
None
Interrupt mask bit value (0= not masked, 1= masked)
Mask state memory is fetched as the interrupt mask bit value.

Title

Function

Function Specifications

Set interrupt mask register

Format:Input:

denFormat:Input:
Output:Function Value:
Function:

Function NameNo.

INT_SetMsk

2

Co

nfi

void INT_SetMsk(Uint32 msk_bit)
msk_bit : Interrupt mask bit value(0= not masked, 1= masked)
Output:None
Function Value: None
Function:
Sets the interrupt mask bit value to the interrupt mask register and mask storage
memory.

Title

Function

Function Name

No.

Function Specifications

Change interrupt mask register

INT_ChgMsk

3

Format:Input:

SE

GA

void INT_ChgMsk(Uint32 ena_msk_bit, Uint32 dis_msk_bit)
ena_msk_bit: Interrupt mask bit enable value
dis_msk_bit: Interrupt mask bit disable value
Output:None
Function Value: None
Function:
Changes only the interrupt mask register and mask state memory of the specified bit.
The values of unspecified sets are preserved. Set that the value so that the “1” bit of
the interrupt mask bit enable value is not masked and the “1” bit of the interrupt
mask bit disable value is masked. The unspecified bit will preserve its value.
Interrupts are temporarily disabled during this process. In addition, the interrupt
status register that corresponds to the “1” bit of the interrupt mask bit enable value isreset. The interrupt acknowledge register is enabled when the A-Bus interrupt mask
is enabled.
Remarks:
When neither interrupt mask bit is set, specify INT_MSK_NULL.

62

Function

Function Name

Function Specifications

Get interrupt status register

INT_GetStat

Function:

Uint32 INT_GetStat(void)
None
None
Interrupt status register value(0= interrupt not generated, 1= interrupt generated)
Gets the interrupt status register value.

Title

Function

Function Specifications

Reset interrupt status register

Format:Input:

denFormat:Input:
Output:Function Value:

No.

tia
l

Title

4

Function NameNo.

INT_ResStat

5

nfi

void INT_ResStat(Uint32 status_bit)
status_bit : Interrupt status bit value(0: reset, 1: preserve value)
Output:None
Function Value: None
Function:
Resets the “0” bit of the interrupt status bit value.

Function

Function Specifications

Set A-Bus interrupt acknowledge

Format:Input:Co

Title

Function NameNo.

INT_SetAck

6

void INT_SetAck(Uint32 ack)
ack
: Acknowledge value
Acknowledge Value Constant Names
Name of ConstantGA

INT_ACK_ENA
INT_ACK_KEEP

Description

EnablePreserve current stateSE

Output:None
Function Value: None
Function:
Sets the specified acknowledge value to the A-Bus interrupt acknowledge register.

Program Library User's Guide 3

63

Function

Function Name

Function Specifications

Get A-Bus interrupt acknowledge

INT_GetAck

Format:Input:
Output:Function Value:

Uint32 INT_GetAck(void)
None
None
Acknowledge value

Description

Gets the acknowledge value of the A-Bus interrupt acknowledge register.

Interrupt Process RoutineAccess
Title

Function

Function Specifications

Set interrupt function

Function NameNo.

INT_SetFunc

8

nfi

•

7

EnabledDisabled

INT_ACK_ENA
INT_ACK_DIS

Function:denAcknowledge a
Vlue Constant Names
Name of Constant

No.

tia
l

Title

Format:Input:SE

GA

Co

void INT_SetFunc (Uint32 num, void* hdr)num
: Vector number
hdr: Interrupt function address
Output:None
Function Value: None
Function:
Sets the interrupt function address to the interrupt vector specified by the vector
number. The set interrupt function is executed when an interrupt occurs. When theinterrupt function address is NULL, functions set to the interrupt vector by based on
the vector number are as follows:• When the vector number is SCU:
Resets the SCU interrupt function.
• When the vector number is not SCU: Sets a dummy function. The dummyfunction only performs return processing.
Remarks:
Interrupt functions can be specified with save register, return, and RTE instructions.
(In C, functions using the #pragma interrupt declaration can be specified) Thisfunction can be used with both the master and slave SH2. This function must be
executed with the CPU to be set.

64

Function

Function Name

Function Specifications

Set SCU function

INT_SetScuFunc

No.

tia
l

Title

Format:Input:

9

Function

Function Specifications

Get interrupt function address

No.

INT_GetFunc

10

void* INT_GetFunc(Uint32 num)num
: Vector number
NoneInterrupt function address
Gets the interrupt function address set in the specified vector number.
This function can be used with both the master and slave SH2. Execute thisfunction on the CPU to get the address for that CPU.

Co

Format:Input:
Output:Function Value:
Function:
Remarks:

Function Name

nfi

Title

de
n

void INT_SetScuFunc (Uint32 num, void* hdr)num
: Vector number(Only SCU vector numbers can be specified)
hdr: SCU function address
Output:None
Function Value: None
Function:
Sets only the SCU function address to the SCU interrupt function of the specified
vector number. The specified SCU function is executed when an SCU interrupt
occurs. When the specified interrupt routine address is NULL, an SCU dummyfunction is set. The SCU dummy function performs only return processing.
Remarks:
This function may only be used on the master SH2. When setting the interrupt
function with INT_Setfunc, the vector of the SCU interrupt routine becomes
invalid and the set function cannot be called.

Title

Function

Function Name

No.

Function Specifications

Get SCU function address

INT_GetScuFunc

11

SE

Remarks:

void* INT_GetScuFunc(Uint32 num)num
: Vector number (SCU vector number only can be specified)
None
SCU function address
Gets the SCU function address set in the SCU interrupt function of the specified
vector number.
This function can be used with the master SH2 only. Execute this function
with the master SH2.

GA

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 3

65

tia
l

Memory Management Library
1.0 Guide
1.1 Objectiveden

Use the Memory Management Library for simplifying memory management tasks.
1.2 Overview

nfi

Various functions that allocate and free memory are provided. Functions that free up
memory check adjacent memory space for additional free memory. When free memoryis detected, it is linked with the memory being freed. These functions reduce the burden of memory management on the user. Memory Management Library functions havefunction interfaces similar to standard C library functions related to memory management.
1.3 Calling Sequence

The following example shows the calling sequence for allocating and freeing memory
blocks.

. . .
}

/*

GA

. . .
void userFunc(){
Uint32 *mem_area1;
Uint8 *mem_area2;

Co

void sysInit(){. . .
MEM_Init(0x6050000, 0x10000);

Sets 10000H byte from 6050000H
to memory management area
*/

. . .

mem_area1 = (Uint32 *)MEM_Malloc(4);/*

allocates a 4 byte area*/

allocates a 1 byte area*/

frees mem_areal memory*/

if(mem_area1 == NULL) {return(ERR);}

mem_area2 = (Uint8 *)MEM_Malloc(1); /*SE

if(mem_area2 == NULL) {return(ERR);
}
. . .
. . .
MEM_Free(mem_areal);
. . .

}

66

/*

2.1 List of Functions
Function

Name

No.

MEM_Init

1

Allocate array area

MEM_Calloc

2

Free memory blocks

MEM_Free3

Allocate memory blocks

MEM_Malloc

Reallocate memory blocks

MEM_Reallocden

Set memory management area

2.2 Function Specifications

tial

2.0 Reference

Function

Function Specifications

Set memory management area

5

Function NameNo.

MEM_Init

1

nfi

Title

4

Format:Input:

Co

void MEM_Init(Uint32 top_address, Uint32 mem_size)
top_address : Memory management area start address
mem_size: Memory management area size (specify in bytes)
Output:None
Function Value: None
Function:
Sets the memory management area used by MEM_Calloc, MEM_Malloc,
MEM_Realloc, and MEM_Free. The memory space defined by the start addressand size is handled as the memory management area.
Remarks:
Before using MEM_Calloc, MEM_Malloc, MEM_Realloc, and MEM_Free, use thisfunction only once. If used twice or more, the contents of the previously allocatedmemory cannot be guaranteed.

Function

Function Name

No.

Function Specifications

Allocate array area

MEM_Calloc

2

GA

Title

Format:Input:
Output:Function Value:SE

Function:

void *MEM_Calloc(Uint32 arg_num, Uint32 arg_size)
arg_num: Number of array elements
arg_size: Array element byte size
Returns a pointer to the allocated memory block when the function executes
correctly. Returns NULL when an error occurs.
Allocates memory space to the memory management area equivalent to thespecified array element byte size for the specified number of array elements.
Allocated memory blocks are cleared to 0.

Program Library User's Guide 3

67

Function

Function Name

Function Specifications

Free memory blocks

MEM_Free

Title

Function

Function Specifications

Allocate memory blocks

No.

MEM_Malloc

4

void *MEM_Malloc(Uint32 mem_size)
mem_size: Requested memory block size (specified in bytes)
None
Returns a pointer to the allocated memory area when the function executes.
Returns NULL when an error occurs.
Allocates blocks of the requested memory size to the memory management area,
and returns a pointer for those blocks. When the requested memory block size is0, NULL is returned as the function value. Initialization is not performed by
setting this function to 0.

Co

Function:

Function Name

nfi

Format:Input:
Output:Function Value:

3

void MEM_Free(void *mem_ptr)
mem_ptr: Pointer to the memory block
None
None
Frees specified memory blocks. Memory blocks that can be specified are those
allocated by MEM_Calloc, MEM_Malloc, and MEM_Realloc.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Title

Function

Function Name

No.

Function Specifications

Reallocate memory blocks

MEM_Realloc

5

Format:Input:

SE

GA

void *MEM_Realloc(void *mem_ptr, Uint32 mem_size)
mem_ptr: Pointer to the previous memory block
mem_size: New memory block size (specified in bytes)
Output:None
Function Value: Normally returns a pointer to reallocated memory. Returns NULL when anerror occurs.
Function:
The memory block size of the pointer belonging to the memory blocks prior toreallocation is updated. The contents of the previous memory block is transferred
to a new area through reallocation.

68

tia
l

Timer Library
1.0 Guide
1.1 Objectiveden

The Timer Library provides function format macros that access the programmable wait
and processing timer values.
1.2 Overview

The timer uses the free running timer (FRT) in the SH2 and the timer interrupt in the
SCU. Function format macro are provided for each device in consideration of the following applications.
SCU

Timing that is in sync with V-Blanks and H-Blanks can be obtained. This timing
information can be used for performing graphics processing tasks.

nfi

•

CPU

SE

GA

•

The correct wait time can be set as required when programming. Relatively accurate
waits within a C language program can be executed.
Elapsed time can be determined. This can be used to profile code execution times.

Co•

Program Library User's Guide 3

69

•

tia
l

1.3 Detailed Information
SCU

Usage Method

For more details on how to use the SCU’s Timer Function, refer to the Timer Interrupt
section in the SCU User’s Manual .
Calling Sequence/*interrupt flag*//*

execute V-BLANK OUT function *//*interrupt counter*//*

disable timer 1 interrupt

*/

nfi

Uint32 time_flg;. . .
void vblankOut (){Uint32 intr_count = 0;
. . .
TIM_T1_DISABLE ():den

The following calling sequence example shows timer 1 being used to generate a timer
1 interrupt at the 10th bit of every line that is drawn. If the line is odd, it is flipped.

TIM_T1_SET_MODE(TIM_MD_LINE); /*specify interrupt ofevery line

•

CPU

GA

Co

*/
TIM_T1_SET_DATA (10);/* specify interrupt timing at the 10th bit of
the line*/
time_flg = OFF;/*turns off the interrupt flag */TIM_T1_ENABLE();/*
enable timer 1 interrupt*/. . .
for(intr_count < ALL_LINE_NUM) {/* until interrupt of all lines has been
executed*/changeLine(intr_count);/*
flip odd line*/
intr_count ++;/*line count*/}}void timeIntr()/*
execute interrupt function*/{
time_flg = ON;/*turn on the interrupt flag*/}

Basic Items•

Counter Value

SE

Counter values are used when the FRT is used as a timer. The counter value isexplained below.
The count up cycle of the counter value varies depending on the period specifica
tion and graphics mode. Use the following formula to calculate the count-up
cycle.
Count Up Cycle (sec) = (cycle period) x 1 / clock frequency (Hz)70

Function

tialConversion from the counter to microseconds and visa versa can be done conveniently if the following function format macro is used.
Function Format Macro

Convert counter value to microseconds
Convert microseconds to counter value

15
16

de
n

Usage Method•
Initialization

TIM_FRT_CNT_TO_MCR
TIM_FRT_MCR_TO_CNT

No.

Execute the following function format macro before using the wait time (WAIT)
function or fetching elapsed time.
Function

Function Format Macro

Initialize FRT•TIM_FRT_INIT

Fetching Elapsed T
ime

No.

8

nfi

Use the following functions to obtain the elapsed time.
Function

Function Format Macro

Set counter value (16 bit)Get counter value (16 bit)Co

void sysInit(){
TIM_FRT_INIT(8);. . .
}TIM_FRT_SET_16
TIM_FRT_GET_16/*

Set period to 8

No.

9
10

*/

GA

void writeFrameBuff(){

Uint16 count:/* store fetched counter value here */float
micro_sec;/* store microseconds here*/
TIM_FRT_SET_16(0);/* set counter value to 0*/
WriteAllVram();/* execute process to be timed*/
count = TIM_FRT_GET_16()/* get counter value*//* count shows the WriteAllVram() execution time*/
micro_sec = TIM_FRT_CNT_TO_MRC(count); /* convert counter value
to microseconds */printDisplay(micro_sec);/ *display elapsed time on the screen */SE}

Program Library User's Guide 3

71

tia
l

2.0 Reference
2.1 List of Function Format Macros
Function

Function Format Macro

TIM_T0_ENABLE

1Disable timer 0 interrupt

TIM_T0_DISABLE

2

Enable timer 1 interrupt

TIM_T1_ENABLE

3

TIM_T1_DISABLE

4

TIM_T0_SET_CMP

5

TIM_T1_SET_DATA

6

TIM_T1_SET_MODE

7

TIM_FRT_INIT

8

TIM_FRT_SET_16

9

TIM_FRT_GET_16

10

TIM_FRT_DELAY_16

11

Disable timer 1 interrupt
Set timer 0 compare register
Set timer 1 set data register
Set timer 1 mode register
CPU

Initialize FRTSet counter value (16-bit)
Get counter value (16 bit)nfi

Delay Time (16 bit)
Convert counter value to microseconds

TIM_FRT_CNT_TO_MCR

12Convert microseconds to counter value

TIM_FRT_MCR_TO_CNT

13

Set timer interrupt enable register

TIM_FRT_SET_TIER

14

Set timer control/status register

TIM_FRT_SET_TCSR

15

Set free running counter

TIM_FRT_SET_FRC

16

TIM_FRT_SET_OCRA

17

Set output compare register B

TIM_FRT_SET_OCRB

18

Set timer control register

TIM_FRT_SET_TCR

19

Set timer output compare control register

TIM_FRT_SET_TOCR

20

Get timer interrupt enable register

TIM_FRT_GET_TIER

21

Get timer control/status register

TIM_FRT_GET_TCSR

22

Get free running counter

TIM_FRT_GET_FRC

23

Get output compare register A

TIM_FRT_GET_OCRA

24

Get output compare register B

TIM_FRT_GET_OCRB

25

Get timer control register

TIM_FRT_GET_TCR

26

Get timer output compare control register

TIM_FRT_GET_TOCR

27

Get input capture register A

TIM_FRT_GET_ICRA

28

SE

GA

Co

Set output compare register A

72

No.

Enable timer 0 interrupt

de
n

SCU

tia
l

2.2 Function Specifications• SCU
Function

Function Name

No.

Function Specifications

Enable timer 0 interrupt

TIM_T0_ENABLE

1

Format:Input:
Output:Function Value:
Function:

void TIM_T0_ENABLE(void)
None
None
None
Enables timer 0 interrupt.

Title

Function

Function Specifications

Disable timer 0 interrupt

Function NameNo.

TIM_T0_DISABLE

2

nfi

void TIM_T0_DISABLE(void)
None
None
None
Disables timer 0 interrupt.

Co

Format:Input:
Output:Function Value:
Function:

de
n

Title

Title

Function

Function Name

No.

Function Specifications

Enable timer 1 interrupt

TIM_T1_ENABLE

3

Function

Function NameNo.

Disable timer 1 interrupt

TIM_T1_DISABLE

4

Title

void TIM_T1_ENABLE(void)
None
None
None
Enables timer 1 interrupt.

GA

Format:Input:
Output:Function Value:
Function:

Function Specifications

void TIM_T1_DISABLE(void)
None
None
None
Disables timer 1 interrupt.

SE

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 373

Function

Function Name

Function Specifications

Set timer 0 compare register

TIM_T0_SET_CMP

Title

Function

Function Specifications

Set timer 1 set data register

Function

Function Specifications

Set timer 1 mode register

6

Function NameNo.

TIM_T1_SET_MODE

7

GA

Co

void TIM_T1_SET_MODE(Uint32 time_mode)
time_mode: Timer 1 mode register value
None
None
Sets the timer 1 mode register value to the timer 1 mode register.

SE
74

No.

TIM_T1_SET_DATA

void TIM_T1_SET_DATA(Uint32 time_data)
time_data : Timer 1 set data register value
None
None
Sets the timer 1 set data register value to the timer 1 set data register.

Title

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Format:Input:
Output:Function Value:
Function:

5

void TIM_T0_SET_CMP(Uint32 time_cmp)
time_cmp: Timer 0 compare register value
None
None
Sets the timer compare register value to the timer 0 compare register.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

tia
l

• CPU
Title

Function

Function Name

No.

Function Specifications

Initialize FRTTIM_FRT_INIT

8

Format:Input:

void TIM_FRT_INIT(Uint32 mode)
mode: Period
Constant

Description

8

TIM-CKS-32

32

TIM-CKS-128

128

de
n

TIM-CKS-8

nfi

Output:None
Function Value: None
Function:
Sets the selected period and initializes the FRT.

Title

Function

Function Specifications

Set counter value (16 bit)

No.

TIM_FRT_SET_16

9void TIM_FRT_SET_16(Uint16 cnt)
cnt
: Counter value
None
None
Sets the 16-bit counter value to the FRT. The FRT counts from this value.

Co

Format:Input:
Output:Function Value:
Function:

Function Name

Title

Function

Function Name

No.

Function Specifications

Get counter value (16 bit)

TIM_FRT_GET_16

10

Uint16 TIM_FRT_GET_16(void)
None
None
counter value
Gets the 16-bit counter value of the FRT.

SEGA

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 375

Function

Function Name

Function Specifications

Delay time (16 bit)

TIM_FRT_DELAY_16

Title

Function

Function Specifications

Convert counter value tomicroseconds

Convert microseconds to counter
value

Function NameNo.

TIM_FRT_MCR_TO_CNT

13

Uint32 TIM_FRT_MCR_TO_CNT(Float micro)
micro: microsecond value
None
Counter value
Converts microsecond value to a counter value.

Function

GA

Title

Function Specifications

Set Timer Interrupt Enable
Register

Function NameNo.

TIM_FRT_SET_TIER

14void TIM_FRT_SET_TIER(Uint8 reg)reg
: Value
None
None
Sets a value to the timer interrupt enable register.

SE
76

12

Co

Function

Function Specifications

Format:Input:
Output:Function Value:
Function:No.

TIM_FRT_CNT_TO_MCR

Float TIM_FRT_CNT_TO_MCR(Uint32 count)
count: Counter value
None
Microseconds value
Converts specified counter value to a microsecond value.

Title

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Format:Input:
Output:Function Value:
Function:

11

void TIM_FRT_DELAY_16(Uint16 cnt)
cnt
: Delay time counter value
None
None
Waits for the specified delay time counter value. Executes TIM_FRT_SET_16 (0)internally and loops on TIM_FRT_GET_16 (w_cnt) until cnt == w_cnt.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Function

Function Name

Function Specifications

Set timer control/status register

TIM_FRT_SET_TCSR

Title

Function

Function Specifications

Set free running counter

No.

TIM_FRT_SET_FRC

16void TIM_FRT_SET_FRC(Uint16 reg)reg
: Value
None
None
Sets the setting value to the free running counter.

Title

Function

Function Specifications

Set output compare register A

Function NameNo.

TIM_FRT_SET_OCRA

17

void TIM_FRT_SET_OCRA(Uint16 reg)reg
: Value
None
None
Sets the setting value to output compare register A.

Co

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Format:Input:
Output:Function Value:
Function:

15

void TIM_FRT_SET_TCSR(Uint8 reg)reg
: Value
None
None
Sets the setting value to the timer control/status register.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Title

Function

Function Name

No.

Function Specifications

Set Output Compare Register B

TIM_FRT_SET_OCRB

18

void TIM_FRT_SET_OCRB(Uint16 reg)reg
: Value
None
None
Sets the setting value to output compare register B.

SE

GA

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 377

Function

Function Name

Function Specifications

Set timer control register

TIM_FRT_SET_TCR

void TIM_FRT_SET_TCR(Uint8 reg)reg
: Set value
None
None
Sets the setting value to the timer control register.

Title

Function

Function Specifications

Sets timer output compare control TIM_FRT_SET_TOCR
register

Function Name

Title

Function

Function Specifications

Get timer interrupt enable register TIM_FRT_GET_TIER

No.

20

Function Name

No.

21

Uint8 TIM_FRT_GET_TIER(void)
None
None
Register value
Gets the timer interrupt enable register value.

Co

Format:Input:
Output:Function Value:
Function:19

void TIM_FRT_SET_TOCR(Uint8 reg)reg
: Set value
None
None
Sets the setting value to the timer output compare control register.

nfi

Format:Input:
Output:Function Value:
Function:

Title

Function

Function Name

No.

Function Specifications

Get timer control/status register

TIM_FRT_GET_TCSR

22

Uint8 TIM_FRT_GET_TCSR(void)
None
None
Register value
Gets the timer control/status register value.

SE

GA

Format:Input:
Output:Function Value:
Function:

78

de
n

Format:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Function

Function Name

Function Specifications

Get free running counter

TIM_FRT_GET_FRC

Uint16 TIM_FRT_GET_FRC(void)
None
None
Register value
Gets the free running counter value.

Title

Function

Function Specifications

Get output compare register A

Function Name

No.

24

Uint16 TIM_FRT_GET_OCRA(void)
None
None
Register value
Gets the output compare register A value.

Title

Function

Function Specifications

Get output compare register B

Function NameNo.

TIM_FRT_GET_OCRB

25

Uint16 TIM_FRT_GET_OCRB(void)
None
None
Register value
Gets the output compare register B value.

Co

Format:Input:
Output:Function Value:
Function:

23

TIM_FRT_GET_OCRA

nfi

Format:Input:
Output:Function Value:
Function:denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Title

Function

Function Name

No.

Function Specifications

Get timer control register

TIM_FRT_GET_TCR

26

Uint8 TIM_FRT_GET_TCR(void)
None
None
Register value
Gets the timer control register value.

SE

GA

Format:Input:
Output:Function Value:
Function:

Program Library User's Guide 379

Function

Function Name

Function Specifications

Get timer output compare control
register

TIM_FRT_GET_TOCR

Uint8 TIM_FRT_GET_TOCR(void)
None
None
Register value
Gets the timer output compare control register value.

Title

Function

Function Specifications

Get input capture register A

No.

TIM_FRT_GET_ICRA

28

Uint16 TIM_FRT_GET_ICRA(void)
None
None
Register value
Gets the interrupt capture register A value.

Co
GA
SE
80

27

Function Name

nfi

Format:Input:
Output:Function Value:
Function:denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

tia
l

Debug Support Library
1.0 Guide
1.1 ObjectivedenIncorporating the Debug Support Library in the application during code development
enables various debug functions such as the display of character strings to the screen,data input using a software “keyboard”, and read/writes to memory.
1.2 Description

1.3 Coding Example

nfiThis library uses the VDP2 graphics library and constructs a simple debug environment using the normal scroll screen NBG0. The Debug Support Library cannot be
used if the VDP2 library is not used.
• This library only supports the standard SATURN control pad. This library cannot be
used if the peripheral library is not used.
•

The following is an example of an actual C language program.
“sega_scl.h”“sega_dbg.h”

Co#include#includevoid
err(Uint8 *mess);
Uint16 PadData;main(){}GA

SCL_Vdp2Init();
DBG_Initial(&PadData,RGB16_COLOR(31, 31, 31),0);. . . . . . . . . .
/* program*/if (. . . . . . )err(“error occurred in main() ~ function”) ;. . . . . . . . . .
/* program*/SE

void err(Uint8 *mess){
DBG_Printf(“%s¥n”,mess); /*display message
DBG_Monitor():/*go to simple debug environment}

Program Library User's Guide 3

*/
*/

81

2.1 List of Functions
Function

Name

tia
l

2.0 Reference

DBG_Initial

Turn on debug screen display

DBG_DisplayOn

Turn off debug screen display
Clear debug screen
Set debug screen cursor
Display character string on debug screen
Key input by software keyboard

2.2 Function Specifications
Title

Function

Function Specifications

Initialize debug environment

Format:2

DBG_DisplayOff

3

DBG_ClearScreen

4

DBG_SetCursor

5

DBG_Printf

6

DBG_GetKeyStr

7

DBG_Monitor8

nfi

Simple debug process

1

de
n

Initialize debug environment

No.

Function NameNo.

DBG_Initial

1

SE

GA

Co

void DBG_Initial (Uint16 *PadData, Rgb16 charColor, Rgb16
backColor)
Input:
apPadData: Control pad data pointerSpecify the pad data area that is used to set the pad dataobtained by using the peripheral library within a user
V-Blank routine. Pad data should be set byflipping 0 and 1.
charColor: The character display color is specified by 16-bit RGB values.
backColor: The color of the background display is specified by 16-bit
RGB values. Transparent when 0 is specified.
Output:None
Function Value: None
Function:
Sets the program error display routine entry to the Debug Support Library
initialization and the following program exception interrupt vectors.
• General invalid instruction interrupt• Invalid slot instruction interrupt• CPU address error interrupt• DMA address error interrupt
When an error occurs, the program error display routine displays the source of theerror, the current register content, the stack area content, and then passes control to asimple monitor.
Remarks:
Users using the Debug Support Library must execute this function first.

82

Function

Function Name

Function Specifications

Turn on debug screen display

DBG_DisplayOnvoid DBG_DisplayOn(void)
None
None
None
Displays the debug screen.

Title

Function

Function Specifications

Turn off debug screen display

void DBG_DisplayOff(void)
None
None
None
Does not display the debug screen.

Title

Function

Function Specifications

Clear debug screenNo.

DBG_DisplayOff

3

Function NameNo.

DBG_ClearScreen

4void DBG_ClearScreen(void)
None
None
None
Erases data written on the debug screen.

Co

Format:Input:
Output:Function Value:
Function:2

Function Name

nfi

Format:Input:
Output:Function Value:
Function:denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

Title

Function

Function Name

No.

Function Specifications

Set debug screen cursor

DBG_SetCursor

5

Format:Input:

SE

GA

void DBG_SetCursor(Uint16 x, Uint16 y)x: x coordinatey: y coordinate
Output:None
Function Value: None
Function:
Specifies the cursor position.

Program Library User's Guide 383

Function

Function Name

Function Specifications

Display character string on debug
screenDBG_Printf

No.

tia
l

Title

Format:Input:

6denvoid DBG_Printf(const char *control, . . .)control: Pointer to character string that represents the expression...
: Parameter list
Output:None
Function Value: None
Function:
Writes character strings to the debug screen. Used in the same manner as
printf().
Example:sample (){DBG_Printf(“%s¥n”,”SEGA”);}

Function

Function Specifications

Key input by software keyboard

GA
SE
84

No.

DBG_GetKeyStr

7char *DBG_GetKeyStr(char *KeyStr)
keyStr: Input key string return area pointer.
keyStr: Input key string data.
Specified input key string return area pointer.
A software "keyboard" is displayed on the debug screen and a character string isretrieved.
Key pad operation:R: Move key select cursor rightL: Move key select cursor left
U
: Move key select cursor up
D: Move key select cursor down
B+R
: Move key window right
B+L: Move key window left
B+U
: Move key window up
B+D: Move key window downA
: Input key select cursor position character
C: Delete input character (backspace)
START: End input (return)X: Display/don’t display sprite screenY: Display/don’t display scroll screen(other than NBG0 screen)

Co

Format:Input:
Output:Function Value:
Function:

Function Name

nfi

Title

Function

Function Name

Function Specifications

Simple debug process

DBG_Monitor

8

void DBG_Monitor(void)
None
None
None
The following commands are used to display and edit memory. Data within square
brackets [ ] can be omitted, and items separated by a back slash (/) can be selected.

denFormat:Input:
Output:Function Value:
Function:

No.

tia
l

Title

• Display Memorynfi

D fromAddr [toAddr/@size] [;B/W/L] <RTN>
fromAddr: Dump start address
toAddr: Dump end address@size: Dump size (HEX)B: Byte (8 bit) displayW: Word (16 bit) display
L: Long (32 bit) display
After inputting the D command, the memory dump may be continued byentering <RTN>.
• Change Memory Contents

Co

D toAddr [data] [;B/W/L] <RTN>
toAddr: Memory addressdata: Edit data (HEX)B: Byte (8 bits) dataW
: Word (16 bits) dataL
: Long (32 bits) data
If data is omitted, input sequential data from the specified address when thedata entry prompt is displayed. If “^” is input at this time, the edit address isdecremented; if <RTN> is input, the address is incremented. The memory edit
ends when “.” is input.
• Display Register Contents

R<RTN>
Valid only when calling from the exception process routine of the program.

GA• Quit Simple Debug Process

Q<RTN>
Returns to the calling point of this routine. Invalid when called from theexception processing routine of the program.

• Display Command HelpSE

H<RTN>

Program Library User's Guide 385

Terminology
Term

DescriptiontialCompression Decompression Library

Equal to (Size after compression / Size before compression)
X 100 [%]

Symbol (character)1 processing unit of input data for the compression process.
BYTE, WORD, DWORD can be specified in this library.

Code

Smallest unit of compression process output data. Defined
per method.

Run Length Encoding(RLE)

Technique for compressing data based on replacing input
data with a run length value and a corresponding value forthat run length.

Run length

Number of occurrences of the same input value.

Non-pattern phrase

A set of data with a short “run” that results in the creation of
more data under the conventional RLE method.

SE

GA

Co

nfi

de
n

Compression rate

86

tia
l

1.0 Guide
1.1 Application

den

The Compression-Decompression Library is used to decode run length encoded (compressed) data. Run length encoding is done via a utility called CMPRUN.EXE (provided
separately).
1.2 Compression Method

This implementation of RLE has additional processing for handling non-patternphrases. Since a simple RLE algorithm has a tendency of having reduced compression
efficiency when processing non-pattern phrases, those data are organized and processed
together.

nfi

Pattern phrases are represented by a run length and a value. Non-pattern phrases are
represented as non-pattern lengths and data values (i.e. uncompressed data). In order
to differentiate between code that represent pattern and non-pattern data, non-patterndata are expressed as negative values (two’s complement).

Co

Data with short run lengths tend to reduce the processing efficiency of non-patternphrases as well as the overall compression rate. Those data are handled in the samemanner as non-pattern phrases.
Non-Pattern Phase Definition

A non-pattern phrase data set is defined as the following start and end conditions.
• Start condition of non-pattern phrase data:
Symbol (character) with a run length of 1.
• End condition of non-pattern phrase data.

SEGA• Non-pattern phrase with a run length of 3 or greater
OR
When the pattern phrase length can be expressed in terms of the processing byte
number unit.

Program Library User's Guide 387Figure 1.1 shows an example of a non-pattern phrase data.

start

tia
l

Example of Non-Pattern Phrase

A A A A B C C C C D D D D
start

de
n

end

A A A A B C D E F G G G G
end

start

A A A A B C C D D E E E E
end

start

nfi

A A A A B C C D D E F F F F
end

Processing Unit

Co

Figure 1.1 Non-pattern phrase data

As shown in the following table, there are three processing unit types. One character(symbol) is input from the start and broken up into the processing unit size.
Table 1.1 Process Units

Representation of compression processing units for input data

BYTE
(1 byte)11 11 11 11 22 22 33 44 55 66 66 66 66

WORD(2 bytes)

11 11 11 11 22 22 33 44 55 66 66 66 66

SE

GA

Unit

DWORD
(4 bytes)

11 11 11 11 22 22 33 44 55 66 66 66 66

Values are in hexadecimal. 11 corresponds to 1 byte.

88

Expression of Run Length

Table 1.2 Run Length W
idths and Expressions
Run Length(Pattern Phrase Length)
Representation(Description)

Processing
Units

2~
(00h ~

WORD 2 bytes

Representation(Description)

1292~7Fh) (FFh ~

2~

32769

(0000h -

-128

80h)

2~

-32769

7FFFh)(FFFFh ~80000h)231 + 2
2~
7FFFFFFFh) (FFFFFFFFh ~2(00000000h ~Co

DWORD 3 bytes(Non-Pattern Phrase Length)

nfi

BYTE 1 byte

de
n

tia
l

A normal run length (pattern phrase length) is expressed as a positive number, and thenon-pattern phrase length is expressed as a negative number. Because a run length isalways 2 or greater, it is expressed as a value that is value -2. The byte number used forexpressing run length is the same as the processing unit byte number. The actual
amount of data for the run length is decoded by the processing units. That is, a processing unit in words with a run length of 5 is equivalent to the encoding process for 10
bytes of data. The following table shows the range of run length values that can be
expressed.

-231
8000000h)

Processing Image Diagram

Figure 1.2 is a processing image of the compression algorithm using the run length/
non-pattern phrase process.
Non-Pattern Phrase

Coded units
A

A

A

B

B

B

C

D

D

D

E

F

G

3

B

-1 C

3

D

-2 E

F

4

G

GA

Input data

Non-Pattern Phrase

G

G

G

X

Compressed data

3

A

SE

Code unitsA

Pattern phrase value or non-pattern phrase value (uncompressed data).

Any of WORD,
BYTE, WORD,
DWORD.
Processing units. BYTE,
or DWORDn

Run length or non-pattern phrase length.
Run length width. Equivelant to processing units.

Figure 1.2

Program Library User's Guide 3

Run length/non-pattern phrase processing

89Compressed File Format

Header0(K BYTE)

CompressedFile(2 Byte)

Code
Z

Code

Source size
1
(Variable
Length)(Variable
Length)tialFigure 1.3 and the table on the next page show the run length compression file format.
Code(Variable
Length)denK= 2: When source size width is 2 bytes.
K = 6: When source size width is 4 bytes. (The last 2 bytes of the header are omitted tokeep the data in the 4 byte boundary.)

Two types of codes exist, and are differentiated by whether the run length is a positive ora negative value.

Run length n-2<pattern phrase length>(M BYTE)

Pattern phrase length(M BYTE)

nfi

Code(When runlength ≥ 0)
Add 2 and interpretas pattern phrase
lengthM = Processing unit byte number

Code(When runlength < 0)Flip negative sign
and interpret as
pattern phrase
lengthCon: number of units

Run length -n<non-pattern phrase
length> (M BYTE)

Non-pattern phrase
value 0 <uncompressed
data> (M BYTE)

Non-pattern phrase
value n-1 <uncompressed
data> (M BYTE)

M = Processing unit byte number

SE

GA

Figure 1.3

90

Run length compression file format

MSB
Meaning

Bit
PositionCompression Algorithm

15 . . 12

Run length
Reserved

12

11

8

7

11 . . 10

4

3

0

de
n

00 00
00 01

1 byte2 bytes
4 bytes00
01
11

Reserved

9. . 4

Source size width

3

2 bytes
4 bytes

00

00 00

0
1

2. . 0

000

SE

GA

Co

Reserved

LSB

nfi

Processing Units

15

tia
l

Table 1.3 Run length compression file header

Program Library User's Guide 3

91

tia
l

1.3 Decompression Library
Overview

The Decompression Library expands data compressed by the compression tool. Compressed data may be handled as discrete files on the CD-ROM itself or stored by othermeans. However, when the data is decompressed using the Decompression Library, an
input and output data buffer must be set up in a main CPU accessible memory area.

denBoth of these buffers must be reserved for the Decompression Library, and their addresses specified in the library functions.

For example, when input data is read off the CD to be decompressed, the Decompression Library functions must be executed after all of the input data used for a single
decompression pass is read into memory.

nfi

The output data buffer must also be specified in the Decompression Library functions.
When the function exceeds this buffer size, it will halt processing and stop the output ofdata. It is possible to use this feature as a means to perform partial decompression
processing. However, note that there is no feature to resume the interrupted decompression process.

Co

Figure 1.4 gives an overview of the decompression process.

Main CPU(Decompression
Library Function)

MemoryGA

in

Input Data Buffer

out
Output Data Buffer

bufsizeSE

in:
Input buffer start address. Specify in terms of a 4-byte boundary.
out:
Output buffer start address. Specify in terms of a 4-byte boundary.
bufsize: Output buffer size. Integer multiple of the processing unit byte number.

92

Figure 1.4

Decompression Process

Module Configuration

tial

The Decompression Library function has a hierarchical module configuration in termsof the features of each function. The high-level functions are easier to use since theyinterpret the compressed data’s algorithm and parameter attributes and perform decompression processing. The downside is that additional object code must be linked.

denThe low-level functions may be used when it is desirable to link only the minimum
amount of object code that is necessary. If this approach is taken, it is necessary to makesure that there are no functional discrepancies between the output of the compression
tool and the processing of the library function.
Figure 1.5 shows the configuration of the Decompression Library modules.
(High-level function

Low-level function)

nfi

CMP_DecRunlen ()Run length decompression

CMP_DecRunlenByte ()Run length decompression/BYTE unitsCo

CMP_DecRunlenWord ()Run length decompression/WORD units
CMP_DecRunlenDword ()Run length decompression/DWORD units

Module Configuration

SE

GA

Figure 1.5

Program Library User's Guide 393

Usage Examples

tial

The following programming examples show the use of the library functions included in
CMPLIB.LIB. The use of these functions assumes that there is compression data inmemory that can be directly accessed from the main CPU.
Example 1denFigure 1.6 shows an example in which compressed data is included in the source file asa C language data array.

#include "cmplib.h"/* RLE compressed data converted from binary to text data
cmpdata [ ] = {0x10, 0x01, 0x04,. . . . .

nfi

char

Co

}
;
/* decompresseddata bufferchar outputbuf[4096] ;GA

main(){/* decompressed data pointerchar *bufp;/* set to start of decompressed data buffer
bufp = outputbuf;/* run length dictionary decompression
CMP_DecRunlen (cmpdata, &bufp, sizeof(outputbuf));/* use of expanded data}

SE

Figure 1.6 Decompression Library Usage Example 1

94

Example 2"sega_gfs.h""cmplib.h"den#include#includetialFigure 1.7 shows an example in which compressed data is read from the CD-ROM anddecompressed.

/* file read buffer
Uint8 readbuf[READ_SIZE]/* expanded data buffer
Uint8 outputbuf[4096]

nfi

main(){
GfsFid fid;/* file identifier
Sint32 fsize; /* file sizechar*bufp; */fid = 5;/* Set compressed data file identifier
fsize=GFS_Load(fid, 0, readbuf, READBUF_SIZE) file batch readCo/* set to start of decompression data buffer
bufp = outputbuf;/* run length decompression
CMP_DecRunlen (cmpdata, &bufp, sizeof (outputbuf));/*use of decompressed data

GA

}

SE

Figure 1.7 Decompression Library Usage Example 2

Program Library User's Guide 395

2.1 Data Specifications
The following table shows the basic types used in this library.
Table 2.1 Basic Types

Uint8

Unsigned 1-byte integer

Sint8

Signed 1-byte integer

Uint16

Unsigned 2-byte integer

Sint16Signed 2-byte integer

Uint32

Unsigned 4-byte integer

Sint32Signed 4-byte integer

Bool

Boolean type. Takes the following values:
FALSE
TRUE

nfi

.

Description

de
n

Name

tia
l

2.0 ReferenceCo

The following table shows the constant macros defined in this library.
Table 2.2 Constant Macros
Macro Name

Value

Description0

Decompression function return value. Normalend.

1

Decompression function return value. Normal
end. Halt decompression process.

-1

Decompression function return value.
Abnormal end. Input data error.

CMP_DEC_ERR_H_ALGO-2

Decompression function return value.
Abnormal end. Unsupported algorithm.

CMP_DEC_ERR_H_UNIT-3

Decompression function return value.
Abnormal end. Unsupported processing units.

CMP_DEC_OK
CMP_DEC_STOPSEGA

CMP_DEC_ERR

96

tia
l

2.2 List of Functions
The following table lists the functions of the Decompression Library.
Table 1.6 List of Data Decompression Library Functions
Function

Name

No.

CMP_DecRunlen

1

Run length decompression/BYTE units

CMP_DecRunlenByte

1.1

Run length decompression/WORD units CMP_DecRunlenWord

1.2

Run length decompression/DWORD
units

1.3

de
n

Run length decompression

SE

GA

Co

nfi

CMP_DecRunlenDword

Program Library User's Guide 3

97

tia
l

2.3 Function Specifications
Title

Function

Function Name

No.

Function Specifications

Run length decompression

CMP_DecRunlen

1

Return Value:

Note:

Remarks:Co

nfi

Function:

Sint32 CMP_DecRunlen(void *in, void **out, Sint32 size)in(input): Compressed data input buffer pointerout(input): Address of decompressed data output buffer pointer(output): Decompressed data output end pointerbufsize (input): Output buffer size [BYTE]
Processing results:
CMP_DEC_OK( 0) : Normal end. Input data decompression completed.
CMP_DEC_STOP( 1) : Decompressed data to output buffer size.
CMP_DEC_ERR(-1) : Abnormal end. Input data error.
CMP_DEC_ERR_H_ALGO (-2) : Abnormal end. Unsupported algorithm.
CMP_DEC_ERR_H_UNIT (-3) : Abnormal end. Unsupported processing units.
Expands compressed data.
This function processes the compressed data created by the run length compression
tool CMPRUN.EXE. This function interprets the header of the input data and executes the decompression function that supports the compression parameters.
Compressed data is read from in. Decompressed data is written to *out.
*Out performs a post increment for each 1 byte written. The size of decompresseddata can be determined by comparing the difference between the *out value set
before and after the function is executed. The process is stopped if decompresseddata exceeds bufsize [byte]. Decompressed data is written to the available
memory in the buffer even when the process is stopped.

denFormat:Argument:

The input buffer and the output buffer must be reserved. The start
address of each buffer must be specified in terms of a 4-byte boundary.
The output buffer must be large enough to store decompressed data
and be an integer multiple of the processing unit number.

GAin (input)
Input buffer

bufsize (input)

SE

Output buffer

Figure 2.1

98*out (input)*out (output): Compressed data
: Decompressed data
Description of Decompression Function Parameters

Function

Function Name

Function Specifications

Run length decompression / BYTE
units

CMP_DecRunlenByte

Function:

Sint32 CMP_DecRunlenByte(void *in, void **out, Sint32 size)in(input): Compressed data input buffer pointerout(input): Address of decompressed data output buffer pointer(output): Decompressed data output end pointerbufsize (input): Output buffer size [BYTE]
Processing results
CMP_DEC_OK( 0) : Normal end. Input data decompression completed.
CMP_DEC_STOP( 1) : Decompressed data to output buffer size.
CMP_DEC_ERR(-1) : Abnormal end. Input data error.
CMP_DEC_ERR_H_ALGO (-2) : Abnormal end. Unsupported algorithm.
CMP_DEC_ERR_H_UNIT (-3) : Abnormal end. Unsupported processing units.
Expands compressed data.
Processes byte unit RLE compressed data.
Compressed data is read from in. Decompressed data is written to *out.
*Out performs a post increment for each 1 byte written. The size of decompresseddata can be determined by comparing the difference between the *out value set
before and after the function is executed. The process is stopped if decompresseddata exceeds bufsize [byte]. Decompressed data is written to the available
memory in the buffer even when the process is stopped.

denReturn Value:

The input buffer and the output buffer must be reserved. The start
address of each buffer must be specified in terms of a 4-byte boundary.
The output buffer must be large enough to to store decompressed data
and be an integer multiple of the processing unit number.

Co

Note:

The function interface is the same as CMP_DecRunlen().
See Figure 2.1.

SE

GA

Remarks:

1.1

nfi

Format:Argument:

No.

tia
l

Title

Program Library User's Guide 399

Function

Function Name

Function Specifications

Run length decompression / WORD
units

CMP_DecRunlenWord

Function:denReturn Value:

The input buffer and the output buffer must be reserved. The start
address of each buffer must be specified in terms of a 4-byte boundary.
The output buffer must be large enough to store decompressed data
and be an integer multiple of the processing unit number.

Co

Note:

The function interface is the same as CMP_DecRunlen().
See Figure 2.1.

SE

GA

Remarks:100

1.2

Sint32 CMP_DecRunlenWord(void *in, void **out, Sint32 size)in(input): Compressed data input buffer pointerout(input): Address of decompressed data output buffer pointer(output): Decompressed data output end pointerbufsize (input): Output buffer size [BYTE]
Processing results
CMP_DEC_OK( 0) : Normal end. Input data decompression completed.
CMP_DEC_STOP( 1) : Decompressed data to output buffer size.
CMP_DEC_ERR(-1) : Abnormal end. Input data error.
CMP_DEC_ERR_H_ALGO (-2) : Abnormal end. Unsupported algorithm.
CMP_DEC_ERR_H_UNIT (-3) : Abnormal end. Unsupported processing units.
Expands compressed data.
Processes word unit RLE compressed data.
Compressed data is read from in. Decompressed data is written to *out.
*Out performs a post increment for each 1 byte written. The size of decompresseddata can be determined by comparing the difference between the *out value set
before and after the function is executed. The process is stopped if decompresseddata exceeds bufsize [byte]. Decompressed data is written to the available
memory in the buffer even when the process is stopped.

nfi

Format:Argument:

No.

tia
l

Title

Function

Function Name

Function Specifications

Run length decompression /DWORD units

CMP_DecRunlenDword 1.3

Function:denReturn Value:Sint32 CMP_DecRunlenDword(void *in, void **out, Sint32 size)in(input): Compressed data input buffer pointerout(input): Address of decompressed data output buffer pointer(output): Decompressed data output end pointerbufsize (input): Output buffer size [BYTE]
Processing results
CMP_DEC_OK( 0) : Normal end. Input data decompression completed.
CMP_DEC_STOP( 1) : Decompressed data to output buffer size.
CMP_DEC_ERR(-1) : Abnormal end. Input data error.
CMP_DEC_ERR_H_ALGO (-2) : Abnormal end. Unsupported algorithm.
CMP_DEC_ERR_H_UNIT (-3) : Abnormal end. Unsupported processing units.
Expands compressed data.
Processes DWord unit RLE compressed data.
Compressed data is read from in. Decompressed data is written to *out.
*Out performs a post increment for each 1 byte written. The size of decompresseddata can be determined by comparing the difference between the *out value set
before and after the function is executed. The process is stopped if decompresseddata exceeds bufsize [byte]. Decompressed data is written to the available
memory in the buffer even when the process is stopped.

The function interface is the same as CMP_DecRunlen().
See Figure 2.1.

SE

GA

Remarks:

The input buffer and the output buffer must be reserved. The start
address of each buffer must be specified in terms of a 4-byte boundary.
The output buffer must be large enough to store decompressed data
and be an integer multiple of the processing unit number.

Co

Note:

nfi

Format:Argument:

No.

tia
l

Title

Program Library User's Guide 3

101

tia
l

PCM-ADPCM Playback Library
1.0 Overview
1.1 Objectiveden

The PCM-ADPCM Playback Library enables simplified playback of PCM audio on the
SEGA SATURN.
1.2 Features
Easy PCM Playback

ADPCM Support

nfi

The user simply makes calls to the PCM task function periodically in order to perform
audio playback. The library reads from the CD, controls the ring buffer, manages timing, supplies data to the PCM buffer, and issues commands to the sound driver.

This library is capable of decompressing ADPCM compressed data on-the-fly while
playback occurs. ADPCM is a CD-ROM XA audio data format standard that provides
superior sound quality at a compression ratio of approximately 4:1.
Three Types of File Formats

Pause Function

Co(1) AIFF format (uncompressed PCM)
(2) CD-ROM XA audio format (ADPCM compression)(3) User-specified ADPCM format (OptImage Interactive Services AudioStack file
output format)

GA

Although the hardware has no function to pause PCM playback, this library makes
pausing simple.
Multiple Stream Playback

SE

This feature allows four PCM streams to be played at the same time. For example, thiscan be used for a game where overlapping voice-overs from three characters can beplayed back asynchonously with an additional background soundtrack.

102

tia
l

1.3 System Image
Figures 1.1 and 1.2 show the configuration of the PCM-ADPCM Playback Library.
Application

PCM, ADPCM
Playback library

File System, Stream SystemdenSound Memory

Function Call
Data Flownfi

CD BlockCo

Figure 1.1 Playback of Uncompressed PCM Data

Application

GA

PCM,
ADPCM
PCM, ADPCM
Playback
Play
Library
Library

ADPCM
ADPCM
DecomExpansion
pression
Library
LibrarySound Memory(Applicationprogram
program(Application
does
recognize
is notnot
requiredto
ADPCM.)
handle ADPCM.)

SE

File System, Stream System
Function Call
Data Flow

CD Block

Figure 1.2 Playback of Compressed
ADPCM Data

Program Library User's Guide 3

103

tia
l

2.0 Specifications
The following two tables list the specifications of the PCM-ADPCM Playback Library.

Item

Specification

Sampling frequency

Maximum 44.1 kHz

Bit resolution

8 bit, 16 bit

Number of channels

Mono, stereo

File format

AIFF
User-specified ADPCM (1)CD-ROM XA Audio (2)denTable 2.1 Library Specifications (1)Mode 2 Form 2 for CD-ROM XA Audio format
Mode 1 or Mode 2 Form 1 for other cases

Playback modes

Memory Playback Mode (plays data in memory)
File Playback Mode (reads and plays from CDs)
Stream Playback Mode (reads and plays from
CDs)
Branching playback, continuous playback
Multiple stream playback (can play up to 4
streams at the same time)
Pause, stop, volume/pan setting

Co

FunctionsContinuous play time

Maximum 1 hour

Libraries used

File System, Stream System, DMA Library,
ADPCM Decompression LibraryThis library uses the CPU timer (FRT) set to theclock count of 128.

GA

CPU timer (FRT)usage

PCM Uncompressed
ADPCM Compressed
ADPCM Compressednfi

CD-ROM format

Remarks(3)

Uses the File System
Uses the Stream System

Only 1 ADPCM stream
can be played.

These libraries must be
linked along with the PCMADPCM Playback Library(4)

Values can be obtained by
TIM_FRT_GET_16

Initialization is done only once within the

PCM_Init function.

User FRT initialization and settings areprohibited.

SE

Sound driver104

The application performs initialization settings(68000 reset, sound driver transfer, etc.). Thislibrary issues commands for PCM playback(PCM start, stop, parameter change).
When the application issues a command,interrupts must be disabled from the point prior
to the clearing of the command block until thecompletion of the command settings.

See the Saturn Sound
Driver System Interface
manual(Doc. # ST-166-R2-091394).

Both this library and theSound Interface Library are
structured so that they do
not override each other’scommands.

Item

Buffer requirements

SpecificationtialTable 2.2 Library Specifications (2)Remarks

Work buffer: Work structure (about 530 bytes)

Fixed size

(5)
(6)

Ring buffer: Sector size * 10 bytes ~PCM buffer: 4096 * 2 ~ 4096 * 4 sample/1 ch

Required only when
Pause processing work: 4096 samples ~ PCM buffer pause is executed.
size
44 kHz stereo 16 bit: 10%

PCM uncompressed

44 kHz mono 16 bit: 6%

ADPCM compressed

44 kHz stereo 16 bit: 33%

ADPCM compressed37.8 kHz stereo 16 bit: 29%

ADPCM compressed

22 kHz stereo 16 bit: 17%

ADPCM compressed

11 kHz stereo 16 bit: 8%

ADPCM compressed

11 kHz mono 16 bit: 4%• Called at a frequency equal to or greater thanthe V-Blank interrupt frequency (once every 16
ms).
• Single-session task function maximum processingtime
PCM uncompressed stereo 16 bit: 15 msnfi

PCM_Task (taskfunction) specification

PCM uncompressed

These values covers allprocessing times, suchas data transfers fromthe CD block throughwork memory to soundmemory, and in thecase of ADPCM,
decompression
processing.

denCPU overhead (7)(CPU task function
overhead ratio after
play starts): 8 ms: 34 ms: 15 msCo

PCM uncompressed mono 16 bit
ADPCM compressed stereo 16 bit
ADPCM compressed mono 16 bit

If called at an
appropriate frequency,
longer processing
occurs once per several
times of processing.

Notes:The “user-specified ADPCM format” refers to the data file format output by an AIFF to ADPCM fileconverter utility called AudioStack by OptImage Interactive Services.

(2)

CD-ROM XA Audio has 16-bit data ADPCM compressed to 4 bits and has the following formats:Mode B (37.8 kHz) stereo/monoMode C (18.9 kHz) stereo/mono
Only the Stream Playback Mode can be used when CD-ROM XA Audio is used.
For more information, see the CD-ROM XA Standards.

(3)

The Memory Playback Mode can be used in two ways:• To play small files, prepared as memory-based files.
• To play data read by the application from the CD through a series of ring buffers.

(4)

There are also object files that no not need to be linked depending on the functions used.
The ADPCM Decompression Library does not need to be linked if the ADPCM usage declaration
PCM_DeclareUseAdpcm is not made. In Memory Playback Mode, the File System and Stream
System are not linked. In File Playback Mode, the Stream System is not linked. The File System andthe Stream System are linked if the Stream Playback Mode is used.

SE

GA

(1)

Program Library User's Guide 3105

During branching playback or when data is supplied to the ring buffer using memory playback, thedanger of playback interruptions are reduced by using a larger ring buffer. The larger the ring buffer,
the greater the safety margin for playing PCM audio. However, the drawback is that each task’s
processing time becomes somewhat unstable.

tia
l

(5)

When all files are kept in memory for memory playback, the addresses and files sizes for each file
must be specified. These values need not be integer multiples of the sector size.

A PCM buffer size of 4096 * 2 [sample/1 ch] is adequate if there are no special reasons for a larger
buffer.) By allocating enough memory, playback will complete without glitches even when the task
function cannot be called at the required intervals.

(7)

The CPU overhead (CPU overhead ratio for the task function after playback begins) is defined asfollows.
R = (100 X Ttask) / Tplay

de
n

(6)

SE

GA

Co

nfi

R=
CPU overhead [%]Ttask = Total PCM_Task
processing time from start to end of playback.
Tplay = Playback time

106

tia
l

3.0 Playback Sequence
Playback Sequence

Figure 3.1 shows the sequence for audio playback using the Stream System.

Corresponding Functions

Initialization

PCM_Init, PCM_DeclareUseAdpcm

Setof V-Blank
V-Blank Interrupt
Interrupt Process
ProcessSet

INT_Set ScuFunc, PCM_Vblln,
SCL_???, SPR_???

de
n

START

GFS_Init, STM_Init, STM_OpenGrp,
STM-SetExecGrp

Open Stream

STM_OpenFid, GFS_NameTold

PCM_CreateStmHandle
PCM_Set Info
*Playback information settings are required
only for CD_ROM XA Audio format data

Co

Create Handle

nfi

File Initialization

Set Playback Information

PCM_Start

Playback Task Processing

PCM_Task

GA

Start Playback

Completed?

No

PCM_GetPlayStatus

Yes

STM_DestroyMemHandle

Close Stream

STM_CloseSE

Destroy Handle

End Processing

PCM_Finish

END

Program Library User's Guide 3

Figure 3.1 Sequence for Stream Playback107

#define RING_BUF_SIZE (2048L*10)#define PCM_ADDR ((void*)0x25a20000)#define PCM_SIZE (4096L*2)/* Work
PcmWork*/
pcm_work;/* Initialization
PCM_Init();den/* Ring Buffer */Uint32 ring_buf[RING_BUF_SIZE / sizeof(Uint32)];
StmHn
stm;
PcmHn
pcm;

tia
l

Sample Program
The following example is a program that plays either AIFF or ADPCM format files
using the Stream System Library.

*//* ADPCM Use Declaration (required when using ADPCM) */PCM_DeclareUseAdpcm();nfi/* Set Interrupt Process */Use INT_??? and set V-Blank IN interrupt.
Call PCM_VblIn(); within V-Blank IN interrupt.

Co/* File initialization */GFS_Init(..);
STM_Init(..);
STM_OpenGrp();
STM_SetExecGrp(..);/* Open Stream */stm = STM_OpenFid(..);

GA/* Create Handle */PCM_PARA_WORK(&para) = &pcm_work;
PCM_PARA_RING_ADDR(&para) = ring_buf;
PCM_PARA_RING_SIZE(&para) = RING_BUF_SIZE;
PCM_PARA_PCM_ADDR(&para) = PCM_ADDR;
PCM_PARA_PCM_SIZE(&para) = PCM_SIZE;
pcm = PCM_CreateStmHandle(&para, stm);/* Start Playback */PCM_Start(pcm);
while(TRUE) {/* Playback task processing */PCM_Task(pcm);

SE/* End condition */if (PCM_GetPlayStatus(pcm) == PCM_STAT_PLAY_END) break;}/* Destroy Handle */PCM_DestroyStmHandle(pcm);/* Close stream */STM_Close(stm);/* End Processing */PCM_Finish();

108

tia
l

4.0 Programming Precautions
This section lists the precautions that must be taken when implementing the PCMADPCM Playback Library in your application.

Application Development Issues• This library uses the CPU’s DMA and timer functions. The CPU’s DMA and timer
functions may not be used when the library is in operation.
• The frequency with which PCM_Task is called should be more than the V-Blank
interrupt frequency (1 time/16 ms). Calling PCM_Task at every V-Blank interrupt may
not be adequate when the same sound is played back twice.

de
n

1.

2.

Relationship with Other Libraries• This library uses the File System, Stream System, DMA, and ADPCM Decompression
Libraries. Be sure to link these libraries.
Creating a Buffer

nfi

3.

• Reserve the following memory areas:

Size of the work structure
Minimum (sector size) * 10 [byte]. Integer multiple of the sector size.
1 sector = 2324 bytes during CD-ROM XA audio playback.
In all other cases, 1 sector = 2048 bytes.
PCM buffer:4096*2 ~ 4096*4 [sample/1 ch].
Pause processing work: Minimum 4096 [sample]. Optimal when it is the same size as the PCM buffer.

Co

Work buffer:
Ring buffer:

Seamless Branching• The PCM volume and pan settings are the same as the prior handle when seamlessbranching is performed by PCM_EntryNext.
• Up to 60 minutes of continuous playback is possible when seamless branching is performed with PCM_EntryNext. Continuous playback longer than this cannot be done.
• Use file pre-read processing in the application program when seamless branching is
performed.
• The seamless branching function cannot be used when the File System is used.
• The seamless branching function can be performed only during single playback, andnot during multiple system playback.
Multiple System Playback• Use different PCM stream playback numbers when using this feature.
• When playing more than one CD file at the same time, be sure to use file interleaving or
channel interleaving. Use the Stream System in this case.
• Multiple System Playback cannot be done with the same file. Different files
must be specified.
• Multiple System Playback is able to play up to four audio channels at the same time.
• Only one channel of ADPCM compressed audio data can be played.

SE

5.

GA

4.

Program Library User's Guide 3109

ADPCM Support• Link the ADPCM Decompression Library SEGA_ADP.LIB.
• Call the ADPCM usage declaration PCM_DeclareUseAdpcm after the initialization
function.

tia
l

6.

User-SpecifiedADPCM Format Playback• It is possible to play back audio with the same process (same program) as for thedenAIFF format. However, be aware that the CPU overhead increases compared with
the AIFF format.

CD-ROM XA Audio Format Playback• The library determines the playback frequency and the number of channels (stereo/nfimono) from the coding information contained in the subheader area. Confirm thatthe information is entered correctly.
• The library user sets the stream key.
• Set the ring buffer to an integer multiple of the sector size 2324 bytes.
• Set playback information using PCM_SetInfo.
• Use only the Stream Playback mode for CD-ROM XA audio.
• See the sample program smppcm5.c.
Using the Functions• Be sure to call PCM_Init at the start of the program.
• Be sure to call PCM_VblIn within the V-Blank IN interrupt.
• PCM_Start can be executed only once for the handle.
If the same file is played more than once, create a handle for each time it is played.
• Call PCM_SetLoadNum, PCM_SetPcmCmdBlockNo, PCM_SetPcmStreamNo before beginningplayback.
• For handles created using PCM_CreateMemHandle, be sure to communicate the data
size to the ring buffer using PCM_NotifyWriteSize.
• When using the pause function, pause processing work must first be specified by
PCM_SetPauseWork. This work need not be prepared for every handle.
Because this work is a work area that is used temporarily during pause-on processing, the area can be reserved immediately prior to the pause-on processing and can bereleased immediately thereafter.
• CPU DMA is used as the default method to transfer data from the CD block to thering buffer.
Use PCM_SetTrModeCd to specify program transfer, CPU DMA, or SCU DMA.
Call PCM_SetTrModeCd after creating a handle and before calling the task function for
the first time.
• Be sure to set playback information with PCM_SetInfo when playing back
CD-ROM XA audio.

SE

GA

Co

7.

110

5.1 List of Data
Table 5.1 lists the data used by this library.
Table 5.1 List of Data
Function Name

Basic Data

No.

de
n

Functiontial

5.0 Data Specifications

1.0

Constants

2.0

Error code

PCM_ERR_~

2.1

Playback status

PCM_STAT_PLAY_~

2.2

Pause control command

PCM_PAUSE_~

2.3

Forced switch enabled check value

PCM_CHANGE_~

2.4

Data transfer mode select value

PCM_TRMODE_~

2.5

3.0

HandleCreate parameters
Error registration function

PcmHn

3.1

PcmCreatePara

3.2

PcmErrFunc

3.3

PcmInfo

3.4

SE

GA

Co

PCM information

nfi

Data Type

Program Library User's Guide 3111

• Basic Data
Title

Data

Data Specifications

Basic data

Data Name

Description

Unsigned 1 byte integer

Sint8

Signed 1 byte integer

Uint16

Unsigned 2 byte integer

Sint16Signed 2 byte integer

Uint32

Unsigned 4 byte integer

Sint32Signed 4 byte integer

Bool

Boolean type. The following values are taken:
FALSE
TRUE

Co

nfi

Uint8

GA
SE

No.

1.0

de
n

Type

112

tia
l

5.2 Data Details

Constants

tia
l

•

Title

Data

Data NameNo.

Data Specifications

Error Codes

PCM_ERR_~

2.1

Constant Nameden

The following constants represent error codes.

Description

No error has occurred

PCM_ERR_OUT_OF_HANDLE

Out of handles

PCM_ERR_NO_INIT

Initialization function was not called

PCM_ERR_INVALID_HN

Destroyed by invalid handle

PCM_ERR_ILL_CREATE_MODE

Differs than Create mode

PCM_ERR_TOO_LARGE_HEADERHeader is too large (buffer size is too small)

PCM_ERR_HEADER_DATA

Header data error

PCM_ERR_AFI_NO_COMMON
PCM_ERR_AFI_COMPRESS
PCM_ERR_NOT_DECLARE_ADPCM
PCM_ERR_ILLEGAL_PARANo CommonChunk

Unsupported compression type
ADPCM usage declaration not madeMistake in argument specification
Illegal handle

Error status of continuous play handle

PCM_ERR_NEXT_HN_AUDIO

Audio conditions do not match

PCM_ERR_CHANGE_NO_ENTRY

Changed without entries

PCM_ERR_PAUSE_STATUS

Called by conditions other than
PCM_STAT_PLAY_TIME or PCM_STAT_PLAY_PAUSE

PCM_ERR_PAUSE_WORK_NULL

Pause processing work error

PCM_ERR_PAUSE_WORK_SIZEPause processing work error

PCM_ERR_PAUSE_WORK_SET

Illegal pause processing work specification

PCM_ERR_DMA_MODE

Unsupported transfer mode

PCM_ERR_DMA_CPU_PCM

Abnormal end of DMA

PCM_ERR_GFS_READ

GFS read failure

PCM_ERR_RING_SUPPLY

Supplied data to the ring buffer after playback was
finished (data was not supplied in time andprocessing was stopped)

SE

PCM_ERR_NEXT_HN_STATUS

GA

Co

PCM_ERR_ILLEGAL_HANDLE

nfi

PCM_ERR_OK

Program Library User's Guide 3

113

Data

Data Name

Data Specifications

Playback status

PCM_STAT_PLAY_~

The following table shows the playback status data.
Constant Name

No.

tia
l

Title

2.2

Description

Abnormal stop

PCM_STAT_PLAY_CREATE

Creation status

PCM_STAT_PLAY_PAUSE

Pause

PCM_STAT_PLAY_START

Start playback

PCM_STAT_PLAY_HEADERHeader processing status

PCM_STAT_PLAY_TIME

Playing (timer start)

PCM_STAT_PLAY_END

End playbackden

PCM_STAT_PLAY_ERR_STOP

Data

Data Name

Data Specifications

Pause control command

nfi

Title

PCM_PAUSE_~

No.

2.3

The following tables shows pause control data.
Constant Name

PCM_PAUSE_OFF

Immediate pause

Co

PCM_PAUSE_ON_AT_ONCE

Description

Cancel pause

Title

Data

Data NameNo.

Data Specifications

Forced switch enabled check value

PCM_CHANGE_~

2.4

GA

The following table shows forced switching enabled status data.
Constant Name

PCM_CHANGE_OK_AT_ONCE

Forced switching can be done immediately

PCM_CHANGE_NO_DATA

Insufficient data. Cannot do continuous playbacksmoothly if forced switching (PCM_Change) is
executed.

PCM_CHANGE_NO_ENTRY

The next handle is not registered by
PCM_EntryNext. Forced switching (PCM_Change)
cannot be executed.

SE
114

Description

Data

Data Name

Data Specifications

Data transfer mode select value

PCM_TRMODE_~The following table shows data transfer methods.
Constant Name

No.

tia
l

Title

2.5

Description

Software transfer

PCM_TRMODE_SDMA

CPU direct memory access (cycle steal)

PCM_TRMODE_SCU

SCU direct memory access

SE

GA

Co

nfi

de
n

PCM_TRMODE_CPU

Program Library User's Guide 3

115

tia
l

• Data Type
Title

Data

Data NameNo.

Data Specifications

HandlePcmHn

3.1

The following represents information on each playback unit.

Title

Data

Data Specifications

Create parametersdentypedef void *PcmHn;

Data Name

No.

PcmCreatePara

3.2

The following represents handle creation information. All types of parameter values are
set to PCM_Create~ as structures.
typedef struct {PcmWork *work;

Co

nfi

/* Start address of work*//* Work area when this library plays audio */Sint32 *ring_addr; /* Ring buffer address*//* This is the address when playing datafrom memory*/
Sint32 ring_size; /* Ring buffer size [byte]*//* File size when playing data from memory */Sint32 *pcm_addr; /* PCM buffer address of sound memory*/
Sint32 pcm_size;/* PCM buffer size [sample/1 ch] of soundmemory*/}PcmCreatePara;

Cautions Concerning the PCM BufferGA• Set up the PCM buffer in sound memory.
• Specify the integer multiple of 4096 for the PCM buffer size (minimum
4096 X 2).
• If PCM buffer size is considered to be S [sample/1 ch], then—as required by playback conditions—it is expressed in bytes as shown in the following table:
Playback Conditions

PCM Buffer Size (bytes)monauralS [byte]8 bit

stereo

2 X S [byte]

16 bitmonaural

SE

8 bit

16 bitstereo

2 X S [byte]
4 X S [byte]• Specify the same area (address, size) when doing smooth continuous playback.
• Specify a different area when doing multiple stream playback.

116

Data

Data Name

Data Specifications

Error registration function

PcmErrFunc

This function is called when an error occurs.
Format:Input:

No.

tia
l

Title

3.3

Output:

Title

Data

Data Specifications

Playback information

de
n

void
(*PcmErrFunc)(void *obj, Sint32 err_code)
obj: Registered object
err_code : Error code
None

Data NameNo.

PcmInfo

3.4

The following represents PCM playback information.
typedef struct {PcmFileType file_type;
PcmDataType data_type;
Sint32
file_size;

nfi

Co

*/
*/
*/
*/
*/
*/
*/
*/
*/

SE

GA

}

Sint32
Sint32
Sint32
Sint32
Sint32
PcmInfo;/* File type/* Data type/* File size [byte]* Permits the supply of more data than this to* to the ring buffer, but does not process itchannel;/* Number of channels
sampling_bit;/* Sampling bit resolution
sampling_rate;/* Sampling rate [Hz]sample_file;/* Number of samples in the file [sample/1ch]compression_type; /* Compression type

Program Library User's Guide 3117

6.1 List of Functions
Tables 6.1 and 6.2 list the functions of this library.

FunctiondenTable 6.1 List of Functions
Function Name

Initialization and End Processes

No.

1.0

Initialize Library(1) PCM_Init

1.1

Library end process(1) PCM_Finish

1.2

ADPCM use declaration(2) PCM_DeclareUseAdpcm

1.3

2.0

(3) PCM_CreateMemHandle

2.1

Destroy handle (memory)(3) PCM_DestroyMemHandle

2.2

Create handle (file system)(4) PCM_CreateGfsHandle

2.3

Destroy handle (file system)(4) PCM_DestroyGfsHandle

2.4

Create handle (stream system)(5) PCM_CreateStmHandle

2.5

Destroy handle (stream system)(5) PCM_DestroyStmHandle

2.6

Playback task

(1) PCM_Task

2.7
2.8

IN processing function) 1V-Blank(
Playback Controls
Start playbacknfiCreate handle (memory)Co

Handle Operations(1) PCM_VblIn

3.0(6) PCM_Start

3.1

PCM_Stop

3.2(7) PCM_Pause

3.3(6) PCM_EntryNext

3.4

Forced playback handle change

PCM_Change

3.5

Get handle change status

PCM_CheckChange

3.6

Stop playback
Pause

GA

Register next play handle

Notes

Required
Required when using ADPCM
Required for Memory Playback Mode
Required for File Playback Mode
Required for Stream Playback Mode
One or the other is required
Required when using the pause function

SE

(1)
(2)
(3)
(4)
(5)
(6)
(7)

118

tia
l

6.0 Functions Specifications

Function

Function Name

Information Setting Functions

tialTable 6.2 List of Functions (2)
No.

4.0

Set maximum number of transfer
sectors

PCM_SetLoadNum

4.1

Set playback pan position

PCM_SetPan

Set playback volume

PCM_SetVolume

Change PCM playback parameter

PCM_ChangePcmPara

4.4

Set PCM command block number

PCM_SetPcmCmdBlockNo

4.5

4.2

de
n

4.3

Set PCM stream playback number(4)

PCM_SetPcmStreamNo

4.6

Set pause processing work

(5)

PCM_SetPauseWork

4.7

PCM_SetTrModeCd

4.8

PCM_SetInfo

4.9

Set data transfer mode
(CD block→ Ring buffer)
Set playback information(6)

Get Information Functions

5.0

Get playback status(1)

Buffer Controls
Get write buffer

Register error function
Get error information

Notes:

PCM_GetPlayStatus

5.2
6.0

(3)

PCM_GetWriteBuf

6.1

(2)

PCM_NotifyWriteSize

6.2
7.0

PCM_SetErrFunc

7.1

PCM_GetErr

7.2

Required
Required for Memory Playback Mode
Required when supplying data to the ring buffer in the Memory Playback Mode
Required for Multiple Stream Playback Mode
Required when using the pause function
Required for CD-ROM XA audio playback

SE

GA

(1)
(2)
(3)
(4)
(5)
(6)

5.1

Co

Notify write size
Error Controls

PCM_GetTime

nfi

Get playback time

Program Library User's Guide 3

119

tia
l

6.2 Function Details• Initialization and End Processes
Title

Function

Function Name

No.

Function Specifications

Initialize Library

PCM_Init

1.1

Function:
Remarks:

Bool PCM_Init(void)
None
None
When able to initialize normally
TRUE
When unable to initialize normally
FALSE
To enable use of this library, perform this initialization immediately after the
program starts.
Be sure to call this function at the start of the program when using the library.

Function

Function Specifications

Library end process

No.

PCM_Finish

1.2

void PCM_Finish(void)
None
None
None
Performs the PCM library end process.
Call this function when no longer performing PCM playback.

Co

Format:Input:
Output:Value:
Function:
Remarks:

Function Name

nfi

Title

de
n

Format:Input:
Output:Value:

Title

Function

Function Name

Function Specifications

ADPCM use declaration

PCM_DeclareUseAdpcm 1.3

void PCM_DeclareUseAdpcm(void)
None
None
None
This function enables ADPCM playback.
This function is required when the user-specified ADPCM or CD-ROM XA Audioformat data is played back.

GA

Format:Input:
Output:Value:
Function:
Remarks:

No.

SE

Call this function immediately after the initialization function PCM_Init. Calling
this function links the ADPCM Decompression Library module. Calling this function does not restrict playback functions for data formats other than ADPCM.
If this function is not called, the execution file size becomes somewhat smaller.

120

tia
l

• Handle Operations
Title

Function

Function Name

Function Specifications

Create handle (Memory)

PCM_CreateMemHandle 2.1

PcmHn PCM_CreateMemHandle(PcmCreatePara *para)
para : Creation parameters
None
Handle (NULL when unable to generate handle)
Creates handles for playing files that exist in memory.
• 32 handles can be created at the same time.
• Load files with the application program into memory.
• For handles produced by PCM_CreateMemHandle, be sure to communicate the filesize using PCM_NotifyWriteSize.

Title

Function

Function Specifications

Destroy handle (Memory)

Function NameNo.

PCM_DestroyMemHandle 2.2

nfi

void PCM_DestroyMemHandle(PcmHn pcm)
pcm : handle
None
None
Destroys the handle.
Once a handle is destroyed, it can no longer be used.

Co

Format:Input:
Output:Value:
Function:
Remarks:denFormat:Input:
Output:Value:
Function:
Remarks:

No.

Title

Function

Function Name

Function Specifications

Create handle (File System)

PCM_CreateGfsHandle 2.3

Output:Value:
Function:
Remarks:

Title

PcmHn PCM_CreateGfsHandle(PcmCreatePara *para, GfsHn gfs)
para : Creation parameters
gfs : File handle
None
Handle (NULL when unable to generate handle)
Creates a handle for playing files with the File System.
• 32 handles can be created at the same time.
• Get the file handle in advance with the application.

GA

Format:Input:

Function Specifications

Function

Function Name

No.

Destroy handle (File System)

PCM_DestroyGfsHandle 2.4

void PCM_DestroyGfsHandle(PcmHn pcm)
pcm :handleNone
None
Destroys the handle.
Once a handle is destroyed, it can no longer be used.

SE

Format:Input:
Output:Value:
Function:
Remarks:

No.

Program Library User's Guide 3

121

Function

Function Name

Function Specifications

Create handle (Stream System)

PCM_CreateStmHandle

Output:Value:
Function:
Remarks:

Title

Function

Function Specifications

Destroy handle (Stream System)

Playback task

No.

PCM_Task

2.7

GA
Function

Function NameNo.

V-Blank IN processing function

PCM_VblIn

2.8

void PCM_VblIn(void)
None
None
None
Manages the playback time.
Be sure to call this function with a V-Blank IN interrupt process when using thislibrary.

SE
122

Function Name

void PCM_Task(PcmHn pcm)
pcm
: Handle
None
None
Reads files from the CD and transfers data to sound memory.
This function must be called periodically during playback.This function should
be called with a frequency greater than the V-Blank interruptfrequency(1 time/16 ms).

Function Specifications

Format:Input:
Output:Value:
Function:
Remarks:

Co

Function

Function Specifications

Title

No.

PCM_DestroyStmHandle 2.6

void PCM_DestroyStmHandle(PcmHn pcm)
pcm
: Handle
None
None
Destroys handles
Once a handle is destroyed, it can no longer be used.

Title

Format:Input:
Output:Value:
Function:
Remarks:

Function Name

nfi

Format:Input:
Output:Value:
Function:
Remarks:

2.5

PcmHn PCM_CreateStmHandle(PcmCreatePara *para, StmHn stm)
para : Creation parametersstm: Stream handle
None
Handle (NULL when unable to generate handle)
Creates handles for playing files with the Stream System.
• 32 handles can be created at the same time.
• Get the stream handle in advance with the application.

denFormat:Input:

No.

tia
l

Title

tia
l

• Playback Controls
Title

Function

Function Name

No.

Function Specifications

Start playback

PCM_Start

3.1

Title

Function

Function Specifications

Stop playback

Format:Input:
Output:Value:
Function:

void PCM_Stop(PcmHn pcm)
pcm
: Handle
None
None
Stops playback.

Function

Function Specifications

Pause

Format:Input:

Function NameNo.

PCM_Stop

3.2

Function NameNo.

PCM_Pause

3.3

void PCM_Pause(PcmHn pcm, PcmPauseCmd cmd)pcm
: Handle
cmd: Pause control command
None
None
Pauses playback. Also cancels pause.

SE

GA

Output:Value:
Function:

Co

Title

de
n

void PCM_Start(PcmHn pcm)
pcm
: Handle
None
None
Starts playback.
Playback is possible only once per generated handle.
To play the same file repeatedly, a new handle must be generated each time.

nfi

Format:Input:
Output:Value:
Function:
Remarks:

Program Library User's Guide 3

123

Function

Function Name

Function Specifications

Register next play handle

PCM_EntryNext

3.4

void PCM_EntryNext(PcmHn pcm)
pcm
: Handle
None
None
Registers the next playback handle.
When a handle is registered by this function, the next handle automaticallybegins playing when the handle currently playing completes its playback.
The entry is canceled if NULL is specified.

denFormat:Input:
Output:Value:
Function:
Remarks:

No.

tia
l

Title

A handle registered by this function begins playback even if there is a forcedchange by PCM_Change.
Only one handle can be registered. It becomes unregistered when the switch occurs
to the registered handle. In addition, the next handle can be registered.

Function

Function Specifications

Forced playback handle change

Function NameNo.

PCM_Change

3.5

void PCM_Change(void)
None
None
None
Stops the handle currently being played and starts playback of the handle
registered by PCM_EntryNext .

Co

Format:Input:
Output:Value:
Function:

nfi

Title

Title

Function

Function Name

No.

Function Specifications

Get handle change status

PCM_CheckChange

3.6

GA

PcmChangeStatus PCM_CheckChange(void)
None
None
Forced change enabled check value
Enables the application to check whether it can force a change with PCM_Change.

SE

Format:Input:
Output:Value:
Function:

124

tia
l

• Information Setting Functions
Title

Function

Function Name

No.

Function Specifications

Set maximum number of transfer sectors

PCM_SetLoadNum

4.1

Output:Value:
Function:
Remarks:

void PCM_SetLoadNum(PcmHn pcm, Sint32 load_sct)
pcm:
Handleload_set :Maximum number of transfer sectors.
None
None
Sets the maximum number of sectors transferred from the CD buffer to the ringbuffer of the library. Default is 20 sectors.
Call this function before starting playback.

Title

Function

Function Specifications

Set playback pan positionNo.

PCM_SetPan

4.2

nfi

Output:Value:
Function:

Function Name

void PCM_SetPan(PcmHn pcm, Sint32 PAN)
pcm
: Handlepan: Pan value (0 ~ 31)
None
None
Specifies the audio pan position. Default is 0.
Pan settings are valid for mono playback, but are ignored when playing in stereo.

Co

Format:Input:

denFormat:Input:

The following figures shows pan settings.

0

1

→

14

15

16

17

→

30

31

Left Output Max

>>

>>

>>

Off

Max

Max

Max

Max

Max

Max

Max

Max

Max

>>

>>

>>

Off

Pan setting

GA(Volume)Right Output Max

Max

SE

(Volume)

Program Library User's Guide 3

125Function

Function Name

Function Specifications

Set playback volume

PCM_SetVolume

Output:Value:
Function:

Title

Function

Function Specifications

Change PCM playback parameter

Set PCM command block number

SE
126

4.4

Function NameNo.

PCM_SetPcmCmdBlockNo

4.5

void PCM_SetPcmCmdBlockNo(PcmHn pcm, Sint32 blk_no)
pcm: Handle
blk_no :PCM command block number (0 ~ 7)
None
None
Sets the PCM command block number that is set in the sound driver.
Default is 1.
See SATURN Sound Driver System Interface manual for details on the PCM command
block number. This function must be called before starting playback.

GA

Remarks:

Co

Function

Function Specifications

Output:Value:
Function:No.

PCM_ChangePcmPara

void PCM_ChangePcmPara(PcmHn pcm)
pcm
: Handle
None
None
Changes the PCM playback parameter for the sound driver during playback.
The actual parameter change processing is performed by calling this function
after the pan and volume setting are made.

Title

Format:Input:

Function Name

nfi

Format:Input:
Output:Value:
Function:
Remarks:4.3

void PCM_SetVolume(PcmHn pcm, Sint32 volume)pcm: Handle
volume : Volume (0 ~ 7)
None
None
Specifies the volume (no output at 0, maximum volume at 7).
Default is 7.

denFormat:Input:

No.

tia
l

Title

Function

Function Name

Function Specifications

Set PCM stream playback number

PCM_SetPcmStreamNo

Output:Value:
Function:
Remarks:

Title

Function

Function Specifications

Set pause processing work

Example:No.

PCM_SetPauseWork

4.7

void PCM_SetPauseWork(Sint32 *addr, Sint32 size)
addr:Work address
size:
Work size
None
None
Sets the work area used by the pause-on processing.
When using the pause function, a pause processing work area must be specified by
PCM_SetPauseWork in advance. It is not necessary to set the work area up for eachhandle. Because this work area is used temporarily for the pause-on processing, thearea must be reserved immediately before the pause-on processing, and can bereleased immediately thereafter.

nfi

Output:Value:
Function:
Remarks:

Function NameCo

Format:Input:

4.6

void PCM_SetPcmStreamNo(PcmHn pcm, Sint32 stream_no)
pcm:
Handlestream_no :PCM stream playback number (0 ~ 7)
None
None
Sets the PCM stream playback number to set in the sound driver. Default is 1.
See the SATURN Sound Driver System Interface manual for details on PCM stream
playback numbers. Different stream playback numbers must be set to each stream
for multiple stream playback. This function must be called before beginningplayback.

denFormat:Input:

No.

tia
l

Title

#defile PAUSE_WORK_SIZE(4096L*2)

SE

GA

pause_work_addr = malloc(PAUSE_WORK_SIZE);PCM_SetPauseWork(pause_work_addr, PAUSE_WORK_SIZE);PCM_Pause(pcm, PCM_PAUSE_ON_AT_ONCE);
free(pause_work_addr);

Program Library User's Guide 3

127Function

Function Name

Function Specifications

Set data transfer mode
(CD block → ring buffer)

PCM_SetTrModeCd

Format:Input:

Title

Function

Function Specifications

Set playback information

Format:Input:

denRemarks:

Function NameNo.

PCM_SetInfo

4.9

Example:
info;

Co

nfi

void PCM_SetInfo(PcmHn pcm, PcmInfo *info)
pcm:
Handleinfo:
Play information
None
None
Sets information for PCM playback.
Because it gets information for playback from the file header, this function isnormally not used. Currently, it is required only for playing CD-ROM XA audio.
After the handle is created, PCM_SetInfo must be called before the task function iscalled for the first time.
Playback information should be set as shown in the following example for
CD-ROM XA audio playback.

Output:Value:
Function:
Remarks:==

PCM_FILE_TYPE_NO_HEADER;/* without a header */PCM_DATA_TYPE_ADPCM_SCT; /* XA audio sector processing */SEGA

PCM_INFO_FILE_TYPE (&info)
PCM_INFO_DATA_TYPE (&info)
PCM_SetInfo(pcm, &info) ;

128

4.8

void PCM_SetTrModeCd(PcmHn pcm, PcmTrMode mode)
pcm:
Handlemode:
Data transfer method
None
None
Sets the data transfer mode for transfers from the CD block to the ring buffer.
Default is CPU DMA. It is possible to specify software-based transfer.
After the handle is created, PCM_SetTrModeCd must be called before calling the task
function.

Output:Value:
Function:

PcmInfo

No.

tia
l

Title

tia
l

• Get Information Functions
Title

Function

Function Name

No.

Function Specifications

Get play time

PCM_GetTime

5.1

Format:Input:
Output:Value:
Function:

Title

Function

Function Specifications

Get playback status

Format:Input:
Output:Value:
Function:denSint32 PCM_GetTime(PcmHn pcm)
pcm:
HandleNone
Current timeGets the current time (number of samples played from the start of this fileuntil now.)

Function NameNo.

PCM_GetPlayStatus

5.2

nfi

PcmPlayStatus PCM_GetPlayStatus(PcmHn pcm)
pcm:
HandleNone
Playback status
Returns the current playback status.

Co• Buffer Controls
Title

Function

Function Name

No.

Function Specifications

Get write buffer

PCM_GetWriteBuf

6.1

Input:
Output:Value:
Function:
Remarks:

Title

Uint32 *PCM_GetWriteBuf(PcmHn pcm, Sint32 *free_size, Sint32*free_total)
pcm: Handle
free_size : Number of bytes of continuous writeable area
free_total : Total number of bytes of writeable area including
noncontiguous areas.
Start address of contiguous writeable area (NULL when not writeable)
Gets the write destination buffer address and writeable number of bytes.
This function is used by the user to provide data to the ring buffer.

GA

Format:Function Specifications

Function Name

No.

Notify write size

PCM_NotifyWriteSize 6.2

void PCM_NotifyWriteSize(PcmHn pcm, Sint32 write_size)
pcm: Handle
write_size : Number of bytes written
None
None
Notifies the library of the number of data bytes actually output to the ring buffer.
This function is used for implementing user-controlled ring buffer data transfers.
Reports the buffer size (file size) when playing files in memory.

SE

Format:Input:

Function

Output:Value:
Function:
Remarks:

Program Library User's Guide 3

129

tia
l

• Error Controls
Title

Function

Function Name

No.

Function Specifications

Register error function

PCM_SetErrFunc

7.1

Format:Input:

Title

Function

Function Specifications

Get error information

No.

PCM_GetErr

7.2

nfi

GA
SE
130

Function Name

PcmErrCode PCM_GetErr(void)
None
None
Error code
Returns the error code that occurred most recently.

Co

Format:Input:
Output:Value:
Function:denvoid PCM_SetErrFunc(PcmErrFunc func, void *obj)
func : Function called when an error occurs
obj: Registered object
Output:None
Function Value: None
Function:
Sets the function called when an error occurs. The registered object is passed to
the first argument of the registered function.

tia
l

INDEX
C

de
n
I

Co

D

DMA_ScuMemCopy ............................. 42
DMA_ScuResult ..................................... 43
DMA_ScuSetPrm ................................... 47
DMA_ScuStart ........................................ 47
DMA_ScuStop ........................................ 47
DmaCpuComPrm .................................. 38
DmaCpuPrm .......................................... 39
DmaScuPrm ............................................ 35SEGA

DBG_ClearScreen .................................. 83
DBG_DisplayOff .................................... 83
DBG_DisplayOn .................................... 83
DBG_GetKeyStr ..................................... 84
DBG_Initial ............................................. 82
DBG_Monitor ......................................... 85
DBG_Printf ............................................. 84
DBG_SetCursor ...................................... 83
DMA_CpuAllStop ................................. 49
DMA_CpuGetComStatus ..................... 49
DMA_CpuGetStatus ............................. 49
DMA_CpuMemCopy 1 ......................... 44
DMA_CpuMemCopy 16 ....................... 45
DMA_CpuMemCopy 2 ......................... 44
DMA_CpuMemCopy 4 ......................... 45
DMA_CpuResult ................................... 46
DMA_CpuSetComPrm ......................... 48
DMA_CpuSetPrm .................................. 48
DMA_CpuStart ...................................... 48
DMA_CpuStop ...................................... 49
DMA_ScuAllStop .................................. 47

Program Library User's Guide 3

INT_ChgMsk .......................................... 62
INT_GetAck ............................................ 64
INT_GetFunc .......................................... 65
INT_GetMsk ........................................... 62
INT_GetScuFunc .................................... 65
INT_GetStat ............................................ 64
INT_ResStat ............................................ 64
INT_SetAck ............................................. 64
INT_SetFunc ........................................... 65
INT_SetMsk ............................................ 63
INT_SetScuFunc ..................................... 66

nfi

CMP_DecRunlen ................................... 98
CMP_DecRunlenByte ............................ 99
CMP_DecRunlenDword ..................... 101
CMP_DecRunlenWord ........................ 100
CSH_AllClr ............................................. 51
CSH_GetCcr ........................................... 52
CSH_Init .................................................. 51
CSH_Purge ............................................. 52
CSH_SetAcsWay .................................... 54
CSH_SetCcr ............................................ 53
CSH_SetCodeFill ................................... 53
CSH_SetDataFill .................................... 54
CSH_SetEnable ...................................... 53
CSH_SetWayMode ................................ 54

M
MEM_Calloc ........................................... 67
MEM_Free ............................................... 68
MEM_Init ................................................ 67
MEM_Malloc .......................................... 68
MEM_Realloc ......................................... 68

P
PCM_Change ....................................... 124
PCM_CHANGE_~ ............................... 114
PCM_ChangePcmPara ........................ 126

131

tia
l

Co

PCM_SetLoadNum ............................. 125

SEGA

PCM_SetPan ......................................... 125
PCM_SetPauseWork ............................ 127
PCM_SetPcmCmdBlockNo ................ 126
PCM_SetPcmStreamNo ...................... 127
PCM_SetTrModeCd ............................ 128
PCM_SetVolume .................................. 126
PCM_Start ............................................. 123
PCM_STAT_PLAY_~ ........................... 114
PCM_Stop ............................................. 123
PCM_Task ............................................. 122
PCM_TRMODE_~ ............................... 115
PCM_VblIn ........................................... 122
PcmCreatePara ..................................... 116
PcmErrFunc .......................................... 117
PcmHn ................................................... 116
PcmInfo ................................................. 117

132

SND_ChgEfct ......................................... 24
SND_ChgMap ........................................ 24
SND_ChgMix ......................................... 24
SND_ChgMixPrm .................................. 25
SND_ChgPcm ........................................ 28
SND_ChgTempo .................................... 27
SND_ChkHard ....................................... 25
SND_ContSeq ......................................... 26
SND_CtrlDirMidi .................................. 25
SND_GET_ENA_INT ............................ 22
SND_GET_INT_STAT ........................... 30
SND_GetAnlHzVl ................................. 31
SND_GetAnlTlVl ................................... 31
SND_GetPcmPlayAdr ........................... 30
SND_GetSeqPlayPos ............................. 30
SND_GetSeqStat .................................... 30
SND_Init ................................................. 21
SND_MoveData ..................................... 23
SND_PauseSeq ....................................... 26
SND_RESET_INT .................................. 22den

PCM_GetWriteBuf ............................... 129
PCM_Init ............................................... 120
PCM_NotifyWriteSize ......................... 129
PCM_Pause ........................................... 123
PCM_PAUSE_~ .................................... 114
PCM_SetErrFunc ................................. 130
PCM_SetInfo ......................................... 128

Snfi

PCM_CheckChange ............................ 124
PCM_CreateGfsHandle ...................... 121
PCM_CreateMemHandle ................... 121
PCM_CreateStmHandle ..................... 122
PCM_DeclareUseAdpcm .................... 120
PCM_DestroyGfsHandle .................... 121
PCM_DestroyMemHandle ................. 121
PCM_DestroyStmHandle ................... 122
PCM_EntryNext ................................... 124
PCM_ERR_~ ......................................... 113
PCM_Finish .......................................... 120
PCM_GetErr ......................................... 130
PCM_GetPlayStatus ............................ 129
PCM_GetTime ...................................... 129

SND_SET_ENA_INT ............................. 21
SND_SET_FCT_INT .............................. 22
SND_SetCdDaLev ................................. 29
SND_SetCdDaPan ................................. 29
SND_SetSeqVl ........................................ 27
SND_SetTlVl ........................................... 24
SND_StartPcm ........................................ 28
SND_StartSeq ......................................... 26
SND_StartVlAnl ..................................... 27
SND_StopPcm ........................................ 28
SND_StopSeq ......................................... 26
SND_StopVlAnl ..................................... 29
SndAreaMap .......................................... 10
SndCdHzSrVl ......................................... 19
SndEfctBnkNum .................................... 11
SndEfctOut .............................................. 12
SndFade ................................................... 15
SndHardPrm .......................................... 13
SndHardStat ........................................... 13
SndIniDt .................................................. 10
SndLev ..................................................... 12

T

tia
l

de
n

SE

GA

Co

TIM_Frt_Cnt_To_Mcr ............................ 76
TIM_Frt_Delay_16 ................................. 76
TIM_Frt_Get_16 ..................................... 75
TIM_Frt_Get_Frc .................................... 79
TIM_Frt_Get_Icra .................................. 80
TIM_Frt_Get_Ocra ................................. 79
TIM_Frt_Get_Ocrb ................................ 79
TIM_Frt_Get_Tcr .................................... 79
TIM_Frt_Get_Tcsr .................................. 78
TIM_Frt_Get_Tier .................................. 78
TIM_Frt_Get_Tocr .................................. 80
TIM_Frt_Init ........................................... 75
TIM_Frt_Mcr_To_Cnt............................ 76
TIM_Frt_Set_16 ...................................... 75
TIM_Frt_Set_Frc ..................................... 77
TIM_Frt_Set_Ocra .................................. 77
TIM_Frt_Set_Ocrb ................................. 77
TIM_Frt_Set_Tcr ..................................... 78
TIM_Frt_Set_Tcsr ................................... 77
TIM_Frt_Set_Tier ................................... 76
TIM_Frt_Set_Tocr .................................. 78
TIM_T0_Disable ..................................... 73
TIM_T0_Enable ...................................... 73

TIM_T0_Set_Cmp .................................. 74
TIM_T1_Disable ..................................... 73
TIM_T1_Enable ...................................... 73
TIM_T1_Set_Data .................................. 74
TIM_T1_Set_Mode ................................ 74

nfi

SndMixBnkNum .................................... 11
SndPan .................................................... 12
SndPcmChgPrm ..................................... 18
SndPcmIntStat ........................................ 19
SndPcmPlayAdr ..................................... 18
SndPcmStartPrm .................................... 17
SndRet ..................................................... 13
SndSeqBnkNum ..................................... 14
SndSeqNum ............................................ 14
SndSeqPlayPos ....................................... 16
SndSeqPri ................................................ 14
SndSeqSongNum ................................... 14
SndSeqStat .............................................. 16
SndSeqVl ................................................. 15
SndTempo ............................................... 15
SndTlVl .................................................... 11
SndToneBnkNum .................................. 11

Program Library User's Guide 3133