[ssi] Synchronous Serial Interface

Functions
void	SSIConfigSetExpClk (uint32_t ui32Base, uint32_t ui32SSIClk, uint32_t ui32Protocol, uint32_t ui32Mode, uint32_t ui32BitRate, uint32_t ui32DataWidth)
	Configures the synchronous serial port. More...
static void	SSIEnable (uint32_t ui32Base)
	Enables the synchronous serial port. More...
static void	SSIDisable (uint32_t ui32Base)
	Disables the synchronous serial port. More...
void	SSIDataPut (uint32_t ui32Base, uint32_t ui32Data)
	Puts a data element into the SSI transmit FIFO. More...
int32_t	SSIDataPutNonBlocking (uint32_t ui32Base, uint32_t ui32Data)
	Puts a data element into the SSI transmit FIFO. More...
void	SSIDataGet (uint32_t ui32Base, uint32_t *pui32Data)
	Gets a data element from the SSI receive FIFO. More...
int32_t	SSIDataGetNonBlocking (uint32_t ui32Base, uint32_t *pui32Data)
	Gets a data element from the SSI receive FIFO. More...
static bool	SSIBusy (uint32_t ui32Base)
	Determines whether the SSI transmitter is busy or not. More...
static uint32_t	SSIStatus (uint32_t ui32Base)
	Get the status of the SSI data buffers. More...
void	SSIIntRegister (uint32_t ui32Base, void(*pfnHandler)(void))
	Registers an interrupt handler for the synchronous serial port. More...
void	SSIIntUnregister (uint32_t ui32Base)
	Unregisters an interrupt handler for the synchronous serial port. More...
static void	SSIIntEnable (uint32_t ui32Base, uint32_t ui32IntFlags)
	Enables individual SSI interrupt sources. More...
static void	SSIIntDisable (uint32_t ui32Base, uint32_t ui32IntFlags)
	Disables individual SSI interrupt sources. More...
static void	SSIIntClear (uint32_t ui32Base, uint32_t ui32IntFlags)
	Clears SSI interrupt sources. More...
static uint32_t	SSIIntStatus (uint32_t ui32Base, bool bMasked)
	Gets the current interrupt status. More...
static void	SSIDMAEnable (uint32_t ui32Base, uint32_t ui32DMAFlags)
	Enable SSI DMA operation. More...
static void	SSIDMADisable (uint32_t ui32Base, uint32_t ui32DMAFlags)
	Disable SSI DMA operation. More...

Detailed Description

Function Documentation

static bool SSIBusy ( uint32_t  ui32Base )

inlinestatic

Determines whether the SSI transmitter is busy or not.

Allows the caller to determine whether all transmitted bytes have cleared the transmitter hardware. If false is returned, then the transmit FIFO is empty and all bits of the last transmitted word have left the hardware shift register.

Parameters

ui32Base

is the base address of the SSI port.

Returns

Returns status of the SSI transmit buffer.

• true : SSI is transmitting.
• false : SSI transmissions are complete.

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Determine if the SSI is busy.
    return((HWREG(ui32Base + SSI_O_SR) & SSI_SR_BSY) ? true : false);
}

void SSIConfigSetExpClk	(	uint32_t	ui32Base,
		uint32_t	ui32SSIClk,
		uint32_t	ui32Protocol,
		uint32_t	ui32Mode,
		uint32_t	ui32BitRate,
		uint32_t	ui32DataWidth
	)

Configures the synchronous serial port.

This function configures the synchronous serial port. It sets the SSI protocol, mode of operation, bit rate, and data width.

The ui32Protocol parameter defines the data frame format. The Motorola frame formats imply the following polarity and phase configurations:

Polarity Phase       Mode
  0       0   SSI_FRF_MOTO_MODE_0
  0       1   SSI_FRF_MOTO_MODE_1
  1       0   SSI_FRF_MOTO_MODE_2
  1       1   SSI_FRF_MOTO_MODE_3

