4.15. ICU Module

4.15.1. Acronyms and Definitions

Abbreviation/Term

Explanation

AUTOSAR

Automotive Open System Architecture

BSW

Basic Software

MCAL

Micro Controller Abstraction Layer

API

Application Programming Interface

DET

Default Error Tracer

ICU

Input Capture Unit

ECAP

Enhanced Capture

MCU

Micro Controller Unit

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

AM263Px

4.15.3. Functional Overview

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.15.3.1. Functional Description

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

  1. Signal Measurements - High time, Low time, Period time, Duty cycle

  2. Edge Detection - Provide notification for each edge detected

  3. Edge Counting - Measure edge counts

  4. 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.15.4. Hardware Features

4.15.4.1. IP Supported Features

Will be added in future releases:

4.15.4.2. AUTOSAR Supported Features

Will be added in future releases:

4.15.4.3. Not supported Features

Will be added in future releases:

4.15.5. Source files

Description of static files is provided below:

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Icu
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┣ 📜Icu.h : Contains the API’s of the ICU driver to be used by upper layers
┃ ┃ ┃ ┗ 📜Icu_Irq.h : Contains ISR function declaration
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📜Icu.c : Contains the implementation of the API’s for ICU driver
┃ ┃ ┃ ┗ 📜Icu_Irq.c : Contains ISR function definitions
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┣ 📜ecap.h : Contains Internal functions declaration of ICU driver
┃ ┃ ┃ ┣ 📜ecap.c : Contains Internal Functions definitions
┃ ┃ ┃ ┣ 📜hw_icu.h : Contains Internal functions declaration of ICU driver
┃ ┃ ┃ ┣ 📜Icu_Priv.c : Contains Internal Functions definitions
┃ ┃ ┃ ┗ 📜Icu_Priv.h : Contains Internal Functions declaration
┃ ┃ ┗ 📜Makefile
┣ 📂mcal_config
┣ 📂mcal_docs
┗ 📜README.txt

Description of generated files is provided below:

Plugin Files

Description

Icu_Cfg.h

Contains static configuration of this module

Icu_PBcfg.c

Contain the generated configuration for post-build variant

Icu_Cfg.c

Contain the generated configuration for pre-compile variant

4.15.6. Module requirements

Will be updated in future release:

4.15.6.1. Memory Mapping

Memory Mapping Sections

ICU_CODE

ICU_VAR_INIT

ICU_VAR_NOINIT

ICU_CONST

ICU_CONFIG

ICU_START_SEC_VAR_INIT_UNSPECIFIED (.data)

x

ICU_DATA_INIT_32_SECTION

x

ICU_TEXT_SECTION

x

ICU_DATA_NO_INIT_UNSPECIFIED_SECTION

x

ICU_CONST_32_SECTION

x

ICU_ISR_TEXT_SECTION

x

ICU_CONFIG_SECTION

x

4.15.6.2. 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.15.6.3. Scheduling

4.15.6.3.1. SchM (Optional)

Will be added in future release :

4.15.6.3.2. Critical Sections

Will be added in future release :

4.15.6.4. Error handling

4.15.6.4.1. Development Error Reporting

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

4.15.6.5. Error codes

4.15.6.5.1. Development Errors

The errors reported to DET module are described in the following table:

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 buffer 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 service 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

4.15.6.5.2. 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.15.7. Used resources

4.15.7.1. Interrupt Handling

Will be updated in future release:

4.15.8. Integration description

4.15.8.1. Dependent modules

4.15.8.1.1. DET

This implementation depends on the DET in order to report development errors. The detection of development errors is configurable (ON / OFF).

4.15.8.2. Multi-core and Resource allocator

Not Supported

4.15.9. 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:

  1. Change the configuration from the EB tresos tool.

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

  3. For Edge detection mode callback name is: Icu_SignalNotification_Channel1.
    For Timestamp mode callback name is : Icu_TimeStampNotification_Channel1

  4. 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.15.9.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-16

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-16

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”

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;”

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

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

AM263Px

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.15.9.3. 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.15.9.4. 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.15.9.5. 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.15.9.6. X-Bar Configuration

In AM263Px, 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:

1.Input X-Bar for ICU is configured in MCU configuration.

2.In MCU configuration, McuInputXbarChannelTriggerConfiguration container is used to configure different X-Bar with different GPIO.

Input X-Bar is configured for GPIO61 which will be used by ICU

Fig. 4.76 Input X-Bar is configured for GPIO61 which will be used by ICU

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

4.XbarSelect parameter in ICU is the reference of the X-Bar which is configured in MCU.

In ICU Input X-Bar is referenced from MCU configuration

Fig. 4.77 In ICU Input X-Bar is referenced from MCU configuration

5.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:

  1. Interrupt X-Bar for ICU is configured in MCU configuration.

  2. In MCU configuration, McuXbarChannelTriggerConfiguration container is used to configure different X-Bar Interrupt with different peripheral.

  3. Now interrupt registration for the particular X-Bar interrupt, need to be done at the application side of the peripheral.

  4. For example: For ICU, X-Bar Interrupt number 22 is configured in MCU and with the same Interrupt is registered in ICU application.

4.15.10. Examples

4.15.10.1. Overview

Will be updated in future release:

4.15.10.2. Setup required to run example

Will be updated in future release:

4.15.10.3. How to run examples

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

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.

  • 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.15.10.3.2. Flow of the example application

In the IcuApp.c , following steps are there:

  1. Firstly the pin mux is initialize

  2. UART is enabled.

  3. After that EPWM is enabled , since the output of EPWM is used as an input to our ICU.

  4. After that the ICU is initialize

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

  6. By default we are using EPWM0 for our input to ICU.

  7. And we are taking ECAP0( ICU 0\ :sup:TH instance ) for the demonstration of our example.

  8. 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.15.10.4. Sample Log



IcuApp: Sample Application - STARTS !!!
  
ICU_APP: ICU MCAL Version Info
---------------------
ICU_APP: Vendor ID: 44
ICU_APP: Module ID: 122
ICU_APP: SW Major Version: 10
ICU_APP: SW Minor Version: 0
ICU_APP: SW Patch Version: 0
 
ICU_APP: Variant - Post Build being used !!!
 
ICU_APP: Signal Measurement Mode! 
ICU_APP: elapsed time (Period) is  998 us
ICU_APP: Active Time is 499 
ICU_APP: Period Time is 998 
ICU_APP: Duty Cycle is 0.500000
ICU_APP: elapsed time read is  0 us
ICU_APP: elapsed time (Period) is  998 us
ICU_APP: Active Time is 499 
ICU_APP: Period Time is 998 
ICU_APP: Duty Cycle is 0.500000
All tests have passed

4.15.10.5. File Structure

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Icu
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┣ 📜IcuApp.c : Contains Icu test example
┃ ┃ ┃ ┣ 📜IcuApp.h : Contains Icu test example header file
┃ ┃ ┃ ┗ 📜Makefile
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Icu_Demo_Cfg
┃ ┃ ┃ ┗ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┗ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Icu_Cfg.h : Contains the configuration parameters
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Icu_Cfg.c : Contains all Pre-Compile Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜Icu_PBcfg.c : contains all Post build configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┗ 📜README.txt

4.15.10.6. Test Report

Please refer AM26x ICU Driver Test Case Report as part of CSP provided in the release package.

4.15.11. References

AUTOSAR_SWS_ICUDriver\

Technical Reference Manual