AUTOSAR-like SCI Driver

From ErikaWiki

Jump to: navigation, search

Contents

Synopsis

The SCI [Serial Communication Interface] Driver and provides serial communications services.

The SCI Driver is part of the microcontroller abstraction layer (MCAL), performs the hardware access and offers a hardware independent API to the upper layer.

The SCI Driver can support more than one channel. This means that the SCI driver can handle one or more SCI channels as long as they are belonging to the same SCI hardware unit as shown in the figure below.

SCI Architecture.png

Only one SCI channel of an ECU is allowed to connect to a particular Transceiver. Unless there are unused (not connected) channels in the ECU, the number of SCI channels is equal to the number of Transceivers the hardware can potentially connects to.

The hardware of the internal SCI hardware unit depends on the system clock, prescaler(s) and PLL. Hence, the length of the SCI bit timing depends on the clock settings made in module SCI. The SCI driver module will not take care of setting the registers that configure the clock, prescaler(s) and PLL (e.g. switching on/off the PLL) in its init functions.

The MCU module must do this.

The Port driver configures the port pins used for the SCI driver as input or output. Hence, the Port driver has to be initialized prior to the use of SCI functions. Otherwise, SCI driver functions will exhibit undefined behavior . The SCI driver uses interrupts and therefore there is a dependency on the OS, which configures the interrupt sources.

The SCI driver has a state machine that is shown in the figure below.

SCI STATE.png

Module State

  • SCI_UNINIT: The state SCI_UNINIT means that the Sci module has not been initialized yet and cannot be used.
  • SCI_INIT: The SCI_INIT state indicates that the SCI driver has been initialized, making each available channel ready for service.

Channel State

  • SCI_CH_OPERATIONAL: The individual channel has been initialized (using at least one statically configured data set) and is able to communicate.
  • SCI_CH_SLEEP: The SCI hardware is into a low power mode if such a mode is provided by the hardware.
  • Reset -> SCI_UNINIT: After reset, the Sci module shall set its state to SCI_UNINIT.
  • SCI_UNINIT -> SCI_INIT: The Sci module shall transition from SCI_UNINIT to SCI_INIT when the function Sci_Init() is called.
  • SCI_INIT -> SCI_UNINIT: The Sci module shall transition from SCI_INIT to SCI_UNINIT when the function Sci_DeInit() is calle

On entering the state SCI_INIT, the Sci module shall set each channel into state SCI_CH_OPERATIONAL.

  • SCI_CH_OPERATIONAL -> SCI_CH_SLEEP: If a Sci_GoToSleep() function is called, the Sci module enters in the SCI_CH_SLEEP state.
  • SCI_CH_SLEEP -> SCI_CH_OPERATIONAL: if a Sci_Wakeup() functions is called, the Sci module go back in the state SCI_CH_OPERATIONAL.

File Structure

SCI Driver File structure.png

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

struct Sci_ConfigType

 #include "Sci.h"

SCI Configuration Parameters.

The structure Sci_ConfigType is an external data structure (i.e. implementation specific) and shall contain the initialization data for the SCI module.

It shall contain:

  • SCI dependent properties
  • SCI hardware units initialization parameters
  • SFR's [Special Function Register] settings affecting the SCI channels

enum Sci_StatusType

 #include "Sci.h"

SCI Status Type.

The type Sci_StatusType is the type of the return value of the API function Sci_GetStatus().

The type of Sci_StatusType is an enumeration describing the operation states for a SCI channel or for a SCI communication.

Enumerator:

  • SCI_NOT_OK: Development or production error occurred.
  • SCI_TX_OK: Successful transmission.
  • SCI_TX_BUSY: Ongoing transmission.
  • SCI_TX_ERROR: Erroneous transmission such as:
    • Transmission disabled.
    • Physical bus error.
  • SCI_RX_OK: Successful reception.
  • SCI_RX_BUSY: Ongoing reception.
  • SCI_RX_ERROR: Erroneous reception such as:
    • Reception disabled.
    • Parity error.
    • Framing error.
    • Overrun error.
  • SCI_OPERATIONAL: Normal operation; the related SCI channel is ready to transmit or receive. No data from previous communication available (e.g. after

initialization).

  • SCI_CH_SLEEP: Sleep state operation; in this state wake-up detection is enabled.

typedef uint Sci_ChannelType

 #include "Sci.h"

Channel Type.

Parameters of type Sci_ChannelType contain the numeric ID of a SCI channel.

The mapping of the ID is implementation specific but not configurable.

For parameter values of type Sci_ChannelType, the Sci's user shall use the symbolic names provided by the configuration description.

