Ceylan::System::FIFO Class Reference

Interrupt-based FIFO (First In, First Out) class for command-based Inter-Process Communication (IPC). More...

#include <CeylanFIFO.h>

Inheritance diagram for Ceylan::System::FIFO:

Collaboration diagram for Ceylan::System::FIFO:

List of all members.

Classes

class FIFOEmpty

Raised whenever trying to read from an empty FIFO. More...

class FIFOException

Mother class for all FIFO-related exceptions. More...

class FIFOFull

Raised whenever trying to write to a full FIFO. More...

Public Types

enum TextOutputFormat { rawText, html }

Defines what text output formats for TextDisplayable instances are available. More...

Public Member Functions

FIFO ()

Constructs a new bidirectional logical FIFO, notably from two unidirectional hardware FIFO.

virtual ~FIFO () throw ()

Virtual destructor.

virtual bool isActive () const

Returns whereas this FIFO is currently active.

virtual void activate ()

Activates the FIFO, and notifies the ARM7 of the variables it should use to store its status and error code.

virtual void deactivate ()

Deactivates the FIFO.

virtual ARM7StatusWord getLastARM7StatusWord ()

Returns the latest status word set by the ARM7.

virtual std::string interpretLastARM7StatusWord ()

Returns an interpretation of the latest status word set by the ARM7.

virtual ARM7ErrorCode getLastARM7ErrorCode ()

Returns the latest error code set by the ARM7.

virtual std::string interpretLastARM7ErrorCode ()

Returns an interpretation of the latest error code set by the ARM7.

virtual void sendBatteryStatusRequest ()

Sends to the ARM7 a request to update the battery status.

virtual BatteryStatus getBatteryStatus ()

Returns the battery status.

virtual void sendDSTypeRequest ()

Sends to the ARM7 a request to update the DS type.

virtual DSType getDSType ()

Returns the DS actual type (DS Fat,Lite, etc.

virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const

Returns an user-friendly description of the state of this object.

Static Public Member Functions

static FIFOCommandID GetFIFOCommandIDFrom (const FIFOElement &element)

Returns the command identifier read from specified FIFO element.

static FIFOCommandCount GetFIFOCommandCountFrom (const FIFOElement &element)

Returns the command count read from specified FIFO element.

static FIFOCommandCount GetARM7ProcessedCount ()

Returns the number of commands processed by the ARM7, based on the IPC sync register.

static FIFOCommandCount GetARM9ProcessedCount ()

Returns the number of commands processed by the ARM9, based on the IPC sync register.

static void VBlankHandlerForFIFO ()

Callback to catch the reception of a FIFO element by polling during the Vblank interrupt.

static FIFO & GetActivatedFIFO ()

Returns the supposedly already-created and already-activated singleton FIFO.

static FIFO & GetExistingFIFO ()

Returns the supposedly already-created singleton FIFO.

static FIFO & GetFIFO ()

Returns the singleton FIFO, creates it if needed.

static bool RemoveFIFO ()

Removes the singleton FIFO, if any.

static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)

Returns a user-friendly description of this list of pointers to text displayable instances.

static TextOutputFormat GetOutputFormat ()

Returns the current overall text format to be used by TextDisplayable instances.

static void SetOutputFormat (TextOutputFormat newOutputFormat)

Sets the current overall text format to be used by TextDisplayable instances.

Static Public Attributes

static FIFO * _FIFO = 0

The unique FIFO instance.

Protected Member Functions

virtual void handleReceivedCommand ()

Method responsible for the actual decoding of an incoming command.

virtual void handleReceivedSystemSpecificCommand (FIFOCommandID commandID, FIFOElement firstElement)

Method responsible for the actual decoding and management of an incoming system-specific (Ceylan) command.

virtual void handleReceivedIntegratingLibrarySpecificCommand (FIFOCommandID commandID, FIFOElement firstElement)

Method responsible for the actual decoding and management of an incoming command specific to an integrating library (ex: OSDL).

virtual void handleReceivedApplicationCommand (FIFOCommandID commandID, FIFOElement firstElement)

Method responsible for the actual decoding and management of an incoming application-specific command.

virtual void handleUnexpectedApplicationCommand (FIFOCommandID commandID)

Basic helper method called whenever an unexpected application command is received.

virtual FIFOElement prepareFIFOCommand (FIFOCommandID id)

Prepare the first FIFO element for specified command.

virtual void notifyCommandToARM7 ()

Notifies the ARM7 that a new command has been placed in the FIFO.

virtual void sendSynchronizeInterruptToARM7 ()

Sends a synchronize IRQ to the ARM7, for example to make it check its receive FIFO.

bool dataAvailableForReading () const

Tells whether there is data available for reading in the ARM9 receiving queue.

bool spaceAvailableForWriting () const

Tells whether there is space available for writing in the ARM9 sending queue.

FIFOElement read ()

Helper method that returns the first FIFO element available in the FIFO.

FIFOElement readBlocking ()

Helper method that returns the first FIFO element available in the FIFO.

void write (FIFOElement toSend)

Helper methods that write the specified FIFO element in the send queue.

void writeBlocking (FIFOElement toSend)

Helper methods that write the specified FIFO element in the send queue.

FIFOCommandCount getProcessedCount () const

Returns the current count of processed commands, in [0,15].

FIFOCommandCount getSentCount () const

Returns the current count of sent commands, in [0,15].

virtual void incrementProcessedCount ()

Increments the current count of processed commands, in [0,15], and updates accordingly the IPC sync register.

Static Protected Member Functions

static void SyncHandlerForFIFO ()

Callback called whenever the ARM7 triggers an IPC Synchronize interrupt on the ARM9.

static void ManageReceivedCommand ()

