4.8. DIO¶
4.8.1. About This Document¶
Document Title |
User Guide of MCAL DIO Driver |
Document Version |
Version 1.0 |
Company |
Texas Instruments |
Document Name |
DIO User Guide |
4.8.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
13 Oct 2023 |
Initial Release |
Approved |
4.8.3. Table of contents¶
4.8.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.8.5. Functional Overview¶
4.8.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 |
AM263px |
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.8.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.8.5.1.2. Initialization¶
The DIO module shall not provide an interface for initialization of the hardware. The Port Driver performs this.
4.8.5.1.3. States¶
No state is maintained in the DIO driver
4.8.5.2. Features Supported and Not Supported¶
IP Supported Features |
AUTOSAR Supported Features |
Not Supported Features |
|---|---|---|
Dedicated general-purpose pins that can be configured as either inputs or outputs |
Read/write of individual GPIO pins |
Reporting of Dem events on pin write |
programmable pull up/pull down function |
Read/write of GPIO registers |
|
Supports GPIO output in push/pull or open-drain modes |
Read/write of GPIO registers with configurable mask |
|
The GPIO peripheral can produce host CPU interrupts and DMA synchronization events |
Flip the level of a particular GPIO pin |
4.8.5.3. Assumptions¶
None
4.8.5.4. Limitations¶
None
4.8.5.5. Design overview(Link to the Architecture document and Design Document)¶
Will be updated in future release
4.8.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 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.
Figure_2: DIO Driver File Structure
Figure_3: DIO header file include structure
4.8.6. Deviations to requirements(Requirement Traceability)¶
4.8.6.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.8.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.8.7. Integration Details¶
4.8.7.1. Dependency on Other Software Modules¶
4.8.7.1.1. The DIO Driver dependent modules¶
4.8.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.8.7.1.3. Error Handling module¶
4.8.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.8.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.8.7.1.4. Dio Callback Functions¶
The DIO driver does not provide any call back functions
4.8.8. Interrupt Service Routines¶
The DIO modules doesn’t implement any Interrupt Service Routines.
4.8.8.1. Scheduling Strategy¶
4.8.8.1.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module DIO calls at begin and end of critical sections.
4.8.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.8.9. API Description¶
4.8.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.8.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.8.9.3. Description on Non Standard API’s¶
None
4.8.10. Configuration Description¶
4.8.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.8.10.2. Parameter Description¶
4.8.10.2.1. Standard Configuration¶
Will be updated in future release
4.8.10.2.2. IP Specific Configuration¶
DioDemEventParameterRef |
For Dem event in the Dio_WriteChannel() API |
DioDeviceVariant |
To Select SOC AM263px variant |
4.8.11. 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_START_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.8.12. GPIO Information¶
4.8.12.1. 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 the 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.8.13. Memory footprint¶
Please refer Memory Footprint for more details.
4.8.14. Performance¶
Will be updated in future release.
4.8.15. Example Usage¶
4.8.15.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=am263” command in command prompt.
Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.8.15.2. Configuration used to test this example¶
The DIO example app used to verify the port pin (High/Low) functionalities.
GPIOI_128(Ball number A15) 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_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.8.15.3. Example Logs¶
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.8.16. FAQ’s¶
None
4.8.17. Test Report(Link to test report)¶
Will be updated in future release.
4.8.18. References¶
4.8.19. 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