The type shall be uint8, uint16 or uint32, depending on μC platform.

typedef void (*Sci_TxNotification)(void)

 #include "Sci.h"

Channel Transmission Notifications Callback.

The notification prototype Sci_TxNotification() is for the transmission notifications callback function and shall be implemented by the user.

The SCI module's environment shall declare a separate transmission notifications callback for each channel to avoid parameters in notification services and to improve run time efficiency . The transmission notifications callback Sci_TxNotification_<channel>() shall be configurable as pointers to user defined functions within the configuration structure.

Each channel shall provide its own transmission notifications callback if configured.

When disabled, the SCI Driver will send no transmission notifications.

The SCI Driver shall invoke a notification callback whenever a transmission event occurred on channel.

The ISR's, providing the SCI events, shall be responsible for resetting the interrupt flags (if needed by hardware) and calling the according notification function.

For all available channels, callback functions have to be declared by the configuration tool.

typedef void (*Sci_TxErrNotification)(void)

 #include "Sci.h"

Channel Transmission Errors Notifications Callback.

The notification prototype Sci_TxErrNotification() is for the transmission errors notifications callback function and shall be implemented by the user.

The SCI module's environment shall declare a separate transmission errors notifications callback for each channel to avoid parameters in notification services and to improve run time efficiency.

The transmission errors notifications callback Sci_TxErrNotification_<channel>() shall be configurable as pointers to user defined functions within the configuration structure.

Each channel shall provide its own transmission errors notifications callback if configured.

When disabled, the SCI Driver will send no transmission errors notifications.

The SCI Driver shall invoke a notification callback whenever a transmission error occurred on channel.

The ISR's, providing the SCI events, shall be responsible for resetting the interrupt flags (if needed by hardware) and calling the according notification function.

For all available channels, callback functions have to be declared by the configuration tool.

typedef void (*Sci_RxNotification)(void)

 #include "Sci.h"

Channel Reception Notifications Callback.

The notification prototype Sci_RxNotification() is for the reception notifications callback function and shall be implemented by the user.

The SCI module's environment shall declare a separate reception notifications callback for each channel to avoid parameters in notification services and to improve run time efficiency . The reception notifications callback Sci_RxNotification_<channel>() shall be configurable as pointers to user defined functions within the configuration structure.

Each channel shall provide its own reception notifications callback if configured.

When disabled, the SCI Driver will send no reception notifications.

The SCI Driver shall invoke a notification callback whenever a reception event occurred on channel.

The ISR's, providing the SCI events, shall be responsible for resetting the interrupt flags (if needed by hardware) and calling the according notification function.

For all available channels, callback functions have to be declared by the configuration tool.

typedef void (*Sci_RxErrNotification)(void)

 #include "Sci.h"

Channel Reception Errors Notifications Callback.

The notification prototype Sci_RxErrNotification() is for the reception errors notifications callback function and shall be implemented by the user.

The SCI module's environment shall declare a separate reception errors notifications callback for each channel to avoid parameters in notification services and to improve run time efficiency . The reception errors notifications callback Sci_RxErrNotification_<channel>() shall be configurable as pointers to user defined functions within the configuration structure.

Each channel shall provide its own reception errors notifications callback if configured.

When disabled, the SCI Driver will send no reception errors notifications.

The SCI Driver shall invoke a notification errors callback whenever a reception error event occurred on channel.

The ISR's, providing the SCI events, shall be responsible for resetting the interrupt flags (if needed by hardware) and calling the according notification function.

For all available channels, callback functions have to be declared by the configuration tool.

Functions Definitions

void Sci_Init(const Sci_ConfigType *ConfigPtr)

 #include "Sci.h"

SCI Driver Initialization.

Parameters:

  • ConfigPtr: Pointer to SCI driver configuration set.

Returns:

  • None.

This service initializes the SCI driver.

Service 0x00

The function Sci_Init() shall initialize the Sci module (i.e. static variables, including flags and SCI hardware unit global hardware settings), as well as the SCI channels.

Different sets of static configuration may have been configured.

The function Sci_Init() shall initialize the module according to the configuration set pointed to by the parameter ConfigPtr.

The function Sci_Init() shall invoke initializations for relevant hardware register settings common to all channels available on the SCI hardware unit.

The function Sci_Init() shall also invoke initializations for SCI channel specific settings.

The SCI module’s environment shall not call any function of the Sci module before having called Sci_Init() except Sci_GetVersionInfo().

Symbolic names of the available configuration sets are provided by the configuration description of the SCI driver.

void Sci_GetVersionInfo(Std_VersionInfoType *VersionInfoPtr)

 #include "Sci.h"

