4.19. SPI

4.19.1. About This Document

Document Title

User Guide of MCAL SPI Driver

Document Version

Version 1.5

Company

Texas Instruments

Document Name

SPI User Guide

4.19.2. Document Revision History

Version

Date

Revision History

Status

Version 1.0

28 Mar 2022

Initial Version

Approved

Version 1.1

05 Aug 2022

Functional Testing

Approved

Version 1.2

05 May 2023

Functional Testing, Bug Fixes

Approved

Version 1.3

29 Jul 2023

DMA support

Approved

Version 1.4

25 Aug 2023

Document release version column removed

Approved

Version 1.5

2 Feb 2023

Configuration Parameters updated

Approved

4.19.3. Table of contents

  1. Acronyms and Definitions

  2. Functional Overview

  3. Deviations to requirements (Requirement Traceability)

  4. Integration Details

  5. API Description

  6. Configuration Description

  7. Memory Mapping

  8. Memory footprint

  9. Performance

  10. Example Usage

  11. FAQ’s

  12. Test Report

  13. References

  14. TI Disclaimer

4.19.4. Acronyms and Definitions

Acronyms and Definitions used are presented in below table.

Acronyms

Descriptions

BSW

Basic Software

DET

Default Error Tracer

SPI

Serial Peripheral Interface

MCU

Micro Controller Unit

OS

Operating System

API

Application Programming Interface

HW

Hardware

SW

Software

4.19.5. Functional Overview

4.19.5.1. Brief Overview

This document describes MCAL SPI Driver functionality, its application interfaces and configuration details as per AUTOSAR version 4.3.1 .

Supported AUTOSAR Release

4.3.1

Supported Configuration Variants

Post-build, Pre-Compile, Link-Time

Vendor ID

SPI_VENDOR_ID (44)

Module ID

SPI_MODULE_ID (83)

Supported Platform

AM263x

The SPI driver provides services for basic communication with external components. These components can be used by an application.

The main tasks of the SPI are:

  1. Handle data transmission to the components connected via SPI

  2. Take care of the settings required by external components (baud rate etc.)

4.19.5.1.1. SPI Driver Architecture

The following figure shows where the SPI is located in the AUTOSAR architecture

../_images/spi_image5.png

Figure 1: SPI in AUTOSAR architecture.

The next figure shows the interfaces to adjacent modules of the SPI. These interfaces are described in further chapters.

../_images/spi_image3.png

Figure 2: SPI Interfaces.

4.19.5.1.2. Initialization

The SPI driver is initialized by calling Spi_Init(), with parameter ConfigPtr referencing a runtime configuration set. Spi_DeInit() will deinitialize the driver.

4.19.5.1.3. States

There are 3 states in which the SPI driver can be in.

  1. SPI_UNINIT: The SPI Handler/Driver is not initialized or not usable.

  2. SPI_IDLE : The SPI Handler/Driver is not currently transmitting any Job.

  3. SPI_BUSY : The SPI Handler/Driver is performing a SPI Job (transmit).

So the user knows the ongoing action of the driver during a transmission.

4.19.5.1.4. Baudrate calculation

SPI Baud Rate Calculation is as follows:

Baud rate = fSPI / CLKD Where fSPI – SPI Functional clock frequency. fSPI can be set from MCU clocksetting configuration, where user can configure clock source(as per TRM) and clock division value for required fSPI (fSPI=clk/clkdiv+1). Refer the figure below:

../_images/spi_image7.png

Figure 3: MCU Clock setting in Ebtresos

CLKD – Prescalar clock divider (SpiExtDeviceClockDivider value as per EBtresos Configuration).SpiExtDeviceClockDivider can be set from EBtresos as in below figure:

../_images/spi_image6.png

Figure 4: SpiExtDeviceClockDivider value as per EBtresos Configuration

CLKD value should be set such a way to get the expected baudrate as per calculation below:

For example, if fSPI of MCSPI is 50 MHz:

  1. For Baudrate = 50Mbps , CLKD should be given as 0 , calculation will be as following

    Baudrate = 50/(0+1) = 50Mbps

  2. For Baudrate =25Mbps ,CLKD should be given as 1 , calculation will be as following

    Baudrate = 50/(1+1) = 25Mbps

4.19.5.2. Features Supported and Not Supported

SPI IP Features supported

Autosar Features Supported