The ui32Mode parameter defines the operating mode of the SSI module. The SSI module can operate as a master or slave; if a slave, the SSI can be configured to disable output on its serial output line.

The ui32BitRate parameter defines the bit rate for the SSI. This bit rate must satisfy the following clock ratio criteria:

• Master mode : FSSI >= 2 * bit rate
• Slave mode : FSSI >= 12 * bit rate

where FSSI is the frequency of the clock supplied to the SSI module.

The ui32DataWidth parameter defines the width of the data transfers, and can be a value between 4 and 16, inclusive.

Note

The peripheral clock is not necessarily the same as the processor clock. The frequency of the peripheral clock is set by the system control.

Parameters

ui32Base	specifies the SSI module base address.
ui32SSIClk	is the rate of the clock supplied to the SSI module.
ui32Protocol	specifies the data transfer protocol. The parameter can be one of the following values: SSI_FRF_MOTO_MODE_0 SSI_FRF_MOTO_MODE_1 SSI_FRF_MOTO_MODE_2 SSI_FRF_MOTO_MODE_3 SSI_FRF_TI SSI_FRF_NMW.
ui32Mode	specifies the mode of operation. The parameter can be one of the following values: SSI_MODE_MASTER SSI_MODE_SLAVE SSI_MODE_SLAVE_OD
ui32BitRate	specifies the clock rate.
ui32DataWidth	specifies number of bits transferred per frame. Must be a value between 4 and 16, both included.

Returns

None

{
    uint32_t ui32MaxBitRate;
    uint32_t ui32RegVal;
    uint32_t ui32PreDiv;
    uint32_t ui32SCR;
    uint32_t ui32SPH_SPO;

    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));
    ASSERT((ui32Protocol == SSI_FRF_MOTO_MODE_0) ||
           (ui32Protocol == SSI_FRF_MOTO_MODE_1) ||
           (ui32Protocol == SSI_FRF_MOTO_MODE_2) ||
           (ui32Protocol == SSI_FRF_MOTO_MODE_3) ||
           (ui32Protocol == SSI_FRF_TI) ||
           (ui32Protocol == SSI_FRF_NMW));
    ASSERT((ui32Mode == SSI_MODE_MASTER) ||
           (ui32Mode == SSI_MODE_SLAVE) ||
           (ui32Mode == SSI_MODE_SLAVE_OD));
    ASSERT(((ui32Mode == SSI_MODE_MASTER) && (ui32BitRate <= (ui32SSIClk / 2))) ||
           ((ui32Mode != SSI_MODE_MASTER) && (ui32BitRate <= (ui32SSIClk / 12))));
    ASSERT((ui32SSIClk / ui32BitRate) <= (254 * 256));
    ASSERT((ui32DataWidth >= 4) && (ui32DataWidth <= 16));

    // Set the mode.
    ui32RegVal = (ui32Mode == SSI_MODE_SLAVE_OD) ? SSI_CR1_SOD : 0;
    ui32RegVal |= (ui32Mode == SSI_MODE_MASTER) ? 0 : SSI_CR1_MS;
    HWREG(ui32Base + SSI_O_CR1) = ui32RegVal;

    // Set the clock predivider.
    ui32MaxBitRate = ui32SSIClk / ui32BitRate;
    ui32PreDiv = 0;
    do
    {
        ui32PreDiv += 2;
        ui32SCR = (ui32MaxBitRate / ui32PreDiv) - 1;
    }
    while(ui32SCR > 255);
    HWREG(ui32Base + SSI_O_CPSR) = ui32PreDiv;

    // Set protocol and clock rate.
    ui32SPH_SPO = (ui32Protocol & 3) << 6;
    ui32Protocol &= SSI_CR0_FRF_M;
    ui32RegVal = (ui32SCR << 8) | ui32SPH_SPO | ui32Protocol | (ui32DataWidth - 1);
    HWREG(ui32Base + SSI_O_CR0) = ui32RegVal;
}

