4.6. DIO¶
4.6.1. About This Document¶
Document Title |
User Guide of MCAL DIO Driver |
Document Version |
Version 1.5 |
Company |
Texas Instruments |
Document Name |
DIO User Guide |
4.6.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
26 April 2022 |
Initial Release |
Approved |
Version 1.1 |
05 Aug 2022 |
Updated AM273 to AM273x |
Approved |
Version 1.2 |
23 Dec 2022 |
DIO Example application testing procedure is added |
Approved |
Version 1.3 |
8 May 2023 |
DIO Example application testing procedure updated |
Approved |
Version 1.4 |
07 Aug 2023 |
Updated as per HTML format. |
Approved |
Version 1.5 |
12 Sep 2023 |
IP supported features,Standard Configuration,IP Specific Configuration and Version Updated |
Approved |
4.6.3. Table of contents¶
4.6.4. Acronyms and Definitions¶
Acronyms and Definitions Used are presented in below table.
Acronyms |
Descriptions |
|---|---|
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.6.5. Functional Overview¶
4.6.5.1. Brief Overview¶
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 |
AM273x |
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
The Channel ID range shall be as shown below:
For MSS DIO Pins : Channel ID shall be from 0 to 31.
For RCSS DIO Pins : Channel ID shall be from 32 to 63.
4.6.5.1.1. DIO Driver Architecture¶
The DIO driver has architecture as shown in below figure from the AUTOSAR spec
Figure_1: DIO in AUTOSAR architecture
4.6.5.1.2. Initialization¶
The DIO module shall not provide an interface for initialization of the hardware. The Port Driver performs this.
4.6.5.1.3. States¶
No state is maintained in the DIO driver
4.6.5.2. Features Supported and Not Supported¶
IP Supported Features |
AUTOSAR Supported Features |
Not Supported Features |
|---|---|---|
Allows each GIO terminal to be configured for general-purpose input or output functions |
Read/write of individual GPIO pins |
Reporting of Dem events on pin write |
Supports programmable pull directions on each input GIO terminal |
Read/write of GPIO registers |
|
Supports GPIO output in push/pull or open-drain modes |
Read/write of GPIO registers with configurable mask |
|
Allows up to 32 GIO terminals to be used for generating interrupt requests |
Flip the level of a particular GPIO pin |
4.6.5.3. Assumptions¶
None
4.6.5.4. Limitations¶
None
4.6.5.5. Design overview(Link to the Architecture document and Design Document)¶
Will be updated in future release
4.6.5.6. File Structure¶
Static source C Files are defined below in the table.
Static source C File Structure |
Description |
|---|---|
Dio.h |
Contains the API’s of the DIO driver to be used by upper layers |
Dio_Priv.h |
Contains data structures and Internal function declarations |
Dio.c |
Implementation of the API’s for DIO driver |
Dio_Priv.c |
Contains Functions that support the API’s for DIO driver |
Plugin files are defined below in the table.
Plugin Files |
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.
Figure_2: DIO Driver File Structure
Figure_3: DIO header file include structure
4.6.6. Deviations to requirements(Requirement Traceability)¶
4.6.6.1. Module Requirements¶
Will be updated in future release
4.6.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.6.7. Integration Details¶
4.6.7.1. Dependency on Other Software Modules¶
4.6.7.1.1. The DIO Driver dependent modules¶
4.6.7.1.2. 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.6.7.1.3. Error Handling module¶
4.6.7.1.3.1. DET¶
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().
Type of Error |
Relevance |
Related Error Code |
Value |
|---|---|---|---|
API parameter checking: Invalid channel requested |
Development |
DIO_E_PARAM_INVALID_CHANNEL_ID |
0x0A |
API parameter checking: Invalid port requested |
Development |
DIO_E_PARAM_INVALID_PORT_ID |
0x14 |
API parameter checking: Invalid channel group requested. |
Development |
DIO_E_PARAM_INVALID_GROUP |
0x1F |
API service called with a NULL pointer |
Development |
DIO_E_PARAM_POINTER |
0x20 |
4.6.7.1.3.2. DEM¶
By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus().
The errors reported to DEM 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. |
4.6.7.1.4. Dio Callback Functions¶
The DIO driver does not provide any call back functions
4.6.8. Interrupt Service Routines¶
The DIO modules doesn’t implement any Interrupt Service Routines.
4.6.8.1. Scheduling Strategy¶
4.6.8.1.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module DIO calls at begin and end of critical sections.
4.6.8.1.2. Critical Sections¶
There is only one kind of critical sections in this driver. Within these sections all read /modify / write accesses to internal DIO status variables must be protected. This is handled internally in the DIO driver by invoking.
SchM_Enter_Dio_DIO_EXCLUSIVE_AREA_0()/SchM_Exit_Dio_DIO_EXCLUSIVE_AREA_0()
4.6.9. API Description¶
4.6.9.1. Description of the API’s(Can be referred to Api Guide spec)¶
Refer the AUTOSAR SWS for API documentation and Type definition.
4.6.9.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Autosar API’s Supported:
Service ID |
Service |
|---|---|
0x00 |
Dio_ReadChannel |
0x01 |
Dio_WriteChannel |
0x02 |
Dio_ReadPort |
0x03 |
Dio_WritePort |
0x04 |
Dio_ReadChannelGroup |
0x05 |
Dio_WriteChannelGroup |
0x11 |
Dio_FlipChannel |
0x12 |
Dio_GetVersionInfo |
4.6.9.3. Description on Non Standard API’s¶
None
4.6.10. Configuration Description¶
4.6.10.1. Configuration Variants¶
The DIO is configured through GUI in Link-time and Pre-Compile Variants.
Variants |
Configured Files |
|---|---|
Link-time |
Dio_Lcfg.c , Dio_Cfg.h |
Pre-Compile |
Dio_Cfg.c , Dio_Cfg.h |
4.6.10.2. Parameter Description¶
4.6.10.2.1. Standard Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit/Data Type |
|---|---|---|---|---|
DioPortId |
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 |
0 |
0-4294967295 |
Integer |
DioChannelId |
Channel Id of the DIO channel. This value will be assigned to the symbolic names |
0 |
0-4294967295 |
Integer |
DioChannelGroupIdentification |
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 |
NA |
NA |
String |
DioPortMask |
This shall be the mask which defines the positions of the channel |
0 |
0-4294967295 |
Integer |
DioPortOffset |
The position of the Channel Group on the port, counted |
0 |
0-31 |
Integer |
DioDevErrorDetect |
Switches the Development Error Detection and Notification |
TRUE |
TRUE/FALSE |
BOOLEAN |
DioFlipChannelApi |
Adds / removes the service Dio_FlipChannel() from the code |
TRUE |
TRUE/FALSE |
BOOLEAN |
DioVersionInfoApi |
Adds / removes the service Dio GetVersionInfo() from the code. |
TRUE |
TRUE/FALSE |
BOOLEAN |
4.6.10.2.2. IP Specific Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit/Data Type |
|---|---|---|---|---|
DioDemEnable |
Switches the Diagnostic event manager Notification |
TRUE |
TRUE/FALSE |
BOOLEAN |
DioDeviceVariant |
Select SOC (AM273X) variant |
AM273X |
AM273X |
NA |
DIO_WRITE_CHANNEL_EVENT_ID |
This is the event ID for Dem event in the Dio_WriteChannel() API |
NA |
NA |
NA |
DIO_WRITE_PORT_EVENT_ID |
This is the event ID for Dem event in the Dio_WritePort() API |
NA |
NA |
NA |
4.6.10.3. Symbolic Names deviations¶
None
4.6.10.4. Configuration rules and constraints to enable plausibility checks¶
Will be updated in future release
4.6.11. Memory mapping¶
Memory Mapping Sections |
DIO_CODE |
DIO_CODE_ISR |
DIO_VAR_NO_INIT |
DIO_VAR_ZERO_INIT |
|---|---|---|---|---|
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_START_SEC_CODE |
x |
4.6.12. Memory footprint¶
Please refer Memory Footprint for more details.
4.6.13. Performance¶
Will be updated in future release.
4.6.14. Example Usage¶
4.6.14.1. Steps to build and run example¶
DIO example application demonstrating the MCAL DIO driver features is in folder <MCAL_ROOT>/examples/Dio.
This application can be built from the build folder by giving “gmake –s dio_app PLATFORM=am273” command in command prompt.
Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.6.14.2. Configuration used to test this example¶
The DIO example app used to verify the port pin (High/Low) functionalities.
MSS_GPIOA_0(Ball number V9) these pins are configured as a GPIO.
Pin Configurations are provided in mcal/example/Config/Port_PBcfg.c File.
Read the channel level before and after Dio_FlipChannel
Read the Port value before and after Dio_FlipChannel
Setting particular channel group or particular bits of the port. Read the channel group Port value
Dio_ReadChannel – used to read the channel level
Dio_WriteChannel – used to change channel level
Dio_WriteChannelGroup – used to change a subset of the adjoining bits of a port
Dio_ReadPort – used to read the Port level
Dio_WritePort - used to set a value of the port
Dio_ReadChannelGroup – used to read a subset of the adjoining bits of a port
Dio_FlipChannel – used to toggle the channel level
4.6.14.3. Example Logs¶
DioApp: Sample Application - STARTS !!!
DIO Driver version info:9.0.1
DIO Driver Module/Driver:120.44
Pin Value for channel 0 : 1
Dio_FlipChannel(channel_0)
Pin Value for channel 0 : 0
Dio_FlipChannel(channel_0)
Pin Value for channel 0 : 1
Dio_WriteChannel -channel 0
Pin Value for channel : 0
Dio_WriteChannel - channel 0
Pin Value for channel : 1
Port Value Before Flip:1
After Flip Port Value:0
Read channel grp Port Value:1
DIO Test Passed!!!
4.6.15. FAQ’s¶
None
4.6.16. Test Report(Link to test report)¶
Will be updated in future release.
4.6.17. References¶
Autosar SWS 4.3.1 will be updated in future release.
4.6.18. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments Post Office Box 655303 Dallas, Texas 75265