Manages a command sent through the FIFO.

static std::string DescribeCommand (FIFOElement element)

Returns a textual description of the specified command.

Protected Attributes

ARM7StatusWord volatile *volatile _arm7StatusWordPointer

ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its status.

ARM7ErrorCode volatile *volatile _arm7ErrorCodePointer

ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its last error.

volatile FIFOCommandCount _localCommandCount

Records the overall number of sent commands to the FIFO.

volatile FIFOCommandCount _remoteCommandCount

Records the overall number of received commands to the FIFO.

volatile FIFOCommandCount _processedCount

Records the number of commands processed by the ARM9.

volatile FIFOCommandCount _sentCount

Records the number of commands sent by the ARM9 to the ARM7.

volatile bool _activated

Tells whether this FIFO is activated.

volatile System::BatteryStatus _batteryStatus

Records the last battery status retrieved.

volatile System::DSType _dsType

Records the DS type.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText

The text format to be used currently by TextDisplayable instances.

Private Member Functions

FIFO (const FIFO &source)

Copy constructor made private to ensure that it will be never called.

FIFO & operator= (const FIFO &source)

Assignment operator made private to ensure that it will be never called.

Detailed Description

Interrupt-based FIFO (First In, First Out) class for command-based Inter-Process Communication (IPC).

This logical bidirectional IPC bus is synchronized by interrupts only (no polling), for the platforms that support that, i.e. the Nintendo DS.

This class is dedicated to the encapsulation of two hardware FIFO, notably for the two of the Nintendo DS, between the two ARMs.

The FIFO in itself communicates only using the hardware FIFO: no shared variable is used, except two that are used to report ARM7 status and error code. But of course this communication system can be used to send pointers to (shared) variables.

The system in itself is in C for the ARM7, as it has quite little memory for its executable.

See also:: testCeylanFIFO.arm7.c for a full example implementation.

The ARM9 can rely on this C++ abstraction for simpler management.

See also:: testCeylanFIFO.arm9.cc for a full usage example.

Each FIFO register is only 32-bit, thus as soon as a command needs to specify an address (32 bits), it has to use more than one FIFO register by sending a series of FIFO elements. The reading callback will block until a full command is received.

A generic and empty FIFO class is provided here. It is made to be subclassed by adding as many methods as needed to send and receive messages from the end of the FIFO. For example the sendPlayRequest and onPlayNotification methods could be added. They act as callbacks. Their processing should not be too long, and it should not trigger interrupts or use I/O (ex: no libfat call allowed).

An application-specific protocol shall be built on top of this generic FIFO.

Request management should be asynchronous: one should send a request, store in the state of the FIFO child class, and return, without waiting directly in this send function the answer: the other ARM may send a request of its own just after this ARM sent his request, and the request of the other ARM would be read instead of the expected answer.

The FIFO can work on normal mode, or a more paranoid one, if CEYLAN_SAFE_FIFO is equal to 1. According to the tests, both are 100% reliable (if used properly of course), but the later may detect errors by, notably, keeping track of command numbers to ensure none is lost and they are managed in the right order. Note that the CEYLAN_SAFE_FIFO flag must be set for both ARM executables.

There could be a second fail-over mechanism, based on the 4 bits that each ARM can set in the IPC sync register. It is for the moment only used during the ARM handshake, in activation step.

Ceylan, for its inner working, has to use too that FIFO, notably so that the ARM7 state can be transferred and managed on the ARM9. Thus the FIFO has to be shared between Ceylan and the user code, and conventions have to be respected.

Each command can be made of any number of FIFO elements (they can be read one after the other and thus the size of the FIFO does not matter), but the first byte of its first element must be the command identifier.

Command identifiers range from 0 to 255. Ceylan reserves all command ID between 0 and 127, thus the application must choose its identifiers in the 128-255 range (128 free slots).

Note that they are 128 free application-specific command identifiers from the ARM9 to the ARM7, and another 128 identifier in the other way round (they have nothing in common).

Note also that the answer to a command has to use itself a command identifier, to be able to distinguish an answer for a new request.

If not in safe mode (CEYLAN_SAFE_FIFO not equal to 1), the three remaining bytes and the potential next FIFO elements are command-specific.

If in safe mode (CEYLAN_SAFE_FIFO equal to 1), only the two last bytes of the command element can be used by the application, as the command ID (first byte) is followed by a command count (second byte) which allows to catch any lost FIFO element. For the moment no element has been reported lost on a real DS, neither on the emulator.

To send requests, use in a SetEnabledInterrupts pair (to avoid being interrupts during the sending): 'FIFOElement commandElement = prepareFIFOCommand( myID ) ;' followed by the sending of this command element (writeBlocking) and any number of other elements. Then, just out of the SetEnabledInterrupts pair, the other ARM must be notified of the request (ex: notifyCommandToARM7).

Note:: Once a command has been written in the FIFO, the 'notifyCommandToARM7' method must be called, otherwise the ARM7 may not manage it and block, as it does not perform any polling. There is nevertheless a fail-over mechanism: when an ARM uses blocking reads or writes, and if the FIFO cannot perform it (as respectively empty or full), the sending ARM will trigger the receiving ARM so that it manages any elements in its receive queue (thus emptying it) and, possibly, outputs answers to found requests (thus filling its send queue).

To handle incoming requests, override handleReceivedApplicationCommand, which will be given the incoming command ID, and just read the relevant number of elements.

The overriden handleReceivedApplicationCommand method is responsible for reading all the associated elements, so that they will not disturb the next decoding of the handler.

See also:: testCeylanFIFO.arm9.cc and testCeylanFIFO.arm7.c for a complete example.

Due to the use of a callback based on a static method, the FIFO instance is expected to be a singleton.

