4.18. PORT Module

4.18.1. Acronyms and Definitions

Abbreviation/Term

Explanation

AUTOSAR

Automotive Open System Architecture

RTE

Runtime Environment

BSW

Basic Software

GPIO

General Purpose Input Output

ADC

Analogue Digital Converter

MCU

Micro Controller Unit

OS

Operating System

API

Application Programming Interface

HW

Hardware

SW

Software

4.18.2. Introduction

This document describes MCAL PORT Driver functionality, its application interfaces and configuration details as per AUTOSAR version 4.3.1

Supported AUTOSAR Release

4.3.1

Supported Configuration Variants

Pre-Compile, Post-build

Vendor ID

PORT_VENDOR_ID (44)

Module ID

PORT_MODULE_ID (124)

Supported Platform

AM263Px

4.18.3. Functional Overview

The Port driver module is an I/O driver in AUTOSAR Basic Software (BSW) layer. PORT driver provide the services for initializing the whole PORT structure of the microcontroller. It is used to assign various functionalities to Port and port pins (e.g. GPIOs, ADC, SPI and other peripheral modes)

4.18.3.1. PORT Driver Architecture

The following figure shows where the PORT is located in the AUTOSAR architecture

PORT in AUTOSAR architecture

Fig. 4.83 PORT in AUTOSAR architecture

4.18.3.2. Initialization

Port_Init API initializes the PORT driver and does pin configuration of specified PORT PIN Id’s. Port_Init also enables all pins for specified module selected in the config structure passed to Port_Init.

4.18.3.3. States

No state is maintained in the PORT driver.

4.18.3.4. Assumptions

None

4.18.3.5. Limitations

The Pins which are configured as GPIO, the parameter “PortInputOverrideCtrl” and “PortOutputOverrideCtrl” should be as disabled.

Configuration settings

Fig. 4.84 Configuration settings

4.18.3.6. Design overview

Will be updated in future release:

4.18.4. Hardware Features

4.18.4.1. IP Supported Features

  • Configuring the pins for rising and/or falling edge, specified for each GPIO pin.

  • Configuring the GPIO signal conditioning chain

    1. Invert/Non-invert

    2. Signal Qualification:

    • Asynchronous input

    • Synchronize to SYSCLK

    • Qualification using sampling window

  • Enabling all pins of specified peripheral for given mode of operation. This option provides a way configuring all pins for a peripheral for required mode of operation.

  • GPIO Channel/Bank Interrupt notification is supported for Rising, Falling and Both edge interrupts.

4.18.4.2. AUTOSAR Supported Features

  • The PORT Driver module shall initialize the whole port structure of the microcontroller.

  • The PORT Driver module shall allow the configuration of different functionality for each port and port pin. e.g. ADC, SPI, DIO etc.

  • The PORT Driver module shall provide additional configurations for the MCU port/port pins:

    1. Pin direction (input/output)

    2. Pin level initial value

    3. Pin direction changeable during runtime (yes/no)

    4. Port mode changeable during runtime

  • The PORT Driver module shall provide a number of optional configurations for the MCU ports and port pins (if supported by hardware):

    1. Slew rate control

    2. Activation of internal pull-ups

    3. Type of Readback support (pin level,output register value)

4.18.4.3. Not Supported Features

None

4.18.5. Source files

Description of static files is provided below:

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Port
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┗ 📜Port.h : Contains the API’s of the PORT driver to be used by upper layers
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┗ 📜Port.c : Contains the implementation of the API’s for PORT driver
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┣ 📜Port_Irq.h : Contains ISR function declaration
┃ ┃ ┃ ┣ 📜Port_Irq.c : Contains ISR function definitions
┃ ┃ ┃ ┣ 📜Port_Priv.c : Contains Internal functions definition of PORT driver
┃ ┃ ┃ ┗ 📜Port_Priv.h : Contains Internal functions declaration of PORT driver
┃ ┃ ┗ 📜Makefile
┣ 📂mcal_config
┣ 📂mcal_docs
┗ 📜README.txt

Description of generated files is provided below:

Plugin Files

Descriptions

Port_Cfg.h

Contains the Precompile switches, Symbolic names of PortPin

Port_PBcfg.c

Contains all pins Post-Build Configured parameters for Resolver Package

Port_Cfg.c

Contains all pins Pre-Compile Configured parameters

Port_PBcfg_C.c

Contains all pins Post-Build Configured parameters for Compatible Package

