4.14. ICU¶

4.14.1. Introduction¶

This document describes the functionality, API and configuration of the AUTOSAR BSW module Icu.

Supported AUTOSAR Release : 4.3.1

Supported Configuration Variants : Pre-Compile & Post-Build

Vendor ID : ICU_VENDOR_ID (44)

Module ID : ICU_MODULE_ID (122)

Supported Platform : AM263x

The ICU module initializes, configures and controls the internal hardware to realize ICU driver as detailed in AUTOSAR BSW ICU Driver Specification. The ICU functionality is realized through the ECAP IP available on the device. Following section highlights key aspects of this implementation, which would be of interest to an integrator.

4.14.2. Functional Description¶

The ICU driver uses ECAP module to capture events. In AM263x we have a total of 10 instances of ICU. The ICU driver provides the following features:

Signal Measurements - High time, Low time, Period time, Duty cycle
Edge Detection - Provide notification for each edge detected
Edge Counting - Measure edge counts
Edge Timestamping - Measure the absolute time when edges occur

##Clock Source to timers: Programming of clock source for the ICU module, is beyond the scope of this document. The driver expects that the user of this module has programmed required clock source. The example application demonstrates configuring clock sources for ECAP module

4.14.3. Configuration¶

The Icu Driver implementation supports pre as well as post compile configuration variants. The driver expects generated Icu_Cfg.h **to be present for selecting the variant. The associated Icu configuration generated files are **Icu_Cfg.c and Icu_PBcfg.c

By default Signal measurement mode is selected but if user want to change it to some other mode so in that case following operation they need to perform:

Change the configuration from the EB tresos tool.
So in case of icu, timestamp mode and edge detection mode also involve interupt callback to be registered.So by default we have given callback name in our application,with that name you can configure callback also in EB tresos.
For Edge detection mode callback name is: Icu_SignalNotification_Channel1 For Timestamp mode callback name is : Icu_TimeStampNotification_Channel1
Except this rest of the parameters can be configured as provided in EB plugin.

IsrCallback:

Mode	CallBack
Signal Measurement Mode	NA
Edge Detection Mode	Icu_SignalNotification_Channel1
TimeStamp Mode	Icu_TimeStampNotification_Channel1
Edge Count Mode	NA

The following section details on the un-supported features and additional features added.

4.14.3.1. Standard Configuration¶

Parameter	Description	Unit / DataType	Range
IcuMaxChannel	This parameter contains the number of Channels configured. It will be gathered by tools during the configuration stage	INTEGER	0-10
IcuChannelId	Channel Id of the ICU channel. This value will be assigned to the symbolic name derived of the IcuChannel container short name.	INTEGER	0-10
IcuDefaultStartEdge	Configures the default-activation-edge which shall be used for this channel if there was no activation-edge configured by the call of service Icu_SetActivationCondition().	ENUMERATION	ICU_BOTH_EDGES ICU_FALLING_EDGE ICU_RISING_EDGE
IcuMeasurementMode	Configures the measurement mode of this channel.	ENUMERATION	ICU_MODE_EDGE_COUNTER ICU_MODE_SIGNAL_EDGE_DETECT ICU_MODE_SIGNAL_MEASUREMENT ICU_MODE_TIMESTAMP
IcuWakeupCapability	Information about the wakeup-capability of this channel.	BOOLEAN	TRUE/FALSE
IcuSignalMeasurementProperty	Configures the property that could be measured in case the mode is "IcuSignalMeasurement&quot	ENUMERATION	ICU_DUTY_CYCLE ICU_HIGH_TIME ICU_LOW_TIME ICU_PERIOD_TIME
IcuTimestampMeasurementProperty	Configures the handling of the buffer in case the mode is "Timestamp&quot	ENUMERATION	ICU_CIRCULAR_BUFFER ICU_LINEAR_BUFFER
IcuDevErrorDetect	Switches the development error detection and notification on or off.	BOOLEAN	TRUE/FALSE
IcuReportWakeupSource	Switch for enabling Wakeup source reporting.	BOOLEAN	TRUE/FALSE
IcuDeInitApi	Adds/removes the service Icu_DeInit() from the code.	BOOLEAN	TRUE/FALSE
IcuDisableWakeupApi	Adds/removes the service Icu_DisableWakeup() from the code.	BOOLEAN	TRUE/FALSE
IcuEdgeCountApi	Adds/removes all services related to the edge counting functionality as listed below, from the code: Icu_ResetEdgeCount(), Icu_EnableEdgeCount(), Icu_DisableEdgeCount(), Icu_GetEdgeNumbers().	BOOLEAN	TRUE/FALSE
IcuEdgeDetectApi	Adds/removes the services related to the edge detection functionality	BOOLEAN	TRUE/FALSE
IcuEnableWakeupApi	Adds/removes the service Icu_EnableWakeup() from the code.	BOOLEAN	TRUE/FALSE
IcuGetDutyCycleValuesApi	Adds/removes the service Icu_GetDutyCycleValues() from the code.	BOOLEAN	TRUE/FALSE
IcuGetInputStateApi	Adds/removes the service Icu_GetInputState() from the code.	BOOLEAN	TRUE/FALSE
IcuGetTimeElapsedApi	Adds/removes the service Icu_GetTimeElapsed() from the code	BOOLEAN	TRUE/FALSE
IcuGetVersionInfoApi	Adds / removes the service Icu_GetVersionInfo() from the code.	BOOLEAN	TRUE/FALSE
IcuSetModeApi	Adds / removes the service Icu_SetMode() from the code.	BOOLEAN	TRUE/FALSE
IcuSignalMeasurementApi	Adds / removes the services Icu_StartSignalMeasurement() and Icu_StopSignalMeasurement() from the code.	BOOLEAN	TRUE/FALSE
IcuTimestampApi	Adds / removes all services related to the timestamping functionality as listed below from the code: Icu_StartTimestamp(), Icu_StopTimestamp(), Icu_GetTimestampIndex().	BOOLEAN	TRUE/FALSE
IcuWakeupFunctionalityApi	Adds / removes the service Icu_CheckWakeup() from the code.	BOOLEAN	TRUE/FALSE