SCI Driver version informations retrieval.

Parameters:

  • VersionInfoPtr: Pointer to where to store the version information of this module.

Returns:

  • None.

This service retrieves the SCI driver version informations.

Service 0x01

The function Sci_GetVersionInfo() shall return the version information of the SCI module.

The version information includes:

  • Module Id
  • Vendor Id
  • Vendor specific version numbers

The function Sci_GetVersionInfo() shall be configurable On/Off by the configuration parameter SciVersionInfoApi.

If source code for caller and callee of the function Sci_GetVersionInfo() is available, the SCI module should realize this function as a macro.

The SCI module should define this macro in the module’s header file.

Std_ReturnType Sci_WriteTxData(Sci_ChannelType Channel, uint8 Data)

 #include "Sci.h"

Tx Data Write.

Parameters:

  • Channel: ID of SCI Channel
  • Data: Data byte to be write

Returns:

  • E_OK: Write command has been accepted
  • E_NOT_OK: Write command has not been accepted

The service writes a Data byte into the Tx data register of the SCI HW Unit for the addressed Channel.

Service 0x02

The SCI module's environment shall only call Sci_WriteTxData() on a channel which is in state SCI_OPERATIONAL or in one of the sub-states of SCI_OPERATIONAL.

Std_ReturnType Sci_ReadRxData(Sci_ChannelType Channel, uint8 *DataPtr)

 #include "Sci.h"

Rx Data Read.

Parameters:

  • Channel: ID of SCI Channel
  • DataPtr: Buffer pointer for the Data byte to be read

Returns:

  • E_OK: Read command has been accepted
  • E_NOT_OK: Read command has not been accepted

The service reads a Data byte from the Rx data register of the SCI HW Unit for the addressed Channel.

Service 0x03

The SCI module's environment shall only call Sci_ReadRxData() on a channel which is in state SCI_OPERATIONAL or in one of the sub-states of SCI_OPERATIONAL.

Sci_StatusType Sci_GetStatus(Sci_ChannelType Channel)

 #include "Sci.h"

SCI Channel Status Retrieval.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • SCI_NOT_OK: Development or production error occurred
  • SCI_TX_OK: Successful transmission.
  • SCI_TX_BUSY: Ongoing transmission.
  • SCI_TX_ERROR: Erroneous transmission such as:
    • Transmission disabled.
    • Physical bus error.
  • SCI_RX_OK: Successful reception.
  • SCI_RX_BUSY: Ongoing reception.
  • SCI_RX_ERROR: Erroneous reception such as:
    • Reception disabled.
    • Parity error.
    • Framing error.
    • Overrun error.
  • SCI_OPERATIONAL: Normal operation; the related SCI channel is ready to transmit or receive. No data from previous communication available (e.g. after initialization).
  • SCI_CH_SLEEP: Sleep state operation; in this state wake-up detection is enabled.

The service gets the status of the specified SCI channel.

Service 0x08

The function Sci_GetStatus() shall return the current transmission, reception or operation status of the SCI driver.

The return states SCI_TX_OK, SCI_TX_BUSY, SCI_TX_ERROR, SCI_RX_OK, SCI_RX_BUSY and SCI_RX_ERROR are substates of the channel state SCI_CH_OPERATIONAL.