Port_PBcfg_SIP.c

Contains all pins Post-Build Configured parameters for SIP Package

PORT header file include structure

Fig. 4.85 PORT header file include structure

4.18.6. Module requirements

Will be updated in future release:

4.18.6.1. Memory Mapping

Memory Mapping Sections

PORT_CODE

PORT_VAR_ZERO_INIT

PORT_PBCFG

PORT_START_SEC_VAR_INIT_UNSPECIFIED (.data)

x

PORT_STOP_SEC_VAR_INIT_UNSPECIFIED

x

PORT_START_SEC_CODE (.bss)

x

PORT_STOP_SEC_CODE

x

PORT_START_SEC_CONFIG_DATA (.data)

x

PORT_STOP_SEC_CONFIG_DATA

x

PORT_START_SEC_ISR_CODE (.bss)

x

PORT_STOP_SEC_ISR_CODE

x

4.18.6.2. Scheduling

4.18.6.2.1. SchM

Beside the OS the BSW Scheduler provides functions that module PORT calls at begin and end of critical sections.

4.18.6.2.2. Critical Sections

There is only one kind of critical sections in this driver. Within these sections all read /modify / write accesses to internal MCU status variables must be protected. This is handled internally in the driver by invoking SchM_Enter_Port_PORT_EXCLUSIVE_AREA_0()/SchM_Exit_Port_PORT_EXCLUSIVE_AREA_0().

4.18.6.3. Error handling

4.18.6.3.1. Development Error Reporting

The module PORT depends on the DET (by default) in order to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch PORT_DEV_ERROR_DETECT = STD_ON in the Port_Cfg.h

AUTOSAR requires that API functions shall check the validity of their respective parameters. These checks are for development error reporting and can be enabled or disabled.

4.18.6.4. Error Code

4.18.6.4.1. Development Errors

The errors reported to DET module are described in the following table:

Type of Error

Related Error code

Value (Hex)

Invalid Port Pin ID requested.

PORT_E_PARAM_PIN

0x0A

Port Pin not configured as changeable.

PORT_E_DIRECTION_UNCHANGEABLE

0x0B

API Port_Init service called with wrong parameter.

PORT_E_INIT_FAILED

0x0C

API Port_SetPinMode service called when mode is unchangeable.Invalid Mode Passed

PORT_E_PARAM_INVALID_MODE

0x0D

API Port_SetPinMode service called when mode is unchangeable

PORT_E_MODE_UNCHANGEABLE

0x0E

API service called without module initialization.

PORT_E_UNINIT

0x0F

API called with a Null Pointer.

PORT_E_PARAM_POINTER

0x10

4.18.7. Used resources

4.18.7.1. Interrupt Handling

4.18.7.1.1. GPIO Interrupts

Individual channel Interrupt can be configured with particular channel and it’s being used to detect the rising/falling/both edge occurred on configured channel.

../_images/port_image6.jpg

Bank channel Interrupt are the interrupt that can be configured with particular bank and it’s being used to detect the rising/falling/both edge occurred on all channels in configured bank.

../_images/port_image7.jpg

Below are the four GPIO XBAR interrupts available.

GPIO Interrupt

GPIO XBAROUT14 INTR

GPIO XBAROUT15 INTR

GPIO XBAROUT16 INTR

GPIO XBAROUT17 INTR

The above mentioned 4 GPIO XBAR interrupts should be mapped to Software ISR’s mentioned below:

For Individual Channel Interrupt: Port_Ch<n>Isr , here <n> is between 0 to 138.

For Bank Interrupt: Port_Bnk<m>Isr , here <m> is between 0 to 8.

These all four GPIO cross bar interrupt source can be configured either Individual channel Interrupt or Bank interrupt.

Each GPIO pin is interrupt capable and can be configured in PortDioConfig container in PORT Plugins as shown below.

../_images/port_image5.jpg

The PORT module depends on MCU module for the configuration of Channel/Bank Interrupt. All above 4 GPIO interrupts should be configured by MCU driver before usage. McuGpioXbarIntrConfiguration container from MCU plugins can be used to do to the same.

../_images/port_image4.jpg

GPIO interrupt API’s:

APIs

Description

Port_PinEnableIntrNotification

This function is Non- Autosar based and is used to enable bank/channel GPIO Interrupts for particular channel

Port_PinDisableIntrNotification

This function is Non- Autosar based and is used to disable bank/channel GPIO Interrupts for particular channel