4.14.3.2. IP Specific Configuration¶

Parameter	Description	Unit / DataType	Range
IntrCapSelect	Configures the capture event to enable interupt on that capture event or not	ENUMERATION	ECAP_CEVT1_INT ECAP_CEVT2_INT ECAP_CEVT3_INT ECAP_CEVT4_INT ECAP_CEVT1_CEVT2_INT ECAP_CEVT1_CEVT3_INT ECAP_CEVT1_CEVT4_INT ECAP_CEVT2_CEVT3_INT ECAP_CEVT2_CEVT4_INT ECAP_CEVT3_CEVT4_INT ECAP_CEVT1_CEVT2_CEVT3_INT ECAP_CEVT1_CEVT2_CEVT4_INT ECAP_CEVT1_CEVT3_CEVT4_INT ECAP_CEVT2_CEVT3_CEVT4_INT ECAP_INT_ALLCAPS
IcuPrescaler	Time-Base Clock Prescale Bits. Keep value as 0 to by-pass prescaler.	INTEGER	0-62
IcuFunctionalClock	Value of the System clock frequency in MHz Default frequency is 125MHz for ICU.	INTEGER	0-200
IcuIrqType	Type of Isr function: void functionname(void) CAT1 see description in oil tool:interrupt void func(void) CAT2 see description in oil tool:ISR(func)	ENUMERATION	ICU_ISR_VOID ICU_ISR_CAT1 ICU_ISR_CAT2
IcuDeviceVariant	Select SOC variant	ENUMERATION	AM263x AM273x
IcuEnableRegisterReadbackApi	Switch to indicate that the Icu_RegisterReadBack is supported	BOOLEAN	TRUE/FALSE
IcuXbarSelect	Configures the input select xbar to be used in order to give icu the required input	REFERENCE	ASPathDataOfSchema:/AUTOSAR/EcucDefs /Mcu/McuModuleConfiguration/ McuInputXbarChannelTriggerConfiguration

4.14.4. Variance / Deviation from the specification¶

APIs (listed below) related to wakeup capability are not supported as the hardware does not support.

Controlling Wakeup interrupts
Icu_SetMode()
Icu_DisableWakeup()
Icu_EnableWakeup()
Icu_CheckWakeup()

4.14.5. Implementation Specific Configurations¶

This driver implementation introduces below listed configurable options.

IcuFunctionalClock:

Name	IcuFunctionalClock
Description	Value of the system clock freq.
Container Name	IcuConfigSet
Type	Integer
Range	200 (default MHz clock)
Value Configuration Class	VARIANT-PRE-COMPILE