See also:: testCeylanFIFO.arm9.cc to have a complete example showing how to avoid the numerous pitfalls of IPC programming.

For example, the deactivate method should be called from the destructor of the child FIFO class, not from the mother FIFO one, otherwise an IRQ after the child destructor but before the end of the mother destructor would trigger a call to a pure virtual method.

See also:: the Ceylan::System::Pipe class for another means, more general, of doing IPC.

Inspired from: http://www.double.co.nz/nintendo_ds/nds_develop7.html

Definition at line 207 of file CeylanFIFO.h.

Member Enumeration Documentation

enum Ceylan::TextDisplayable::TextOutputFormat [inherited]

Defines what text output formats for TextDisplayable instances are available.

Enumerator:

rawText
html

Definition at line 124 of file CeylanTextDisplayable.h.

Constructor & Destructor Documentation

FIFO::FIFO ( ) [explicit]

Constructs a new bidirectional logical FIFO, notably from two unidirectional hardware FIFO.

Exceptions:

FIFOException

on failure.

See also:: activate to trigger the use of the FIFO.

Definition at line 132 of file CeylanFIFO.cc.

References _arm7ErrorCodePointer, _arm7StatusWordPointer, _FIFO, Ceylan::System::atomicSleep(), Ceylan::System::CacheProtectedNew(), CEYLAN_LOG_FIFO, getLastARM7ErrorCode(), getLastARM7StatusWord(), Ceylan::System::InitializeInterrupts(), NoErrorAvailable, NoStatusAvailable, SyncHandlerForFIFO(), and Ceylan::toString().

Referenced by GetFIFO().

FIFO::~FIFO ( ) throw () [virtual]

Virtual destructor.

Definition at line 381 of file CeylanFIFO.cc.

References _arm7ErrorCodePointer, _arm7StatusWordPointer, _FIFO, and Ceylan::System::CacheProtectedDelete().

Ceylan::System::FIFO::FIFO ( const FIFO & source ) [private]

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

void FIFO::activate ( ) [virtual]

Activates the FIFO, and notifies the ARM7 of the variables it should use to store its status and error code.

Note:: This method cannot be automatically called from the constructor, as an asynchronous IRQ could be triggered on the receive between the call to this method and the end of the constructor. In that case handleReceivedCommand would be called, whereas at this moment is still pure virtual (since still in FIFO constructor).
This method will wait a certain amount of time to let the ARM7 update its status. If the ARM7 implementation is faulty (ex: there is no code on the ARM7 executable to handle the FIFO and the ARM7 report mechanism), an exception will be thrown.

Exceptions:

FIFOException,should

the ARM9 time-out short of an ARM7 update of its status word.

Definition at line 434 of file CeylanFIFO.cc.

References _activated, _arm7ErrorCodePointer, _arm7StatusWordPointer, _localCommandCount, _processedCount, _remoteCommandCount, _sentCount, Ceylan::System::AllInterruptsDisabled, ARM7Running, Ceylan::System::atomicSleep(), CEYLAN_LOG_FIFO, getLastARM7ErrorCode(), getLastARM7StatusWord(), interpretLastARM7ErrorCode(), interpretLastARM7StatusWord(), NoError, NoErrorAvailable, NoStatusAvailable, notifyCommandToARM7(), prepareFIFOCommand(), sendSynchronizeInterruptToARM7(), Ceylan::System::SetEnabledInterrupts(), StatusInitRequest, Ceylan::toString(), generalUtils::true, and writeBlocking().

Referenced by Ceylan::System::InitializeIPC().

bool FIFO::dataAvailableForReading ( ) const [protected]

Tells whether there is data available for reading in the ARM9 receiving queue.

Definition at line 1431 of file CeylanFIFO.cc.

References generalUtils::false.

Referenced by handleReceivedCommand(), read(), readBlocking(), and toString().

void FIFO::deactivate ( ) [virtual]

Deactivates the FIFO.

Note:: This method can be called from the destructor of the most specialized child class inheriting from this one. It cannot be called directly for the destructor of this mother FIFO, as an IRQ could trigger a pure virtual method call before this deactivate method is called.

Definition at line 615 of file CeylanFIFO.cc.

References _activated, Ceylan::System::AllInterruptsDisabled, ARM7IPCShutdown, Ceylan::System::atomicSleep(), CEYLAN_LOG_FIFO, generalUtils::false, getLastARM7StatusWord(), interpretLastARM7StatusWord(), notifyCommandToARM7(), prepareFIFOCommand(), Ceylan::System::SetEnabledInterrupts(), ShutdownIPCRequest, and writeBlocking().

string FIFO::DescribeCommand ( FIFOElement element ) [static, protected]

Returns a textual description of the specified command.

Definition at line 1831 of file CeylanFIFO.cc.

References GetFIFOCommandCountFrom(), GetFIFOCommandIDFrom(), Ceylan::toNumericalString(), and toString().

FIFO & FIFO::GetActivatedFIFO ( ) [static]

Returns the supposedly already-created and already-activated singleton FIFO.

Exceptions:

FIFOException

if the operation failed, including if no FIFO is available or if it is not active.

Definition at line 1087 of file CeylanFIFO.cc.

References _FIFO, and isActive().

Referenced by Ceylan::System::GetBatteryStatus(), and Ceylan::System::GetDSType().

FIFOCommandCount FIFO::GetARM7ProcessedCount ( ) [static]

Returns the number of commands processed by the ARM7, based on the IPC sync register.

Note:: Only the 4 lower bits are used, for a count in [0,15].

Definition at line 1005 of file CeylanFIFO.cc.

Referenced by toString().

FIFOCommandCount FIFO::GetARM9ProcessedCount ( ) [static]

Returns the number of commands processed by the ARM9, based on the IPC sync register.

