AUTOSAR-like SCI Driver
From ErikaWiki
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.
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.
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
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 Data byte reception (polling)
SCI Data byte transmission (polling) - Transmission Error
SCI Data byte reception (polling) - Reception Error
SCI Data byte transmission (interrupt)
SCI Data byte reception (interrupt)
SCI Data byte transmission (interrupt) - Transmission Error
SCI Data byte reception (interrupt) - Reception Error
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