I2S Implementation +Guide

Procedure

Implement each function of class <api-item>I2S</api-item> +with a return value of

KErrArgument,
KErrNone,
KErrNotSupported

and other return values as specified for particular functions.

Implement +the following functions which are generic to I2S and do not depend on access +mode.

Implement each function of class I2S with a return +value of KErrArgument.
The first argument of every +function is aInterfaceId and represents the ID of an I2S +interface. If the passed-in ID is invalid, the function should return KErrArgument without +further activity.
Implement ConfigureInterface() with return value KErrNone for +each possible combination of interface role and interface type.
The +argument aConfig is a pointer to one or more instances of TI2sConfigBufV01. + TI2sConfigBufV01 is a class of two members, TI2sInterfaceRole and + TI2sInterfaceType.
The Symbian platform I2S interface +allows for any combination of the roles Master and Slave with the types Transmitter, +Receiver and Bidirectional. The type Controller is also supported. You must +implement all the configurations supported by the platform.
Implement ConfigureInterface() with +return value KErrNotSupported for configurations not supported +on the platform.
Implement GetInterfaceConfiguration().
Determine the current configuration of the interface and set the argument aConfig to +that value.
Implement SetSamplingRate() with return value KErrNone for +each value of the enumeration TI2sSamplingRate.
The +Symbian platform I2S interface supports sampling rates in the range 7.35KHz +to 96KHz as specified in TI2sSamplingRate. If possible, +implement sampling for each of them. Where one of these sampling rates is +not supported by the hardware, implement SetSamplingRate() with +return value KErrNotSupported.
Implement GetSamplingRate(). </para> <list +ordered="false"><ls.item><para ditatype="tutorialinfo"> Determine the +sampling rate and set the argument aSamplingRate to that +value.
Implement SetFrameLengthAndFormat() for each value +of the enumeration TI2sFrameLength and.
Symbian platform +I2S interface supports the values specified in TI2sFrameLength for +lengths of frames in bits. The frame phases are not necessarily of equal length: +the API specifies that the implementation shall calculate the length of the +right frame phase by subtracting the value of aLeftFramePhaseLength from +the value of aFrameLength. If possible, implement frames +and phases to have all the possible lengths supported by the interface. Where +a given length is not supported by the hardware, implement SetFrameLengthAndFormat() with +return value KErrNotSupported.
Implement GetFrameFormat().
Determine the lengths of the left and right frame phases in bits and +set the arguments aLeftFramePhaseLength and aRightFramePhaseLength to +those values.
Implement SetSampleLength() for each value of the +enumerations TI2sFramePhase and TI2sSampleLength.
The +length of the sample transmitted in a phase may be less than the length of +the phase for reasons such as compression. You must therefore implement sample +length as an independent quantity: this will involve padding the end of the +frame phase with appropriate values, usually 0. Where a given combination +of phase and sample length is not supported by the hardware, implement SetSampleLength with +return value KErrNotSupported.
Implement GetSampleLength().
For each value +of TI2sFramePhase determine the sample length and set aSampleLength to +that value.
Implement SetDelayCycles() for each value of the +enumeration TI2sFramePhase.
Implement SetDelayCycles() for each value of the +enumeration TI2sFramePhase.

The implementation +should delay the onset of the frame phase by the passed-in number of bit clock +cycles. The delay should apply to each frame until a new delay is specifed. +It may be necessary to reduce the frame length and truncate the sample.
Implement GetDelayCycles() for each value of the +enumeration TI2sFramePhase.

Determine the number +of delay cycles for the frame phase and set the argument aDelayCycles to +that value.
Implement Start() for each value of the enumeration TI2sDirection. +

Implement the interface to start data transmission and data reception +in accordance with the argument aDirection, a bitmask of +values of TI2sDirection. If the interface is a Controller, TI2sDirection should +be ignored. If the device is also a Master it should start generation of data +synchronisation signals.
Implement Stop() for each value of the enumeration TI2sDirection. +

Implement the interface to stop data transmission and data reception +in accordance with the argument aDirection, a bitmask of +values of TI2sDirection.
Implement IsStarted() for each value of the enumeration TI2sDirection. +

