OSDLARM7Base.c File Reference

#include "OSDLConfigForNintendoDS.h"
#include "OSDLARM7Base.h"
#include "CeylanARM7Base.h"
#include "CeylanARM7Codes.h"
#include "CeylanIPCCommands.h"
#include "stdlib.h"
#include "string.h"
#include "helix/pub/mp3dec.h"

Include dependency graph for OSDLARM7Base.c:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef uint16	SampleRate
typedef uint8	ChannelVolume
typedef uint8	ChannelPanning
Functions
s32	getFreeSoundChannel ()
	Returns the number of the first free channel, otherwise -1 is all are busy.
void	triggerFirstBufferRefill ()
	Triggers a refill by the ARM9 of the first part of the encoded buffer.
void	triggerSecondBufferRefill ()
	Triggers a refill by the ARM9 of the second part of the encoded buffer.
bool	decodeNextMP3Frame ()
	Decodes next MP3 frame and handles state variables accordingly.
void	handlePlaySoundRequest (FIFOElement firstElement)
	Manages an IPC request to play an OSDL sound.
void	handlePlayMusicRequest (FIFOElement firstElement)
	Requests the ARM7 to play specified music.
void	handleFadeInMusicRequest (FIFOElement firstElement)
	Triggers a music fade-in.
void	handleFadeOutMusicRequest (FIFOElement firstElement)
	Triggers a music fade-out.
void	handleStopMusicRequest ()
	Requests the ARM7 to stop any music currently playing.
void	handlePauseMusicRequest ()
void	handleSetMusicVolumeRequest (FIFOElement firstElement)
void	handleUnpauseMusicRequest ()
void	handleEndOfEncodedStreamReached ()
	Handles the ARM9 notification that the end of encoded buffer has been reached.
void	handleReceivedIntegratingLibrarySpecificCommand (FIFOCommandID commandID, FIFOElement firstElement)
	OSDL-specific command handler.
void	shutdownOSDLSound ()
	Shuts down the sound hardware and software.
void	setMusicBasicSettings ()
void	unsetMusicBasicSettings ()
void	blankDecodedBuffer ()
void	enableMusicPlayback ()
void	manageMusicFadeEffect ()
void	disableMusicPlayback ()
void	manageMP3Playback ()
	Manages the MP3 playback when requested.
void	initOSDLSound ()
	Sets-up the sound software, including the Helix decoder.
void	initOSDL ()
	Sets-up OSDL and its prerequesites.
Variables
volatile bool	startMP3PlaybackRequested = false
	Tells whether a MP3 play command is being processed.
volatile bool	pauseMP3PlaybackRequested = false
	Tells whether a MP3 pause command is being processed.
volatile HMP3Decoder	currentDecoder
	The state of the Helix decoder instance.
volatile MP3FrameInfo	frameInfo
	Gathers informations about a decoded MP3 frame, needed for playback:
volatile SampleRate	outputSampleRate
	The frequency, in Hz, of (decoded) output samples, a.k.a.
const SampleRate	DefaultSampleRate = 22050
volatile BufferSize	bufferSize
	The size of a (simple) buffer, in bytes:
volatile BufferSize	frameSizeUpperBound
	The smallest upper bound chosen to a MP3 frame size:
volatile Byte *	doubleBuffer
	The actual double sound buffer, two simple buffers, one after the other (so the first half buffer has the same address as this double one).
volatile Byte *	secondBuffer
	The actual address of the second sound buffer.
volatile Byte *	readPointer
	The pointer to current bytes being read in the encoded buffer:
volatile bool	readingFirstBuffer
	Tells whether the first buffer is being read (if true) or whether it is the second one (if false).
volatile Byte *	endOfSafeRead
	The pointer to the byte in the encoded buffer from which no more MP3 frame should be read, as the remaining space could be too small to contain a full frame:
volatile Byte *	destinationOffset
	Precomputes an offset for the moving of encoded data:
volatile Byte *	sizeOffset
	Precomputes an offset for the moving of encoded data:
volatile bool	endOfStreamDetected
	Tells whether the end of the MP3 stream has been detected by the ARM9.
volatile bool	readingLastBuffer
	Tells whether, after an end of stream, we are reading last buffer.
volatile uint8	musicFadeInIncrement
	The number of volume level increments during a music fade-in.
volatile uint8	musicFadeOutDecrement
	The number of volume level decrements during a music fade-pout.
volatile bool	endOfProcessingReached
	Tells whether the end of processing of mp3 frames is requested, either because the last frame of the last buffer has been processed or the ARM9 requested to stop.
volatile bool	decodingInError
	Tells whether the decoding encountered a fatal error.
volatile Byte *	decodedBuffer
	The buffer where decoded music will be output.
const uint32	DecodedBufferSize = 2 * MAX_NGRAN * MAX_NSAMP
	The size of PCM final output buffer.
volatile Byte *	decodePointer
	The pointer to the place in decodedBuffer where decoding should be output:
volatile ChannelVolume	currentMusicVolume = 0x7f
const volatile ChannelVolume	defaultSoundVolume = 0x7f
volatile ChannelPanning	currentMusicPanning = 0
volatile ChannelPanning	defaultSoundPanning = 0
const uint16	DecodedFrameLength = 576 * sizeof(uint16)
	Each decoded MP3 frame should result in samples of this size, in bytes: (at least all the mono mp3 streams generated by lame we tested output 576 samples per frame, not depending on the bit rate).
const uint8	MusicChannel = 0
	First music channel (0) is the one reserved to music (mono PCM).
int	counter = 0

Typedef Documentation

typedef uint8 ChannelPanning

Definition at line 254 of file OSDLARM7Base.c.

typedef uint8 ChannelVolume

Definition at line 231 of file OSDLARM7Base.c.

typedef uint16 SampleRate

Definition at line 89 of file OSDLARM7Base.c.

Function Documentation

void blankDecodedBuffer ( )

Definition at line 1038 of file OSDLARM7Base.c.

References decodedBuffer, and DecodedBufferSize.

Referenced by enableMusicPlayback().

bool decodeNextMP3Frame ( )

Decodes next MP3 frame and handles state variables accordingly.

Returns:: true if succeeded, false otherwise.

Definition at line 376 of file OSDLARM7Base.c.

References currentDecoder, decodedBuffer, DecodedFrameLength, decodePointer, decodingInError, destinationOffset, endOfProcessingReached, endOfSafeRead, endOfStreamDetected, frameInfo, HelixDecodingError, HelixFoundTruncatedFrame, HelixLacksDataInBitReservoir, HelixLacksFreeBitrateSlot, HelixSyncWordNotFound, readingFirstBuffer, readingLastBuffer, readPointer, secondBuffer, sizeOffset, triggerFirstBufferRefill(), and triggerSecondBufferRefill().

Referenced by manageMP3Playback().

void disableMusicPlayback ( )

Definition at line 1143 of file OSDLARM7Base.c.

References unsetMusicBasicSettings().

Referenced by manageMP3Playback().

void enableMusicPlayback ( )

Definition at line 1049 of file OSDLARM7Base.c.

References blankDecodedBuffer(), decodedBuffer, DecodedFrameLength, frameInfo, MusicChannel, outputSampleRate, and setMusicBasicSettings().

Referenced by manageMP3Playback().

s32 getFreeSoundChannel ( )

Returns the number of the first free channel, otherwise -1 is all are busy.

Note:: Channel 15 is reserved (for music).

Definition at line 307 of file OSDLARM7Base.c.

Referenced by handlePlaySoundRequest().

void handleEndOfEncodedStreamReached ( )

Handles the ARM9 notification that the end of encoded buffer has been reached.

Definition at line 898 of file OSDLARM7Base.c.

References endOfStreamDetected.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handleFadeInMusicRequest ( FIFOElement firstElement )

Triggers a music fade-in.

