AUTOSAR-like SPI Driver

From ErikaWiki

Revision as of 16:25, 17 July 2013 by Giuseppe Serano (Talk | contribs)
Jump to: navigation, search

Contents

Synopsis

The SPI handler/driver provides the functionality and API for a monolithic SPI [Serial Peripheral Interface] handler/driver. This software module includes handling and driving functionalities. Main objectives of this monolithic SPI Handler/Driver are to take the best of each microcontroller features and to allow implementation optimization depending on static configuration to fit as much as possible to ECU needs.

Hence, this specification defines selectable levels of functionalities and configurable features to allow the design of a high scalable module that exploits the peculiarities of the microcontroller.

The SPI handler/driver is part of the microcontroller abstraction layer (MCAL). It provides services for reading from and writing to devices connected via SPI busses. It also provides the required mechanism to configure the onchip SPI peripheral.

The SPI has a 4-wire synchronous serial interface. SPI Communication is enabled with a chip select wire (CS). SPI Communication is performed with a 3-wire interface consisting of wires for serial data Master-Output-Slave-Input (MOSI), serial data Master-Input-Slave-Output (MISO) and serial clock (CLK).

SPI peripherals may depend on the system clock, prescaler(s) and PLL. Thus, changes of the system clock (e.g. PLL on -> PLL off) may also affect the clock settings of the SPI hardware.

The SPI Handler/Driver module does not take care of setting the registers which configure the clock, prescaler(s) and PLL in its init function. This has to be done by the MCU module.

Depending on microcontrollers, the SPI peripheral could share registers with other peripherals. In this typical case, the SPI Handler/Driver has a relationship with MCU module for initialising and de-initialising those registers.

The general behaviour of the SPI Handler/Driver can be asynchronous or synchronous according to the Level of Functionality selected.

Overall view of functionalities and features

There are 3 Levels of Scalable Functionality for the SPI Handler/Driver:

  • LEVEL 0, Simple Synchronous SPI Handler/Driver: the communication is based on synchronous handling with a FIFO policy to handle multiple accesses. Buffer usage is configurable to optimize and/or to take advantage of HW capabilities.
  • LEVEL 1, Basic Asynchronous SPI Handler/Driver: the communication is based on asynchronous behavior and with a Priority policy to handle multiple accesses. Buffer usage is configurable as for “Simple Synchronous” level.
  • LEVEL 2, Enhanced (Synchronous/Asynchronous) SPI Handler/Driver: the communication is based on asynchronous behavior or synchronous handling, using either interrupts or polling mechanism selectable during execution time and with a Priority policy to handle multiple accesses. Buffer usage is configurable as for other levels.

SPI Scalability.png

The SPI Handler/Driver’s level of scalable functionality shall always be statically configurable, i.e. configured at pre-compile time to allow the best source code optimisation.

To improve the scalability, each level has optional features which are configurable (ON/OFF) or selectable.

General behaviour

This section, on the one hand, introduces common behaviour and configuration for all levels. On the other, it specifies the behaviour of each level and also the allowed optional features.

The SPI Handler/Driver interface configuration shall be based on Channels, Jobs and Sequences as defined in this document.

A Channel is a software exchange medium for data that are defined with the same criteria: Configuration Parameters, Number of Data elements with same size and data pointers (Source & Destination) or location.

A Job is composed of one or several Channels with the same Chip Select (is not released during the processing of Job). A Job is considered atomic and therefore cannot be interrupted by another Job. A Job has an assigned priority.

A Sequence is a number of consecutive Jobs but it can be rescheduled between Jobs using a priority mechanism. A Sequence communication is interruptible (by another Sequence communication) or not depending on a static configuration.

The SPI Handler/Driver shall support one or more Channels, Jobs and Sequences to drive all kind of SPI compatible HW devices.

SPI communication shall be done according to Channels, Jobs and Sequences configuration parameters.

The Chip Select (CS) is attached to the Job definition.

Chip Select shall be handled during Job and shall be released at the end of it. This Chip Select handling shall be done according to the Job configuration parameters.

It shall be possible to define if the Chip Select handling is managed autonomously by the HW peripheral, without explicit chip select control by the driver, or the SPI driver shall drive the chip select lines explicitly as DIO.

Example of CS handling: Set the CS active at the beginning of Job; maintain it until the end of all Channels belonging to this Job afterwards set the CS inactive.