void SSIDataGet	(	uint32_t	ui32Base,
		uint32_t *	pui32Data
	)

Gets a data element from the SSI receive FIFO.

This function gets received data from the receive FIFO of the specified SSI module and places that data into the location specified by the pui32Data parameter.

Note

Only the lower N bits of the value written to pui32Data contain valid data, where N is the data width as configured by SSIConfigSetExpClk(). For example, if the interface is configured for 8-bit data width, only the lower 8 bits of the value written to pui32Data contain valid data.

Parameters

ui32Base	specifies the SSI module base address.
pui32Data	is a pointer to a storage location for data that was received over the SSI interface.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Wait until there is data to be read.
    while(!(HWREG(ui32Base + SSI_O_SR) & SSI_SR_RNE))
    {
    }

    // Read data from SSI.
    *pui32Data = HWREG(ui32Base + SSI_O_DR);
}

int32_t SSIDataGetNonBlocking	(	uint32_t	ui32Base,
		uint32_t *	pui32Data
	)

Gets a data element from the SSI receive FIFO.

This function gets received data from the receive FIFO of the specified SSI module and places that data into the location specified by the ui32Data parameter. If there is no data in the FIFO, then this function returns a zero.

Note

Only the lower N bits of the value written to pui32Data contain valid data, where N is the data width as configured by SSIConfigSetExpClk(). For example, if the interface is configured for 8-bit data width, only the lower 8 bits of the value written to pui32Data contain valid data.

Parameters

ui32Base	specifies the SSI module base address.
pui32Data	is a pointer to a storage location for data that was received over the SSI interface.

Returns

Returns the number of elements read from the SSI receive FIFO.

Gets a data element from the SSI receive FIFO

Parameters

ui32Base	specifies the SSI module base address.
pui32Data	is a pointer to a storage location for data that was received over the SSI interface.

This function gets received data from the receive FIFO of the specified SSI module and places that data into the location specified by the ui32Data parameter. If there is no data in the FIFO, then this function returns a zero.

Note

Only the lower N bits of the value written to pui32Data contain valid data, where N is the data width as configured by

See also

SSIConfigSetExpClk(). For example, if the interface is configured for 8-bit data width, only the lower 8 bits of the value written to pui32Data contain valid data.

Returns

Returns the number of elements read from the SSI receive FIFO.

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Check for data to read.
    if(HWREG(ui32Base + SSI_O_SR) & SSI_SR_RNE)
    {
        *pui32Data = HWREG(ui32Base + SSI_O_DR);
        return(1);
    }
    else
    {
        return(0);
    }
}

void SSIDataPut	(	uint32_t	ui32Base,
		uint32_t	ui32Data
	)

Puts a data element into the SSI transmit FIFO.

This function places the supplied data into the transmit FIFO of the specified SSI module.

Note

The upper 32 - N bits of the ui32Data are discarded by the hardware, where N is the data width as configured by SSIConfigSetExpClk(). For example, if the interface is configured for 8-bit data width, the upper 24 bits of ui32Data are discarded.

Parameters

ui32Base	specifies the SSI module base address.
ui32Data	is the data to be transmitted over the SSI interface.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));
    ASSERT((ui32Data & (0xfffffffe << (HWREG(ui32Base + SSI_O_CR0) &
                                       SSI_CR0_DSS_M))) == 0);

    // Wait until there is space.
    while(!(HWREG(ui32Base + SSI_O_SR) & SSI_SR_TNF))
    {
    }

    // Write the data to the SSI.
    HWREG(ui32Base + SSI_O_DR) = ui32Data;
}

int32_t SSIDataPutNonBlocking	(	uint32_t	ui32Base,
		uint32_t	ui32Data
	)

Puts a data element into the SSI transmit FIFO.

This function places the supplied data into the transmit FIFO of the specified SSI module. If there is no space in the FIFO, then this function returns a zero.