Not Supported

  1. Serial clock with programmable frequency, polarity and phase for each channel

  2. Wide selection of SPI word lengths, ranging from 4 to 32 bits

  3. Each SPI controller operates at up to 50 MHz

  4. SPI0 and SPI4 support 2 chip selects while SPI1, SPI2, and SPI3 support 1 chip select

  5. Interruptible Sequences

  6. Controller multichannel mode

    • Transmit only/transmit and receive modes

    • Flexible input/output(I/O) port controls per channel

    • Programmable clock granularity

    • Per channel configuration for clock definition, polarity enabling and word width

  7. Enable the addition of a programmable start-bit for MCSPI transfer per channel (start-bit mode)

  1. Spi Initilaizes the all features required for Transmiision and reception.

  2. Spi Supports the Using of interna buffers for transfeer and receiving of data

  3. Spi supports asynchronous transmission and reception

  4. Spi supports synchronous transmission and reception.

  5. Spi supports setting of external Buffers.

  6. Spi Supports the Getting the status of

    • Hwunit

    • Job Result

    • Sequence result

  7. Spi Supports setting mode of the Communication

  8. Spi Supports cancel of sequence

  1. Slave Mode not supported

4.19.5.3. Assumptions

None

4.19.5.4. Limitations

  1. A job queued in a sequence cannot be queued via another sequence. This is a design limitation to reduce driver complexity.

  2. A channel in a job in a sequence cannot be part of another active job or sequence. This is a design limitation to reduce driver complexity.

  3. If a sequence is started, another high priority job belonging to another sequence cannot interrupt the job belonging to the same hardware unit. But the job can be scheduled ahead of another pending job of the started sequence if it belongs to another HW queue.

4.19.5.6. File Structure

Description of static files is provided below:

Static source and header files

Description

Spi.h

Contains the API’s of the SPI driver to be used by upper layers.

Spi.c

Contains the implementation of the API’s for SPI driver.

Spi_Irq.c and Spi_Irq.h

Contains ISR function definitions

Spi_Priv.c,Spi_Priv.h,Spi_Utils.c, Spi_Utils.h, Spi_Mcspi.c and hw_mcspi.h

Contains Internal functions definition of SPI driver.

Spi_Dbg.h

Contains Internal functions definition of SPI driver.

Description of generated files is provided below:

Plugin Files

Descriptions

Spi_Cfg.h

Contains the Precompile switches, Symbolic names of Group, channels and hardware units Configured maximum number Groups and hardware units

Spi_PBcfg.c

Contains all channels Post-Build Configured parameters

Spi_Lcfg.c

Contains all channels Link time Configured parameters

Spi_Cfg.c

Contains all channels Pre-Compile Configured parameters
../_images/spi_image4.png

Figure 5: SPI header file include structure

4.19.6. Deviations to requirements (Requirement Traceability)

4.19.6.1. Module Requirements

Please refer Software Product Specification document provided as part of CSP.

4.19.6.2. Deviation of requirements against AUTOSAR specification requirements

Will be updated in future release

4.19.7. Integration Details

4.19.7.1. Dependency on Other Software Modules

4.19.7.1.1. MCU

The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL and the internal clock domains which go to the SPI unit. The SPI module also supports an internal divider which can be changed at configuration time using the ‘clkDivider’ member of Spi_McSPIExternalDeviceConfigType structure to configure the actual SPI functional clock.

4.19.7.1.2. PORT

The module PORT enables the SPI lines at startup time. To operate the SPI properly, the PORT driver must be configured. The PORT driver sets the PINs to the required mux values for the SPI to operate.

4.19.7.1.3. OSEK / AUTOSAR OS (Optional)

An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table. The SPI module may use OSEK/AUTOSAR OS to suspend and restore global interrupts.

4.19.7.2. Error Handling module

4.19.7.2.1. DET

The module SPI depends on the DET (by default) in order to report development errors.

Detection and reporting of development errors can be enabled or disabled by the parameter SpiDevErrorDetect (The macro SPI_DEV_ERROR_DETECT = STD_ON generated in file Spi_Cfg.h).

The DET can be replaced optionally by an equivalent component which is responsible to recognize development errors, if no DET component is available.

The DET error is reported with Module ID.

The reported service IDs identify the services which are described earlier.

The following table represents the service IDs:

Service ID

Service

SPI_SID_INIT = 0x00

Spi_Init

SPI_SID_DEINIT = 0x01

Spi_DeInit

SPI_SID_WRITEIB = 0x02

Spi_WriteIB

SPI_SID_ASYNCTRANSMIT = 0x03

Spi_AsyncTransmit

SPI_SID_READIB = 0x04

Spi_ReadIB

SPI_SID_SETUPEB = 0x05