If Chip Selects are done using microcontroller pins the SPI Handler/Driver has a relationship with PORT module. In this case, this specification assumes that these microcontroller pins are directly accessed by the SPI Handler/Driver module without using APIs of DIO module. Anyhow, the SPI depends on ECU hardware design and for that reason it may depend on other modules.

A Channel is defined one time but it could belong to several Jobs according to the user needs and this software specification.

A Job shall contain at least one Channel.

Each Channel shall have an associated index which is used for specifying the order of the Channel within the Job.

If a Job contains more than one Channel, all Channels contained have the same Job properties during communication and shall be linked together statically.

A Job is defined one time but it could belong to several Sequences according to the user needs and this software specification.

A Sequence shall contain at least one Job.

If it contains more than one, all Jobs contained have the same Sequence properties during communication and shall be linked together statically.

A Channel used for a communication should have its parameters configured but it is allowed to pass NULL pointers as source and destination pointers to generate a dummy communication.

Channel data may differ from the hardware handled and user (client application) given. On the client side the data is handled in 8, 16 or 32bits mode. On the microcontroller side, the hardware may handle between 1 and 32bits or may handle a fixed value (8 or 16bits) and this width is configurable for each Channel.

The SPI Handler/Driver shall take care of the differences between the width of channel data handled by the user and those handled by the hardware.

If width of channel data handled by the user 8/16/32 bits and handled by the hardware 8/16/32 bits means the SPI Handler/Driver can send and receive data without any bit changes straightforward.

If width of channel data handled by the hardware is superior to data width handled by the user, means that communication through the SPI Handler/Driver shall send the lower part, ignoring the upper part. Receive the lower part, extended with zero.

If width of channel data handled by the hardware inferior to data width handled by the user means the communication through the SPI Handler/Driver shall be according to the memory alignment separate the data as two part and send and receive one by one.

This ensures that the user always gets the same interface.

SPI Sequences Jobs Channels.png

Common configurable feature: Allowed Channel Buffers

In order to allow taking advantages of all microcontroller capabilities but also to allow sending/receiving of data to/from a dedicated memory location, all levels have an optional feature with respect to the location of Channel Buffers.

Hence, two main kinds of channel buffering can be used by configuration:

  • Internally Buffered Channels (IB): The buffer to transmit/receive data is provided by the Handler/Driver.
  • Externally Buffered Channels (EB): The buffer to transmit/receive data is provided by the user (statically and/or dynamically).

Both channel buffering methods may be used depending on the 3 use cases described below:

  • Usage 0: the SPI Handler/Driver manages only Internal Buffers.
  • Usage 1: the SPI Handler/Driver manages only External Buffers.
  • Usage 2: the SPI Handler/Driver manages both buffers types.
Behaviour of IB channels

The intention of Internal Buffer channels is to take advantage of microcontrollers including this feature by hardware. Otherwise, this feature should be simulated by software.

For the IB Channels, the Handler/Driver shall provide the buffering but it is not able to take care of the consistency of the data in the buffer during communication. The size of the Channel buffer is fixed.

The channel data received shall be stored in 1 entry deep internal buffers by channel.

The SPI Handler/Driver shall not take care of the overwriting of these “receive” buffers by another communication on the same channel.

The channel data to be transmitted shall be copied in 1 entry deep internal buffers by channel.

The SPI Handler/Driver is not able to prevent the overwriting of these “transmit” buffers by users during communications.

Behaviour of EB channels

The intention of External Buffer channels is to reuse existing buffers that are located outside. That means the SPI Handler/Driver does not monitor them.

For EB Channels the application shall provide the buffering and shall take care of the consistency of the data in the buffer during communication.

The size of the Channel buffer is either fixed or variable. A maximum size for the Channel buffer shall be defined by the configuration.

The buffer provided by the application for the SPI Handler Driver may have a different size.

Buffering channel usage

The following table provides information about the Channel characteristics:

SPI Buffering Channel Usage Table.png

LEVEL 0, Simple Synchronous behaviour

The intention of this functionality level is to provide a Handler/Driver with a reduced set of services to handle only simple synchronous communications. This is often the case for ECU including simple SPI networks but also for ECU using high speed external devices.

A simple synchronous communication means that the user calling the transfer service is blocked during the ongoing communication.

The LEVEL 0 SPI Handler/Driver shall offer a synchronous transfer service for SPI busses.