IcuClkprescaler:

Name	IcuClkPrescaler
Description	Used configure divider for the input clock This parameter could be used to divide this clock before it’s used to count.
Container Name	IcuChannelConfigSet
Type	uint8
Range	0 to 7
Value Configuration Class	VARIANT-PRE-COMPILE & VARIANT-POST-BUILD

4.14.6. Interrupt Configuration¶

The Driver doesn’t register any interrupts handler (ISR), it’s expected that consumer of this driver registers the required interrupt handler.

For every Icu channel with notification enabled, an ISR requires to be registered. The Interrupt number associated with instance of the ECAP is detailed in TRM (also, please refer the demo application). Please refer IcuApp() in Icu demo application.

Some of the ICU interrupts are not routed/mapped to this core, these interrupts would require additional programming to route these to this core. Please refer IcuApp() in Icu demo application.

4.14.7. X-Bar Configuration¶

In AM263X, we have X-Bar support which basically act as a mux and will be used to transmit output signal like of EPWM/GPIO to ECAP(ICU) input. Following steps need to be followed in order to configure Input X-Bar:

Input X-Bar for ICU is configured in MCU configuration.
In MCU configuration, McuInputXbarChannelTriggerConfiguration container is used to configure different X-Bar with different GPIO.

Figure 1: Input X-Bar is configured for GPIO61 which will be used by ICU.

Now in order to select a particular ECAP instance against that X-Bar which we have configured in MCU, their is a reference to the X-Bar in ICU.
XbarSelect parameter in ICU is the reference of the X-Bar which is configured in MCU.

Figure 2: In ICU Input X-Bar is referenced from MCU configuration.

NOTE: When a new X-Bar is configured in MCU then exactly same mapping to be selected for the reference XbarSelect parameter in ICU.

We have a support of Interrupt XBar which act as a mux for interrupts of the peripherals.So in order to provide flexibility to the user since their use cases will be different and our SOC has so many peripherals and a large amount of events like interrupts etc, interrupt XBar is used. Following steps need to be followed in order to configure Interrupt X-Bar:

Interrupt X-Bar for ICU is configured in MCU configuration.
In MCU configuration, McuXbarChannelTriggerConfiguration container is used to configure different X-Bar Interrupt with different peripheral.
Now interrupt registration for the particular X-Bar interrupt, need to be done at the application side of the peripheral.
For example: For ICU, X-Bar Interrupt number 22 is configured in MCU and with the same Interrupt is registered in ICU application.

4.14.8. Non Standard Service APIs¶

As noted from the previous MCAL implementation, some of the critical configuration registers could potentially be corrupted by other entities (s/w or h/w). One of the recommended detection methods would be to periodically read-back the configuration and confirm configuration is consistent. The service API defined below shall be implemented to enable this detection.

	Description	Comments
Service Name	Icu_RegisterReadback	Can potentially be turned OFF
Syntax	Icu_RegisterReadback(Icu_ChannelType Channel,P2VAR(Icu_RegisterReadbackType, AUTOMATIC, ICU_APPL_DATA) RegRbPtr)	E_OK: Register read back has been done, E_NOT_OK: Register read back failed. Icu_RegisterReadbackType defines the type, that holds critical
Parameter in	Channel	Numeric identifier of the ICU channel
Asyn/Syn	Sync	NA
Re-entrancy	Non Reentrant	NA
Parameter out	RegRbPtr	A pointer of type Icu_RegisterReadbackType, which holds the read back values.
Return value	Std_ReturnType	E_OK or E_NOT_OK in case of Icu not initialized or NULL buffer pointer

4.14.9. Build and Running the Example Application¶

Please follow steps detailed in section to build library or example.

ECAP based application name - icu_app

This application uses the PWM (Enhanced Pulse Width Module) to provide input to ECAP instance. The ECAP module (with ICU driver) will capture the signals provided as input.

4.14.10. Memory Mapping¶

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file defines separate section for these objects. When the driver is integrated, its expected that these sections are created and placed in appropriate memory locations. (Locations of these objects depend on the system design and performance needs)

