User Guide: AUTOSAR SPI Handler Driver
User Guide: AUTOSAR SPI Handler Driver
User Guide
Version 1.3
The information and/or drawings set forth in this document and all rights in and to inventions disclosed
herein and patents which might be granted thereon disclosing or employing the materials, methods,
techniques, or apparatus described herein are the exclusive property of Texas Instruments. No
disclosure of information or drawings shall be made to any other person or organization without the
prior consent of Texas Instruments.
Table of Contents
1. Introduction .......................................................................................................................................... 5
1.1. Architecture Overview .................................................................................................................. 5
2. Functional Description .......................................................................................................................... 8
2.1. Features ........................................................................................................................................ 8
Table 2-2 Not Supported SWS features ................................................................................................... 8
2.2. Initialization................................................................................................................................... 8
2.3. States............................................................................................................................................. 8
2.4. Error Handling ............................................................................................................................... 9
2.4.1. Development Error Reporting ............................................................................................... 9
2.4.2. Production Code Error Reporting ....................................................................................... 11
2.5. Scope of Delivery ........................................................................................................................ 11
2.5.1. Static Files ........................................................................................................................... 11
2.5.2. Dynamic Files ...................................................................................................................... 12
2.6. Include Structure......................................................................................................................... 13
2.7. Compiler Abstraction and Memory Mapping ............................................................................. 13
2.8. Dependencies on SW modules ................................................................................................... 15
2.8.1. OSEK/AUTOSAR OS (Optional) ............................................................................................ 15
2.8.2. DET ...................................................................................................................................... 15
2.8.3. DEM ..................................................................................................................................... 15
2.8.4. MCU .................................................................................................................................... 15
2.8.5. PORT .................................................................................................................................... 15
2.8.6. SchM (Optional) .................................................................................................................. 15
2.9. Dependencies on HW modules ................................................................................................... 15
3. API Description .................................................................................................................................... 16
3.1. Interfaces Overview .................................................................................................................... 16
3.2. Imported Type Definitions .......................................................................................................... 16
Table 3-1 Imported Type definitions...................................................................................................... 16
3.3. Exported Type Definitions........................................................................................................... 16
3.4. Exported Objects......................................................................................................................... 18
3.5. Interrupt Service Routines provided by Spi ................................................................................ 18
3.5.1. Spi error interrupt service ................................................................................................... 19
1. Introduction
This document describes the functionality, API and configuration of the AUTOSAR BSW module SPI.
This document describes the functionalities, the configuration and the API of the SPI driver for the
microcontroller Family TMS570LSx from Texas Instruments.
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 the Spi hardware units onboard.
Handle data transmission to the components connected via Spi.
Take care of the settings required by external components (baud rate etc.)
pkg MCAL
ECUAL
(from SoftwarePackages)
MCAL
(from SoftwarePackages)
Hardw are
2. Functional Description
2.1. Features
The "supported" and "not supported" features are presented in the following two tables. For further
information of not supported features also see chapter 5.
Supported Features
Configure Spi with
External devices
Channels
Jobs
Sequences
Configure physical units and callback functions
Configure error detection (DEM and DET)
Configure implementation features like:
Spi scalability level(s).
Spi channel buffers
Spi Interrupts
Spi frame transfers with 8 or 16bit clock frames
Select simple or extended API
Interruptible Sequences
Table 2-1 Supported SWS features
2.2. Initialization
The driver Spi is initialized by calling Spi_Init() with a pointer to a configuration as parameter. To
re-initialize call Spi_DeInit() and then Spi_Init() again with a different configuration. The
service for de-initialization is provided with the function Spi_DeInit().
2.3. States
The Spi maintains states for:
The Spi driver itself,
the configured jobs,
the configured sequences
Service ID Service
SPI_SID_INIT = 0x00 Spi_Init
SPI_SID_DEINIT = 0x01 Spi_DeInit
SPI_SID_WRITE_IB = 0x02 Spi_WriteIB
SPI_SID_ASYNC_TRANSMIT = 0x03 Spi_AsyncTransmit
SPI_SID_READ_IB = 0x04 Spi_ReadIB
SPI_SID_SETUP_EB = 0x05 Spi_SetupEB
SPI_SID_GET_STATUS = 0x06 Spi_GetStatus
SPI_SID_GET_JOB_RESULT = 0x07 Spi_GetJobResult
SPI_SID_GET_SEQ_RESULT = 0x08 Spi_GetSequenceResult
SPI_SID_GETVERSION_INFO = 0x09 Spi_GetVersionInfo
SPI_SID_SYNC_TRANSMIT = 0x0A Spi_SyncTransmit
SPI_SID_GET_UNIT_STATUS = 0x0B Spi_GetHWUnitStatus
SPI_SID_CANCEL = 0x0C Spi_Cancel
SPI_SID_SET_ASYNC_MODE = 0x0D Spi_SetAsyncMode
SPI_SID_MAINFUNCTION_HANDLING = 0x10 Spi_MainFunction_Handling
Table 2-3 Mapping of service IDs to services
configured channels
[0x0B] SPI_E_PARAM_JOB Job out of bounds, exceeds the maximum nuber 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 is still 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.
Table 2-4 Error Reported to DET
Check
SPI_E_ALREADY_INITIALIZE
SPI_E_PARAM_CHANNEL
SPI_E_SEQ_IN_PROCESS
SPI_E_PARAM_POINTER
SPI_E_PARAM_LENGTH
SPI_E_SEQ_PENDING
SPI_E_PARAM_UNIT
SPI_E_PARAM_SEQ
SPI_E_PARAM_JOB
SPI_E_UNINIT
Services
D
Spi_Init ● ●
Spi_DeInit ●
Spi_AsyncTransmit ● ● ●
Spi_SetupEB ● ● ● ●
Spi_GetStatus
Spi_GetJobResult ● ●
Spi_GetSequenceResult ● ●
Spi_GetVersionInfo
Spi_GetHWUnitStatus ● ●
Spi_Cancel ● ●
Table 2-5 Development Error Reporting: Assignment of checks to services
CPU only supports 32bit-addresses. Because of this, it is recommended to define the Compiler
Abstraction definitions required by this module as empty macros in Compiler_Cfg.h.
The objects (e.g. variables, functions, constants) are declared by compiler independent definitions – the
compiler abstraction definitions. Each compiler abstraction definition is assigned to a memory section.
The following table contains the memory section names and the compiler abstraction definitions
defined for the Spi and illustrate their assignment among each other.
Compiler Abstraction
Definitions
SPI_VAR_ZERO_INIT
SPI_VAR_NOINIT
SPI_APPL_CODE
SPI_APPL_DATA
SPI_CONST
SPI_PBCFG
SPI_CODE
SPI_VAR
Memory Mapping
Sections
SPI_START_SEC_CONST_32BIT (.const)
●
SPI_STOP_SEC_CONST_32BIT
SPI_START_SEC_PBCFG_ROOT (.const)
●
SPI_STOP_SEC_PBCFG_ROOT
SPI_START_SEC_PBCFG (.const)
●
SPI_STOP_SEC_PBCFG
SPI_START_SEC_CONST_UNSPECIFIED (.const)
●
SPI_STOP_SEC_CONST_UNSPECIFIED
SPI_START_SEC_CONST_32BIT (.const)
●
SPI_STOP_SEC_CONST_32BIT
SPI_START_SEC_CODE (.text)
●
SPI_STOP_SEC_CODE
SPI_START_SEC_CODE_ISR (.text)
●
SPI_STOP_SEC_CODE_ISR
SPI_START_SEC_VAR_NO_INIT_UNSPECIFIED (.bss)
●
SPI_STOP_SEC_VAR_NO_INIT_UNSPECIFIED
SPI_START_SEC_VAR_INIT_UNSPECIFIED (.data)
●
SPI_STOP_SEC_VAR_INIT_UNSPECIFIED
SPI_START_SEC_VAR_ZERO_INIT_UNSPECIFIED (.data)
●
SPI_STOP_SEC_VAR_ZERO_INIT_UNSPECIFIED
For application buffers passed to SPI ●
For application code used by Spi(like callback functions) ●
Table 2-9 Compiler abstraction and memory mapping
2.8.2. 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 switch "Enable Development Error
Detection" on the tab "General Settings" within the module Spi.
2.8.3. DEM
The module Spi depends on the DEM in order to report diagnostic errors. Detection and reporting of
diagnostic errors cannot be disabled.
2.8.4. MCU
The module MCU powers up the microcontroller’s peripherals at startup time. Since the peripherals are
also containing the registers for I/O functionality they have to be activated if it is intended to use them.
2.8.5. PORT
The module PORT enables the Spi lines at startup time. To operate the Spi properly, the PORT driver has
to be configured. The PORT driver sets the PINs to the required values for the Spi to operate. The
following figure shows an example configuration of the PORT.
3. API Description
SPI_JOB_ACTIVE = 3, job is
running (internal state)
SPI_JOB_FAILED = 4, job failed
Spi_SeqResultType Enum The result / status of the SPI_SEQ_OK = 0, sequence is
sequence IDLE or finished successfully
(default value)
SPI_SEQ_PENDING = 1,
sequence is running now
SPI_SEQ_FAILED = 2, sequence
failed
SPI_SEQ_CANCELLED = 3,
sequence has been aborted
Spi_HWUnitResultType Enum The result / status of the SPI_DLC_OK = 0, driver
hardware hardware is IDLE or finished
successfully
SPI_DLC_PENDING = 1, driver
hardware is running now
SPI_DLC_FAILED = 2, driver
hardware failed
Spi_NumberOfDataType uint16 Type for channel length Range (0-65535)
parameter
Spi_JobType uint16 Type for job ID Range (0-255), limited to 255.
Spi_DataType uint8 Type for data transmission, Range (0-255)
reception
Spi_ChannelType uint8 Type for channel ID Range (0-255)
Spi_SequenceType uint8 Type for sequence ID Range (0-255)
Spi_HWUnitType uint8 Type for hardware unit ID Range (0-4)
Spi_ExternalDeviceType uint8 Type for external device ID Range (0-255)
Spi_ConfigType Struct This is the configuration type Configuration of external
of the Spi. A reference of this devices
type is generated in the
Spi_PBcfg.c file. Configuration of channels
Configuration of job settings
Configuration of sequence
settings
Configuration of hardware units
Spi_LoopbackModeType enum Type to select Loopback Mode SPI_DIGITAL_LPBK
SPI_ANALOG_LPBK
Spi_RegisterReadbackTy struct Structure to report current GCR0, GCR1, DEF, EN
pe status of configuration
registers
Spi_ExternalDeviceConfi Struct Type containing details Dio Pin
gType about the external device CS Property
assigned to a job Baudrate
Mode
Clk Delays
CS Idle Time
CS Mode
HW Instance
Spi_ChannelConfigType Struct Type containing details Channel ID
about Channel Buffer Type
configuration Data Width
Default TX Data
Buffer Length
TX Start (MSB or LSB)
Spi_JobConfigType Struct Type containing details Job notification
about Job configuration Channel Index List
External device assigned
Job ID
Job Priority
HW Unit
Spi_SequenceConfigTyp Struct Type containing details Sequence Notification
e about Sequence Job Index list
configuration Sequence ID
Sequence Interruptible
Table 3-2 Type definitions
Note: Final integrator is required to enable and associate the interrupt channels in VIM to the
corresponding ISRs.
3.6.1. Spi_Init
Prototype
void Spi_Init ( const Spi_ConfigType* ConfigPtr )
Parameter
ConfigPtr Pointer to Spi configuration set.
Return code
void --
Functional Description
The initialization must be called to operate the Spi driver. This applies to a power on reset or a normal
reset. Most API services will throw a DET error if the Spi_Init was not executed before.
If development error detection is activated, the function performs these checks:
Checks if the driver has already been initialized.
Checks if the passed parameter is no NULL pointer.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is always available.
This function returns without action if a check fails
This function should not be called during a running operation.
Expected Caller Context
Expected to be called in application context, during initialization phase.
Table 3-9 Spi_Init
3.6.2. Spi_DeInit
Prototype
Std_ReturnType Spi_DeInit ( void )
Parameter
void --
Return code
Std_ReturnType E_OK, success
E_NOT_OK, request rejected.
Functional Description
The de-initialization can be called to shut down the Spi driver. This applies to a system shutdown of the
system. It can also be used to reinitialize the system in case of a critical error. Critical errors are
reported to the DEM module. A critical error can be detected by evaluating a job result (status:
SPI_JOB_FAILED).
If development error detection is activated, the function performs these checks:
Checks if the driver has been initialized.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component. The Spi driver checks also if it is busy. The request is rejected if the driver is not
idle.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is always available.
This function should not be called during a running operation.
Expected Caller Context
Expected to be called in application context, during shutdown phase.
Table 3-10 Spi_DeInit
3.6.3. Spi_SyncTransmit
Prototype
Std_ReturnType Spi_SyncTransmit ( Spi_SequenceType Sequence )
Parameter
Sequence The transmission and reception for this Sequence ID is engaged
Return code
E_OK, request accepted, transmission will be processed.
Std_ReturnType
E_NOT_OK, request rejected.
Functional Description
The passed sequence will perform transmission on the Spi bus.
If development error detection is activated, the function performs these checks:
Checks if the driver has been initialized.
Checks if the sequence parameter is correct.
Checks if a sequence is pending.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is configurable (Spi scalability level).
Expected Caller Context
Expected to be called in application context, during operational phase.
Table 3-11 Spi_SyncTransmit
3.6.4. Spi_AsyncTransmit
Prototype
Std_ReturnType Spi_AsyncTransmit ( Spi_SequenceType Sequence )
Parameter
Sequence The transmission and reception for this Sequence ID is engaged
Return code
E_OK, request accepted, transmission will be processed.
Std_ReturnType
E_NOT_OK, request rejected.
Functional Description
The passed sequence will trigger a transmission on the Spi bus.
If development error detection is activated, the function performs these checks:
Checks if the driver has been initialized.
Checks if the sequence parameter is correct.
Checks if a sequence is pending.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is asynchronous.
This function is non reentrant.
This function is configurable (Spi scalability level).
Expected Caller Context
Expected to be called in application context, during operational phase.
Table 3-11 Spi_AsyncTransmit
3.6.5. Spi_SetupEB
Prototype
Std_ReturnType Spi_SetupEB ( Spi_ChannelType Channel, const Spi_DataType* SrcDataBufferPtr,
Spi_DataType* DesDataBufferPtr, Spi_NumberOfDataType Length )
Parameter
Channel ID of the channel which stores the data for transmission.
SrcDataBufferPtr Pointer to the buffer which holds the data.
DesDataBufferPtr Pointer to the buffer which gets the data.
Length Length to transmit in bytes.
Return code
E_OK, data has been retrieved a copied to application buffer
Std_ReturnType
E_NOT_OK, request rejected.
Functional Description
The function prepares a buffer, which is passed by the application for transmission.
If development error detection is activated, the function performs these checks:
Checks if the channel is valid.
3.6.6. Spi_GetStatus
Prototype
Spi_StatusType Spi_GetStatus ( void )
Parameter
void --
Return code
Status of the Spi driver.
Spi_StatusType SPI_UNINIT Driver is uninitialized
SPI_IDLE Driver waiting for sequences to process.
SPI_BUSY Driver is processing a sequence(s). .
Functional Description
Returns the current driver status.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is configurable (Spi scalability level).
Expected Caller Context
Expected to be called in application context, during operational phase.
Table 3-33 Spi_GetStatus
3.6.7. Spi_GetJobResult
Prototype
Spi_JobResultType Spi_GetJobResult ( Spi_JobType Job )
Parameter
Job ID of the job.
Return code
Spi_JobResultType Result of the job operation.
3.6.8. Spi_GetSequenceResult
Prototype
Spi_SeqResultType Spi_GetSequenceResult ( Spi_SequenceType Seq )
Parameter
Seq ID of the sequence.
Return code
Result of the sequence operation.
SPI_SEQ_OK sequence is idle or has finished.
Spi_SeqResultType
SPI_SEQ_PENDING sequence is waiting for being serviced.
SPI_SEQ_FAILED sequence aborted due to an error.
SPI_SEQ_CANCELLED sequence cancelled by user.
Functional Description
Returns the current sequence status.
If development error detection is activated, the function performs these checks:
Check if the sequence ID is valid.
Check if the driver is initialized.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is always available.
3.6.9. Spi_GetVersionInfo
Prototype
void Spi_GetVersionInfo ( Std_VersionInfoType * VersioninfoPtr )
Parameter
VersioninfoPtr Pointer to version information.
Return code
void --
Functional Description
Returns the version information of the driver.
If development error detection is activated, the function performs these checks:
Check if the pointer is valid – no NULL_PTR.
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is synchronous.
This function is reentrant.
This function is configurable.
Expected Caller Context
Expected to be called in application context, during operational phase.
Table 3-66 Spi_GetVersionInfo
3.6.10. Spi_GetHWUnitStatus
Prototype
Spi_StatusType Spi_GetHWUnitStatus ( Spi_HWUnitType HWUnit )
Parameter
HWUnit Hardware unit ID.
Return code
Status of the hardware driver.
Spi_StatusType SPI_UNINIT Driver is not initialized
SPI_IDLE Driver is idle
SPI_BUSY Driver is processing data.
Functional Description
Returns the status of the Spi hardware.
If development error detection is activated, the function performs these checks:
3.6.11. Spi_Cancel
Prototype
void Spi_Cancel ( Spi_SequenceType Sequence )
Parameter
Sequence The transmission and reception for this Sequence ID shall be canceled.
Return code
void --
Functional Description
Cancels an actual ongoing sequence. If a job processing is ongoing, the job is finished and the sequence
is aborted. The user will get a notification (if configured) after the job has finished.
If development error detection is activated, the function performs these checks:
Checks if the driver has been initialized or is busy.
Checks if the sequence parameter is correct
If a check is successful, the function executes the request. If one of the checks fails, an error is reported
to the DET component.
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is configurable.
Expected Caller Context
Expected to be called in application context, during operational phase.
Table 3-88 Spi_Cancel
3.6.12. Spi_EnableLoopbackMode
Prototype
Std_ReturnType Spi_EnableLoopbackMode(Spi_HWUnitType HWUnit,Spi_LoopbackModeType
LBMode)
Parameter
Spi_HWUnitType HW Unit to check (Range 0-4)
3.6.13. Spi_DisableLoopbackMode
Prototype
Std_ReturnType Spi_DisableLoopbackMode(Spi_HWUnitType)
Parameter
Spi_HWUnitType HW Unit to check (Range 0-4)
Return code
E_OK, request accepted.
Std_ReturnType
E_NOT_OK, request rejected.
Functional Description
Function to disable Loopback mode for SPI module test purposes
Particularities and Limitations
This function is synchronous.
This function is non reentrant.
This function is configurable.
Expected Caller Context
Expected to be called in application context for diagnostic use only.
Table 3-20 Spi_DisableLoopbackMode
3.6.14. Spi_RegisterReadback
Prototype
Std_ReturnType Spi_RegisterReadback(Spi_RegisterReadbackType RegisterReadbackPtr,
Spi_HWUnitType HWUnit)
Parameter
Spi_RegisterReadbackType Pointer to structure
Component API
DET DET_ReportError
DEM DEM_ReportErrorStatus
Table 3-22 Services used by Spi
3.9.1.1. Spi_JobEndNotification
Prototype
void ( *Spi_JobEndNotification ) ( void )
Parameter
Void --
Return code
void --
Functional Description
Job end notification function. Can be configured in the configuration tool.
Particularities and Limitations
No Limitations
Expected Caller Context
The job notification will be called from interrupt context.
Table 3-23 Spi_JobEndNotification
3.9.1.2. Spi_SequenceEndNotification
Prototype
void ( *Spi_SequenceEndNotification) ( void )
Parameter
Void --
Return code
void --
Functional Description
Sequence end notification function. Can be configured in the configuration tool.
Particularities and Limitations
No Limitations
Expected Caller Context
The sequence notification will be called from interrupt context
Table 3-24 Spi_SequenceEndNotification
4. Configuration
The module Spi can easily be configured using the EB TRESOS configuration tool. The outputs of the
configuration and generation process are the configuration source files. This chapter describes the
graphical elements of the view of the Spi, to help you to pre-estimate the results of the configuration.
MIBSPI3 CSIB2
SPI4 CSIB3
MIBSPI5 CSIB4
SpiShiftClockIdleLevel Enum High This parameter defines the SPI shift
Low clock idle level.
SpiTimeClk2Cs Float 1E-5 Set the timing between last clock
0-0.0001sec signal and CS back to idle. Unit is in
nanoseconds. A value of zero
disables this feature.
SpiTimeCs2Clk Float 1E-5 Chip-select-active-to-transmit-
0-0.0001sec start-delay.
SpiCsMode Enum CONTINUOUS, At the end of a frame transfer the
SINGLE chip select stays active. If SINGLE is
selected, the CS will go idle. A
frame is the smallest data unit on
the Spi bus.
SpiCsIdleTime Float 1E-4 Active if CS select mode is
0-0.0001sec “SINGLE”. This is the duration the
CS signal will go idle. If 0 is selected
the duration is at last 2xVBUS clock.
The VBUS clock can be obtained
from “Resulting clock for Spi in
MHz”
Table 4-1 Spi external device configuration
5.2. Limitations
SPI Sync is implemented in polling mode only.
SPI Async is implemented in Interrupt mode only.
External Buffers only
MIBSPI1, MIBSPI3 and MIBSPI5 hardware units use mutibuffered mode only
SPI2 and SPI4 hardware units use DMA mode only
Sequences not interruptible
5.2.1. Runtimes
The Spi driver provides only one runtime (runtime means only one post-build configuration).
5.2.2. Configuration
1) Sequence must contain Jobs that containing same Hardware unit.
2) Channel / Job / Sequence ID must be same as Index of that particular Channel / Job / Sequence
ID.
3) Only SPI2 and SPI4 support DMA.
4) SPI2 and SPI4 cannot be used in Parallel.
5) SPI1, SPI3 and SPI 5 units use Multi-Buffered mode only
6. General Recommendations
Use of MPU (Memory Protection Unit) is highly advised at the OS level
Code generated using AUTOSAR Configuration Tool shall not be altered manually
Use of Watchdog Timer and Reset cause monitoring is highly advised