Note

The upper 32 - N bits of the ui32Data are discarded by the hardware, where N is the data width as configured by SSIConfigSetExpClk(). For example, if the interface is configured for 8-bit data width, the upper 24 bits of ui32Data are discarded.

Parameters

ui32Base	specifies the SSI module base address.
ui32Data	is the data to be transmitted over the SSI interface.

Returns

Returns the number of elements written to the SSI transmit FIFO.

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));
    ASSERT((ui32Data & (0xfffffffe << (HWREG(ui32Base + SSI_O_CR0) &
                                       SSI_CR0_DSS_M))) == 0);

    // Check for space to write.
    if(HWREG(ui32Base + SSI_O_SR) & SSI_SR_TNF)
    {
        HWREG(ui32Base + SSI_O_DR) = ui32Data;
        return(1);
    }
    else
    {
        return(0);
    }
}

static void SSIDisable ( uint32_t  ui32Base )

inlinestatic

Disables the synchronous serial port.

This function disables operation of the synchronous serial port.

Parameters

ui32Base

specifies the SSI module base address.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Read-modify-write the enable bit.
    HWREG(ui32Base + SSI_O_CR1) &= ~(SSI_CR1_SSE);
}

static void SSIDMADisable ( uint32_t  ui32Base, uint32_t  ui32DMAFlags  )

inlinestatic

Disable SSI DMA operation.

This function is used to disable SSI DMA features that were enabled by SSIDMAEnable(). The specified SSI DMA features are disabled.

Parameters

ui32Base	is the base address of the SSI port.
ui32DMAFlags	is a bit mask of the DMA features to disable. The parameter is the bitwise OR of any of the following values: SSI_DMA_RX : Disable DMA for receive. SSI_DMA_TX : Disable DMA for transmit.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Clear the requested bits in the SSI DMA control register.
    HWREG(ui32Base + SSI_O_DMACR) &= ~ui32DMAFlags;
}

static void SSIDMAEnable ( uint32_t  ui32Base, uint32_t  ui32DMAFlags  )

inlinestatic

Enable SSI DMA operation.

The specified SSI DMA features are enabled. The SSI can be configured to use DMA for transmit and/or receive data transfers.

Note

The uDMA controller must also be set up before DMA can be used with the SSI.

Parameters

ui32Base	is the base address of the SSI port.
ui32DMAFlags	is a bit mask of the DMA features to enable. The parameter is the bitwise OR of any of the following values: SSI_DMA_RX : Enable DMA for receive. SSI_DMA_TX : Enable DMA for transmit.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Set the requested bits in the SSI DMA control register.
    HWREG(ui32Base + SSI_O_DMACR) |= ui32DMAFlags;
}

static void SSIEnable ( uint32_t  ui32Base )

inlinestatic

Enables the synchronous serial port.

This function enables operation of the synchronous serial port. The synchronous serial port must be configured before it is enabled.

Parameters

ui32Base

specifies the SSI module base address.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Read-modify-write the enable bit.
    HWREG(ui32Base + SSI_O_CR1) |= SSI_CR1_SSE;
}

static void SSIIntClear ( uint32_t  ui32Base, uint32_t  ui32IntFlags  )

inlinestatic

Clears SSI interrupt sources.

The specified SSI interrupt sources are cleared so that they no longer assert. This function must be called in the interrupt handler to keep the interrupts from being recognized again immediately upon exit.

Note

Due to write buffers and synchronizers in the system it may take several clock cycles from a register write clearing an event in a module and until the event is actually cleared in the NVIC of the system CPU. It is recommended to clear the event source early in the interrupt service routine (ISR) to allow the event clear to propagate to the NVIC before returning from the ISR. At the same time, an early event clear allows new events of the same type to be pended instead of ignored if the event is cleared later in the ISR. It is the responsibility of the programmer to make sure that enough time has passed before returning from the ISR to avoid false re-triggering of the cleared event. A simple, although not necessarily optimal, way of clearing an event before returning from the ISR is:

1. Write to clear event (interrupt source). (buffered write)
2. Dummy read from the event source module. (making sure the write has propagated)
3. Wait two system CPU clock cycles (user code or two NOPs). (allowing cleared event to propagate through any synchronizers)

Parameters

ui32Base	specifies the SSI module base address.
ui32IntFlags	is a bit mask of the interrupt sources to be cleared. The parameter can consist of either or both of: SSI_RXTO : Timeout interrupt. SSI_RXOR : Overrun interrupt.

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Clear the requested interrupt sources.
    HWREG(ui32Base + SSI_O_ICR) = ui32IntFlags;
}

static void SSIIntDisable ( uint32_t  ui32Base, uint32_t  ui32IntFlags  )

inlinestatic

Disables individual SSI interrupt sources.

Disables the indicated SSI interrupt sources.

Parameters

ui32Base	specifies the SSI module base address.
ui32IntFlags	is a bit mask of the interrupt sources to be disabled. SSI_TXFF SSI_RXFF SSI_RXTO SSI_RXOR

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Disable the specified interrupts.
    HWREG(ui32Base + SSI_O_IMSC) &= ~(ui32IntFlags);
}

static void SSIIntEnable ( uint32_t  ui32Base, uint32_t  ui32IntFlags  )

inlinestatic

Enables individual SSI interrupt sources.

Enables the indicated SSI interrupt sources. Only the sources that are enabled can be reflected to the processor interrupt; disabled sources have no effect on the processor.

Parameters

ui32Base	specifies the SSI module base address.
ui32IntFlags	is a bit mask of the interrupt sources to be enabled. SSI_TXFF SSI_RXFF SSI_RXTO SSI_RXOR

Returns

None

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Enable the specified interrupts.
    HWREG(ui32Base + SSI_O_IMSC) |= ui32IntFlags;
}

void SSIIntRegister	(	uint32_t	ui32Base,
		void(*)(void)	pfnHandler
	)

Registers an interrupt handler for the synchronous serial port.

This sets the handler to be called when an SSI interrupt occurs. This will enable the global interrupt in the interrupt controller; specific SSI interrupts must be enabled via SSIIntEnable(). If necessary, it is the interrupt handler's responsibility to clear the interrupt source via SSIIntClear().

Parameters

ui32Base	specifies the SSI module base address.
pfnHandler	is a pointer to the function to be called when the synchronous serial port interrupt occurs.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

Registers an interrupt handler for the synchronous serial port

Parameters

ui32Base	specifies the SSI module base address.
pfnHandler	is a pointer to the function to be called when the synchronous serial port interrupt occurs.

This sets the handler to be called when an SSI interrupt occurs. This will enable the global interrupt in the interrupt controller; specific SSI interrupts must be enabled via SSIIntEnable(). If necessary, it is the interrupt handler's responsibility to clear the interrupt source via SSIIntClear().

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None

{
    uint32_t ui32Int;

    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Determine the interrupt number based on the SSI port.
    ui32Int = (ui32Base == SSI0_BASE) ? INT_SSI0_COMB : INT_SSI1_COMB;

    // Register the interrupt handler.
    IntRegister(ui32Int, pfnHandler);

    // Enable the synchronous serial port interrupt.
    IntEnable(ui32Int);
}

Here is the call graph for this function:

static uint32_t SSIIntStatus ( uint32_t  ui32Base, bool  bMasked  )

inlinestatic

Gets the current interrupt status.

This function returns the interrupt status for the SSI module. Either the raw interrupt status or the status of interrupts that are allowed to reflect to the processor can be returned.

Parameters

ui32Base	specifies the SSI module base address.
bMasked	selects either raw or masked interrupt. false : Raw interrupt status is required. true : Masked interrupt status is required.

Returns