Memory Mapping Sections	ICU_CODE	ICU_VAR_INIT	ICU_VAR_NOINIT	ICU_CONST	ICU_CONFIG
ICU_START_SEC_VAR_INIT_UNSPECIFIED (.data)		USED
ICU_DATA_INIT_32_SECTION		USED
ICU_TEXT_SECTION	USED
ICU_DATA_NO_INIT_UNSPECIFIED_SECTION			USED
ICU_CONST_32_SECTION				USED
ICU_ISR_TEXT_SECTION	USED
ICU_CONFIG_SECTION					USED

4.14.11. Cache¶

This driver implementation has been validated with cache enabled. For optimal performance it’s recommended to place memmap sections in cache enabled memory area.

4.14.12. Dependencies on SW Modules¶

DET: This implementation depends on the DET in order to report development errors and can be turned OFF. Refer section (13) for detailed error codes.

4.14.13. File Structure¶

Driver implemented by : Icu.h, Icu_Irq.h, Icu.c, Icu_Priv.c ,Icu_Irq.c and Icu_Priv.h

Example application:

There is one example application provided: icu_app. Please refer to below directory structures.
Config files for icu_app are located along with other applications’ configs at /mcal_sitara_mcu/mcal/examples/config/Icu_Cfg and Icu_PBcfg can also be found as this location.
Icu_Cfg.h: Contains static configuration of this module.
Icu_Cfg.c: Shall implement the generated configuration for pre-compile variant.
Icu_PBcfg.c: Shall implement the generated configuration for post-build variant
IcuApp.c and IcuApp.h: Shall implement the start-up code sequence and register interrupts and also shall implement the example application that demonstrates the use of the driver.

4.14.14. Development Error Reporting¶

Development errors are reported to the DET using the service Det_ReportError(), when enabled.

Error codes

Type of Error	Related Error code	Value (Hex)
API is called with invalid pointer	ICU_E_PARAM_POINTER	0x0A
API service used with an invalid channel identifier or channel was not configured for the functionality of the called API	ICU_E_PARAM_CHANNEL	0x0B
API service used with an invalid or not feasible activation	ICU_E_PARAM_ACTIVATION	0x0C
Init Function Failed	ICU_E_INIT_FAILED	0x0D
API service used with an invalid bugger size	ICU_E_PARAM_BUFFER_SIZE	0x0E
API serice Icu_SetMode used with an invalid mode	ICU_E_PARAM_MODE	0x0F
API service used without module initialization	ICU_E_UNINIT	0x14
API serice Icu_SetMode is called while in running operation	ICU_E_BUSY_OPERATION	0x16
API Icu_Init ervice is called and when the ICU driver and the Hardware are already Initialized	ICU_E_ALREADY_INITIALIZED	0x17
API Icu_StartTimeStamp is called and the parameter NotifyInterval is Invalid	ICU_E_PARAM_NOTIFY_INTERVAL	0x18
API Icu_GetVersionInfo is called and the parameter versioninfo is invalid	ICU_E_PARAM_VINFO	0x19

Runtime Errors

Type of Error	Related Error code	Value (Hex)
API service Icu_StopTimestamp called on a channel which was not started or already stopped	ICU_E_NOT_STARTED	0x15

4.14.15. API Description¶

The AUTOSAR BSW ICU Driver specification details the APIs required for Icu Driver. Please refer to (Refer to SWS of ICU ) for detailed API description. APIs related to wakeup capability are not implemented.

4.14.16. Example Application¶

In the IcuApp.c , following steps are there:

Firstly the pin mux is initialize
UART is enabled.
After that EPWM is enabled , since the output of EPWM is used as an input to our ICU.
After that the ICU is initialize
So by default we have configured ICU in signal measurement mode, but if the user want to change then they need to change the configuration accordingly.
By default we are using EPWM0 for our input to ICU.
And we are taking ECAP0( ICU 0^TH instance ) for the demonstration of our example.
So now when we execute our example with default configuration we will be getting active time, period time and duty cycle as part of the signal measurement.

4.14.17. References¶

AUTOSAR_SWS_ICUDriver

Technical Reference Manual

4.14.18. Document Revision History¶

Version	Date	Author	Revision History
1.0	21 October 2022	Mudit Bhansali	Initial Version
1.1	17 November 2022	Mudit Bhansali	Driver Api’s according to autosar specification
1.2	24 February 2023	Mudit Bhansali	Driver Api’s according to autosar specification
1.3	31 January 2023	pranay krosuri	Configuration parameters Added

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