MCUSW
Icu User Guide

Introduction

This document details AUTOSAR BSW ICU module implementation

  • 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)

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.

Icu Driver Architecture/Design

Please refer the ICU design, which is included as part of release (Icu Design Document)

Functional Description

The Icu driver uses ECAP module to capture events. There are three ECAP instances available to work with (ECAP0 - ECAP2) on J721E and J7200. 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.

Back To Top

Icu Channel ID , Instance mapping and ISR mapping

The Icu module is implemented using the ECAP instances on the device.

Three ECAP instances are supported by this driver implementation (three instances present in MAIN domain on J721E & J7200). The following table lists the mapping between instance of ECAP and IcuChannelId of the configurator.

IcuChannelId ECAP Instance Associated ISR (if notification is enabled)
0 ECAP0 Icu_ch0Notify
1 ECAP1 Icu_ch1Notify
2 ECAP2 Icu_ch2Notify

Back To Top

Configuration

The Icu Driver implementation supports multiple configuration variants (refer section Introduction), the driver expects generated Icu_Cfg.h to be present as (File Structure). Please refer (Build) to specify path to generated configuration. The associated Icu configuration generated files Icu_Cfg.c and Icu_PBcfg.c to be present as shown (File Structure)

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

Variance / Deviation from the specification

APIs related to wakeup capability

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()

Please note that only preliminary functionality testing has been done on ICU driver module. Unit Test and API testing is planned for future releases.

Back To Top

Implementation Specific Configurations

This driver implementation introduces below listed configurable options

Back To Top

IcuFunctionalClock

Name IcuFunctionalClock
Description Value of the system clock freq.
Container Name IcuConfigSet
Type Integer
Range 125 (Default MHZ Clock)
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top

IcuDeviceVariant

Name IcuDeviceVariant
Description Used to specific family of devices, the variant of the device being used will belong one or more family of devices. Please refer (Supported Device Families) to determine the family of device.
Container Name IcuGeneral
Type Enumeration
Range J721E, J7200, etc… (new family of devices could be added in future)
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top

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

Back To Top

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_InterruptConfig () 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_IntrConfig () in Icu demo application.

Refer section (Icu Channel ID , Instance mapping and ISR mapping), for association between channel ID and ISR

Back To Top

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.

Back To Top

Build and Running the Example Application

Please follow steps detailed in section (Build) 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.

Modification to EVM are required to ensure that EPWM signal is fed into the ECAP input.

For example, to run the icu_app:

  1. J721E: Uses instance ECAP1 instance and EPWM1 instance User need to connect EPWM output (Pin 2 on J22 on GESI Expansion Board) to ECAP input (TP30 on SOM Board).
  1. J7200: Uses instance ECAP0 instance and EPWM1 instance User need to connect EPWM output (Pin 2 on J22 on GESI Expansion Board) to ECAP input (TP97 on base Board).

The icu_app by default is configured to use "Signal Detect Measurement Mode". The configuration set can be modified to test out a different mode.

caution.png

Please note that since EPWM module is used internally by the icu_app, it is required to perform a clean build.

Back To Top

Steps to run example application

Please refer (Running Examples)

Back To Top

Memory Mapping

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file at (Examples Linker File (Select memory location to hold example binary)) 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)

Section 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

Back To Top

Cache

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

Back To Top

Prescaler/Dividers for ECAP based implementation

Prescaler value can be set using the IcuClkPrescaler vairable. Please note that various prescaler values (apart from 0) has not been tested for Icu driver. This activity is planned for later release.

Back To Top

Dependencies on SW Modules

DET

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

Back To Top

SchM

This implementation requires 1 level of exclusive access to guard critical sections. Invokes SchM_Enter_Icu_ICU_EXCLUSIVE_AREA_0 (), SchM_Exit_Icu_ICU_EXCLUSIVE_AREA_0 () to enter critical section and exit.

In the example implementation (File Structure SchM_Icu.c) , all the interrupts on CPU are disabled. However, disabling of the enabled ECAP interrupt should suffice.

Back To Top

File Structure

  1. 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' demo configs at /workarea/mcusw/mcal_drv/mcal/example/Icu/icu_app/Icu_Demo_Cfg. Pwm_Demo_Cfg 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_Startup.c and IcuApp_Startup.h: Shall implement the start-up code sequence and register interrupts.
  • IcuApp.c and IcuApp.h: Shall implement the example application that demonstrates the use of the driver

Back To Top

Error Handling

Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface (Icu.h File Structure) lists the SID.

Back To Top

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

Back To Top

API Description

The AUTOSAR BSW ICU Driver specification details the APIs required for Icu Driver. Please refer to (Low Level Definitions) for detailed API description. APIs related to wakeup capability are not implemented, please refer to (Variance / Deviation from the specification).

Refer API Documentation for details

Back To Top

Example Application

IcuApp

The example application demonstrate use of ECAP based Icu module, the list below identifies key steps performed the example. The configuration file is present at (File Structure)