For an SPI Handler/Driver operating in LEVEL 0, when there is no ongoing Sequence, the SPI Handler/Driver shall be in the idle state (SPI_IDLE).

This monolithic SPI Handler/Driver is able to handle one to n SPI buses according to the microcontroller used.

Then SPI buses are assigned to Jobs and not to Sequences. Consequently, Jobs, on different SPI buses, could belong to the same Sequence. Therefore:

The LEVEL 0 SPI Handler/Driver shall not allow more than one Sequence at the same time. That means during an ongoing Sequence, all requests to transfer another Sequence shall be rejected.

The LEVEL 0 SPI Handler/Driver behaviour shall include the common feature: Allowed Channel Buffers, which is selected.

If different Jobs (and consequently also Sequences) have common Channels, the SPI Handler/Driver’ environment shall ensure that read and/or write functions are not called during an SPI communication.

Read and write functions can not guarantee the data integrity while Channel is communicating.

LEVEL 1, Basic Asynchronous behavior

The intention of this functionality level is to provide a Handler/Driver with a reduced set of services to handle asynchronous communications only. This is often the case for ECU with functions related to SPI networks having different priorities but also for ECU using low speed external devices.

An asynchronous communication means that the user calling the transef service is not blocked when the communication is ongoing. Furthermore, the user can be notified at the end of communication.

The LEVEL 1 SPI Handler/Driver shall offer an asynchronous transef service for SPI buses.

For an SPI Handler/Driver operating in LEVEL 1, when there is no ongoing Sequence, the SPI Handler/Driver shall be in the idle state (SPI_IDLE).

This Handler/Driver will be used by several software modules which may be independent from each other and also may belong to different layers. Therefore, priorities will be assigned to Jobs in order to figure out specific cases of multiple accesses. These cases usually occur within real time systems based on asynchronous mechanisms.

Jobs have priorities assigned. Jobs linked in a Sequence shall have decreasing priorities. That means the first Job shall have the highest priority of all Jobs within the Sequence.

Priority order of jobs shall be from the lower to the higher value defined, higher value higher priority (from 0, the lower to 3, the higher, limited to 4 priority levels).

With reference to Jobs priorities, this Handler/Driver needs rules to make a decision in these specific cases of multiple accesses.

The SPI Handler/Driver scheduling method shall schedule Jobs in order to send the highest priority Job first.

This monolithic SPI Handler/Driver is able to handle 1 to N SPI busses according to the microcontroller used. But SPI busses are assigned to Jobs and not to Sequences.

Consequently, Jobs on different SPI buses could belong to the same Sequence. Therefore:

The LEVEL 1 SPI Handler/Driver may allow more than one Sequence at the same time. That means during a Sequence, all requests to transfer another Sequence shall be evaluated in order to accept to start a new sequence or to reject it accordingly to the lead Job.

The LEVEL 1 SPI Handler/Driver behaviour shall include the common feature: Allowed Channel Buffers, which is selected, and the configured asynchronous feature: Interruptible Sequences (see below).

When a hardware error is detected, the SPI Handler/Driver shall stop the current Sequence and set the state of the Job to SPI_JOB_FAILED and the state of the Sequence to SPI_SEQ_FAILED.

If Jobs are configured with a specific end notification function, the SPI Handler/Driver shall call this notification function at the end of the Job.

If Sequences are configured with a specific end notification function, the SPI Handler/Driver shall call this notification function at the end of the Sequence.

When a valid notification function pointer is configured, the SPI Handler/Driver shall call this notification function at the end of a Job regardless of the result of the Job being either SPI_JOB_FAILED or SPI_JOB_OK (rational: avoid deadlocks or endless loops).

When a valid notification function pointer is configured, the SPI Handler/Driver shall call this notification function at the end of a Sequence regardless of the result of the Sequence being either SPI_SEQ_FAILED, SPI_SEQ_OK or SPI_SEQ_CANCELLED (rational: avoid deadlocks or endless loops).

Asynchronous configurable feature: Interruptible Sequences

In order to allow taking advantages of asynchronous communication mechanism, LEVEL 1 and LEVEL 2 of this SPI Handler/Driver have an optional feature with respect to suspending the Sequences.

