AUTOSAR SPI DRIVER USER GUIDE - Texas Instruments

AUTOSAR SPI Handler DriverUser GuideVersion 1.3Nov 30, 2016Copyright Texas Instruments IncorporatedThe information and/or drawings set forth in this document and all rights in and to inventions disclosedherein 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. Nodisclosure of information or drawings shall be made to any other person or organization without theprior consent of Texas Instruments.Texas Instruments Proprietary Information

AUTOSAR SPI DRIVER USER GUIDETable of Contents1.Introduction . 51.1.2.Architecture Overview . 5Functional Description . 82.1.Features . 8Table 2-2 Not Supported SWS features . 82.2.Initialization. 82.3.States. 82.4.Error Handling . 92.4.1.Development Error Reporting . 92.4.2.Production Code Error Reporting . 112.5.2.5.1.Static Files . 112.5.2.Dynamic Files . 122.6.Include Structure. 132.7.Compiler Abstraction and Memory Mapping . 132.8.Dependencies on SW modules . 152.8.1.OSEK/AUTOSAR OS (Optional) . 152.8.2.DET . 152.8.3.DEM . 152.8.4.MCU . 152.8.5.PORT . 152.8.6.SchM (Optional) . 152.9.3.Scope of Delivery . 11Dependencies on HW modules . 15API Description . 163.1.Interfaces Overview . 163.2.Imported Type Definitions . 16Table 3-1 Imported Type definitions. 163.3.Exported Type Definitions. 163.4.Exported Objects. 183.5.Interrupt Service Routines provided by Spi . 183.5.1.Spi error interrupt service . 19Texas Instruments Proprietary – Strictly PrivatePage 2

AUTOSAR SPI DRIVER USER GUIDE3.5.2.Spi data exchange interrupt service. 193.5.3.DMA block transfer end interrupt . 193.6.API services provided by Spi . 203.6.1.Spi Init . 203.6.2.Spi DeInit . 203.6.3.Spi SyncTransmit . 213.6.4.Spi AsyncTransmit . 223.6.5.Spi SetupEB . 223.6.6.Spi GetStatus . 233.6.7.Spi GetJobResult . 233.6.8.Spi GetSequenceResult . 243.6.9.Spi GetVersionInfo . 253.6.10.Spi GetHWUnitStatus . 253.6.11.Spi Cancel . 263.6.12.Spi EnableLoopbackMode . 263.6.13.Spi DisableLoopbackMode . 273.6.14.Spi RegisterReadback . 273.7.Services used by Spi . 283.8.Callback Functions. 283.9.Configurable Interfaces . 283.9.1.4.Configuration . 304.1.5.Notifications . 28Configuration of the Spi driver. 304.1.1.Spi configuration . 304.1.2.Spi general settings . 35AUTOSAR Standard Compliance . 365.1.Additions/ Extensions . 365.1.1.5.2.Request queuing . 36Limitations. 365.2.1.Runtimes . 365.2.2.Configuration . 36Texas Instruments Proprietary – Strictly PrivatePage 3

AUTOSAR SPI DRIVER USER GUIDE6.General Recommendations . 37Texas Instruments Proprietary – Strictly PrivatePage 4

AUTOSAR SPI DRIVER USER GUIDE1. IntroductionThis document describes the functionality, API and configuration of the AUTOSAR BSW module SPI.Supported AUTOSAR ReleaseSupported Configuration VariantsVendor IDModule IDRelease version4.03Post-buildSPI VENDOR IDSPI MODULE ID02.22.004483This document describes the functionalities, the configuration and the API of the SPI driver for themicrocontroller Family TMS570LSx from Texas Instruments.The Spi driver provides services for basic communication with external components. These componentscan 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.)1.1.Architecture OverviewThe following figure shows where the Spi is located in the AUTOSAR architecture.Texas Instruments Proprietary – Strictly PrivatePage 5

AUTOSAR SPI DRIVER USER GUIDEpkg MCALECUAL(from SoftwarePackages)MCALMcDriv ersMemDriv ersComDriv ersIoDriv ers Gpt Eep Ttcan Ocu Wdg Fls Spi Icu Mcu FlsTst Lin Pwm RamTst Can Adc Fr Dio Port(from SoftwarePackages)Hardw are(from External Elements)Figure 1-1 AUTOSAR ArchitectureBelow figure shows the interfaces to adjacent modules of the Spi.Texas Instruments Proprietary – Strictly PrivatePage 6