To run the icu_app:

  1. J721E: Uses instance ECAP1 instance and EPWM1 instance User need to connect EPWM output (Pin 2 on J22 on GESI Expansion Board) to ECAP input (TP30 on SOM Board).
  1. J7200: Uses instance ECAP0 instance and EPWM1 instance User need to connect EPWM output (Pin 2 on J22 on GESI Expansion Board) to ECAP input (TP97 on base Board).
  • Initializes “Result Status Flag”
  • IcuApp_Startup ()
    • Initialize board for pin mux
    • Initialize the control mmr registers for ECAP io muxing
    • Builds interrupt list and registers ISR for the enabled Icu channel
  • IcuApp_mainTest ()
    • Initializes EPWM module (Clock config, Pinmux, interrupt registration)
    • Initializes EPWM module to 60 Percent, 1000Hz signal.
    • Initialize and start ICU module
    • Selects the functional API flow based on measurement mode selected in configurator
    • By default, Edge Detect Mode is configured.
    • Check input state of channel.
    • Enable Notification for channel.
    • Enable Edge Detection for channel.
    • Wait 1 sec (capture edges for 1 sec)
    • Count the number of notifications (edges) reached in 1 sec.
    • Disable edge detection.
    • Set activation edge to both edges (default is set to rising edge only)
    • Enable edge detection again, wait 1 sec, and count the number of edges.
    • Disable edge detection.
    • Set EPWM signal output to 25000Hz.
    • Follow above sequence again to count number of edges in 1 sec.
    • De-initialize and Stop Icu
  • Checks for error status, stack corruption and prints result

Back To Top

Example Log

J721E - icu_app

    ICU_APP: Sample Application - STARTS !!!                                                                                           

    ICU_APP: ICU MCAL Version Info                                                                                                     
    ---------------------                                                                                                              
    ICU_APP: Vendor ID           : 44                                                                                                  
    ICU_APP: Module ID           : 122                                                                                                 
    ICU_APP: SW Major Version    : 1                                                                                                   
    ICU_APP: SW Minor Version    : 3                                                                                                   
    ICU_APP: SW Patch Version    : 2                                                                                                   

    ICU_APP: Variant - Pre Compile being used !!!                                                                                      

    ICU_APP: EPWM Channel Initialized                                                                                                  
    ICU_APP: EPWM Duty cycle: 60 Percent, 1000Hz                                                                                       
    ICU_APP: Use EPWM (Pin 2 in J22 on GESI Board) as input to ECAP test point (TP30 on SOM board) for J721E EVM                       
    ICU_APP: Edge Detect Mode!                                                                                                         
    ICU_APP: input state is ICU_IDLE                                                                                                   
    ICU_APP: SignalNotification for Double Edge Detection Reached in 1 sec: 2000                                                       
    ICU_APP: SignalNotification for Single Edge Detection Reached in 1 sec: 1000                                                       
    ICU_APP: input state is ICU_ACTIVE                                                                                                 

    ICU_APP: Changing EPWM Frequency from 1000Hz to 25000Hz and Duty Cycle to 50%                                                      
    ICU_APP: Edge Detect Mode!                                                                                                         
    ICU_APP: input state is ICU_IDLE                                                                                                   
    ICU_APP: SignalNotification for Single Edge Detection Reached in 1 sec: 25002                                                      
    ICU_APP: input state is ICU_ACTIVE                                                                                                 
    ICU_APP: SignalNotification for after disabling notification Edge Detection Reached: 0                                             
    ICU_APP: Calling Deinit                                                                                                            
    ICU_APP: Icu Stack Usage 1076 bytes                                                                                                
    ICU_APP: ICU Test Passed!!!

J7200 - icu_app

    ICU_APP: Sample Application - STARTS !!!                                                                                           

    ICU_APP: ICU MCAL Version Info                                                                                                     
    ---------------------                                                                                                              
    ICU_APP: Vendor ID           : 44                                                                                                  
    ICU_APP: Module ID           : 122                                                                                                 
    ICU_APP: SW Major Version    : 1                                                                                                   
    ICU_APP: SW Minor Version    : 3                                                                                                   
    ICU_APP: SW Patch Version    : 2                                                                                                   

    ICU_APP: Variant - Pre Compile being used !!!                                                                                      

    ICU_APP: EPWM Channel Initialized                                                                                                  
    ICU_APP: EPWM Duty cycle: 60 Percent, 1000Hz                                                                                       
    ICU_APP: Use EPWM (Pin 2 in J22 on GESI Board) as input to ECAP test point (TP97 on base board) for J7200 EVM                      
    ICU_APP: Edge Detect Mode!                                                                                                         
    ICU_APP: input state is ICU_IDLE                                                                                                   
    ICU_APP: SignalNotification for Double Edge Detection Reached in 1 sec: 2000                                                       
    ICU_APP: SignalNotification for Single Edge Detection Reached in 1 sec: 1000                                                       
    ICU_APP: input state is ICU_ACTIVE                                                                                                 

    ICU_APP: Changing EPWM Frequency from 1000Hz to 25000Hz and Duty Cycle to 50%                                                      
    ICU_APP: Edge Detect Mode!                                                                                                         
    ICU_APP: input state is ICU_IDLE                                                                                                   
    ICU_APP: SignalNotification for Single Edge Detection Reached in 1 sec: 25002                                                      
    ICU_APP: input state is ICU_ACTIVE                                                                                                 
    ICU_APP: SignalNotification for after disabling notification Edge Detection Reached: 0                                             
    ICU_APP: Calling Deinit                                                                                                            
    ICU_APP: Icu Stack Usage 1328 bytes                                                                                                
    ICU_APP: ICU Test Passed!!!

Back To Top

References

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 09 March 2021 Nikki Shah First version Pending Review
0.2 16 March 2021 Nikki Shah Update Approved