4.17. PORT¶
4.17.1. About This Document¶
Document Title |
User Guide of MCAL PORT Driver |
Document Version |
Version 1.7 |
Company |
Texas Instruments |
Document Name |
PORT User Guide |
4.17.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
24-Mar-2022 |
Initial Version |
Approved |
Version 1.1 |
26 April 2022 |
Performed Performance Test |
Approved |
Version 1.2 |
05 Aug 2022 |
Fixed Bugs and updated AM263 to AM263x |
Approved |
Version 1.3 |
22 Dec 2022 |
Example Application section updated. |
Approved |
Version 1.4 |
8 May 2023 |
Version Change |
Approved |
Version 1.5 |
12 Jun 2023 |
Updated as per HTML format. |
Approved |
Version 1.6 |
25 Aug 2023 |
Document release version column removed |
Approved |
Version 1.7 |
23 Oct 2023 |
Updated Information for GPIO Interrupts. |
Approved |
4.17.3. Table of contents¶
4.17.4. Acronyms and Definitions¶
Acronyms and Definitions used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
ADC |
Analogue Digital Converter |
MCU |
Micro Controller Unit |
OS |
Operating System |
API |
Application Programming Interface |
HW |
Hardware |
SW |
Software |
4.17.5. Functional Overview¶
4.17.5.1. Brief Overview¶
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 |
AM263x |
PORT module shall provide the service for initializing the whole PORT structure of the microcontroller. This driver specification is applicable for on-chip ports and port pins.
4.17.5.1.1. PORT Driver Architecture¶
The following figure shows where the PORT is located in the AUTOSAR architecture
Figure 1: PORT in AUTOSAR architecture.
4.17.5.1.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.17.5.1.3. States¶
No state is maintained in the PORT driver.
4.17.5.2. Features Supported and Not Supported¶
AUTOSAR features:
IP Supported Features |
AUTOSAR Supported Features |
Not Supported |
|---|---|---|
Configuring the pins for rising and/or falling edge, specified for each GPIO pin. |
The PORT Driver module shall initialize the whole port structure of the microcontroller. |
None |
Configuring the GPIO signal conditioning chain
|
The PORT Driver module shall allow the configuration of different functionality for each port and port pin. e.g. ADC, SPI, DIO etc. |
None |
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. |
The PORT Driver module shall provide additional configurations for the MCU port/port pins:
|
None |
GIO Channel/Bank Interrupt notification is supported for Rising, Falling and Both edge interrupts. |
The PORT Driver module shall provide a number of optional configurations for the MCU ports and port pins (if supported by hardware):
|
None |
4.17.5.3. Assumptions¶
None
4.17.5.4. Limitations¶
The Pins which are configured as GPIO, the parameter “PortInputOverrideCtrl” and “PortOutputOverrideCtrl” should be as disabled.
Figure 2:Configuration settings.
4.17.5.5. Design overview¶
Please refer SITARA MCU MCAL Architecture Document and AM26x MCAL: PORT Detailed Design Document provided as part of CSP.
4.17.5.6. File Structure¶
Description of static files is provided below:
Static source and header files |
Description |
|---|---|
Port.h |
Contains the API’s of the PORT driver to be used by upper layers. |
Port.c |
Contains the implementation of the API’s for PORT driver. |
Port_Priv.c |
Contains Internal functions definition of PORT driver. |
Port_Priv.h |
Contains Internal functions declaration of PORT driver. |
Port_Irq.c & Port_Irq.h |
Contains ISR function definitions |
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 |
Port_Cfg.c |
Contains all pins Pre-Compile Configured parameters |
Figure 4: PORT header file include structure
4.17.6. Deviations to requirements (Requirement Traceability)¶
4.17.6.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.17.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.17.7. Integration Details¶
4.17.7.1. Dependency on Other Software Modules¶
PORT driver doesn’t depend on other peripheral drivers
4.17.7.1.1. Error Handling module¶
4.17.7.1.1.1. DET¶
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.
The errors reported to DET module are described in the following table:
Error Code |
Error Macro |
Description |
|---|---|---|
[0x0A] |
PORT_E_PARAM_PIN |
Invalid Port Pin ID requested |
[0x0B] |
PORT_E_DIRECTION_UNCHANGEABLE |
Port Pin not configured as changeable |
[0x0C] |
PORT_E_INIT_FAILED |
API Port_Init service called with wrong parameter. |
[0x0D] |
PORT_E_PARAM_INVALID_MODE |
API Port_SetPinMode service called when mode is unchangeable. |
[0x0E] |
PORT_E_MODE_UNCHANGEABLE |
API Port_SetPinMode service called when mode is unchangeable. |
[0x0F] |
PORT_E_UNINIT |
API service called without module initialization |
[0x10] |
PORT_E_PARAM_POINTER |
APIs called with a Null Pointer |
4.17.7.1.1.2. DEM¶
The extended production errors reported to DEM module are described in the following table:
Error Code |
Description |
|
|---|---|---|
Assigned by DEM |
PORT_E_HARDWARE_ERROR |
This error is raised when register write failure occurs. (Hardware Failure) |
4.17.7.1.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, which are described in the following.
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.17.7.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.17.7.3. Scheduling Strategy¶
4.17.7.3.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module PORT calls at begin and end of critical sections.
4.17.7.3.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.17.8. API Description¶
4.17.8.1. Description of the API’s¶
Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.
4.17.8.2. List of API’s¶
The following table presents the list of API’s:
Service ID |
Autosar API’s Supported Service |
Autosar API’s not Supported Service |
|---|---|---|
0x00 |
Port_Init |
|
0x01 |
Port_SetPinDirection |
|
0x02 |
Port_RefreshPortDirection |
|
0x03 |
Port_GetVersionInfo |
|
0x04 |
Port_SetPinMode |
Refer Autosar SWS for API description mentioned in above table.
4.17.8.3. Description on Non Standard API’s¶
Port_DeInit API
This function is Non- Autosar based and is used to de-initialize port module.
Port_PinEnableIntrNotification API
This function is Non- Autosar based and is used to enable bank/channel GPIO Interrupts for particular channel.
Port_PinDisableIntrNotification API
This function is Non- Autosar based and is used to disable bank/channel GPIO Interrupts for particular channel.
Port_GetInterruptStatus API
This function is Non- Autosar based and is used to collect interrupt register value for each GPIO bank.
Port_ClearInterruptStatus API
This function is Non- Autosar based and is used to clear interrupt register for each GPIO bank.
4.17.9. Configuration Description¶
4.17.9.1. 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.17.9.2. Parameter Description¶
4.17.9.2.1. Standard Configuration¶
Standard Parameters |
Description |
Default Value(AM263X) |
Range(AM263X) |
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.17.9.2.2. IP Specific Configuration¶
Standard Parameters |
Description |
Default Value(AM263X) |
Range(AM263X) |
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 |
AM263X |
AM263X |
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
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
R5F CPU ownership of GPIO.
Note
PortDioConfig container is specifically used only to configure the GPIO interrupt feature parameters.
To use the GPIO interrupt feature, user should configure the 0required GPIO channels in PortDioConfig container.
4.17.9.3. Symbolic Names deviations¶
None.
4.17.9.4. Configuration rules and constraints to enable possibility checks¶
Will be updated in future release
4.17.10. 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 |
x |
||
PORT_STOP_SEC_CONFIG_DATA |
x |
||
PORT_START_SEC_ISR_CODE (.bss) |
x |
||
PORT_STOP_SEC_ISR_CODE |
x |
4.17.11. GPIO Interrupt Feature Information¶
4.17.11.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.17.11.2. GPIO Interrupts¶
Individual channel Interrupt are the interrupt can be configured with particular channel and it’s being used to detect the rising/falling/both edge occured on configured channel.
Bank channel Interrupt are the interrupt can be configured with particular bank and it’s being used to detect the rising/falling/both edge occured on all channels in configured bank.
The 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.
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.
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 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.17.12. Memory footprint¶
Please refer Memory Footprint for more details.
4.17.13. Performance¶
Not Applicable
4.17.14. Example Usage¶
4.17.14.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=am263.
Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.17.14.2. External set up Information¶
PORT module is tested using CC board (PROC111E2).
4.17.14.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.17.14.4. Example Logs¶
CLANG compiled : portApp: Sample Application - STARTS !!!
Port Driver version info:9.0.1
Port Driver Module/Driver:124.44
[GPIO INTR verification] => Press SW1 switch on board to trigger the interrupt
Interrupt -- Bank Number : 1 GpioChannelNum : 255 Edge : 1
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.17.15. FAQ’s¶
None
4.17.16. Test Report¶
Please refer AM26x PORT Driver Test Case Report provided as part of CSP.
4.17.17. References¶
4.17.18. 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