Note:: Only the 4 lower bits are used, for a count in [0,15].

Definition at line 1031 of file CeylanFIFO.cc.

BatteryStatus FIFO::getBatteryStatus ( ) [virtual]

Returns the battery status.

If the status is 'BatteryStatusUnknown', will wait until either a supposedly-called 'sendBatteryStatusRequest' method completes (resulting in an update of the status), or a time-out expires.

Note:: Uses waiting based on atomic sleeps.

Exceptions:

FIFOException

if the operation failed, including if the time-out expires.

Definition at line 878 of file CeylanFIFO.cc.

References _batteryStatus, Ceylan::System::atomicSleep(), and Ceylan::System::BatteryStatusUnknown.

Referenced by Ceylan::System::GetBatteryStatus().

DSType FIFO::getDSType ( ) [virtual]

Returns the DS actual type (DS Fat,Lite, etc.

).

If the status is 'DSTypeUnknown', will wait until either a supposedly-called 'sendDSTypeRequest' method completes (resulting in an update of the DS type), or a time-out expires.

Note:: Uses waiting based on atomic sleeps.

Exceptions:

FIFOException

if the operation failed, including if the time-out expires.

Definition at line 921 of file CeylanFIFO.cc.

References _dsType, Ceylan::System::atomicSleep(), and Ceylan::System::DSTypeUnknown.

Referenced by Ceylan::System::GetDSType().

FIFO & FIFO::GetExistingFIFO ( ) [static]

Returns the supposedly already-created singleton FIFO.

Exceptions:

FIFOException

if the operation failed, including if not FIFO is available.

Definition at line 1104 of file CeylanFIFO.cc.

References _FIFO.

FIFO & FIFO::GetFIFO ( ) [static]

Returns the singleton FIFO, creates it if needed.

Exceptions:

FIFOException

if the operation failed.

Definition at line 1117 of file CeylanFIFO.cc.

References _FIFO, and FIFO().

FIFOCommandCount FIFO::GetFIFOCommandCountFrom ( const FIFOElement & element ) [static]

Returns the command count read from specified FIFO element.

Definition at line 995 of file CeylanFIFO.cc.

Referenced by DescribeCommand(), and handleReceivedCommand().

FIFOCommandID FIFO::GetFIFOCommandIDFrom ( const FIFOElement & element ) [static]

Returns the command identifier read from specified FIFO element.

Definition at line 986 of file CeylanFIFO.cc.

Referenced by DescribeCommand(), and handleReceivedCommand().

ARM7ErrorCode FIFO::getLastARM7ErrorCode ( ) [virtual]

Returns the latest error code set by the ARM7.

Reads the relevant shared variable.

See also:: CeylanARM7Codes.h for list of known error codes.

Definition at line 757 of file CeylanFIFO.cc.

References _arm7ErrorCodePointer, NoErrorVariableAvailable, and generalUtils::temp.

Referenced by activate(), FIFO(), and interpretLastARM7ErrorCode().

ARM7StatusWord FIFO::getLastARM7StatusWord ( ) [virtual]

Returns the latest status word set by the ARM7.

Reads the relevant shared variable.

See also:: CeylanARM7Codes.h for list of known status codes.

Definition at line 692 of file CeylanFIFO.cc.

References _arm7StatusWordPointer, NoStatusVariableAvailable, and generalUtils::temp.

Referenced by activate(), deactivate(), FIFO(), and interpretLastARM7StatusWord().

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat ( ) [static, inherited]

Returns the current overall text format to be used by TextDisplayable instances.

Definition at line 63 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::formatStringList(), Ceylan::formatStringMap(), Ceylan::XML::XMLMarkup::toString(), Ceylan::Maths::Linear::Vector3::toString(), Ceylan::Maths::Linear::Vector2::toString(), Ceylan::Maths::Linear::Tripoint::toString(), Ceylan::Module::toString(), Ceylan::Maths::Linear::Matrix3::toString(), Ceylan::Maths::Linear::Matrix2::toString(), Ceylan::Maths::Linear::HomogeneousMatrix3::toString(), and Ceylan::Maths::Linear::Bipoint::toString().

FIFOCommandCount FIFO::getProcessedCount ( ) const [protected]

Returns the current count of processed commands, in [0,15].

Definition at line 1677 of file CeylanFIFO.cc.

References _processedCount.

Referenced by toString().

FIFOCommandCount FIFO::getSentCount ( ) const [protected]

Returns the current count of sent commands, in [0,15].

Definition at line 1686 of file CeylanFIFO.cc.

References _sentCount.

Referenced by toString().

void FIFO::handleReceivedApplicationCommand	(	FIFOCommandID	commandID,
		FIFOElement	firstElement
	)			`[protected, virtual]`

Method responsible for the actual decoding and management of an incoming application-specific command.

Meant to be overriden according to the chosen application-specific protocol.

Parameters:

	commandID	the application-specific command ID read from the first FIFO element of the command.
	firstElement	the full (first) FIFO element corresponding to the command (thus containing commandID).

Note:: Called automatically by handleReceivedCommand when relevant.
Only lightweight operations should be performed here.

Definition at line 1327 of file CeylanFIFO.cc.

References handleUnexpectedApplicationCommand().

Referenced by handleReceivedCommand().

void FIFO::handleReceivedCommand ( ) [protected, virtual]

Method responsible for the actual decoding of an incoming command.

Discriminates between Ceylan commands, that are managed automatically, and application-specific commands, that result in an appropriate call to handleReceivedApplicationCommand, which is most probably overriden.

Note:: Called automatically by ManageReceivedCommand.

Definition at line 1155 of file CeylanFIFO.cc.