The last 16 bits contains the requested fade-in duration, in milliseconds.

Definition at line 752 of file OSDLARM7Base.c.

References currentMusicVolume, DecodedFrameLength, DefaultSampleRate, musicFadeInIncrement, and outputSampleRate.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handleFadeOutMusicRequest ( FIFOElement firstElement )

Triggers a music fade-out.

The last 16 bits contains the requested fade-out duration, in milliseconds.

Definition at line 803 of file OSDLARM7Base.c.

References currentMusicVolume, DecodedFrameLength, DefaultSampleRate, musicFadeOutDecrement, and outputSampleRate.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handlePauseMusicRequest ( )

Definition at line 866 of file OSDLARM7Base.c.

References pauseMP3PlaybackRequested.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handlePlayMusicRequest ( FIFOElement firstElement )

Requests the ARM7 to play specified music.

A boolean parameter is set in the command element: its last bit tells whether the playback should start from first buffer (if 1) or from second (if 0).

The second element is a pointer to the cache-aligned sound buffer, third is composed of the full size of the encoded buffer (16 first bits), then the delta value (the MP3 frame size upper bound, 16 last bits).

No answer expected.

See also:: StopMusicRequest

Definition at line 692 of file OSDLARM7Base.c.

References bufferSize, decodedBuffer, decodePointer, decodingInError, destinationOffset, doubleBuffer, endOfProcessingReached, endOfSafeRead, endOfStreamDetected, frameSizeUpperBound, musicFadeInIncrement, musicFadeOutDecrement, outputSampleRate, pauseMP3PlaybackRequested, readingFirstBuffer, readingLastBuffer, readPointer, secondBuffer, sizeOffset, and startMP3PlaybackRequested.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handlePlaySoundRequest ( FIFOElement firstElement )

Manages an IPC request to play an OSDL sound.

Definition at line 613 of file OSDLARM7Base.c.

References defaultSoundPanning, defaultSoundVolume, getFreeSoundChannel(), NoAvailableChannelNotification, and UnexpectedSampleFormat.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handleReceivedIntegratingLibrarySpecificCommand	(	FIFOCommandID	commandID,
		FIFOElement	firstElement
	)

OSDL-specific command handler.

Definition at line 908 of file OSDLARM7Base.c.

References EndOfEncodedStreamReached, FadeInMusicRequest, FadeOutMusicRequest, handleEndOfEncodedStreamReached(), handleFadeInMusicRequest(), handleFadeOutMusicRequest(), handlePauseMusicRequest(), handlePlayMusicRequest(), handlePlaySoundRequest(), handleSetMusicVolumeRequest(), handleStopMusicRequest(), handleUnpauseMusicRequest(), PauseMusicRequest, PlayMusicRequest, PlaySoundRequest, SetMusicVolumeRequest, StopMusicRequest, UnexpectedOSDLCommand, and UnpauseMusicRequest.

void handleSetMusicVolumeRequest ( FIFOElement firstElement )

Definition at line 875 of file OSDLARM7Base.c.

References currentMusicVolume.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handleStopMusicRequest ( )

Requests the ARM7 to stop any music currently playing.

No direct answer expected.

See also:: PlayMusicRequest

Definition at line 857 of file OSDLARM7Base.c.

References endOfProcessingReached.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void handleUnpauseMusicRequest ( )

Definition at line 884 of file OSDLARM7Base.c.

References pauseMP3PlaybackRequested.

Referenced by handleReceivedIntegratingLibrarySpecificCommand().

void initOSDL ( )

Sets-up OSDL and its prerequesites.

Integrating library-specific (ex: OSDL) command handler, declared here but to be defined by user code, typically the OSDL library, if used.

Definition at line 1287 of file OSDLARM7Base.c.

References initOSDLSound().

void initOSDLSound ( )

Sets-up the sound software, including the Helix decoder.

Definition at line 1259 of file OSDLARM7Base.c.

References currentDecoder, decodedBuffer, DecodedBufferSize, and HelixInitializationFailed.