Determine whether a transmission or reception is under way. If so, +set the argument aStarted to ETrue: otherwise set it to EFalse. +
Implement each of the following functions with a return value of KErrInUse. +

For each function in the list, detemine whether the interface is +quiescent or a transfer is under way. If a transfer is under way, the functions +should return KErrInUse without further activity.
- ConfigureInterface()
- SetSamplingRate()
- SetFrameLengthAndFormat()
- SetSampleLength()
- SetCycleDelays()
- Start()

Implementing PIO

If the platform supports PIO access mode, +implement the following functions with a return value of KErrNone: +otherwise implement them with a return value of KErrNotSupported. +

Implement ReadReceiveRegister() for each value +of the enumeration TI2sFramePhase.

Implement +this function to read the contents of the register which receives data for +each frame phase and place the data in the argument aData. +

Implementation of this function depends on design decisions. If +a single register is used both to transmit and receive with half-duplex operation, +read data from that register. If a single register is used to hold the contents +of each frame phase, read data from that register, ignoring the argument aFramePhase. +In such cases it will be the responsibility of the user of the API to maintain +the integrity of the data, for instance by calling ReadRegisterModeStatus() to +determine which frame phase the data belongs to.
Implement WriteTransmitRegister() for each value +of the enumeration TI2sFramePhase.

Implement +this function to write the data in the argument aData to +the register which transmits data for each frame phase.

Implementation +of this function depends on design decisions. If a single register is used +both to transmit and receive with half-duplex operation, write data to that +register. If a single register is used to hold the contents of each frame +phase, write data to that register, ignoring the argument aFramePhase. +In such cases it will be the responsibility of the user of the API to maintain +the integrity of the data, for instance by calling ReadRegisterModeStatus() to +determine which frame phase the data belongs to.
Implement ReadTransmitRegister() for each value +of the enumeration TI2sFramePhase.

Implement +this function to read the contents of the register which transmits data for +each frame phase and place the data in the argument aData. +

Implementation of this function depends on design decisions. If +a single register is used both to transmit and receive with half-duplex operation, +read data from that register. If a single register is used to hold the contents +of each frame phase, read data from that register, ignoring the argument aFramePhase. +In such cases it will be the responsibility of the user of the API to maintain +the integrity of the data, for instance by calling ReadRegisterModeStatus() to +determine which frame phase the data belongs to.
Implement ReadRegisterModeStatus() for each value +of the enumeration TI2sFlags and each value of the enumeration TI2sFramePhase. +

Determine whether these conditions are true or false:
- Receive register for the specified frame phase is full.
- Transmit register for the specified frame phase is empty.
- Receive register for the specified frame phase has overrun.
- Transmit register for the specified frame phase has underrun.
- A framing error for the specified frame phase has occurred.
Convert the values into a bitmask (1 means the condition is true) +and set the argument aFlags to that bitmask.
Implement EnableRegisterInterrupts() for each value +of the enumerations TI2sFramePhase and TI2sFlags. +

Ensure that there is an interrupt for each interrupt flag in TI2sFlags. +Implement the interface to enable the interrupts in response to a bitmask +containing the interrupt flags: enable when the flag is set to 1. If there +are separate registers for each frame phase, implement the interrupts separately +for each frame phase which may be passed as aFramePhase: +otherwise ignore the argument aFramePhase.
Implement DisableRegisterInterrupts() for each +value of the enumerations TI2sFramePhase and TI2sFlags. +

Ensure that there is an interrupt for each interrupt flag in TI2sFlags. +Implement the interface to disable the interrupts in response to a bitmask +containing the interrupt flags: disable when the flag is set to 1. If there +are separate registers for each frame phase, implement the interrupts separately +for each frame phase which may be passed as aFramePhase: +otherwise ignore the argument aFramePhase.
Implement IsRegisterInterruptEnabled() for each +value of the enumerations TI2sFramePhase and TI2sFlags. +

Determine which interrupts are enabled for each frame phase and +convert the values to a bitmask. Set the argument aEnabled to +that bitmask.

Implementing FIFO

If the platform supports FIFO access mode, +implement the following functions with a return value of KErrNone: +otherwise implement them with a return value of KErrNotSupported. +