Port_GetInterruptStatus

This function is Non- Autosar based and is used to collect interrupt register value for each GPIO bank

Port_ClearInterruptStatus

This function is Non- Autosar based and is used to clear interrupt register for each GPIO bank

Note

Mcu Plugins should be added with Port Plugins while Port configuration files generation.

Each used channel in PortDioConfig container should be configured as a GPIO with INPUT direction.

Please refer PORT Example Application to know more about GPIO Interrupt feature configuration and its usage.

4.18.7.1.2. Hardware - Software - ISR API name mapping

For interrupt notification, ISR is provided in PORT driver. The following interrupt is generated by PORT module. The supported ISR is a part of the Port_Irq.h file.

Following are PORT module ISR’s:

For Individual Channel Interrupt: Port_Ch<\n>Isr , here <n> is between 0 to 138.

For Bank Interrupt: Port_Bnk<m>Isr , here <m> is between 0 to 8.

4.18.7.2. Hardware-Software Mapping

4.18.7.2.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.18.8. Integration description

4.18.8.1. Dependent modules

4.18.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 PORT_DEV_ERROR_DETECT will activate or deactivate the detection of all development errors.

4.18.8.1.2. DEM

Note

Dem Event is enable only if $(Module_Name)DemEventParameterRefs is enabled.

4.18.8.1.3. Callback Notification

Notifications:

As it is a configurable interface, the PORT defines notifications that can be mapped to callback functions provided by other modules. The mapping is not statically defined by the PORT but can be performed at configuration time. The function prototypes that can be used for the configuration have to match the appropriate function prototype signatures, described below:

PortDioInterruptNotification:

This is of type Port_IsrNotificationType which is defined in Port_Cfg.h file. This is called to notify the group about the completion of the requested conversion and availability of the conversion results.

4.18.8.2. Multi-core and Resource allocator

Not Supported

4.18.9. Configuration

4.18.9.1. Port Plugins

AM263Px Port have 3 different plugins.

Resolver Package

Port_TI_AM263Px

Compatible Package

Port_TI_AM263Px_C

SIP Package

Port_TI_AM263Px_SIP

User should load only one package plugin in EB Tresos at a given point of time to successfully generate the output.

4.18.9.2. Configuration Variants

The PORT can be configured as Post-Build or Pre-Compile variant, using EB tresos tool.

Variants

Generated Files

PostBuild

Port_PBcfg.c , Port_Cfg.h

Pre-Compile

Port_Cfg.c , Port_Cfg.h

4.18.9.3. Parameter Description

4.18.9.3.1. Standard Configuration

Standard Parameters

Description

Default Value(AM263PX)

Range(AM263PX)

Unit/Datatype

PortNumberOfPortPins

The number of specified PortPins in this PortContainer

NA

1..65535

Integer

PortPinId

Pin Id of the port pin. This value will be assigned to the symbolic name derived from the port pin container short name.

NA

1..144

Integer

PortPinDirection

The initial direction of the pin (IN or OUT). If the direction is not changeable, the value configured here is fixed.

PORT_PIN_DEFAULT

PORT_PIN_IN

PORT_PIN_OUT

PORT_PIN_DEFAULT

Enumeration

PortPinDirectionChangeable

Parameter to indicate if the direction is changeable on a port pin during runtime.

FALSE

TRUE/ FALSE

Boolean

PortPinInitialMode

Port pin mode from mode list for use with Port_Init() function.

NA

1..104

Enumeration

PortPinLevelValue

Port Pin Level value from Port pin list.

PORT_PIN_LEVEL_HIGH

PORT_PIN_LEVEL_HIGH

PORT_PIN_LEVEL_LOW

Enumeration

PortPinMode

Port pin mode from mode list.

NA

1..104

Enumeration

PortPinModeChangeable

Parameter to indicate if the mode is changeable on a port pin during runtime. True: Port Pin mode changeable allowed. False: Port Pin mode changeable not permitted.

FALSE

TRUE/ FALSE

Boolean

PortDevErrorDetect

Switches the Development Error Detection and Notification on or off

TRUE

TRUE/ FALSE

Boolean

PortSetPinDirectionApi

Pre-processor switch to enable / disable the use of the function Port_SetPinDirection().

TRUE

TRUE/ FALSE

Boolean

PortSetPinModeApi

Pre-processor switch to enable / disable the use of the function Port_SetPinMode().

TRUE