Referenced by initOSDL().

void manageMP3Playback ( )

Manages the MP3 playback when requested.

Definition at line 1164 of file OSDLARM7Base.c.

References decodeNextMP3Frame(), decodingInError, disableMusicPlayback(), enableMusicPlayback(), endOfProcessingReached, manageMusicFadeEffect(), MusicEndedNotification, pauseMP3PlaybackRequested, setMusicBasicSettings(), startMP3PlaybackRequested, and unsetMusicBasicSettings().

void manageMusicFadeEffect ( )

Definition at line 1093 of file OSDLARM7Base.c.

References currentMusicPanning, currentMusicVolume, endOfProcessingReached, MusicChannel, musicFadeInIncrement, and musicFadeOutDecrement.

Referenced by manageMP3Playback().

void setMusicBasicSettings ( )

Definition at line 1011 of file OSDLARM7Base.c.

References currentMusicPanning, currentMusicVolume, and MusicChannel.

Referenced by enableMusicPlayback(), and manageMP3Playback().

void shutdownOSDLSound ( )

Shuts down the sound hardware and software.

Definition at line 996 of file OSDLARM7Base.c.

References currentDecoder.

void triggerFirstBufferRefill ( )

Triggers a refill by the ARM9 of the first part of the encoded buffer.

Definition at line 332 of file OSDLARM7Base.c.

References FirstBufferFillRequest.

Referenced by decodeNextMP3Frame().

void triggerSecondBufferRefill ( )

Triggers a refill by the ARM9 of the second part of the encoded buffer.

Definition at line 351 of file OSDLARM7Base.c.

References SecondBufferFillRequest.

Referenced by decodeNextMP3Frame().

void unsetMusicBasicSettings ( )

Definition at line 1024 of file OSDLARM7Base.c.

References MusicChannel, and outputSampleRate.

Referenced by disableMusicPlayback(), and manageMP3Playback().

Variable Documentation

volatile BufferSize bufferSize

The size of a (simple) buffer, in bytes:

Definition at line 104 of file OSDLARM7Base.c.

Referenced by OSDL::EmbeddedFileSystemManager::copyFile(), and handlePlayMusicRequest().

int counter = 0

Definition at line 367 of file OSDLARM7Base.c.

volatile HMP3Decoder currentDecoder

The state of the Helix decoder instance.

Definition at line 81 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), initOSDLSound(), and shutdownOSDLSound().

volatile ChannelPanning currentMusicPanning = 0

Definition at line 264 of file OSDLARM7Base.c.

Referenced by manageMusicFadeEffect(), and setMusicBasicSettings().

volatile ChannelVolume currentMusicVolume = 0x7f

Definition at line 239 of file OSDLARM7Base.c.

Referenced by handleFadeInMusicRequest(), handleFadeOutMusicRequest(), handleSetMusicVolumeRequest(), manageMusicFadeEffect(), and setMusicBasicSettings().

volatile Byte* decodedBuffer

The buffer where decoded music will be output.

Will be directly played by the sound hardware.

Note:: Allocated directly from the ARM7.

Definition at line 205 of file OSDLARM7Base.c.

Referenced by blankDecodedBuffer(), decodeNextMP3Frame(), enableMusicPlayback(), handlePlayMusicRequest(), and initOSDLSound().

const uint32 DecodedBufferSize = 2 * MAX_NGRAN * MAX_NSAMP

The size of PCM final output buffer.

Must be able to contain two full decoded frames: MAX_NCHAN = 2 (stereo), MAX_NGRAN = 2 granules, MAX_NSAMP = 576 samples, hence 2*1152 = 2*DecodedFrameLength

Note:: Use only 2 * MAX_NGRAN * MAX_NSAMP = 2 * 1152 if mono, otherwise use 2 * MAX_NCHAN * MAX_NGRAN * MAX_NSAMP if stereo.

Definition at line 219 of file OSDLARM7Base.c.