Hence two main kinds of sequences can be used by configuration:

  • Non-Interruptible Sequences, every Sequence started is not suspended by the Handler/Driver until the end of communication.
  • Mixed Sequences, according to its configuration, a Sequence started may be suspended by the Handler/Driver between two of their consecutives Jobs.
Behavior of Non-Interruptible Sequences

The intention of the Non-Interruptible Sequences feature is to provide a simple software module based on a basic asynchronous mechanism, if only non blocking communications should be used.

Interruptible Sequences are not allowed within LEVEL 1 and LEVEL2 of the SPI Handler/Driver when the configuration parameter is switched off (i.e. configured with value “OFF”).

When the SPI Handler/Driver is configured not allowing interruptible Sequences, all Sequences declared are considered as Non-Interruptible Sequences.

When the SPI Handler/Driver is configured not allowing interruptible Sequences their dedicated configuration parameter can be omitted or the FALSE value should be used as default.

The SPI Handler/Driver is not allowed to suspend a Sequence already started in favour of another Sequence.

Behavior of Mixed Sequences

The intention of the Mixed Sequences feature is to provide a software module with specific asynchronous mechanisms, if, for instance, very long Sequences that could or should be suspended by others with higher priority are used.

Interruptible Sequences are allowed within LEVEL 1 and LEVEL 2 of SPI Handler/Driver when the configuration parameter is switched on (i.e. configured with value “ON”).

When the SPI Handler/Driver is configured allowing interruptible Sequences, all Sequences declared shall have their dedicated configuration parameter to identify whether the Sequence can be suspended during communication.

In case of a Sequence configured as Interruptible Sequence, the SPI Handler/Driver is allowed to suspend an already started Sequence in favour of another Sequence with a higher priority Job. That means, at the end of a Job transmission (that belongs to the interruptible sequence) with another Sequence request pending, the SPI Handler/Driver shall perform a rescheduling in order to elect the next Job to transmit.

In case of a Sequence configured as Non-Interruptible Sequence and according to requirement, the SPI Handler/Driver is not allowed to suspend this already started Sequence in favour of another Sequence.

When using Interruptible Sequences, the caller must be aware that if the multiple Sequences access the same Channels, the data for these Channels may be overwritten by the highest priority Job accessing each Channel.

LEVEL 2, Enhanced behaviour

The intention of this functionality level is to provide a Handler/Driver with a complete set of services to handle synchronous and asynchronous communications. This could be the case for ECU with a lot of functions related to SPI networks having different priorities but also for ECU using external devices with different speeds.

Handling asynchronous and synchronous communications means that the microcontroller for which this software module is dedicated has to provide more than one SPI bus In fact, the goal is to support SPI buses using a so-called synchronous driver and to support other SPI buses using a so-called asynchronous driver.

The LEVEL 2 SPI Handler/Driver shall offer a synchronous transfer service for a dedicated SPI bus and it shall also offer an asynchronous transfer service for other SPI buses.

In LEVEL 2 if there is no ongoing Sequence, the SPI Handler/Driver shall be in idle state (SPI_IDLE).

The SPI bus dedicated for synchronous transfers is prearranged. This information shall be published by the supplier of this software module.

This functionality level, based on a mixed usage of synchronous communication on one prearranged SPI bus and asynchronous communication on others, generates restrictions on configuration and usage of Sequences and Jobs.

The so-called synchronous Sequences shall only be composed of Jobs that are associated to the prearranged SPI bus. These Sequences shall be used with synchronous services only.

Jobs associated with the prearranged SPI bus shall not belong to Sequences containing Jobs associated with another SPI bus. In other words, mixed Sequences (synchronous with asynchronous Jobs) shall not be allowed.

Usually, depending on software design, asynchronous end of communication may be detected by polling or interrupt mechanisms. This level of functionality proposes both mechanisms that are selectable during execution time.

The SPI Handler/Driver LEVEL 2 shall implement one polling mechanism mode and one interrupt mechanism mode for SPI busses handled asynchronously.

Both the polling mechanism and interrupt mechanism modes for SPI busses shall be selectable during execution time.

The requirements for LEVEL 0 apply to synchronous behaviour.

The requirements for LEVEL 1 apply to asynchronous behaviour.

Scheduling Advices

For asynchronous levels, LEVEL 1 and LEVEL 2, the SPI Handler/Driver can call end notification functions at the end of a Job and/or Sequence. In a second time, in case of interruptible Sequences (that could be suspended), if another Sequence request is pending, a rescheduling is also done by the SPI Handler/Driver in order to elect the next Job.

