MCUSW
Spi User Guide

Introduction

This document details AUTOSAR BSW SPI module implementation

  • Supported AUTOSAR Release : 4.3.1
  • Supported Configuration Variants : Post-build, Link-time, Pre-Compile
  • Vendor ID : SPI_VENDOR_ID (44)
  • Module ID : SPI_MODULE_ID (83)

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 driver are:

  • Handle the SPI hardware units onboard – MCSPI
  • Handle data transmission to the components connected via SPI
  • Take care of the settings required by external components (baud rate etc.
  • DMA support has also been added to SPI module for Jacinto Family of Devices. PDK UDMA driver is a dependency for usage.

Spi Driver Architecture/Design

Please refer the SPI design Document provided as part of CSP.

Functional Description

The The Multi-channel Serial Peripheral Interface (MCSPI) is a master/slave synchronous serial bus. It allows a master device to initiate serial data transfers to a slave device.

Programming of clock source for the MCSPI, is beyond the scope of this document. The driver expects user of this module has programmed required clock source.

Back To Top

Spi Instance ID mapping and ISR mapping

Please refer to the SOC User Manual for detail.

Back To Top

Configuration

The Spi Driver implementation supports multiple configuration variants (refer section Introduction), the driver expects generated Spi_Cfg.h to be present as (File Structure). Please refer (Build) to specify path to generated configuration. The associated MCSPI configuration generated files Spi_Cfg.c, Spi_Lcfg.c and Spi_PBcfg.c to be present as show (File Structure)

NOTE: Always use configurator tool for MCAL configuration generation.

The following section details on the un-supported features and additional features added.

Variance / Deviation from the specification

SpiBaudrate

This parameter is the communication baudrate which allows using a range of values, from the point of view of configuration tools, from Hz up to MHz.This is achieved using modulespecific parameter SpiExtDeviceClockDivider

SpiTimeClk2Cs

This parameter is the timing between clock and chip select (in seconds) This parameter allows to use a range of values from 0 up to 0.0001 seconds. Range specified by AUTOSAR specification is not supported by SPI hardware. TI specific SpiCsIdleTime parameter is used instead of this.

Implementation Specific Configurations

This driver implementation introduces below listed configurable options

Please refer the SPI design section NON Standard configurable parameters (Refer to Design Document provided in CSP).

Implementation Specific Configuration Constraint

This driver implementation introduces configurable constraint as mentioned below.

  • Please define all the SPI instances defined in SpiHwUnitType.

Sitara SMPU Family

  • Hw Unit Id 0 always corresponds to SPI_UNIT_MCU_MCSPI0 and SPI_UNIT_MCU_MCSPI1 corresponds to 1.
  • Similarly, Hw Unit Ids 2, 3 and 4 correspond to SPI_UNIT_MCSPI0, SPI_UNIT_MCSPI1 and SPI_UNIT_MCSPI2 respectively.
SOc Hw Unit Id SpiHwUnitType
AM62X/AM62AX/AM62PX 0 SPI_UNIT_MCU_MCSPI0
AM62X/AM62AX/AM62PX 1 SPI_UNIT_MCU_MCSPI1
AM62X 2 SPI_UNIT_MCSPI0
AM62X 3 SPI_UNIT_MCSPI1
AM62X 4 SPI_UNIT_MCSPI2
  • The loopback configuration is based only on the pinmux configuration from user. There is no API to disable it.

Back To Top

Non Standard Service APIs

Spi_RegisterReadback

As noted from the previous MCAL implementation, some of the critical configuration registers could potentially be corrupted by other entities (s/w or h/w). One of the recommended detection methods would be to periodically read-back the configuration and confirm configuration is consistent. The service API defined below shall be implemented to enable this detection

Description Comments
Service Name Spi_RegisterReadback Can potentially be turned OFF (Refer to Design Document provided in CSP)
Syntax uint32 Spi_RegisterReadback ( Spi_HWUnitType HWUnit, P2VAR(Spi_RegisterReadbackType, AUTOMATIC, SPI_APPL_DATA) RegRbPtr) E_OK: Register read back has been done, E_NOT_OK: Register read back failed
Service ID NA
Sync / Async Sync
Reentrancy Reentrant
Parameter in HWUnit SPI Hardware microcontroller peripheral unit ID. If this is invalid, then the API will return E_NOT_OK.
Parameters out RegRbPtr - Pointer to where to store the readback values. If this pointer is NULL_PTR, then the API will return E_NOT_OK.
Return Value Std_ReturnType E_OK, E_NOT_OK

Spi_SetLoopbackMode

This function enables or disables the internal loopback mode of SPI. Note: Only McSPI HW units supports this feature. This API should be called after Spi_Init is called. Otherwise this API will return E_NOT_OK. Also this API should not be called when the HW unit is busy. This API could be used to check the integrity of the SPI module. When the loopback mode is enabled, the data transferred is received back and hence the caller can verify and compare the TX buffer with RX buffer for any HW failures.

Description Comments
Service Name Spi_SetLoopbackMode Can potentially be turned OFF (Refer to Design Document provided in CSP)
Syntax uint32 Spi_SetLoopbackMode ( Spi_HWUnitType HWUnit, boolean LpbkEnable)
Service ID NA
Sync / Async ASync
Reentrancy Reentrant
Parameter in HWUnit SPI Hardware microcontroller peripheral unit ID. If this is invalid, then the API will return E_NOT_OK.
Parameters in LpbkEnable - Loopback enable/disable, TRUE - Enable loopback, FALSE - Disable loopback
Return Value Std_ReturnType E_OK : Loopback enable successfully E_NOT_OK : Loopback enable failed

Back To Top

Interrupt Configuration

The Driver doesn’t register any interrupt service routine(ISR), it’s expected that consumer of this driver registers the required interrupt handler.

For every Spi instance an ISR needs to be registered. The Interrupt number associated with instance of the Spi is detailed in TRM. Please refer SpiApp_InterruptConfig () in Spi demo application.

Some of the spi interrupts are not routed/mapped to this core, these interrupts would require additional programming to route these to this core. Please refer SpiApp_InterruptConfig () in Spi demo application.

Jacinto: Dedicated interrupt lines are available from DMA after event completion to the R5 core (80-90 for MCU1_0) and (229 to 247 for MCU2_1). For Details of interrupt numbers, please refer below: 

"mcusw\mcal_drv\mcal\examples_config\Spi_Demo_Cfg\output\generated\soc\<SoC>\<CORE>\src\Spi_PBcfg.c"

Refer section (Spi Instance ID mapping and ISR mapping), for association between channel ID and ISR

Back To Top

Power-up

The driver doesn't configure the functional clock and power for the spi modules. It's expected that secondary boot loader(SBL) power-up the required modules. Please refer SBL documentation.

Back To Top

Build and Running the Application

Please follow steps detailed in section (Build) to build library or example

Back To Top

Steps to run example application

Please follow steps detailed in section (Build) to build example

Back To Top

Memory Mapping

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file at (Examples Linker File (Select memory location to hold example binary)) defines separate section for these objects. When the driver is integrated, its expected that these sections are created and placed in appropriate memory locations. (Locations of these objects depend on the system design and performance needs)

Section SPI_CODE SPI_VAR SPI_VAR_NOINIT SPI_CONST SPI_CONFIG
SPI_START_SEC_VAR_INIT_UNSPECIFIED (.data) USED
SPI_DATA_INIT_32_SECTION USED
SPI_TEXT_SECTION USED
SPI_DATA_NO_INIT_UNSPECIFIED_SECTION USED
SPI_CONST_32_SECTION USED
SPI_ISR_TEXT_SECTION USED
SPI_CONFIG_SECTION USED

Back To Top

Cache

This driver implementation has been validated with cache enabled. For optimal performance it’s recommended to place (Memory Mapping) sections in cache enabled memory area.

Back To Top

Dependencies on SW Modules

DET

This implementation depends on the DET in order to report development errors and can be turned OFF. Refer section (Development Error Reporting) for detailed error codes.

Back To Top

SchM

This implementation requires one level of exclusive access to guard critical sections. Invokes SchM_Enter_Spi_SPI_EXCLUSIVE_AREA_0 (), SchM_Exit_Spi_SPI_EXCLUSIVE_AREA_0 () to enter critical section and exit.

In the example implementation (File Structure SchM_Spi.c) , all the interrupts on CPU are disabled. However, disabling of the enabled Spi interrupt should suffice.

Back To Top

File Structure

spi_design_dir_structure.png
Detailed Directory Structure
  1. Driver implemented by : Spi.h, Spi_Irq.h, Spi.c, Spi_Priv.c,Spi_Mcspi.c Spi_Irq.c and Spi_Priv.h
  2. Example Configuration by : Spi_Cfg.h, Spi_Cfg.c,Spi_Lcfg.c and Spi_PBcfg.c
  3. Example Application by : McspiApp.c and McspiApp.h

Back To Top

Error Handling

Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface (Spi.h File Structure) lists the SID

Back To Top

Error codes

Type of Error Related Error code Value (Hex)
Channel out of bounds, exceeds the maximum number of configured channels SPI_E_PARAM_CHANNEL 0x0A
Job out of bounds, exceeds the maximum number of configured jobs SPI_E_PARAM_JOB 0x0B
Sequence out of bounds, exceeds the maximum number of configured sequences SPI_E_PARAM_SEQ 0x0C
Length out of bounds, exceeds the maximum number of configured EB- or IB- buffer length SPI_E_PARAM_LENGTH 0x0D
The requested hardware unit does not exist SPI_E_PARAM_UNIT 0x0E
An invalid configuration has been passed (i.e. a NULL_PTR). This is an extension to AUTOSAR. SPI_E_PARAM_POINTER 0x10
A service was requested, but the driver has not been initialized SPI_E_UNINIT 0x1A
The requested sequence is still pending SPI_E_SEQ_PENDING 0x2A
Transmission of synchronous sequence in progress (not supported) SPI_E_SEQ_IN_PROCESS 0x3A
The driver is already initialized. SPI_E_ALREADY_INITIALIZED 0x4A

Back To Top

Production Code Error Reporting

Production error are reported to DEM via the service DEM_ReportErrorStatus(). In addition to standard errors, this implementation reports "SPI_E_HARDWARE_ERROR" when SPI Timer register hardware reset fails.

Back To Top

API Description

The AUTOSAR BSW Spi Driver specification details the APIs required for Spi Driver. Please refer to (Refer to Design Document provided in CSP) for detailed API description. Also refer to (Non Standard Service APIs) for non-standard APIs which are included in this implemented.

Refer API Documentation for details Back To Top

Example Application

The example application demonstrate use of Spi module, the list below identifies key steps performed the example. The configuration file is present at (File Structure)

Sitara MPU:

AM62X

MCSPI example app is ported and tested with MCU_MCSPI0, MCU_MCSPI1, MCSPI0, MCSPI1, MCSPI2 instances on MCU0_0.

Please note that Multiple MCSPI Instances configuration is not tested.

AM62AX

Either interrupt/polling or DMA mode is supported per MCSPI instance for each configuration.Both modes are not supported simultaneously. Note: Spi_SetAsyncMode API should be bypassed in application is DMA mode if enabled. 

MCSPI example app is ported and tested with both MCU_MCSPI0 and MCU_MCSPI1 instances on MCU0_0.

AM62PX

MCSPI example app is ported and tested with both MCU_MCSPI0 and MCU_MCSPI1 instances on MCU0_0.

Either interrupt/polling or DMA mode is supported per MCSPI instance for each configuration.Both modes are not supported simultaneously. Note: Spi_SetAsyncMode API should be bypassed in application is DMA mode if enabled.

  • Initializes “Result Status Flag”
  • SpiApp_Startup ()
    • Builds interrupt list and registers ISR for enabled Spi instances
    • Pinmux configuration required for internal loopback testing mode
  • SpiApp_PowerAndClkSrc ()
    • Dummy function for now.
  • Core application ()
    • For each enabled instance
      • Initialize Spi hardware
      • Enable loopback mode
      • Prints module version info
      • Set Async/Sync mode
      • Set Up and Initialize Tx and Rx Buffers
      • Start Sequence transmission
      • Wait for transmission completion
      • Get Sequence result
      • Compare Tx and Rx Buffers
      • De-Initialize Spi hardware
  • Checks for error status, stack corruption and prints result

Back To Top

Example Log

    SPI_APP: Sample Application - STARTS !!!

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

    SPI_APP: CH 1: JOBS 1: SEQ 1: HWUNIT 1: NUM OF WORDS 10000:!!!
    SPI_APP: Variant - Post Build being used !!!
    SPI_APP: SPI Async transmit in progress!!
    SPI_APP: SPI Stack Usage: 792 bytes
    SPI_APP: SPI Loopback Test Passed!!!

Back To Top

References

Back To Top