Returns the current interrupt status as an OR'ed combination of:

• SSI_TXFF
• SSI_RXFF
• SSI_RXTO
• SSI_RXOR

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Return either the interrupt status or the raw interrupt status as
    // requested.
    if(bMasked)
    {
        return(HWREG(ui32Base + SSI_O_MIS));
    }
    else
    {
        return(HWREG(ui32Base + SSI_O_RIS));
    }
}

void SSIIntUnregister

(

uint32_t

ui32Base

)

Unregisters an interrupt handler for the synchronous serial port.

This function will clear the handler to be called when a SSI interrupt occurs. This will also mask off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

Parameters

ui32Base

specifies the SSI module base address.

Returns

None

See also

IntRegister() for important information about registering interrupt handlers.

Unregisters an interrupt handler for the synchronous serial port

Parameters

ui32Base

specifies the SSI module base address.

This function will clear the handler to be called when a SSI interrupt occurs. This will also mask off the interrupt in the interrupt controller so that the interrupt handler no longer is called.

See also

IntRegister() for important information about registering interrupt handlers.

Returns

None

{
    uint32_t ui32Int;

    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Determine the interrupt number based on the SSI port.
    ui32Int = (ui32Base == SSI0_BASE) ? INT_SSI0_COMB : INT_SSI1_COMB;

    // Disable the interrupt.
    IntDisable(ui32Int);

    // Unregister the interrupt handler.
    IntUnregister(ui32Int);
}

Here is the call graph for this function:

static uint32_t SSIStatus ( uint32_t  ui32Base )

inlinestatic

Get the status of the SSI data buffers.

This function is used to poll the status of the internal FIFOs in the SSI module. The status of both TX and RX FIFO is returned.

Parameters

ui32Base

specifies the SSI module base address.

Returns

Returns the current status of the internal SSI data buffers. The status is a bitwise OR'ed combination of:

• SSI_RX_FULL : Receive FIFO full.
• SSI_RX_NOT_EMPTY : Receive FIFO not empty.
• SSI_TX_NOT_FULL : Transmit FIFO not full.
• SSI_TX_EMPTY : Transmit FIFO empty.

{
    // Check the arguments.
    ASSERT(SSIBaseValid(ui32Base));

    // Return the status
    return (HWREG(ui32Base + SSI_O_SR) & SSI_STATUS_MASK);
}

Macro Definition Documentation

#define SSI_DMA_RX   0x00000001

#define SSI_DMA_TX   0x00000002

#define SSI_FRF_MOTO_MODE_0   0x00000000

Referenced by SSIConfigSetExpClk().

#define SSI_FRF_MOTO_MODE_1   0x00000002

Referenced by SSIConfigSetExpClk().

#define SSI_FRF_MOTO_MODE_2   0x00000001

Referenced by SSIConfigSetExpClk().

#define SSI_FRF_MOTO_MODE_3   0x00000003

Referenced by SSIConfigSetExpClk().

#define SSI_FRF_NMW   0x00000020

Referenced by SSIConfigSetExpClk().

#define SSI_FRF_TI   0x00000010

Referenced by SSIConfigSetExpClk().

#define SSI_MODE_MASTER   0x00000000

Referenced by SSIConfigSetExpClk().

#define SSI_MODE_SLAVE   0x00000001

Referenced by SSIConfigSetExpClk().

#define SSI_MODE_SLAVE_OD   0x00000002

Referenced by SSIConfigSetExpClk().

#define SSI_RX_FULL   0x00000008

#define SSI_RX_NOT_EMPTY   0x00000004

#define SSI_RXFF   0x00000004

#define SSI_RXOR   0x00000001

#define SSI_RXTO   0x00000002

#define SSI_STATUS_MASK   0x0000000F

Referenced by SSIStatus().

#define SSI_TX_EMPTY   0x00000001

#define SSI_TX_NOT_FULL   0x00000002

#define SSI_TXFF   0x00000008