Spi_SetupEB

SPI_SID_GETSTATUS = 0x06

Spi_GetStatus

SPI_SID_GETJOBRESULT = 0x07

Spi_GetJobResult

SPI_SID_GETSEQUENCERESULT = 0x08

Spi_GetSequenceResult

SPI_SID_GETVERSIONINFO = 0x09

Spi_GetVersionInfo

SPI_SID_SYNCTRANSMIT = 0x0A

Spi_SyncTransmit

SPI_SID_GETHWUNITSTATUS = 0x0B

Spi_GetHwUnitStatus

SPI_SID_CANCEL = 0x0C

Spi_Cancel

SPI_SID_SETASYNCMODE = 0x0D

Spi_SetAsyncMode

SPI_SID_MAINFUNCTION_HANDLING = 0x10

Spi_MainfunctionHandling

The errors reported to DET module are described in the following table:

Error Code

Error Macro

Description

[0x0A]

SPI_E_PARAM_CHANNEL

channel out of bounds, exceeds the maximum number of configured channels.

[0x0B]

SPI_E_PARAM_JOB

Job out of bounds, exceeds the maximum number of configured jobs.

[0x0C]

SPI_E_PARAM_SEQ

Sequence out of bounds, exceeds the maximum number of configured sequences.

[0x0D]

SPI_E_PARAM_LENGTH

Length out of bounds, exceeds the maximum number of configured EB- or IB- buffer length.

[0x0E]

SPI_E_PARAM_UNIT

The requested hardware unit does not exist.

[0x10]

SPI_E_PARAM_POINTER

An invalid configuration has been passed (i.e., a NULL_PTR). This is an extension to AUTOSAR.

[0x1A]

SPI_E_UNINIT

A service was requested, but the driver has not been initialized.

[0x2A]

SPI_E_SEQ_PENDING

The requested sequence isstill pending.

[0x3A]

SPI_E_SEQ_IN_PROCESS

Transmission of synchronous sequence in progress (not supported).

[0x4A]

SPI_E_ALREADY_INITIALIZED

The driver is already initialized.

AUTOSAR requires to check the validity of function parameters. These checks are for development error reporting and can be en/dis-abled separately. En/dis-abling of single checks is an addition to the AUTOSAR standard which requires to en/dis-able the complete parameter checking via the parameter SPI_DEV_ERROR_DETECT. The following table shows which parameter checks are performed on which services:

Check Services

SPI_E_PARAM_CHANNEL

SPI_E_PARAM_JOB

SPI_E_PARAM_SEQ

SPI_E_PARAM_LENGTH

SPI_E_PARAM_UNIT

SPI_E_PARAM__POINTER

SPI_E_PARAM_UNINIT

SPI_E_SEQ_PENDING

SPI_E_SEQ_PROCESS

SPI_E_ALREADY_INITILAIZE

Spi_Init

x

x

x

x

x

Spi_DeInit

x

Spi_AsyncTransmit

x

x

x

Spi_SetupEB

x

x

x

x

Spi_GetStatus

Spi_GetJobResult

x

x

Spi_GetSequenceResult

x

x

Spi_GetVersionInfo

x

Spi_GetHwUnitStatus

x

x

Spi_Cancel

x

x

4.19.7.2.2. DEM

By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus ().

The errors reported to DEM are described in the following table

Error Code

Error Macro

Description

Assigned by DEM

SPI_E_HARDWARE_ERROR

This error is raised when McSPI RX FIFO overflows.

Assigned by DEM

SPI_E_BIT_ERROR

A bit error was detected.

Assigned by DEM

SPI_E_DESYNC_ERROR

Slave desynchronized.

Assigned by DEM

SPI_E_DLEN_ERROR

Data length mismatch detected during transmission.

Assigned by DEM

SPI_E_TXSTALL_ERROR

This error occurs if the driver tries to write data which has not been transmitted yet.

Assigned by DEM

SPI_E_RXSTALL_ERROR

The driver tries to read data, but no data has been provided by the hardware.

Assigned by DEM

SPI_E_DOVR_ERROR

The hardware reported an internal receive buffer overrun

Assigned by DEM

SPI_E_TO_ERROR

The hardware reported a Timeout error because of non-activation of ENA pin

4.19.7.3. Callback Functions

The SPI driver does not provide any call back functions.

4.19.7.4. Callback Notification

Notifications:

At its configurable interfaces, the SPI defines notifications that can be mapped to callback functions provided by other modules. The mapping is not statically defined by the SPI but can be performed at configuration time. The function prototypes that can be used for the configuration have to match the appropriate function prototype signatures, which are described in the following.