TRUE/ FALSE

Boolean

PortVersionInfoApi

Pre-processor switch to enable / disable the API to read out the modules version information.

TRUE

TRUE/ FALSE

Boolean

PortRefreshPortDirectionApi

Pre-processor switch to enable / disable the API to refresh the port direction.

TRUE

TRUE/ FALSE

Boolean

4.18.9.3.2. IP Specific Configuration

Standard Parameters

Description

Default Value(AM263PX)

Range(AM263PX)

Unit/Datatype

PortPinPeripheral

Select peripheral of interest to narron down list of pins of interest.

NA

List of peripherals in HW, Refer TRM for more details

Enumeration

PortPinPeripheralSignal

Select specific peripheral signal pin of interest

NA

List of signals for each peripheral, Refer TRM for more details

Enumeration

PortPinName

PAD IO name of the selected pin

NA

List of Port pin names, Refer TRM for more details

Enumeration

PortPinIdAddr

Pin Id of the port pin. This value will be assigned to the symbolic name derived from the port pin container short name.

NA

NA

String

PortPinInhibitEnable

The port pin inhibit enable.

PORT_PIN_PULL_INHIBIT_DEFAULT

PORT_PIN_PULL_INHIBIT_ENABLE

PORT_PIN_PULL_INHIBIT_DISABLE

PORT_PIN_PULL_INHIBIT_DEFAULT

Enumeration

PortPullTypeSelect

Type of PULL U/D selection

PORT_PIN_PULLTYPE_DEFAULT

PORT_PIN_PULLTYPE_PULLDOWN

PORT_PIN_PULLTYPE_PULLUP

PORT_PIN_PULLTYPE_DEFAULT

Enumeration

PortSlewControlSelect

Slew control configuration

PORT_PIN_SLEWCONTROL_DEFAULT

PORT_PIN_SLEWCONTROL_FAST_SLEW

PORT_PIN_SLEWCONTROL_SLOW_SLEW

PORT_PIN_SLEWCONTROL_DEFAULT

Enumeration

PortInputOverrideCtrl

Port inputOverride control

PORT_PIN_INPUT_RETAIN_HW_CTRL

PORT_PIN_DISABLE_INPUT_OVERRIDE

PORT_PIN_ENABLE_INPUT_OVERRIDE

PORT_PIN_INPUT_RETAIN_HW_CTRL

Enumeration

PortOutputOverrideCtrl

Port OutputOverride control

PORT_PIN_OUTPUT_RETAIN_HW_CTRL

PORT_PIN_DISABLE_OUTPUT_OVERRIDE

PORT_PIN_ENABLE_OUTPUT_OVERRIDE

PORT_PIN_OUTPUT_RETAIN_HW_CTRL

Enumeration

PortDioPinNumber

Port GPIO Pin Number (0 to 138)

0

Will be calculated

Integer

PortDioEdgeTrigger

EdgeTrigger Interrupt Selection

PORT_FALLING_EDGE

PORT_RISING_EDGE

PORT_FALLING_EDGE

PORT_BOTH_EDGE

Enumeration

PortPinSelectInterruptType

Select Interrupt type

PORT_BANK_INTR

PORT_BANK_INTR / PORT_CHANNEL_INTR

Enumeration

PortDioInterruptNotification

Definition of the Callback function.

NULL_PTR

NA

Function Name

PortMcuGpioXbarReference

Reference to the McuGpioXbarIntrConfiguration container (Each channel configuration should be linked to respective interrupt which is configured by MCU driver.)

NULL

It is calculated based on McuGpioXbarIntrConfiguration container data

REFERENCE

PortDeviceVariant

Select SOC variant .This parameter shall be used by driver to impose device specific constraints. The user guide shall detail the device specific constraints

AM263PX

AM263PX

Enumeration

PortDefaultOSCounterId

Default Os Counter Id if node reference to OsCounter ref PortOsCounterRef is not set

0

0..16

Integer

PortSafeTIApi

Enable/Disable SAFETI Configuration register readback.

TRUE

TRUE/ FALSE

Boolean

PortEnableIntrApi

Pre-processor switch to enable / disable the use of Interrupt Functionality

TRUE

TRUE/ FALSE

Boolean

PortGetIntrStatusApi

Pre-processor switch to enable / disable the use of Port_GetInterruptStatus API

TRUE

TRUE/ FALSE

Boolean

PortClearIntrStatusApi

