4.14. PORT¶
4.14.1. About This Document¶
Document Title |
User Guide of MCAL PORT Driver |
Document Version |
Version 1.2 |
Company |
Texas Instruments |
Document Name |
PORT User Guide |
4.14.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
24-Nov-2020 |
Initial Version |
Approved |
Version 1.1 |
12 Jun 2023 |
Updated as per HTML format. |
Approved |
Version 1.2 |
15 Sep 2023 |
Configuration details are added, GPIO Interrupt Notification feature is added. |
Approved |
4.14.3. Table of contents¶
4.14.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.14.5. Functional Overview¶
4.14.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 |
AM273x |
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.14.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.14.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.14.6. States¶
No state is maintained in the PORT driver.
4.14.6.1. 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. |
GIO generates aggregated interrupts for all inputs from PAD. |
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 allow the configuration of different functionality for each port and port pin. e.g. ADC, SPI, DIO etc. |
None |
GIO Interrupt notification is supported for HIGH and LOW Level interrupt. |
The PORT Driver module shall provide additional configurations for the MCU port/port pins:
|
None |
The PORT Driver module shall provide a number of optional configurations for the MCU ports and port pins (if supported by hardware):
|
None |
4.14.6.2. Assumptions¶
None
4.14.6.3. Limitations¶
The Pins which are configured as GPIO, the parameter “PortInputOverrideCtrl” and “PortOutputOverrideCtrl” should be as disabled.
Figure 2:Configuration settings.
4.14.6.4. Design overview(Link to the Architecture document and Design Document)¶
Will be available in future release.
4.14.6.5. 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.14.7. Deviations to requirements(Requirement Traceability)¶
4.14.7.1. Module Requirements¶
Will be updated in future release
4.14.7.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.14.8. Integration Details¶
4.14.8.1. Dependency on Other Software Modules¶
PORT driver doesn’t depend on other peripheral drivers
4.14.8.1.1. Error Handling module¶
4.14.8.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 |
The run time errors reported to DET module are described in the following table:
4.14.8.1.1.2. DEM¶
There are no DEM errors.
4.14.8.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.14.8.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 is PORT module ISR for the hardware unit:
GPIO |
HW Interrupt |
SW ISR for PORT module |
|---|---|---|
MSS GPIO(0 to 31) |
MSS_GIO_INT0 |
Port_MssPinHighLevelIsr |
MSS GPIO(0 to 31) |
MSS_GIO_INT1 |
Port_MssPinLowLevelIsr |
RCSS GPIO(32 to 63) |
RCSS_GIO_INT0 |
Port_RcssPinHighLevelIsr |
RCSS GPIO(32 to 63) |
RCSS_GIO_INT1 |
Port_RcssPinLowLevelIsr |
4.14.8.3. Scheduling Strategy¶
4.14.8.3.1. SchM (Optional)¶
Beside the OS the BSW Scheduler provides functions that module PORT calls at begin and end of critical sections.
4.14.8.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.14.9. API Description¶
4.14.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.14.9.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.14.9.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 GPIO Interrupt.
Port_PinDisableIntrNotification API
This function is Non- Autosar based and is used to disable GPIO Interrupt.
4.14.10. Configuration Description¶
4.14.10.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.14.10.2. Parameter Description¶
4.14.10.2.1. Standard Configuration¶
Standard Parameters |
Description |
Default Value(AM273X) |
Range(AM273X) |
Default Value(AM272S) |
Range(AM272S) |
Unit/Datatype |
|---|---|---|---|---|---|---|
PortNumberOfPortPins |
The number of specified PortPins in this PortContainer |
NA |
1..65535 |
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..104 |
NA |
1..109 |
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 |
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 |
FALSE |
TRUE/ FALSE |
Boolean |
PortPinInitialMode |
Port pin mode from mode list for use with Port_Init() function. |
NA |
(Refer section PIN Details of AM273x) |
NA |
(Refer section PIN Details of AM2732S) |
Enumeration |
PortPinLevelValue |
Port Pin Level value from Port pin list. |
PORT_PIN_LEVEL_HIGH |
PORT_PIN_LEVEL_HIGH PORT_PIN_LEVEL_LOW |
PORT_PIN_LEVEL_HIGH |
PORT_PIN_LEVEL_HIGH PORT_PIN_LEVEL_LOW |
Enumeration |
PortPinMode |
Port pin mode from mode list. |
NA |
(Refer section PIN Details of AM273x) |
NA |
(Refer section PIN Details of AM2732S) |
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 |
FALSE |
TRUE/ FALSE |
Boolean |
PortDevErrorDetect |
Switches the Development Error Detection and Notification on or off |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortSetPinDirectionApi |
Pre-processor switch to enable / disable the use of the function Port_SetPinDirection(). |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortSetPinModeApi |
Pre-processor switch to enable / disable the use of the function Port_SetPinMode(). |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortVersionInfoApi |
Pre-processor switch to enable / disable the API to read out the modules version information. |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
4.14.10.2.2. IP Specific Configuration¶
Standard Parameters |
Description |
Default Value(AM273X) |
Range(AM273X) |
Default Value(AM2732s) |
Range(AM2732s) |
Unit/Datatype |
|---|---|---|---|---|---|---|
PortPinPeripheral |
Select peripheral of interest to narron down list of pins of interest. |
NA |
(Refer section PIN Details of AM273x) |
NA |
(Refer section PIN Details of AM2732S) |
Enumeration |
PortPinPeripheralSignal |
Select specific peripheral signal pin of interest |
NA |
(Refer section PIN Details of AM273x) |
NA |
(Refer section PIN Details of AM2732S) |
Enumeration |
PortPinName |
PAD IO name of the selected pin |
NA |
(Refer section PIN Details of AM273x) |
NA |
(Refer section PIN Details of AM2732S) |
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 |
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 |
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 |
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 |
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 |
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 |
PORT_PIN_OUTPUT_RETAIN_HW_CTRL |
PORT_PIN_DISABLE_OUTPUT_OVERRIDE PORT_PIN_ENABLE_OUTPUT_OVERRIDE PORT_PIN_OUTPUT_RETAIN_HW_CTRL |
Enumeration |
PortDioConfigRegId |
identified of GPIO register number (GPIOA=>0, GPIOB=>1 …) |
1 |
1..8 |
1 |
1..8 |
Integer |
PortDioSubsystem |
Select Port Subsystem (MSS or RCSS) |
PORT_MSS |
PORT_MSS PORT_RCSS |
PORT_MSS |
PORT_MSS PORT_RCSS |
Enumeration |
PortDioPinNumber |
Port GPIO Pin Number (MSS - 0 to 31, RCSS - 32 to 63) |
0 |
Will be calculated |
0 |
Will be calculated |
Integer |
PortDioEdgeTrigger |
EdgeTrigger Interrupt Selection |
PORT_FALLING_EDGE |
PORT_RISING_EDGE PORT_FALLING_EDGE PORT_BOTH_EDGE |
PORT_FALLING_EDGE |
PORT_RISING_EDGE PORT_FALLING_EDGE PORT_BOTH_EDGE |
Enumeration |
PortDioLevelTrigger |
LevelTrigger Interrupt Selection |
PORT_LOW_LEVEL |
PORT_HIGH_LEVEL PORT_LOW_LEVEL |
PORT_LOW_LEVEL |
PORT_HIGH_LEVEL PORT_LOW_LEVEL |
Enumeration |
PortDioInterruptNotification |
Definition of the Callback function. |
NULL_PTR |
NA |
NULL_PTR |
NA |
Function Name |
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 |
AM273X |
AM273X |
AM2732S |
AM2732S AM273X AWR29xx |
Enumeration |
PortRefreshPortDirectionApi |
Pre-processor switch to enable / disable the API to refresh the port direction. |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortDefaultOSCounterId |
Default Os Counter Id if node reference to OsCounter ref PortOsCounterRef is not set |
0 |
0..16 |
0 |
0..16 |
Integer |
PortSafeTIApi |
Enable/Disable SAFETI Configuration register readback. |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortEnableIntrApi |
Pre-processor switch to enable / disable the use of Interrupt Functionality |
TRUE |
TRUE/ FALSE |
TRUE |
TRUE/ FALSE |
Boolean |
PortTimeoutDuration |
PORT timeout - used in PORT busy wait |
32000 |
1..4294967295 |
32001 |
1..4294967295 |
Integer |
PortTypeofInterruptFunction |
Type of ISR function |
PORT_ISR_CAT1 |
PORT_ISR_VOID PORT_ISR_CAT1 PORT_ISR_CAT2 |
PORT_ISR_CAT1 |
PORT_ISR_VOID PORT_ISR_CAT1 PORT_ISR_CAT2 |
Enumeration |
4.14.10.3. Symbolic Names deviations¶
None.
4.14.10.4. Configuration rules and constraints to enable posibility checks¶
Will be updated in future release
4.14.11. 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.14.12. Memory footprint¶
Please refer Memory Footprint for more details.
4.14.13. Performance¶
Not Applicable
4.14.14. Example Usage¶
4.14.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=am273.
Once the build is completed we get a binary file,which is loaded in our controller and executed.
4.14.14.2. External set up Information¶
PORT module is tested using AM273x-evm board.
4.14.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 |
|---|---|
V9 |
MSS_GPIOA_0 |
G3 |
MSS_GPIOD_28 |
E19 |
RCSS_GPIOC_49 |
4.14.14.4. Example Logs¶
CLANG compiled : portApp: Sample Application - STARTS !!!
Port Driver version info:9.0.1
Port Driver Module/Driver:124.44
[RCSS INTR verification] => Please provide signal from Pin1 of J24 connector to Pin16 of J7 connector using jumper wire.
Interrupt -- PinNum : 49 Level : 0
[MSS INTR verification] => Press SW2 switch on board to trigger the interrupt
Interrupt -- PinNum : 28 Level : 1
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
Pin Value for channel 0 : 0
Dio_FlipChannel(channel_0)
Pin Value for channel 0 : 0
PORT Test Passed!!!
4.14.15. FAQ’s¶
None
4.14.16. Test Report(Link to test report)¶
Will be updated in future release
4.14.17. References¶
Autosar SWS 4.3.1 will be updated in future release.
4.14.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