Example:Spi_JobEndNotification:

4.19.7.5. Hardware - Software - ISR API name mapping

For interrupt notification, ISR’s are provided in SPI driver. There are Two ISR for each SPI hardware unit. Depending on hardware unit configured, it will call group notify function. The interrupt service routines shall be mapped to the interrupt sources of the respective cross bar interrupt. The supported ISR’s are part of the Spi_Irq.h file.

Following are SPI module ISRs for each hardware unit:

  1. SPI HW UNIT 0

    • Spi_IrqUnitMcspi0TxRx()

    • ISR(Spi_IrqUnitMcspi0TxRx)

  2. SPI HW UNIT 1

    • Spi_IrqUnitMcspi1TxRx()

    • ISR(Spi_IrqUnitMcspi1TxRx)

  3. SPI HW UNIT 2

    • Spi_IrqUnitMcspi2TxRx()

    • ISR(Spi_IrqUnitMcspi2TxRx)

  4. SPI HW UNIT 3

    • Spi_IrqUnitMcspi3TxRx()

    • ISR(Spi_IrqUnitMcspi3TxRx)

  5. SPI HW UNIT 4

    • Spi_IrqUnitMcspi4TxRx()

    • ISR(Spi_IrqUnitMcspi4TxRx)

For using SPI wth DMA mode, register CDD_EDMA_lld_transferCompletionMasterIsrFxn with appropriate INTAGG line.

4.19.7.6. Scheduling Strategy

4.19.7.6.1. SchM (Optional)

Beside the OS the BSW Scheduler provides functions that SPI calls at begin and end of critical sections.

Example: SchM_Enter_Spi_SPI_EXCLUSIVE_AREA_0(), SchM_Exit_Spi_SPI_EXCLUSIVE_AREA_0().

4.19.7.6.2. Critical Sections

There is only one kind of critical sections in this driver. Within these sections all read /modify / write accesses to internal SPI driver data structures must be protected. Therefore switching to tasks that also access SPI has to be avoided and all SPI interrupts have to be suspended.

4.19.8. API Description

4.19.8.1. Description of the API’s

Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.

4.19.8.2. API’s with Service ID

The following table presents the service IDs and the related services:

AUTOSAR API’s Supported:

Service ID

Service

SPI_SID_INIT = 0x00

Spi_Init

SPI_SID_DEINIT = 0x01

Spi_DeInit

SPI_SID_WRITEIB = 0x02

Spi_WriteIB

SPI_SID_ASYNCTRANSMIT = 0x03

Spi_AsyncTransmit

SPI_SID_READIB = 0x04

Spi_ReadIB

SPI_SID_SETUPEB = 0x05

Spi_SetupEB

SPI_SID_GETSTATUS = 0x06

Spi_GetStatus

SPI_SID_GETJOBRESULT = 0x07

Spi_GetJobResult

SPI_SID_GETSEQUENCERESULT = 0x08

Spi_GetSequenceResult

SPI_SID_GETVERSIONINFO = 0x09

Spi_GetVersionInfo

SPI_SID_SYNCTRANSMIT = 0x0A

Spi_SyncTransmit

SPI_SID_GETHWUNITSTATUS = 0x0B

Spi_GetHwUnitStatus

SPI_SID_CANCEL = 0x0C

Spi_Cancel

SPI_SID_SETASYNCMODE = 0x0D

Spi_SetAsyncMode

SPI_SID_MAINFUNCTION_HANDLING = 0x10

Spi_MainfunctionHandling

AUTOSAR API’s not Supported:

None

Refer AUTOSAR SWS for API description per service mentioned in the above table.

4.19.8.3. Description on Non Standard API’s

Spi_RegisterReadback API–This function is non-autosar based and is used to read the data in the registers of Spi if we keep SPI_REGISTER_READBACK_API Macro as ON.

4.19.9. Configuration Description

4.19.9.1. Configuration Variants

The SPI can be configured as Post-Build or Pre-Compile or Link-time variant, using EB tresos tool.

Variants

Generated Files

PostBuild

Spi_PBcfg.c , Spi_Cfg.h

Link-time

Spi_Lcfg.c , Spi_Cfg.h

Pre-Compile

Spi_Cfg.c , Spi_Cfg.h

4.19.9.2. Parameter Description

4.19.9.2.1. Standard Configuration

Standard Parameters

Description

Default Value

Range

Unit

SPI_E_HARDWARE_ERROR