Pre-processor switch to enable / disable the use of PortClearIntrStatusApi API

TRUE

TRUE/ FALSE

Boolean

PortTimeoutDuration

PORT timeout - used in PORT busy wait

32000

1..4294967295

Integer

PortTypeofInterruptFunction

Type of ISR function

PORT_ISR_CAT1

PORT_ISR_VOID

PORT_ISR_CAT1

PORT_ISR_CAT2

Enumeration

Note

PortDioConfig container is specifically used only to configure the GPIO interrupt feature parameters.

To use the GPIO interrupt feature, user should configure the required GPIO channels in PortDioConfig container.

4.18.9.4. Symbolic Names deviations

None.

4.18.9.5. Configuration rules and constraints to enable possibility checks

Will be updated in future release:

4.18.9.6. Steps To Configure Port Module

  1. Open EB Tresos configurator tool and Select the Config Variant ( Precompile/Post-Build) and Device Variant ( Pin Package ) parameters

  2. Go to Port Container tab and create a new container

  3. Open the created container and go to PortPin container to create a portPin configuration. ( Multiple PortPin configurations can be created )

  4. Open the created Port pin, and configure the pin parameters

  5. Select the Port pin peripheral instance ( Mode ) which needs to be configured and accordingly select the Peripheral Signal. As per selected Signal, physical pin ID needs to be selected from the list

  6. Configure the other parameters as per pin usage.

  7. Open Port pin Mode tab and add the default port pin mode ( at least one mode is required for this field ). Other supported modes for that pin can also be configured if user needs to change the mode for the pin afterwards.

  8. Configure the number of port pins in port container general tab

  9. Save the configuration and generate the configuration.

4.18.10. Examples

The example application demonstrates use of Port module, the list below identifies key steps performed in the example.

4.18.10.1. Overview

Will be updated in future release:

4.18.10.2. Setup required to run example

Will be updated in future release:

4.18.10.3. How to run examples

4.18.10.3.1. Steps to build and run example

PORT example application demonstrating the MCAL PORT driver features is in folder <MCAL_ROOT>/examples/Port.

This application can be built from the root folder by giving gmake –s port_app PLATFORM=am263px.

Once the build is completed we get a binary file, which is loaded in our controller and executed.

4.18.10.3.2. External set up Information

PORT module is tested using CC board (PROC111E2).

4.18.10.3.3. Configuration used to test this example

Pin configurations : Following pins are configured as a GPIO and used in example application to test.

Pin Ball Number

Pin Signal Name

C15

GPIOGH_120

B8

GPIOAB_21

4.18.10.4. Sample Log

PORT Example application logs with Resolver Package.

CLANG compiled : portApp: Sample Application - STARTS !!!
 Port Driver version info:9.1.0
 Port Driver Module/Driver:124.44 

 Pin Value for channel 120 : 1 

 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 0 

 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 1 

 Pin Value for channel 120 : 1 
 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 1 

 PORT Test Passed!!!

PORT Example application logs with Compatible Package.

Note

Please change the GPIO_PIN_ID macro value as per generated configuration while testing with compatible package.

þCLANG compiled : portApp: Sample Application - STARTS !!!
 Port Driver version info:9.1.0
 Port Driver Module/Driver:124.44 

 Pin Value for channel 120 : 1 

 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 0 

 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 1 

 Pin Value for channel 120 : 1 
 Dio_FlipChannel(channel_120)
 Pin Value for channel 120 : 1 

 PORT Test Passed!!!

4.18.10.5. File Structure

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Port
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┣ 📜Portapp.c : Contains Port test example
┃ ┃ ┃ ┗ 📜Makefile
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Port_Demo_Cfg
┃ ┃ ┃ ┗ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┗ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Port_Cfg.h : Contains the configuration parameters
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_Cfg.c : Contains all Pre-Compile Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg.c : contains all Post build configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg_C.c : Contains all Post Build Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Port_PBcfg_CAN.c : contains all Post Build configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg_Intr.c : Contains all Pre-Compile Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg_LIN.c : contains all Post build configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg_Ospi.c : Contains all Post Build Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Port_PBcfg_SIP.c : Contains all Post Build Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Port_PBcfg_UART0.c : contains all Post Build configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┗ 📜README.txt

4.18.10.6. Test Report

Please refer AM26x PORT Driver Test Case Report as part of CSP provided in the release package.

4.18.11. References

AUTOSAR_SWS_PortDriver
Technical Reference Manual