References _remoteCommandCount, dataAvailableForReading(), GetFIFOCommandCountFrom(), GetFIFOCommandIDFrom(), handleReceivedApplicationCommand(), handleReceivedIntegratingLibrarySpecificCommand(), handleReceivedSystemSpecificCommand(), incrementProcessedCount(), readBlocking(), and Ceylan::toNumericalString().

Referenced by ManageReceivedCommand().

void FIFO::handleReceivedIntegratingLibrarySpecificCommand	(	FIFOCommandID	commandID,
		FIFOElement	firstElement
	)			`[protected, virtual]`

Method responsible for the actual decoding and management of an incoming command specific to an integrating library (ex: OSDL).

Implements the library-specific protocol for these commands.

Parameters:

	commandID	the library-specific command ID read from the first FIFO element of the command.
	firstElement	the full (first) FIFO element corresponding to the command (thus containing commandID).

Note:: Called automatically by handleReceivedCommand when relevant, made to be overriden by the integrating library.
Only lightweight operations should be performed here.

Definition at line 1308 of file CeylanFIFO.cc.

References Ceylan::toNumericalString().

Referenced by handleReceivedCommand().

void FIFO::handleReceivedSystemSpecificCommand	(	FIFOCommandID	commandID,
		FIFOElement	firstElement
	)			`[protected, virtual]`

Method responsible for the actual decoding and management of an incoming system-specific (Ceylan) command.

Implements the system-specific protocol for these commands.

Parameters:

	commandID	the system-specific command ID read from the first FIFO element of the command.
	firstElement	the full (first) FIFO element corresponding to the command (thus containing commandID).

Note:: Called automatically by handleReceivedCommand when relevant.
Only lightweight operations should be performed here.

Definition at line 1248 of file CeylanFIFO.cc.

References _batteryStatus, _dsType, Ceylan::System::AlmostEmpty, BatteryStatusAnswer, Ceylan::System::DSFat, Ceylan::System::DSLite, DSTypeAnswer, HelloToTheARM9, PongARM9, Ceylan::toNumericalString(), and Ceylan::System::WellCharged.

Referenced by handleReceivedCommand().

void FIFO::handleUnexpectedApplicationCommand ( FIFOCommandID commandID ) [protected, virtual]

Basic helper method called whenever an unexpected application command is received.

Parameters:

commandID

the identifier of the unexpected command.

Note:: Basic implementation made to be overriden.

Definition at line 1342 of file CeylanFIFO.cc.

References Ceylan::toNumericalString().

Referenced by handleReceivedApplicationCommand().

void FIFO::incrementProcessedCount ( ) [protected, virtual]

Increments the current count of processed commands, in [0,15], and updates accordingly the IPC sync register.

Definition at line 1695 of file CeylanFIFO.cc.

References _processedCount.

Referenced by handleReceivedCommand().

string FIFO::interpretLastARM7ErrorCode ( ) [virtual]

Returns an interpretation of the latest error code set by the ARM7.

Reads the relevant shared variable.

Definition at line 774 of file CeylanFIFO.cc.

References AwokenWithNothingToRead, CommandOverlapping, ErrorVoluntarilyLeftBlank, FIFOErrorWhileReading, FIFOErrorWhileWriting, FIFOTimeOutWhileReading, FIFOTimeOutWhileWriting, getLastARM7ErrorCode(), IncorrectApplicationAnswer, IncorrectInitialError, IncorrectInitialStatus, IPCAlreadyStarted, IPCAlreadyStopped, NoError, NoErrorVariableAvailable, toString(), UnexpectedApplicationCommand, UnexpectedBehaviour, UnexpectedCommandCount, and UnexpectedSystemCommand.

Referenced by activate(), and interpretLastARM7StatusWord().

string FIFO::interpretLastARM7StatusWord ( ) [virtual]

Returns an interpretation of the latest status word set by the ARM7.

Reads the relevant shared variable.

Definition at line 717 of file CeylanFIFO.cc.

References ARM7InError, ARM7IPCShutdown, ARM7Running, getLastARM7StatusWord(), interpretLastARM7ErrorCode(), NoStatusAvailable, NoStatusVariableAvailable, StatusReset, StatusVoluntarilyLeftBlank, and toString().

Referenced by activate(), and deactivate().

bool FIFO::isActive ( ) const [virtual]

Returns whereas this FIFO is currently active.

Definition at line 425 of file CeylanFIFO.cc.

References _activated.

Referenced by GetActivatedFIFO().

void FIFO::ManageReceivedCommand ( ) [static, protected]

Manages a command sent through the FIFO.

Static, to be called as an IRQ handler.

See also:: handleReceivedCommand

Definition at line 1740 of file CeylanFIFO.cc.

References _FIFO, generalUtils::false, handleReceivedCommand(), and generalUtils::true.

Referenced by SyncHandlerForFIFO(), and VBlankHandlerForFIFO().

void FIFO::notifyCommandToARM7 ( ) [protected, virtual]

Notifies the ARM7 that a new command has been placed in the FIFO.

Increments the sent count, and triggers an IPC IRQ in the ARM7.

Definition at line 1390 of file CeylanFIFO.cc.

References _sentCount, and sendSynchronizeInterruptToARM7().

Referenced by activate(), deactivate(), sendBatteryStatusRequest(), and sendDSTypeRequest().