Reference to configured DEM event to report "Hardware failure". If the reference is not configured the error shall not be reported.

–

–

–

SpiMaxChannel

This parameter contains the number of Channels configured. It will be gathered by tools during the configuration stage.

28

0..255

Integer

SpiMaxJob

Total number of Jobs configured.

14

0..65535

Integer

SpiMaxSequence

Total number of Sequences configured.

14

0..255

Integer

SpiChannelId

SPI Channel ID, used as parameter in SPI API functions.

0

0..255

Integer

SpiChannelType

Buffer usage with EB/IB channel.

–

–

Enumeration

SpiDataWidth

This parameter is the width of a transmitted data unit.

16

1..32

Integer

SpiDefaultData

The default data to be transmitted when (for internal buffer or external buffer) the pointer passed to Spi_WriteIB (for internal buffer) or to Spi_SetupEB (for external buffer) is NULL.

0

0..4294967295

Integer

SpiEbMaxLength

This parameter contains the maximum size (number of data elements) of data buffers in case of EB Channels and only.

255

0..65535

Integer

SpiIbNBuffers

This parameter contains the maximum number of data buffers in case of IB Channels and only.

10

0..65535

Integer

SpiTransferStart

This parameter defines the first starting bit for transmission.

MSB

LSB MSB

Enumeration

SpiBaudrate

This parameter is the communication baudrate - This parameter allows

500

1.0 .. 4.0E7

Float

SpiCsIdentifier

This parameter is the symbolic name to identify the Chip Select (CS) allocated to this Job (CS0 to CS3).

CS0

–

String

SpiCsPolarity

This parameter defines the active polarity of Chip Select.

HIGH

LOW HIGH

Boolean

SpiCsSelection

When the Chip select handling is enabled (see SpiEnableCs), then this parameter specifies if the chip select is handled automatically by Peripheral HW engine or via general purpose IO by Spi driver.

CS_VIA_PERIPHERAL_ENGINE

CS_VIA_GPIO CS_VIA_PERIPHERAL_ENGINE

Enumeration

SpiDataShiftEdge

This parameter defines the SPI data shift edge.

LEADING

LEADING TRAILING

Enumeration

SpiEnableCs

This parameter enables or not the Chip Select handling functions. If this parameter is enabled then parameter SpiCsSelection further details the type of chip selection.

TRUE

TRUE FALSE

Boolean

SpiHwUnit

This parameter is the symbolic name to identify the HW SPI Hardware

CSIB0

CSIB0 CSIB1 CSIB2 CSIB3 CSIB4

Enumeration

SpiShiftClockIdleLevel

This parameter defines the SPI shift clock idle level.

LOW

LOW HIGH

Boolean

SpiTimeClk2Cs

Timing between clock and chip select (in seconds) - This parameter allows to use a range of values from 0 up to 0.0001 seconds.

0.0001

0.0 .. 1.0E-4

Float

SpiHwUnitSynchronous

the SpiJob uses its containing SpiDriver in a synchronous manner. If it is set to "ASYNCHRONOUS", it uses the driver in an asynchronous way. If the parameter is not set, the SpiChannel uses the driver also in an asynchronous way.

ASYNCHRONOUS

ASYNCHRONOUS SYNCHRONOUS

Enumeration

SpiJobEndNotification

This parameter is a reference to a notification function.

NULL_PTR

–

Function

SpiJobId

SPI Job ID, used as parameter in SPI API functions.

–

0..65535

Integer

SpiJobPriority

Priority set accordingly to SPI093: 0, lowest, 3, highest priority

3

0..3

Integer

SpiDeviceAssignment

Reference to the external device used by this job

–

–

–

SpiChannelIndex

This parameter specifies the order of Channels within the Job.

–

0..255

Integer

SpiChannelAssignment

A job reference to a SPI channel.

–

–

–

SpiInterruptibleSequence

This parameter allows or not this Sequence to be suspended by another one.

TRUE

TRUE FALSE

Boolean

SpiSeqEndNotification

This parameter is a reference to a notification function.

NULL_PTR

–

Function

SpiSequenceId

SPI Sequence ID, used as parameter in SPI API functions.

–

0..255

Integer

SpiJobAssignment

A sequence references several jobs, which are executed during a communication sequence

–

–

–

SpiCancelApi

Switches the Spi_Cancel function ON or OFF.

TRUE

TRUE FALSE

Boolean

SpiChannelBuffersAllowed

Selects the SPI Handler/Driver Channel Buffers usage allowed

–

0..2

Integer

SpiDevErrorDetect