Implement EnableFIFO() for each value of the enumerations TI2sFramePhase and TI2sDirection.

Implement the ability to enable FIFO receive and transmit for +each direction, as passed in through the bitmask aFifoMask, +and frame phase. If the same FIFO is used for receive and transmit, ignore +the argument aFifoMask. If the same FIFO is used for both +frame phases, ignore the argument aFramePhase.
Implement DisableFIFO() for each value of the enumerations TI2sFramePhase and TI2sDirection.

Implement the ability to disable FIFO receive and transmit for +each direction, as passed in through the bitmask aFifoMask, +and frame phase. If the same FIFO is used for receive and transmit, ignore +the argument aFifoMask. If the same FIFO is used for both +frame phases, ignore the argument aFramePhase.
Implement IsFIFOEnabled() for each value of the +enumeration TI2sFramePhase.

Determine the enablement +status of the FIFOs for each value of the enumeration TI2sFramePhase. +Convert the values into a bitmask and set the argument aEnabled to +it. If the same FIFO is used for both frame phases, ignore the argument aFramePhase. +
Implement SetFIFOThreshold() for each value of +the enumerations TI2sFramePhase and TI2sDirection. +

Implement the interface to set the FIFO threshold to the value passed +through the argument aThreshold. If the same FIFO is used +for receive and transmit, ignore the argument aFifoMask. +If the same FIFO is used for both frame phases, ignore the argument aFramePhase. +
Implement ReadFIFOModeStatus() for each value of +the enumeration TI2sFramePhase.

Determine the +status of the access modes for each frame phase. Convert the values into a +bitmask and set the argument aFlags to it. If the same FIFO +is used for both frame phases, ignore the argument aFramePhase. +
Implement EnableFIFOInterrupts() for each value +of the enumeration TI2sFramePhase.

Ensure +that there is an interrupt for each interrupt flag in TI2sFlags. +Implement the interface to enable the interrupts in response to a bitmask +containing the interrupt flags: enable when the flag is set to 1. If there +are separate registers for each frame phase, implement the interrupts separately +for each frame phase which may be passed as aFramePhase: +otherwise ignore the argument aFramePhase.
Implement DisableFIFOInterrupts() for each value +of the enumeration TI2sFramePhase.

Ensure that +there is an interrupt for each interrupt flag in TI2sFlags. +Implement the interface to disable the interrupts in response to a bitmask +containing the interrupt flags: disable when the flag is set to 1. If there +are separate registers for each frame phase, implement the interrupts separately +for each frame phase which may be passed as aFramePhase: +otherwise ignore the argument aFramePhase.
Implement IsFIFOInterruptEnabled() for each value +of the enumeration TI2sFramePhase.

Determine +which interrupts are enabled for each frame phase and convert the values to +a bitmask. Set the argument aEnabled to that bitmask.
Implement ReadFIFOLevel() for each value of the +enumerations TI2sFramePhase and TI2sDirection. +

Implement the interface to return the FIFO level for each pair of +values taken from TI2sFramePhase and TI2sDirection. +For each pair of values passed as the arguments aFramePhase and aDirection write +the FIFO level to the argument aLevel.

Implementing DMA

If +the platform supports DMA access mode, implement the following functions with +a return value of KErrNone: otherwise implement them with +a return value of KErrNotSupported.

Implement EnableDMA() for each value of the enumerations TI2sFramePhase and TI2sDirection.

Implement the ability to enable DMA receive and transmit for +each direction, as passed in through the bitmask aFifoMask, +and frame phase. If the same FIFO is used for receive and transmit, ignore +the argument aFifoMask. If the same FIFO is used for both +frame phases, ignore the argument aFramePhase.
Implement DisableDMA() for each value of the enumerations TI2sFramePhase and TI2sDirection.

Implement the ability to disable DMA receive and transmit for +each direction, as passed in through the bitmask aFifoMask, +and frame phase. If the same FIFO is used for receive and transmit, ignore +the argument aFifoMask. If the same FIFO is used for both +frame phases, ignore the argument aFramePhase.
Implement IsDMAEnabled() for each value of the +enumeration TI2sDirection.

Determine the enablement +status of each FIFO and convert the values to a bitmask. Set the argument aEnabled to +that bitmask.