4.12. ICU¶
4.12.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 : AM273x
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.12.2. Functional Description¶
The ICU driver uses ECAP module to capture events. In AM273x we have a total of 3 instances of ICU ( MSS_I2C, RCSS_I2CA and RCSS_I2CB). 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.12.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.12.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.12.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.12.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.12.7. 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.12.8. Power-up¶
The driver doesn’t configure the functional clock and power for the timer modules. Its expected that SBL power-up the required modules. Please refer SBL documentation.
4.12.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.12.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.12.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.12.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.12.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.12.14. Development Error Reporting¶
Development errors are reported to the DET using the service Det_ReportError(), when enabled.
4.12.14.1. 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.12.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.12.16. Example Application¶
In the IcuApp.c , following steps are there:
Firstly the pin mux is initialized
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 initialized
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 0TH 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.12.17. References¶
AUTOSAR Spec : Refer to SWS of ICU for AUTOSAR 4.3.1
Technical Reference Manual: AM273X Technical Reference Manual
4.12.18. Document Revision History¶
Version |
Date |
Revision History |
|---|---|---|
1.0 |
07 Aug 2023 |
Initial Version |
4.12.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