Switches the Development Error Detection and Notification ON or OFF.

TRUE

TRUE FALSE

Boolean

SpiHwStatusApi

Switches the Spi_GetHWUnitStatus function ON or OFF.

TRUE

TRUE FALSE

Boolean

SpiInterruptibleSeqAllowed

Switches the Interruptible Sequences handling functionality ON or OFF.

TRUE

TRUE FALSE

Boolean

SpiLevelDelivered

Selects the SPI Handler/Driver level of scalable functionality: SYNC ONLY(0), ASYNC ONLY (1), SYNC/ASYNC(2)

2

0..2

Integer

SpiMainFunctionPeriod

This parameter defines the cycle time of the function Spi_MainFunction_Handling in seconds.

0.01

1.0E-7 .. 0.1

Float

SpiSupportConcurrentSyncTransmit

Specifies whether concurrent Spi_SyncTransmit() calls for different sequences shall be configurable.

FALSE

TRUE FALSE

Boolean

SpiUserCallbackHeaderFile

Header file name which will be included by the Spi. The value of this parameter shall be used as h-char-sequence or q-char-sequence according to ISO C90 section 6.10.2 "source file inclusion".

FALSE

TRUE FALSE

Boolean

SpiVersionInfoApi

Switches the Spi_GetVersionInfo function ON or OFF.

TRUE

TRUE FALSE

Boolean

SpiMaxHwUnit

Number of different SPI hardware microcontroller peripherals (units/busses) available and handled by this SPI Handler/Driver module.

5

1..5

Integer

4.19.9.2.2. IP Specific Configuration

Standard Parameters

Description

Default Value

Range

Unit

SpiMaxHwUnit

Maximum number of HW unit

5

1..5

Integer

SpiMaxExternalDeviceConfig

Maximum Number of different SPI hardware microcontroller peripherals available and handled by this SPI Handler/Driver module.Max range is derived from SpiMaxExternalDevices.

5

1..5

Integer

SpiExternalDeviceId

The index of the corresponding external device config associated with job.

0..65535

Integer

SpiCsMode

This selects which CS mode the device should enter. SPI_SINGLE: the CS will return to default level after one transmission unit has been sent. SPI_CONTINUOUS: the CS will remain active during the whole transmission.

SPI_CONTINUOUS

SPI_SINGLE SPI_CONTINUOUS

Enumeration

SpiCsIdleTime

CS idle time (Timing between clock and chip select) if single mode is chosen.

SPI_DATADELAY_0

SPI_DATADELAY_0 SPI_DATADELAY_1 SPI_DATADELAY_2 SPI_DATADELAY_3

Enumeration

SpiExtDeviceClockDivider

Clock divider. This is used to derive the required baudrate from the QSPI functional clock.

0

0..65535

Integer

SpiExtDeviceMCSPITxRxMode

TX and RX mode. Data is transmitted (shifted out serially on SPIDAT[0]) and received (shifted in serially on SPIDAT[1]) simultaneously on separate data lines.Tx only mode - Data is only transmiited (shifted out serially on SPIDAT).

SPI_TX_RX_MODE_BOTH

SPI_TX_RX_MODE_BOTH SPI_TX_RX_MODE_TX_ONLY

Enumeration

SpiExtDeviceMCSPIStartBitEnable

Start bit D/CX added before SPI transfer. Polarity is defined by StartBitLevel

TRUE

TRUE FALSE

Boolean

SpiExtDeviceMCSPIStartBitLevel

Start-bit polarity used when startBitEnable is TRUE.

SPI_LOW

SPI_LOW SPI_HIGH

Enumeration

SpiExtDeviceMCSPIDataLineSelectReception

Data Line 0 or 1 selected for reception

DATA_LINE_0_RECEPTION

DATA_LINE_0_RECEPTION DATA_LINE_1_RECEPTION

Enumeration

SpiExtDeviceMCSPIDataLineSelectTransmission

Data Line 0 or 1 or both selected for transmission.No transmission on data lines if DATA_LINE_NO_TRANSMISSION is selected

DATA_LINE_1_TRANSMISSION

DATA_LINE_NO_TRANSMISSION DATA_LINE_0_TRANSMISSION DATA_LINE_1_TRANSMISSION DATA_LINE_BOTH_TRANSMISSION

Enumeration

SpiHwUnitAssignment

Reference to the HW unit used by this job

SpiHwUnitType

SPI HW unit to use

SPI_UNIT_MCSPI0

