4.19. SPI¶
4.19.1. About This Document¶
Document Title |
User Guide of MCAL SPI Driver |
Document Version |
Version 1.0 |
Company |
Texas Instruments |
Document Name |
SPI User Guide |
4.19.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
---|---|---|---|
Version 1.0 |
13 Oct 2023 |
Initial Version |
Approved |
4.19.3. Table of contents¶
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 |
AM263px |
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:
Handle data transmission to the components connected via SPI
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

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.

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.
SPI_UNINIT: The SPI Handler/Driver is not initialized or not usable.
SPI_IDLE : The SPI Handler/Driver is not currently transmitting any Job.
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:

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:

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:
For Baudrate = 50Mbps , CLKD should be given as 0 , calculation will be as following
Baudrate = 50/(0+1) = 50Mbps
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 |
---|---|---|
|
|
|
4.19.5.3. Assumptions¶
None
4.19.5.4. Limitations¶
A job queued in a sequence cannot be queued via another sequence. This is a design limitation to reduce driver complexity.
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.
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.5. Design overview(Link to the Architecture document and Design Document)¶
Will be avialable in future release.
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 |

Figure 5: SPI header file include structure
4.19.6. Deviations to requirements (Requirement Traceability)¶
4.19.6.1. Module Requirements¶
Will be updated in future release
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:
SPI HW UNIT 0
Spi_IrqUnitMcspi0TxRx()
ISR(Spi_IrqUnitMcspi0TxRx)
SPI HW UNIT 1
Spi_IrqUnitMcspi1TxRx()
ISR(Spi_IrqUnitMcspi1TxRx)
SPI HW UNIT 2
Spi_IrqUnitMcspi2TxRx()
ISR(Spi_IrqUnitMcspi2TxRx)
SPI HW UNIT 3
Spi_IrqUnitMcspi3TxRx()
ISR(Spi_IrqUnitMcspi3TxRx)
SPI HW UNIT 4
Spi_IrqUnitMcspi4TxRx()
ISR(Spi_IrqUnitMcspi4TxRx)
SPI HW UNIT 5
Spi_IrqUnitMcspi5TxRx()
ISR(Spi_IrqUnitMcspi5TxRx)
SPI HW UNIT 6
Spi_IrqUnitMcspi6TxRx()
ISR(Spi_IrqUnitMcspi6TxRx)
SPI HW UNIT 7
Spi_IrqUnitMcspi7TxRx()
ISR(Spi_IrqUnitMcspi7TxRx)
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(Can be referred to Api Guide spec)¶
Refer the AUTOSAR SWS for API documentation and Type definition.
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¶
None
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¶
channelCfg: Configurations per Channel
channelBufType: Type of channel buffer, whether internal or external.
dataWidth: Data Width per transmission in bits, with a maximum of 32 bits supported in one go.
defaultTxData: Default data bit to use for transmission.
maxBufLength: Maximum Buffer Length usable for channel
transferType: Type of data transfer order, out of LSB or MSB first.
jobCfg: Configurations per Job
jobPriority: Priority number for Job. Higher number means more priority.
hwUnitId: Hardware Unit instance number linked with this Job
Spi_JobEndNotification: Job completion notification function
channelPerJob: Number of Channels assigned with this Job
channelList: Array of channel numbers with this Job
seqCfg: Configurations per Sequence
seqInterruptible: Toggle for interruptability of sequence
Spi_SequenceEndNotification: Sequence completion notification function
jobPerSeq: Number of Jobs assigned with this sequence
jobList: Array of jobs for this sequence
hwUnitCfg: Configurations per MCSPI Hardware Unit
hwUnitId: Instance Number
enableDmaMode: Toggles DMA mode usage for data exchange for a particular HwUnit
dmaTxHandlerID: DMA Transmission Handle ID Number as configured with DMA configurator plugin. Applicable only when enableDmaMode is set to true.
dmaRxHandlerID: DMA Receiving Handle ID Number as configured with DMA configurator plugin. Applicable only when enableDmaMode is set to true.
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.

Fig. 4.7 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¶
Will be updated in future release
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=am263px.
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¶
In example application,the status of spi is checked,whether it is idle or busy.
After checking the status,it sets the external buffer as per requirement.
Then the mode of transmission is set and post that async transmission takes place with loopback enable.
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 :8U
Max External Devices:8U
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 8: NUM OF WORDS 1120:!!!
SPI_APP: SPI Async transmit in progress!!
SPI_APP: SPI Loopback Test Passed!!!
SPI Stack Usage: 1000 bytes
4.19.14. FAQ’s¶
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 (Link to test report)¶
Will be updated in future release
4.19.16. References¶
For Recommended R5 MPU settings, Optimize R5F MPU settings
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