4.12. DIO Module
4.12.1. Acronyms and Definitions
Abbreviation/Term |
Explanation |
|---|---|
LSB |
Least Significant Bit |
MSB |
Most Significant Bit |
DIO |
Digital Input Output |
ID |
Identifier |
ADC |
Analog to Digital Converter |
SPI |
Serial Peripheral Interface |
PWM |
Pulse Width Modulation |
ICU |
Input Capture Unit |
DET |
Default Error Tracer |
DEM |
Diagnostic Event Manager |
Definitions |
Descriptions |
|---|---|
DIO channel |
Represents a single general-purpose digital input/output pin |
DIO port |
Represents several DIO channels that are grouped by hardware |
DIO channel group |
Represents several adjoining DIO channels represented by a logical group |
Physical Level(Input) |
Two states possible: LOW/HIGH. A bit value ‘0’ represents a LOW, a bit value ‘1’ represents a HIGH |
Physical Level(Output) |
Two states possible: LOW/HIGH. A bit value ‘0’ represents a LOW, a bit value ‘1’ represents a HIGH |
4.12.2. Introduction
This document describes the functionality, API and configuration of the AUTOSAR BSW module DIO.
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Link-time, Pre-compile |
Vendor ID |
DIO_VENDOR_ID (44) |
Module ID |
DIO_MODULE_ID (120) |
Supported Platform |
AM263Px |
4.12.3. Functional Overview
The DIO driver provides port and channel based read and write access to the internal general purpose I/O ports. The read and write behaviour is unbuffered. The basic behaviour of this driver is synchronous.
The DIO Driver provides services for reading and writing to/from
DIO Channels (Pins)
DIO Ports
DIO Channel Groups
4.12.3.1. DIO Driver Architecture
The DIO driver has architecture as shown in below figure from the AUTOSAR spec
Fig. 4.54 DIO in AUTOSAR architecture
4.12.3.2. Initialization
The DIO module shall not provide an interface for initialization of the hardware. The Port Driver performs this.
4.12.3.3. States
No state is maintained in the DIO driver
4.12.3.4. Assumptions
None
4.12.3.5. Limitations
None
4.12.3.6. Design overview
Will be updated in future release:
4.12.4. Hardware Features
4.12.4.1. IP Supported Features
Dedicated general-purpose pins that can be configured as either inputs or outputs
Programmable pull up/pull down function
Supports GPIO output in push/pull or open-drain modes
The GPIO peripheral can produce host CPU interrupts and DMA synchronization events
4.12.4.2. AUTOSAR Supported Features
Read/write of individual GPIO pins
Read/write of GPIO registers
Read/write of GPIO registers with configurable mask
Flip the level of a particular GPIO pin
4.12.4.3. Not Supported Features
Reporting of Dem events on pin write
4.12.5. Source files
Static source C Files are defined below in the table.
📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Dio
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┗ 📜Dio.h : Contains the API’s of the DIO driver to be used by upper layers
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┗ 📜Dio.c : Implementation of the API’s for DIO driver
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┣ 📜Dio_Priv.h : Contains data structures and Internal function declarations
┃ ┃ ┃ ┗ 📜Dio_Priv.c : Contains Functions that support the API’s for DIO driver
┃ ┃ ┗ 📜Makefile
┣ 📂mcal_config
┣ 📂mcal_docs
┗ 📜README.txt
Plugin files are defined below in the table.
Plugin Structure |
Descriptions |
|---|---|
Dio_Cfg.h |
Contains the base addresses, Precompile switches, Macros for channels, counters etc. |
Dio_Lcfg.c |
Contains all channels Link time Configuration parameters |
Dio_Cfg.c |
Contains all channels Pre-Compile Configuration parameters |
The below diagram shows the files structure for the DIO driver. The Dio.c and Dio.h are the 2 files that contain the DIO driver’s API’s.
Fig. 4.55 DIO Driver File Structure
Fig. 4.56 DIO header file include structure
4.12.6. Module requirements
Will be updated in future release:
4.12.6.1. Memory Mapping
Memory Mapping Sections |
DIO_CODE |
DIO_CODE_ISR |
DIO_VAR_NO_INIT |
DIO_VAR_ZERO_INIT |
DIO_PBCFG |
DIO_PBCFG_ROOT |
|---|---|---|---|---|---|---|
DIO_START_SEC_VAR_INIT_UNSPECIFIED(.bss) |
x |
|||||
DIO_STOP_SEC_VAR_INIT_UNSPECIFIED |
x |
|||||
DIO_START_SEC_CODE_APPL(.text) |
x |
|||||
DIO_STOP_SEC_CODE_APPL |
x |
|||||
DIO_START_SEC_VAR_UNSPECIFIED(.data) |
x |
|||||
DIO_STOP_SEC_VAR_UNSPECIFIED |
x |
|||||
DIO_START_SEC_CODE(.text) |
x |
|||||
DIO_STOP_SEC_CODE |
x |
|||||
DIO_START_SEC_PBCFG(.data) |
x |
|||||
DIO_STOP_SEC_PBCFG |
x |
|||||
DIO_START_SEC_PBCFG_ROOT(.const) |
x |
|||||
DIO_STOP_SEC_PBCFG_ROOT |
x |
4.12.6.2. Scheduling
There is no scheduling functions in Dio.
4.12.6.3. Error handling
4.12.6.3.1. Development Error Reporting
By default, development errors are reported to the Development Error Tracer (DET) using the service Det_ReportError() if detection and reporting of development errors is enabled in the configuration tool. If another module is used for development error reporting, the function name for reporting the error can be configured by the integrator, but must have the same signature as the service Det_ReportError().
4.12.6.4. Error Code
4.12.6.4.1. Development Errors
Type of Error |
Related Error Code |
Value |
|---|---|---|
API parameter checking: Invalid channel requested |
DIO_E_PARAM_INVALID_CHANNEL_ID |
0x0A |
API parameter checking: Invalid port requested |
DIO_E_PARAM_INVALID_PORT_ID |
0x14 |
API parameter checking: Invalid channel group requested |
DIO_E_PARAM_INVALID_GROUP |
0x1F |
API service called with a NULL pointer |
DIO_E_PARAM_POINTER |
0x20 |
4.12.6.4.2. DEM Errors
The extended production errors reported to DEM module are described in the following table:
Error Code |
Description |
|
|---|---|---|
Assigned by DEM |
DIO_WRITE_CHANNEL_EVENT_ID |
This error is raised when IO check for the DIO channel fails |
Assigned by DEM |
DIO_WRITE_PORT_EVENT_ID |
This error is raised when DIO write to port fails |
Assigned by DEM |
DIO_E_HARDWARE_ERROR |
This error is raised when register write failure occurs(Hardware Failure) |
4.12.7. Used resources
4.12.7.1. Interrupt Handling
The DIO modules doesn’t implement any Interrupt Service Routines.
4.12.7.2. Hardware-Software Mapping
GPIO Channels Mapping
AM263x have total 139 GPIO pins available which allocated from Bank A(Bank 0) to Bank I(Bank 8).
Each Bank contains 16 channels except Bank I(Bank 8).
Bank I contains 11 channels.
GPIO Banks |
GPIO Channels |
|---|---|
BankA / Bank0 |
Channel 0 to channel 15 |
BankB / Bank1 |
Channel 16 to channel 31 |
BankC / Bank2 |
Channel 32 to channel 47 |
BankD / Bank3 |
Channel 48 to channel 63 |
BankE / Bank4 |
Channel 64 to channel 79 |
BankF / Bank5 |
Channel 80 to channel 95 |
BankG / Bank6 |
Channel 96 to channel 111 |
BankH / Bank7 |
Channel 112 to channel 127 |
BankI / Bank8 |
Channel 128 to channel 138 |
4.12.8. Integration description
4.12.8.1. Dependent modules
4.12.8.1.1. DET
This implementation depends on the DET in order to report development errors The detection of development errors is configurable (ON / OFF), The switch DIO_DEV_ERROR_DETECT will activate or deactivate the detection of all development errors.
4.12.8.1.2. DEM
By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus ().
Note
Dem Event is enable only if $(Module_Name)DemEventParameterRefs is enabled.
4.12.8.1.3. PORT
The DIO Modules expects that pinmux is set correctly to configure the GPIO pins for GPIO mode. This is done by the PORT driver. The pin direction shall also be set by the PORT driver.
4.12.8.1.4. SchM
If multiple AUTOSAR runnables have access to the same Data Store Memory block, the exported AUTOSAR specification enforces data consistency by using an AUTOSAR exclusive area. With this specification, the runnables have mutually exclusive access to the per-instance memory global data, which prevents data corruption. Beside the OS, the BSW Scheduler provides functions that DIO module calls at begin and end of critical sections. This implementation requires 1 level of exclusive access to guard critical sections.
The data consistency mechanism that has to be applied to an ExclusiveArea might be domain, ECU or even project specific. The decision which mechanism has to be applied by RTE / Basic Software Scheduler is taken during ECU integration by setting the Exclusive Area configuration parameter RteExclusiveAreaImplMechanism. This parameter is an input for RTE generator.
For DIO Module, data consistency and exclusive access to critical sections are required for the following sections as shown in the table below:
Exclusive Area Functions used |
Dio Function calling Exclusive Area |
Need for Exclusive Area |
Recommended Exclusive Area Mapping |
|---|---|---|---|
DIO_EXCLUSIVE_AREA_0 |
Dio_WritePort |
To protect against multiple access for shared resources |
ALL_INTERRUPT_BLOCKING : All interrupts should be blocked as this API’s can be called in the interrupts |
4.12.8.1.5. Dio Callback Functions
The DIO driver does not provide any call back functions
4.12.8.2. Multi-core support
Not Supported
4.12.9. Configuration
4.12.9.1. DioConfig
This container contains the configuration parameters and sub containers of the AUTOSAR DIO module. This container is a MultipleConfigurationContainer, i.e. this container and its sub-containers exist once per configuration set.
4.12.9.1.1. DioPort
Configuration of individual DIO ports, consisting of channels and possible channel groups.
4.12.9.1.1.1. DioPortId
Item |
|
|---|---|
Name |
DioPortId |
Description |
Numeric identifier of the DIO port. Not all MCU ports may be used for DIO, thus there may be “gaps” in the list of all IDs. This value will be |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
0 |
Max-value |
4 |
Min-value |
0 |
4.12.9.1.2. DioChannel
Configuration of an individual DIO channel. Besides a HW specific channel name which is typically fixed for a specific micro controller, additional symbolic names can be defined per channel.
4.12.9.1.2.1. DioChannelId
Item |
|
|---|---|
Name |
DioChannelId |
Description |
Channel Id of the DIO channel. This value will be assigned to the symbolic names. |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
0 |
Max-value |
138 |
Min-value |
0 |
4.12.9.1.3. DioChannelGroup
Definition and configuration of DIO channel groups. A channel group represents several adjoining DIO channels represented by a logical group.
4.12.9.1.3.1. DioChannelGroupIdentification
Item |
|
|---|---|
Name |
DioChannelGroupIdentification |
Description |
The DIO channel group is identified in DIO API by a pointer to a data structure (of type Dio_ChannelGroupType). That data structure contains the channel group information. |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
4.12.9.1.3.2. DioPortMask
Item |
|
|---|---|
Name |
DioPortMask |
Description |
This shall be the mask which defines the positions of the channel |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Max-value |
4294967295 |
Min-value |
0 |
4.12.9.1.3.3. DioPortOffset
Item |
|
|---|---|
Name |
DioPortOffset |
Description |
The position of the Channel Group on the port, counted |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Max-value |
31 |
Min-value |
0 |
4.12.9.2. DioGeneral
General DIO module configuration parameters.
4.12.9.2.1. DioDevErrorDetect
Item |
|
|---|---|
Name |
DioDevErrorDetect |
Description |
Switches the Development Error Detection and Notification |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
true |
4.12.9.2.2. DioDemEnable
Item |
|
|---|---|
Name |
DioDemEnable |
Description |
Switches the Diagnostic event manager Notification |
Origin |
Texas Instruments |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
true |
4.12.9.2.3. DioFlipChannelApi
Item |
|
|---|---|
Name |
DioFlipChannelApi |
Description |
Adds / removes the service Dio_FlipChannel() from the code. |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
true |
4.12.9.2.4. DioVersionInfoApi
Item |
|
|---|---|
Name |
DioVersionInfoApi |
Description |
Adds / removes the service Dio_ GetVersionInfo() from the code. |
Origin |
AUTOSAR_ECUC |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
true |
4.12.9.2.5. DioHostCoreId
Item |
|
|---|---|
Name |
DioHostCoreId |
Description |
R5F CPU ownership of GPIO. 0 - R5FSS0 Core0, 1 - R5FSS0 Core1, 2 - R5FSS1 Core0, 3 - R5FSS1 Core1 |
Origin |
Texas Instruments |
Post-Build-Variant-Value |
false |
Value-Configuration-Class |
– |
Link-Time |
VARIANT-LINK-TIME |
Pre-Compile-Time |
VARIANT-PRE-COMPILE |
Default-value |
0 |
Max-value |
3 |
Min-value |
0 |
Note
GPIO usage for the cores other than R5F0_0 If AUTOSAR MCAL is running on cores other than R5F0_0, user need to take care of following configuration
DioHostCoreId: R5F CPU ownership of GPIO.
0 -> R5FSS0 Core0
1 -> R5FSS0 Core1
2 -> R5FSS1 Core0
3 -> R5FSS1 Core1
4.12.10. Examples
4.12.10.1. Overview
Dio Example
Initialize clock using Mcu_Init()
Initialize port using Port_Init()
Get Dio Version using Dio_GetVersionInfo()
Set Port Pin direction of GPIOGH_128 to PORT_PIN_OUT using Port_SetPinDirection()
Read the Port pin channel level using Dio_ReadChannel()
Toggle the channel level using Dio_FlipChannel()
Change the channel level using Dio_WriteChannel()
Set a value to the Port using Dio_WritePort()
Read the port level using Dio_ReadPort()
Change a subset of the adjoining bits of a port using Dio_WriteChannelGroup()
Read a subset of the adjoining bits of a port using Dio_ReadChannelGroup()
Verify the read result.
4.12.10.2. Setup required to run example
None
4.12.10.3. How to run examples
1.DIO example application demonstrating the MCAL DIO driver features is in folder <MCAL_ROOT>/examples/Dio.
2.This application can be built from the build folder by giving “gmake –s dio_app PLATFORM=am263px” command in command prompt.
3.Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.12.10.3.1. Configuration used to test this example
1.The DIO example app used to verify the port pin (High/Low) functionalities.
2.GPIOI_128(Ball number A15) these pins are configured as a GPIO.
3.Pin Configurations are provided in mcal/example/Config/Port_PBcfg.c File.
4.Read the channel level before and after Dio_FlipChannel
5.Read the Port value before and after Dio_FlipChannel
4.12.10.4. Sample Log
CLANG compiled : DioApp: Sample Application - STARTS !!!
DIO Driver version info:9.1.0
DIO Driver Module/Driver:120.44
Port Value:1
Port Value for GPIOGH channel 2 :1
Dio_FlipChannel - GPIOGH
Port Value:0
Dio_FlipChannel - GPIOGH
Port Value:1
Port Value for GPIOGH :1
Dio_FlipChannel - GPIOGH
Port Value:0
Dio_FlipChannel -GPIOGH
Port Value:1
Dio_WriteChannel -GPIOGH
Port Value:0
Dio_WriteChannel -GPIOGH
Port Value:1
Port Value Before Flip:1c1
After Flip Port Value:0
Read channel grp Port Value:1
DIO Test Passed!!!
4.12.10.5. File Structure
📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Dio
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┣ 📜Dioapp.c : Contains Dio test example
┃ ┃ ┃ ┗ 📜Makefile
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Dio_Demo_Cfg
┃ ┃ ┃ ┗ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┗ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Dio_Cfg.h : Contains the configuration parameters
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Dio_Cfg.c : Contains all Pre-Compile configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜Dio_Lcfg.c : contains all Link time configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┗ 📜README.txt