FIFO& Ceylan::System::FIFO::operator= ( const FIFO & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

FIFOElement FIFO::prepareFIFOCommand ( FIFOCommandID id ) [protected, virtual]

Prepare the first FIFO element for specified command.

Sets the specified ID in the returned FIFO element and, if used (in safe mode), sets as well the command number.

Note:: The two (if using command number) or three (if not) remaining bytes can be used freely by application code.
Ensure there is exactly one command sent for each call to this method, otherwise the command count will be incorrect.

Parameters:

id

the command ID to set in the FIFO element.

Returns:: a FIFO element patched with the specified ID and, possibly, command number.

Definition at line 1357 of file CeylanFIFO.cc.

References _localCommandCount.

Referenced by activate(), deactivate(), sendBatteryStatusRequest(), and sendDSTypeRequest().

FIFOElement FIFO::read ( ) [protected]

Helper method that returns the first FIFO element available in the FIFO.

Exceptions:

FIFOException,including

FIFOEmpty if the FIFO has no such element.

Definition at line 1467 of file CeylanFIFO.cc.

References dataAvailableForReading().

FIFOElement FIFO::readBlocking ( ) [protected]

Helper method that returns the first FIFO element available in the FIFO.

If not already available, the method will wait for it (potentially forever), while helping notifying never-ending reads and overcoming them, by triggering the ARM7.

Exceptions:

FIFOException

in case a FIFO error is reported.

Definition at line 1508 of file CeylanFIFO.cc.

References dataAvailableForReading(), and sendSynchronizeInterruptToARM7().

Referenced by handleReceivedCommand().

bool FIFO::RemoveFIFO ( ) [static]

Removes the singleton FIFO, if any.

Returns:: true iff there was a FIFO to remove.

Exceptions:

FIFOException

if the operation failed.

Definition at line 1130 of file CeylanFIFO.cc.

References _FIFO, generalUtils::false, and generalUtils::true.

void FIFO::sendBatteryStatusRequest ( ) [virtual]

Sends to the ARM7 a request to update the battery status.

Note:: Non-blocking, not waiting for the answer.

Exceptions:

FIFOException

if the operation failed.

See also:: getBatteryStatus for a blocking wait for the update.

Definition at line 858 of file CeylanFIFO.cc.

References _batteryStatus, Ceylan::System::AllInterruptsDisabled, BatteryStatusRequest, Ceylan::System::BatteryStatusUnknown, notifyCommandToARM7(), prepareFIFOCommand(), Ceylan::System::SetEnabledInterrupts(), and writeBlocking().

Referenced by Ceylan::System::GetBatteryStatus().

void FIFO::sendDSTypeRequest ( ) [virtual]

Sends to the ARM7 a request to update the DS type.

Note:: Non-blocking, not waiting for the answer.

Exceptions:

FIFOException

if the operation failed.

See also:: getDSType for a blocking wait for the update.

Definition at line 901 of file CeylanFIFO.cc.

References _dsType, Ceylan::System::AllInterruptsDisabled, DSTypeRequest, Ceylan::System::DSTypeUnknown, notifyCommandToARM7(), prepareFIFOCommand(), Ceylan::System::SetEnabledInterrupts(), and writeBlocking().

Referenced by Ceylan::System::GetDSType().

void FIFO::sendSynchronizeInterruptToARM7 ( ) [protected, virtual]

Sends a synchronize IRQ to the ARM7, for example to make it check its receive FIFO.

Definition at line 1400 of file CeylanFIFO.cc.

Referenced by activate(), notifyCommandToARM7(), readBlocking(), and writeBlocking().

void TextDisplayable::SetOutputFormat ( TextOutputFormat newOutputFormat ) [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:

newOutputFormat

the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

bool FIFO::spaceAvailableForWriting ( ) const [protected]

Tells whether there is space available for writing in the ARM9 sending queue.

Definition at line 1449 of file CeylanFIFO.cc.

Referenced by toString(), write(), and writeBlocking().

void FIFO::SyncHandlerForFIFO ( ) [static, protected]

Callback called whenever the ARM7 triggers an IPC Synchronize interrupt on the ARM9.

This signature is mandatory.

See also:: handleReceivedCommand
VBlankHandlerForFIFO

Definition at line 1723 of file CeylanFIFO.cc.

References ManageReceivedCommand().

Referenced by FIFO().

const std::string TextDisplayable::ToString	(	std::list< TextDisplayable * >	displayables,
		Ceylan::VerbosityLevels	level = `Ceylan::high`
	)			`[static, inherited]`

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:

	displayables	a list of pointers to TextDisplayable instances/
	level	the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const std::string FIFO::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: TextDisplayable

Implements Ceylan::TextDisplayable.

Definition at line 944 of file CeylanFIFO.cc.

References _activated, _arm7StatusWordPointer, _localCommandCount, _remoteCommandCount, dataAvailableForReading(), GetARM7ProcessedCount(), getProcessedCount(), getSentCount(), Ceylan::low, and spaceAvailableForWriting().

Referenced by DescribeCommand(), interpretLastARM7ErrorCode(), and interpretLastARM7StatusWord().

void FIFO::VBlankHandlerForFIFO ( ) [static]

Callback to catch the reception of a FIFO element by polling during the Vblank interrupt.

Expected to be called regularly in the VBlank handler, to add a polling-based layer of security to the IRQ-based approach, in case an interrupt is lost.

This signature is mandatory. Public so that it can be registered as an handler externally.

Just checks whether the FIFO is empty. If not, calls the handleReceivedCommand method.

Note:: Not used here anymore as not needed: no polling needed, and used to create synchronization issues.

Definition at line 1057 of file CeylanFIFO.cc.

References ManageReceivedCommand().

void FIFO::write ( FIFOElement toSend ) [protected]

Helper methods that write the specified FIFO element in the send queue.

Exceptions:

FIFOException,including

FIFOFull if the FIFO has no free space for that.

Definition at line 1577 of file CeylanFIFO.cc.

References spaceAvailableForWriting().

void FIFO::writeBlocking ( FIFOElement toSend ) [protected]

Helper methods that write the specified FIFO element in the send queue.

If there is no more space available in that queue, the method will wait for it (potentially forever), while helping notifying never-ending writes and overcoming them, by triggering the ARM7.

Exceptions:

FIFOException

in case a FIFO error is reported.

Definition at line 1612 of file CeylanFIFO.cc.

References sendSynchronizeInterruptToARM7(), and spaceAvailableForWriting().

Referenced by activate(), deactivate(), sendBatteryStatusRequest(), and sendDSTypeRequest().

Member Data Documentation

volatile bool Ceylan::System::FIFO::_activated [protected]

Tells whether this FIFO is activated.

Note:: No need to have ot declared volatile normally.

Definition at line 973 of file CeylanFIFO.h.

Referenced by activate(), deactivate(), isActive(), and toString().

ARM7ErrorCode volatile* volatile Ceylan::System::FIFO::_arm7ErrorCodePointer [protected]

ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its last error.

Note:: We expected to declare it only as 'ARM7ErrorCode volatile *', as only the pointed value can be modified by the ARM7. It worked on NoCashGBA emulator, but not on the DS, until we declared as well the pointer itself to be volatile. Maybe a problem due to the ARM9 cache.

Definition at line 902 of file CeylanFIFO.h.

Referenced by activate(), FIFO(), getLastARM7ErrorCode(), and ~FIFO().

ARM7StatusWord volatile* volatile Ceylan::System::FIFO::_arm7StatusWordPointer [protected]

ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its status.

Note:: We expected to declare it only as 'ARM7StatusWord volatile *', as only the pointed value can be modified by the ARM7. It worked on NoCashGBA emulator, but not on the DS, until we declared as well the pointer itself to be volatile. Maybe a problem due to the ARM9 cache.

Definition at line 886 of file CeylanFIFO.h.

Referenced by activate(), FIFO(), getLastARM7StatusWord(), toString(), and ~FIFO().

volatile System::BatteryStatus Ceylan::System::FIFO::_batteryStatus [protected]

Records the last battery status retrieved.

Definition at line 981 of file CeylanFIFO.h.

Referenced by getBatteryStatus(), handleReceivedSystemSpecificCommand(), and sendBatteryStatusRequest().

volatile System::DSType Ceylan::System::FIFO::_dsType [protected]

Records the DS type.

Definition at line 989 of file CeylanFIFO.h.

Referenced by getDSType(), handleReceivedSystemSpecificCommand(), and sendDSTypeRequest().

FIFO * FIFO::_FIFO = 0 [static]

The unique FIFO instance.

Definition at line 583 of file CeylanFIFO.h.

Referenced by FIFO(), GetActivatedFIFO(), GetExistingFIFO(), GetFIFO(), ManageReceivedCommand(), RemoveFIFO(), and ~FIFO().

volatile FIFOCommandCount Ceylan::System::FIFO::_localCommandCount [protected]

Records the overall number of sent commands to the FIFO.

The number of a command may be stored in its FIFO element for increased reliability, in safe mode.

Note:: 8-bit, hence wraps around after 255.
Automatically incremented when using the prepareFIFOCommand method, hence not to be especially managed by user code.

Definition at line 919 of file CeylanFIFO.h.

Referenced by activate(), prepareFIFOCommand(), and toString().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:: Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

volatile FIFOCommandCount Ceylan::System::FIFO::_processedCount [protected]

Records the number of commands processed by the ARM9.

Note:: Only the 4 lower bits are used, for a count in [0,15].
Automatically incremented by the handleReceivedCommand method, hence not to be especially managed by user code.

Definition at line 949 of file CeylanFIFO.h.

Referenced by activate(), getProcessedCount(), and incrementProcessedCount().

volatile FIFOCommandCount Ceylan::System::FIFO::_remoteCommandCount [protected]

Records the overall number of received commands to the FIFO.

The number of a command may be stored in its FIFO element for increased reliability, in safe mode.

Note:: 8-bit, hence wraps around after 255.
Automatically incremented by the handleReceivedCommand method, hence not to be especially managed by user code.

Definition at line 935 of file CeylanFIFO.h.

Referenced by activate(), handleReceivedCommand(), and toString().

volatile FIFOCommandCount Ceylan::System::FIFO::_sentCount [protected]

Records the number of commands sent by the ARM9 to the ARM7.

Note:: Only the 4 lower bits are used, for a count in [0,15].
Automatically incremented by the notifyCommandToARM7 method, hence not to be especially managed by user code.

Definition at line 963 of file CeylanFIFO.h.

Referenced by activate(), getSentCount(), and notifyCommandToARM7().

The documentation for this class was generated from the following files:


Classes
class	FIFOEmpty
	Raised whenever trying to read from an empty FIFO. More...
class	FIFOException
	Mother class for all FIFO-related exceptions. More...
class	FIFOFull
	Raised whenever trying to write to a full FIFO. More...
Public Types
enum	TextOutputFormat { rawText, html }
	Defines what text output formats for TextDisplayable instances are available. More...
Public Member Functions
	FIFO ()
	Constructs a new bidirectional logical FIFO, notably from two unidirectional hardware FIFO.
virtual	~FIFO () throw ()
	Virtual destructor.
virtual bool	isActive () const
	Returns whereas this FIFO is currently active.
virtual void	activate ()
	Activates the FIFO, and notifies the ARM7 of the variables it should use to store its status and error code.
virtual void	deactivate ()
	Deactivates the FIFO.
virtual ARM7StatusWord	getLastARM7StatusWord ()
	Returns the latest status word set by the ARM7.
virtual std::string	interpretLastARM7StatusWord ()
	Returns an interpretation of the latest status word set by the ARM7.
virtual ARM7ErrorCode	getLastARM7ErrorCode ()
	Returns the latest error code set by the ARM7.
virtual std::string	interpretLastARM7ErrorCode ()
	Returns an interpretation of the latest error code set by the ARM7.
virtual void	sendBatteryStatusRequest ()
	Sends to the ARM7 a request to update the battery status.
virtual BatteryStatus	getBatteryStatus ()
	Returns the battery status.
virtual void	sendDSTypeRequest ()
	Sends to the ARM7 a request to update the DS type.
virtual DSType	getDSType ()
	Returns the DS actual type (DS Fat,Lite, etc.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static FIFOCommandID	GetFIFOCommandIDFrom (const FIFOElement &element)
	Returns the command identifier read from specified FIFO element.
static FIFOCommandCount	GetFIFOCommandCountFrom (const FIFOElement &element)
	Returns the command count read from specified FIFO element.
static FIFOCommandCount	GetARM7ProcessedCount ()
	Returns the number of commands processed by the ARM7, based on the IPC sync register.
static FIFOCommandCount	GetARM9ProcessedCount ()
	Returns the number of commands processed by the ARM9, based on the IPC sync register.
static void	VBlankHandlerForFIFO ()
	Callback to catch the reception of a FIFO element by polling during the Vblank interrupt.
static FIFO &	GetActivatedFIFO ()
	Returns the supposedly already-created and already-activated singleton FIFO.
static FIFO &	GetExistingFIFO ()
	Returns the supposedly already-created singleton FIFO.
static FIFO &	GetFIFO ()
	Returns the singleton FIFO, creates it if needed.
static bool	RemoveFIFO ()
	Removes the singleton FIFO, if any.
static const std::string	ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
	Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat	GetOutputFormat ()
	Returns the current overall text format to be used by TextDisplayable instances.
static void	SetOutputFormat (TextOutputFormat newOutputFormat)
	Sets the current overall text format to be used by TextDisplayable instances.
Static Public Attributes
static FIFO *	_FIFO = 0
	The unique FIFO instance.
Protected Member Functions
virtual void	handleReceivedCommand ()
	Method responsible for the actual decoding of an incoming command.
virtual void	handleReceivedSystemSpecificCommand (FIFOCommandID commandID, FIFOElement firstElement)
	Method responsible for the actual decoding and management of an incoming system-specific (Ceylan) command.
virtual void	handleReceivedIntegratingLibrarySpecificCommand (FIFOCommandID commandID, FIFOElement firstElement)
	Method responsible for the actual decoding and management of an incoming command specific to an integrating library (ex: OSDL).
virtual void	handleReceivedApplicationCommand (FIFOCommandID commandID, FIFOElement firstElement)
	Method responsible for the actual decoding and management of an incoming application-specific command.
virtual void	handleUnexpectedApplicationCommand (FIFOCommandID commandID)
	Basic helper method called whenever an unexpected application command is received.
virtual FIFOElement	prepareFIFOCommand (FIFOCommandID id)
	Prepare the first FIFO element for specified command.
virtual void	notifyCommandToARM7 ()
	Notifies the ARM7 that a new command has been placed in the FIFO.
virtual void	sendSynchronizeInterruptToARM7 ()
	Sends a synchronize IRQ to the ARM7, for example to make it check its receive FIFO.
bool	dataAvailableForReading () const
	Tells whether there is data available for reading in the ARM9 receiving queue.
bool	spaceAvailableForWriting () const
	Tells whether there is space available for writing in the ARM9 sending queue.
FIFOElement	read ()
	Helper method that returns the first FIFO element available in the FIFO.
FIFOElement	readBlocking ()
	Helper method that returns the first FIFO element available in the FIFO.
void	write (FIFOElement toSend)
	Helper methods that write the specified FIFO element in the send queue.
void	writeBlocking (FIFOElement toSend)
	Helper methods that write the specified FIFO element in the send queue.
FIFOCommandCount	getProcessedCount () const
	Returns the current count of processed commands, in [0,15].
FIFOCommandCount	getSentCount () const
	Returns the current count of sent commands, in [0,15].
virtual void	incrementProcessedCount ()
	Increments the current count of processed commands, in [0,15], and updates accordingly the IPC sync register.
Static Protected Member Functions
static void	SyncHandlerForFIFO ()
	Callback called whenever the ARM7 triggers an IPC Synchronize interrupt on the ARM9.
static void	ManageReceivedCommand ()
	Manages a command sent through the FIFO.
static std::string	DescribeCommand (FIFOElement element)
	Returns a textual description of the specified command.
Protected Attributes
ARM7StatusWord volatile *volatile	_arm7StatusWordPointer
	ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its status.
ARM7ErrorCode volatile *volatile	_arm7ErrorCodePointer
	ARM9-allocated variable whose address will be sent to the ARM7 when the activate method will be called so that the ARM7 can report its last error.
volatile FIFOCommandCount	_localCommandCount
	Records the overall number of sent commands to the FIFO.
volatile FIFOCommandCount	_remoteCommandCount
	Records the overall number of received commands to the FIFO.
volatile FIFOCommandCount	_processedCount
	Records the number of commands processed by the ARM9.
volatile FIFOCommandCount	_sentCount
	Records the number of commands sent by the ARM9 to the ARM7.
volatile bool	_activated
	Tells whether this FIFO is activated.
volatile System::BatteryStatus	_batteryStatus
	Records the last battery status retrieved.
volatile System::DSType	_dsType
	Records the DS type.
Static Protected Attributes
static TextOutputFormat	_OutputFormat = rawText
	The text format to be used currently by TextDisplayable instances.
Private Member Functions
	FIFO (const FIFO &source)
	Copy constructor made private to ensure that it will be never called.
FIFO &	operator= (const FIFO &source)
	Assignment operator made private to ensure that it will be never called.