Referenced by blankDecodedBuffer(), and initOSDLSound().

const uint16 DecodedFrameLength = 576 * sizeof(uint16)

Each decoded MP3 frame should result in samples of this size, in bytes: (at least all the mono mp3 streams generated by lame we tested output 576 samples per frame, not depending on the bit rate).

(multiplied by two as 16-bit, so 1152).

Definition at line 285 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), enableMusicPlayback(), handleFadeInMusicRequest(), and handleFadeOutMusicRequest().

volatile Byte* decodePointer

The pointer to the place in decodedBuffer where decoding should be output:

Definition at line 226 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), and handlePlayMusicRequest().

volatile bool decodingInError

Tells whether the decoding encountered a fatal error.

Definition at line 188 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), handlePlayMusicRequest(), and manageMP3Playback().

const SampleRate DefaultSampleRate = 22050

Definition at line 96 of file OSDLARM7Base.c.

Referenced by handleFadeInMusicRequest(), and handleFadeOutMusicRequest().

volatile ChannelPanning defaultSoundPanning = 0

Definition at line 274 of file OSDLARM7Base.c.

Referenced by handlePlaySoundRequest().

const volatile ChannelVolume defaultSoundVolume = 0x7f

Definition at line 248 of file OSDLARM7Base.c.

Referenced by handlePlaySoundRequest().

volatile Byte* destinationOffset

Precomputes an offset for the moving of encoded data:

Definition at line 151 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), and handlePlayMusicRequest().

volatile Byte* doubleBuffer

The actual double sound buffer, two simple buffers, one after the other (so the first half buffer has the same address as this double one).

Definition at line 117 of file OSDLARM7Base.c.

Referenced by handlePlayMusicRequest().

volatile bool endOfProcessingReached

Tells whether the end of processing of mp3 frames is requested, either because the last frame of the last buffer has been processed or the ARM9 requested to stop.

Definition at line 183 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), handlePlayMusicRequest(), handleStopMusicRequest(), manageMP3Playback(), and manageMusicFadeEffect().

volatile Byte* endOfSafeRead

The pointer to the byte in the encoded buffer from which no more MP3 frame should be read, as the remaining space could be too small to contain a full frame:

Definition at line 146 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), and handlePlayMusicRequest().

volatile bool endOfStreamDetected

Tells whether the end of the MP3 stream has been detected by the ARM9.

Definition at line 160 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), handleEndOfEncodedStreamReached(), and handlePlayMusicRequest().

volatile MP3FrameInfo frameInfo

Gathers informations about a decoded MP3 frame, needed for playback:

Definition at line 86 of file OSDLARM7Base.c.

Referenced by decodeNextMP3Frame(), and enableMusicPlayback().

volatile BufferSize frameSizeUpperBound

The smallest upper bound chosen to a MP3 frame size:

Definition at line 108 of file OSDLARM7Base.c.

Referenced by handlePlayMusicRequest().

const uint8 MusicChannel = 0

First music channel (0) is the one reserved to music (mono PCM).

Using preferably the first one as channels 8-15 are special channels: 8-13 are the only channels that can also play PSG sounds and 14-15 the only that can generate noise.

Definition at line 297 of file OSDLARM7Base.c.

Referenced by enableMusicPlayback(), manageMusicFadeEffect(), setMusicBasicSettings(), and unsetMusicBasicSettings().

volatile uint8 musicFadeInIncrement

The number of volume level increments during a music fade-in.

Definition at line 169 of file OSDLARM7Base.c.

Referenced by handleFadeInMusicRequest(), handlePlayMusicRequest(), and manageMusicFadeEffect().

volatile uint8 musicFadeOutDecrement

The number of volume level decrements during a music fade-pout.

Definition at line 173 of file OSDLARM7Base.c.

Referenced by handleFadeOutMusicRequest(), handlePlayMusicRequest(), and manageMusicFadeEffect().

volatile SampleRate outputSampleRate

The frequency, in Hz, of (decoded) output samples, a.k.a.