SPI_UNIT_MCSPI0 SPI_UNIT_MCSPI1 SPI_UNIT_MCSPI2 SPI_UNIT_MCSPI3 SPI_UNIT_MCSPI4

Enumeration

SpiHwUnitDmaEnable

Enables DMA support for MCSPI instance

FALSE

TRUE FALSE

BOOLEAN

SpiHwUnitCddDmaTxHandler

References the CDD DMA handler used for MCSPI transmission

SpiHwUnitCddDmaRxHandler

References the CDD DMA handler used for MCSPI reception

SpiEnableJobLog

Enable/disable SPI job log

TRUE

TRUE FALSE

Boolean

SpiMaxExternalDevices

Number of different SPI hardware microcontroller peripherals (units/busses) available and handled by this SPI Handler/Driver module.

5

1..5

Integer

SpiMaxJobLogLength

Maximum job log entries when logging is ON

100

1.65535

Integer

SpiMaxTimeoutDuration

Maximum time duration for SPI transmission.Unit is clock ticks.

10000

1..4294967295

Integer

SpiMaxChannelsPerJob

Maximum channels allowed per job

4

1..32

Integer

SpiMaxJobsPerSequence

Maximum jobs allowed per sequence

4

1..32

Integer

SpiMaxChannels

Maximum channels across all jobs/sequence/hwunit

24

1..128

Integer

SpiMaxJobs

Maximum jobs across all sequence/hwunit

10

1..65535

Integer

SpiMaxSequences

Maximum sequence across all hwunit

10

1..255

Integer

SpiIrqType

Type of Isr function: void functionname(void) 1.CAT1 : interrupt void func(void) 2.CAT2 : ISR(func)

SPI_ISR_CAT2

SPI_ISR_VOID SPI_ISR_CAT1 SPI_ISR_CAT2

Enumeration

SpiDefaultOSCounterId

Default Os Counter Id if node reference to OsCounter ref SpiOsCounterRef is not set

0

0..16

Integer

SpiOsCounterRef

This parameter contains a reference to the OsCounter, which is used by the SPI driver.

SpiTimeoutDuration

SPI timeout - used in SPI busy wait

32000

1..4294967295

Integer

SpiRegisterReadbackApi

Specifies whether RegisterReadback API is enabled

TRUE

TRUE FALSE

Boolean

SpiSafetyApi

Enable API to do safety diagnostic

TRUE

TRUE FALSE

Boolean

SpiChannelInternalBufferMaxLength

Internal Buffer length in bytes - applicable for SpiChannelBuffer type - SPI_IB. This is the maximum length that can be allocated by each channel and it is fixed.Can vary buffer length per channel by configuring SpiIbNBuffers and SpiDataWidth.

64

1..4294967295

Integer

SpiDeviceVariant

Select SOC variant

AM263x

AM263x

Enumeration

SpiHwUnitEnabledFlag

Group configurations

SPI_HWUNIT_MCSPI0

SPI_HWUNIT_MCSPI0 SPI_HWUNIT_MCSPI1 SPI_HWUNIT_MCSPI2 SPI_HWUNIT_MCSPI3 SPI_HWUNIT_MCSPI4

Enumeration

4.19.9.3. Symbolic Names deviations

None

4.19.9.4. Configuration rules and constraints to enable plausibility checks

SPI DMA Tx and Rx Handler should be configured to match Channel IDs with the EDMA TRIG XBAR MODULE number selected with appropriate CDD DMA channel trigger source selected from the dropdown as per the instance. Channel crossbar and channel crossbar map can be left to default as SPI driver doesn’t make use of those parameters.

../_images/DMA_SPI_trigger_configuration_AM263.png

Fig. 4.8 CDD DMA Crossbar configuration matching Channel ID for SPI Handle

As an example, for SPI0 instance with Chip Select 0, channel trigger source CDD_DMA_TRIG_XBAR_SPI0_DMA_WRITE_REQ0 shall be used.

4.19.10. Memory Mapping

Memory Mapping Sections

SPI_CODE

SPI_VAR

SPI_VAR_NO_INIT

SPI_CONST

SPI_APPL_DATA

SPI_APPL_CODE

SPI_START_SEC_VAR_INIT_UNSPECIFIED (.data) SPI_STOP_SEC_VAR_INIT_UNSPECIFIED

x

SPI_START_SEC_CODE (.text) SPI_STOP_SEC_CODE

x

SPI_START_SEC_VAR_NO_INIT_UNSPECIFIED (.bss) SPI_STOP_SEC_VAR_NO_INIT_UNSPECIFIED

x