For asynchronous levels, LEVEL 1 and LEVEL 2, the SPI Handler/Driver can call end notification functions at the end of a Job.

For asynchronous levels, LEVEL 1 and LEVEL 2, the SPI Handler/Driver can call end notification functions at the end of a Sequence.

For asynchronous levels, LEVEL 1 and LEVEL 2 in case of interruptible Sequences, if another Sequence request is pending, a rescheduling is also done by the SPI Handler/Driver in order to elect the next Job.

In case call end notification function and rescheduling are fully done by software, the order between these shall be first scheduling and then the call of end notification function executed.

In case call end notification function and rescheduling are fully done by hardware, the order could not be configured as required; the order shall be completely documented.

File Structure

API Specification

Imported Types

typedef uint8 Std_ReturnType

 #include "Std_Types.h"

Standard Return Type.

This type can be used as standard API return type which is shared between AUTOSAR-like modules.

The Std_ReturnType shall normally be used with value E_OK or E_NOT_OK. If those return values are not sufficient user specific values can be defined by using the 6 least specific bits.

struct Std_VersionInfoType

 #include "Std_Types.h"

Standard Version Informations Type.

This type shall be used to request the version of a AUTOSAR-like module using the <Module Name>_GetVersionInfo() function.

Field Documentation:

 uint16 Std_VersionInfoType::moduleID

Module Identifier.

 uint8 Std_VersionInfoType::sw_major_version

Software Version Major Number.

 uint8 Std_VersionInfoType::sw_minor_version

Software Version Minor Number.

 uint8 Std_VersionInfoType::sw_patch_version

Software Version Patch Number.

 uint16 Std_VersionInfoType::vendorID

Vendor Identifier.

Types Defintions

Functions Definitions

Usage Examples

Build

To enable AUTOSAR DPI Driver for Texas Instruments Stellaris LM4F232xxxx with ARM KEIL uVision Compiler Toolchain, the following EE_OPT attribute is needed in the OS object of the OSEK/VDX configuration:

 EE_OPT = "__AS_SPI_DRIVER__";

The configuration C header file inclusion is done by CFLAGS attribute in the OS object of the OSEK/VDX configuration:

 CFLAGS = "-I<PATH>";

Where <PATH> is the absolute or relative directory path which configuration C header file is stored.

Instead the configurations C source file is added to the compilation process by APP_SRC attribute in the CPU_DATA object of the OSEK/VDX configuration:

 APP_SRC = "<PATH>/Spi_Cfg.c";

Where <PATH> is the absolute or relative directory path which configuration C source file is stored.

Supported Architectures

TI Stellaris LM4F232XXXX with ARM KEIL uVision Compiler Toolchain

Driver Configuration

In order to configure the AUTOSAR-like SPI Driver for Texas Instruments Stellaris LM4F232xxxx with ARM KEIL uVision Compiler Toolchain, you have to select the "Spi" tab-sheet on driver configuration instance file.

File:Erika Driver Configurator SPI.png

Configuration Selection

In this section you can add/edit/delete configurations in SPI Driver configuration set:

  • Each configuration SHALL have an Identifier which must be unique inside the configurations set.
  • Each configuration, inside the configurations set, has a set of Channels.
    • Each Channel SHALL have a Name which must be unique inside the Channels.
API Selection

In this section you can select SPI Driver APIs and features will be included in build process:

  • Version Info: Spi_GetVersionInfo() API

File:Erika Driver Configurator SPI set.png

Interrupts

In order to use the AUTOSAR SPI driver, the AUTOSAR SPI driver must be enabled and configured too. Moreover an ISR object must be added to OSEK/VDX configuration for every TI Stellaris SSI harware unit configured and :

 ISR Spi_HwUnit_<Hardware Unit Number>_ISR {
   CATEGORY = 2;
   ENTRY = "SSI_<Hardware Unit Number>";
   PRIORITY = <ISR Priority>;
 }

Where <Hardware Unit Number> is the TI Stellaris SSI hardware unit number (from 0 to 3) and <ISR Priority> is a number indicating the level of priority (0: Lowest).

Implemetations Demos

Implementation Demos of the AUTOSAR-like SPI Driver can be found at examples/cortex_mx/lm4f232xxxx/as

Personal tools