4.8. DIO

4.8.1. About This Document

Document Title

User Guide of MCAL DIO Driver

Document Version

Version 1.7

Company

Texas Instruments

Document Name

DIO User Guide

4.8.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 AM263 to AM263x

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

12 Jun 2023

Updated as per HTML format.

Approved

Version 1.5

25 Aug 2023

Document release version column removed

Approved

Version 1.6

23 Oct 2023

Updated Information about GPIO

Approved

Version 1.7

12 Feb 2024

Updated Information about Readback function, Assumptions, Parameter Description

Approved

4.8.3. Table of contents

  1. Acronyms and Definitions

  2. Functional Overview

  3. Deviations to requirements(Requirement Traceability)

  4. Integration Details

  5. API Description

  6. Configuration Description

  7. Memory mapping

  8. GPIO Information

  9. Memory footprint

  10. Performance

  11. Example Usage

  12. FAQ’s

  13. Test Report

  14. References

  15. TI Disclaimer

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

AM263x

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

  1. DIO Channels (Pins)

  2. DIO Ports

  3. 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

../_images/dio_image2.png

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

None

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

Below listed are assumed to valid for this design/implementation, exceptions and other deviations are listed for each explicitly. Care should be taken to ensure these assumptions are addressed by an entity outside DIO driver.

  1. This module works on pins and ports which must be configured external to this device. Overall configuration and initialization of the port structure which is used in the DIO module.

  2. The DIO functions are valid only after the Port Driver has been initialized. If it is not initialized, then DIO behavior is undefined.

  3. The functional clock to the DIO module is expected to be ON before calling any DIO module API.

  4. Please Note that an entity outside DIO module will take care to configured required voltage level for DIO.

4.8.5.4. Limitations

None

4.8.5.5. Design overview

Please refer SITARA MCU MCAL Architecture Document and AM26x MCAL: DIO Detailed Design Document provided as part of CSP.

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.

../_images/dio_image3.png

Figure_2: DIO Driver File Structure

../_images/dio_image4.jpg

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

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.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

Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.

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

Dio_RegisterReadback API

This function is non-autosar based and is used to read the data in the registers of DIO.

This functionality is enabled, if parameter DioEnableRegisterReadbackApi is TRUE (The Parameter sets DIO_REGISTER_READBACK_API Macro as STD_ON ).

Service Id is 0x19.

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

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

DioRegisterReadbackAp

Adds / removes the service Dio GetVersionInfo() from the code.

TRUE

TRUE/FALSE

BOOLEAN

4.8.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

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
../_images/dio_image5.jpg

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

Performance is not applicable for DIO Driver.

4.8.15. Example Usage

4.8.15.1. Steps to build and run example

  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=am263” command in command prompt.

  3. 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

  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

  6. 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

Please refer AM26x DIO Driver Test Case Report provided as part of CSP.

4.8.18. References

AUTOSAR_SWS_DIODriver
Technical Reference Manual

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