AUTOSAR SPI DRIVER USER GUIDEFigure 1-2 Interfaces to adjacent modules of the SpiTexas Instruments Proprietary – Strictly PrivatePage 7

AUTOSAR SPI DRIVER USER GUIDE2. Functional Description2.1.FeaturesThe "supported" and "not supported" features are presented in the following two tables. For furtherinformation of not supported features also see chapter 5.Supported FeaturesConfigure Spi with External devices Channels Jobs SequencesConfigure physical units and callback functionsConfigure 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 framesSelect simple or extended APIInterruptible SequencesTable 2-1 Supported SWS featuresNot Supported Features32bit clock frames are not supported in DMA modeDMA mode supported only on SPI2 and SPI4 instancesSynchronous modeInternal buffers not supportedTable 2-2 Not Supported SWS features2.2.InitializationThe driver Spi is initialized by calling Spi Init() with a pointer to a configuration as parameter. Tore-initialize call Spi DeInit() and then Spi Init() again with a different configuration. Theservice for de-initialization is provided with the function Spi DeInit().2.3.StatesThe Spi maintains states for: The Spi driver itself, the configured jobs, the configured sequencesTexas Instruments Proprietary – Strictly PrivatePage 8

AUTOSAR SPI DRIVER USER GUIDE and Hardware units.These states can be obtained by the: Spi GetStatus, Spi GetJobResult, Spi GetSequenceResult, Spi GetHWUnitStatus functions, so the user knows the ongoing action of the driver during atransmission.2.4.Error Handling2.4.1. Development Error ReportingBy default, development errors are reported to the DET using the service DET ReportError() ifdevelopment error reporting is enabled (i.e. pre-compile parameter SPI DEV ERROR DETECT STD ON). If another module is used for development error reporting, the function prototype forreporting the error can be configured by the integrator, but must have the same signature as the serviceDET ReportError(). The reported service IDs identify the services which are described in 3.8. Thefollowing table presents the service IDs and the related services:Service IDSPI SID INIT 0x00ServiceSpi InitSPI SID DEINIT 0x01Spi DeInitSPI SID WRITE IB 0x02Spi WriteIBSPI SID ASYNC TRANSMIT 0x03Spi AsyncTransmitSPI SID READ IB 0x04Spi ReadIBSPI SID SETUP EB 0x05Spi SetupEBSPI SID GET STATUS 0x06Spi GetStatusSPI SID GET JOB RESULT 0x07Spi GetJobResultSPI SID GET SEQ RESULT 0x08Spi GetSequenceResultSPI SID GETVERSION INFO 0x09Spi GetVersionInfoSPI SID SYNC TRANSMIT 0x0ASpi SyncTransmitSPI SID GET UNIT STATUS 0x0BSpi GetHWUnitStatusSPI SID CANCEL 0x0CSpi CancelSPI SID SET ASYNC MODE 0x0DSpi SetAsyncModeSPI SID MAINFUNCTION HANDLING 0x10Spi MainFunction HandlingTable 2-3 Mapping of service IDs to servicesThe errors reported to DET are described in the following table:Error Code[0x0A] SPI E PARAM CHANNELDescriptionchannel out of bounds, exceeds the maximum number ofTexas Instruments Proprietary – Strictly PrivatePage 9