SPI_START_SEC_CONST_UNSPECIFIED (.const) SPI_STOP_SEC_CONST_UNSPECIFIED

x

SPI_START_SEC_CODE_ISR (.text) SPI_STOP_SEC_CODE_ISR

x

For application code used by SPI (like callback functions)

x

4.19.11. Memory footprint

Please refer Memory Footprint for more details.

4.19.12. Performance

4.19.12.1. Actual Performance details

Performance Result through MCSPI with Interrupt mode are as follows:

No. of words

Datawidth (bits)

Clock Frequency (MHz)

Transfer Time (us)

Throughput (Mbps)

Total Average time

112000

8

5

206905

4.33049

2069 micro-seconds

112000

8

10

110605

8.1009

1106 micro-seconds

112000

8

50

36652

24.4461

366 micro-seconds

56000

16

5

193405

4.63277

1934 micro-seconds

56000

16

10

100205

8.94167

1002 micro-seconds

56000

16

50

27606

32.4567

276 micro-seconds

28000

32

5

186606

4.80156

1866 micro-seconds

28000

32

10

95403

9.39174

954 micro-seconds

28000

32

50

23106

38.7778

231 micro-seconds

Performance Result through MCSPI with Dma are as follows:

No. of words

Datawidth (bits)

Clock Frequency (MHz)

Transfer Time (us)

Throughput (Mbps)

Total Average time

112000

8

5

224409

3.99271

2244 micro-seconds

112000

8

10

128313

6.98292

1283 micro-seconds

112000

8

50

54511

16.437

545 micro-seconds

56000

16

5

202813

4.41786

2028 micro-seconds

56000

16

10

110219

8.12927

1102 micro-seconds

56000

16

50

37712

23.7584

377 micro-seconds

28000

32

5

193493

4.63066

1935 micro-seconds

28000

32

10

100912

8.87902

1009 micro-seconds

28000

32

50

29306

30.5739

292 micro-seconds

4.19.13. Example Usage

4.19.13.1. Steps to build and run example

Spi example application demonstrating the MCAL SPI driver features is in folder <MCAL_ROOT>/examples/Spi.

This application can be built from the root folder by giving gmake –s mcspi_app PLATFORM=am263.

Then launch TI Code Composer Studio (CCS) and connect the Board with it using an appropriate target configuration, load the application binary in to R5_0 core and execute the binary.

4.19.13.2. Document external set up Information

None

4.19.13.3. Flow of the example application

  1. In example application,the status of spi is checked,whether it is idle or busy.

  2. After checking the status,it sets the external buffer as per requirement.

  3. Then the mode of transmission is set and post that async transmission takes place with loopback enable.

  4. After the transmission is completed,the recieve and transmit data is compared and the datas should be same.

4.19.13.4. Configuration used to test this example

The example application is configured with the following Parametrs:

Max Channels :10U

Max channels per Sequence :4U

Max Jobs per seq:4U

Max HwUnit :5U

Max External Devices:5U

Channel BufferType :SPI_EB

Maximum Buffer Length :1120U

Transfer Type :SPI_MSB

Mode of Transmission:Asynchronous

Method of Testing :Loopback

4.19.13.4.1. Program changes with DMA mode

For DMA mode support, DMA TPCC0 Interrupt aggregation (INTR) line number 72 gets used to register ISR with EDMA and Cache write back for source buffer before data transmission as well as Cache invalidation before validating destination buffers should happen using respective Mcal_CacheP_wb and Mcal_CacheP_inv APIs.

4.19.13.5. Example Logs

SPI_APP: Variant - Post Build being used !!!
SPI_APP
: Sample Application - STARTS !!!

SPI MCAL Version Info
---------------------
Vendor ID           : 44
Module ID           : 83
SW Major Version    : 9
SW Minor Version    : 1
SW Patch Version    : 0

SPI_APP: CH 10: JOBS 4: SEQ 3: HWUNIT 5: NUM OF WORDS 100:!!!

SPI_APP: SPI Async transmit in progress!!

SPI_APP: SPI Loopback Test Passed!!!

SPI Stack Usage: 1000 bytes

4.19.14. FAQ’s

  1. Is SPI Driver DMA compliant?

    Yes, MCSPI driver has been enabled to support DMA transfers by means of EDMA driver.

4.19.15. Test Report

Please refer AM26x SPI Driver Test Case Report provided as part of CSP.

4.19.16. References

AUTOSAR_SWS_SPIHandlerDriver
Technical Reference Manual

4.19.17. TI Disclaimer

Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.

TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.

Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.

TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.

Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265