Std_ReturnType Sci_GoToSleep(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Go To Sleep.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: command has been accepted
  • E_NOT_OK: command has not been accepted

The service instructs the driver to set the addressed SCI channel in the state SCI_CH_SLEEP.

Service 0x06

The function Sci_GoToSleep() shall set the channel state to SCI_CH_SLEEP.

The function Sci_GoToSleep() shall optionally set the SCI hardware unit to reduced power operation mode (if supported by HW).

The SCI channel shall enter SCI_CH_SLEEP state even in case of an erroneous transmission/reception.

The function Sci_GoToSleep() shall terminate ongoing frame transmission of prior transmission requests, even if the transmission is unsuccessfully completed.

Std_ReturnType Sci_Wakeup(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Wake-up.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: command has been accepted
  • E_NOT_OK: command has not been accepted

The service generates a wake-up pulse on the addressed SCI channel.

Service 0x07

The function Sci_Wakeup() shall generate a wake up pulse on the addressed SCI channel.

The SCI driver's environment shall only call Sci_Wakeup() when the SCI channel is in state SCI_CH_SLEEP.

Std_ReturnType Sci_CheckWakeup(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Wake-up Check.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: SCI Channel Waked-up
  • E_NOT_OK: SCI Channel Sleep

This service checks if a wake-up has occurred on the addressed SCI channel.

Service 0x0A

The function Sci_CheckWakeup() shall evaluate the wake-up on the addressed SCI channel.

Std_ReturnType Sci_DisableTx(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Transmission Disable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: Command has been accepted
  • E_NOT_OK: Command has not been accepted

The service instructs the driver to disable the transmission for the addressed SCI channel.

Service 0x0B

The function Sci_DisableTx() shall terminate ongoing transmission of prior transmission requests, even if the transmission is unsuccessfully completed.

Std_ReturnType Sci_EnableTx(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Transmission Enable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: Command has been accepted
  • E_NOT_OK: Command has not been accepted

The service instructs the driver to enable the transmission for the addressed SCI channel.

Service 0x0B

Std_ReturnType Sci_DisableRx(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Reception Disable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: Command has been accepted
  • E_NOT_OK: Command has not been accepted

The service instructs the driver to disable the reception for the addressed SCI channel.

Service 0x0C

The function Sci_DisableRx() shall terminate ongoing transmission of prior reception requests, even if the reception is unsuccessfully completed.

Std_ReturnType Sci_EnableRx(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Reception Enable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • E_OK: Command has been accepted
  • E_NOT_OK: Command has not been accepted

The service instructs the driver to enable the reception for the addressed SCI channel.

Service 0x0D

void Sci_EnableNotifications(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Notifications Enable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • None.

The service enables the interrupt notifications for a channel.

Service 0x04

The function Sci_EnableNotifications() shall enable the interrupt notifications of the referenced channel configured for notifications.

The function shall save an attribute like "notifications enabled" of the channel.

'Note: This attribute affects the interrupt notifications always when the channel is in SCI_OPERATIONAL state or substates. In SCI_CH_SLEEP state the attribute has no influence.

The function Sci_EnableNotifications() shall be reentrant, if the SCI channels used in concurrent calls are different.

The function Sci_EnableNotifications() shall be pre compile time configurable On/Off by the configuration parameter: SciEnableDisableNotificationsApi.

void Sci_DisableNotifications(Sci_ChannelType Channel)

 #include "Sci.h"

Channel Notifications Disable.

Parameters:

  • Channel: ID of SCI Channel

Returns:

  • None.

The service disables the interrupt notifications for a channel.

Service 0x05

The function Sci_DisableNotifications() shall disable the interrupt notifications of the referenced channel configured for notifications.

The function shall save an attribute like "notifications disabled" of the channel.

'Note: This attribute affects the interrupt notifications always when the channel is in SCI_OPERATIONAL state or substates. In SCI_CH_SLEEP state the attribute has no influence.

The function Sci_DisableNotifications() shall be reentrant, if the SCI channels used in concurrent calls are different.

The function Sci_DisableNotifications() shall be pre compile time configurable On/Off by the configuration parameter: SciDisableDisableNotificationsApi.

Usage Examples

SCI Data byte transmission (polling)

Sci WriteTxData Seq Dia.png

SCI Data byte reception (polling)

Sci ReadRxData Seq Dia.png

SCI Data byte transmission (polling) - Transmission Error

Sci WriteTxData Err Seq Dia.png

SCI Data byte reception (polling) - Reception Error

Sci ReadRxData Err Seq Dia.png

SCI Data byte transmission (interrupt)

Sci WriteTxData Int Seq Dia.png

SCI Data byte reception (interrupt)

Sci ReadRxData Int Seq Dia.png

SCI Data byte transmission (interrupt) - Transmission Error

Sci WriteTxData Int Err Seq Dia.png

SCI Data byte reception (interrupt) - Reception Error

Sci ReadRxData Int Err Seq Dia.png

Build

To enable AUTOSAR SCI 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_SCI_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>/Sci_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 SCI Driver for Texas Instruments Stellaris LM4F232xxxx with ARM KEIL uVision Compiler Toolchain, you have to select the "Sci" tab-sheet on driver configuration instance file.

File:Erika Driver Configurator SCI.png

Configuration Selection

In this section you can add/edit/delete configurations in SCI 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 SCI Driver APIs and features will be included in build process:

  • Version Info: Sci_GetVersionInfo() API

File:Erika Driver Configurator SCI set.png

Interrupts

To use the SCI driver in interrupt mode, an ISR object must be added to OSEK/VDX configuration for every SCI Channel:

 ISR Sci_Channel_<Channel Number>_ISR {
   CATEGORY = 2;
   ENTRY = "UART_<Channel Number>";
   PRIORITY = <ISR Priority>;
 };

Where <Channel Number> is the "channel number" as stated in the SCI Driver Channel Identifier of the channel and <ISR Priority> is a number indicating the level of priority (0: Lowest).

Implemetations Demos

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

Personal tools