AUTOSAR SPI DRIVER USER GUIDEconfigured channels[0x0B]SPI E PARAM JOBJob out of bounds, exceeds the maximum nuber of configuredjobs[0x0C]SPI E PARAM SEQSequence out of bounds, exceeds the maximum number ofconfigured sequences[0x0D] SPI E PARAM LENGTHLength out of bounds, exceeds the maximum number ofconfigured EB- or IB- buffer length[0x0E]SPI E PARAM UNITThe requested hardware unit does not exist[0x10]SPI E PARAM POINTERAn invalid configuration has been passed (i.e. a NULL PTR). Thisis an extension to AUTOSAR.[0x1A] SPI E UNINITA service was requested, but the driver has not been initialized[0x2A] SPI E SEQ PENDINGThe requested sequence is still pending[0x3A] SPI E SEQ IN PROCESSTransmission of synchronous sequence in progress (notsupported)[0x4A] SPI E ALREADY INITIALIZED The driver is already initialized.Table 2-4 Error Reported to DET Texas Instruments Proprietary – Strictly Private SPI E SEQ IN PROCESSSPI E SEQ PENDINGSPI E UNINITSPI E PARAM POINTERSPI E PARAM UNITSPI E PARAM LENGTHSPI E PARAM SEQSPI E PARAM JOBServicesSpi InitSpi DeInitSpi AsyncTransmitSpi SetupEBSpi GetStatusSpi GetJobResultSpi GetSequenceResultSPI E PARAM CHANNELCheckSPI E ALREADY INITIALIZED2.4.1.1. Parameter CheckingAUTOSAR requires that API functions check the validity of their parameters. The checks in Table 3-5Development Error Reporting: Assignment of checks to services are internal parameter checks of the APIfunctions. These checks are for development error reporting and can be en-/disabled separately. Theconfiguration of en-/disabling the checks is described in chapter 6.1. En-/disabling of single checks is anaddition to the AUTOSAR standard which requires to en-/disable the complete parameter checking viathe parameter SPI DEV ERROR DETECT. The following table shows which parameter checks areperformed on which services: Page 10

AUTOSAR SPI DRIVER USER GUIDESpi GetVersionInfoSpi GetHWUnitStatusSpi Cancel Table 2-5 Development Error Reporting: Assignment of checks to services2.4.2. Production Code Error ReportingBy default, production code related errors are reported to the DEM using the serviceDEM ReportErrorStatus().The errors reported to DEM are described in the following table:Error CodeAssigned SPI E BIT ERRORby DEMDescriptionA bit error was detected.Assigned SPI E DESYNC ERRORby DEMSlave desynchronized.Assigned SPI E DLEN ERRORby DEMData length mismatch detected during transmission.Assigned SPI E TXSTALL ERRORby DEMThis error occurs if the driver tries to write data which has notbeen transmitted yet.Assigned SPI E RXSTALL ERRORby DEMThe driver tries to read data, but no data has been provided bythe hardware.Assigned SPI E DOVR ERRORby DEMThe hardware reported an internal receive buffer overrunAssigned SPI E TO ERRORby DEMThe hardware reported an Timeout error because of nonactivation of ENA pin.Table 2-6 Errors reported to DEM2.5.Scope of DeliveryThe delivery of the Spi contains the files which are described below:2.5.1. Static FilesFile NameSpi.cDescriptionMain Spi file, contains the API for the external visible servicesSpi.hContains the type and function declarations for the Spi driverSpi Hw.cThis layer handles the execution of jobs and sequencesSpi Hw.hContains the type and function declarations for the Spi Hw moduleSpi Dlc.cDriver layer, handles channels and all hardware related tasksSpi Dlc.hContains the type and function declarations for the Spi Dlc module. Alsocontains the register definitions.Spi Irq.cSource file that contain the ISR’sSpi Irq.hHeader file that contains the declaration of the ISR’sTexas Instruments Proprietary – Strictly PrivatePage 11

AUTOSAR SPI DRIVER USER GUIDEplugin.xmlXML file used to register resources with EB Tresos Studio.MANIFEST.MFManifestSpi.xdmContains the formal notation of all information, which belongs to the Spi driver.Spi Rec.xdmContains values to a recommended default configuration of the Spi.Table 2-7 Static files2.5.2. Dynamic FilesThe dynamic files are generated by the configuration toolFile NameSpi Cfg.hDescriptionPre-compile parameters are generated into this file.Spi PBcfg.cPost-build configuration parameters are generated into this file.Table 2-8 Dynamic filesTexas Instruments Proprietary – Strictly PrivatePage 12

AUTOSAR SPI DRIVER USER GUIDE2.6.Include StructureFigure 2-1 AUTOSAR Architecture2.7.Compiler Abstraction and Memory MappingAlthough the Compiler Abstraction is implemented in the sources, there is no compiler specific keywordthat could be assigned to the Compiler Abstraction definitions mentioned above. The TMS570 platform'sTexas Instruments Proprietary – Strictly PrivatePage 13