MCUSW
Icu Design Document

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)

Overview

The figure below depicts the AUTOSAR layered architecture as 3 distinct layers,

  • Application
  • Runtime Environment (RTE) and
  • Basic Software (BSW).

The BSW is further divided into 4 layers:

  • Services
  • Electronic Control Unit Abstraction
  • MicroController Abstraction (MCAL) and
  • Complex Drivers.
autosar_acrhitecture_common.png
AUTOSAR Architecture

MCAL is the lowest abstraction layer of the Basic Software. It contains internal drivers that are software modules that interact with the Microcontroller and its internal peripherals directly. ICU driver will use ECAP (Enhanced Capture) hardware IP for demodulation of a PWM signal, counting pulses, measuring of frequency and duty cycle and generating simple interrupts.

Icu Overview

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

The hardware ECAP module includes the following features:

  • 32-bit time base Counter
  • 4x32 event time-stamp capture Registers
  • Interrupt capability for capture events
  • Absolute time-stamp capture
  • Difference (Delta) mode time-stamp capture
  • All above resources dedicated to a single input pin

Please note that this is just for reference purpose, for other details please refer to technical reference manual. Note that not all feature available in ECAP hardware IP are currently supported by ICU driver.

Diagrams are from device TRM.

Icu

icu_design_blockdiagram.png
ICU Block Diagram

Back To Top

References

Sl No Specification Comment / Link
1 AUTOSAR 4.3.1 AUTOSAR Specification for Icu Driver Internet Link
2 TDA4x TRM Technical Reference Manual, TDA4X
3 BSW General Requirements / Coding guidelines Intranet Link
4 Software Product Specification (SPS) Intranet Link Requirements are derived from 1

Requirements

The Icu Driver implements a standardized interface specified in the AUTOSAR_SWS_ICUDriver document, specified in: 4, 1 and 3. It’s recommended to refer 1 for clarification.

Features Supported

  • Capture Functionality using the ECAP module.
  • Edge polarity (activation) setting.
  • Enabling of Development Error Detection and Runtime Error Detection.

Back To Top

caution.png

Features Not Supported / NON Compliance

Hardware does not support wakeup capability. Hence, the below features are not supported.
- Controlling Wakeup interrupts.
- Icu_SetMode()
- Icu_DisableWakeup()
- Icu_EnableWakeup()
- Icu_CheckWakeup()

Back To Top

Assumptions

Below listed points are assumed to be valid for this design/implementation, exceptions and other deviations are listed for each explicitly. Care should be taken to ensure these assumptions are addressed.

  1. The functional clock to the Icu module is expected to be ON before calling any Icu service APIs. The Icu driver doesn’t perform any programming to enable the module functional clock. The default functional clock is 125Mhz.
  2. Interrupt configuration for Icu interrupt registration should be done by application. Refer to example application for reference.
  3. The Icu module depends on the system clock, prescalers and PLL.

Back To Top

Design Description

Fundamental Operation

  • ECAP Edge Polarity Select and Qualifier Four Independent edge polarity selection multiplexers are used, one for each capture event. Each edge(capture event) will have the polarity set according to the activation edge selected.
  • ECAP Interrupt Control An interrupt can be generated on capture events 1 through 4. In ICU driver module, interrupt will be generated for every single capture event - so all 4 capture events are triggered for edge counting, edge detection, timestamp calculation and signal measurements.

Sequence Diagrams

The Icu driver follows the code sequence outlined by the Autosar Spec for Icu Module. Please refer to 1 for more details.

Back To Top

Resource Behavior

There are no hard requirements for resource allocation for Icu driver. Average Stack Size of ICU Driver is around 2 kilo bytes.

Back To Top

Interrupt Service Routines

An interrupt can be generated on capture events 1 through 4. In ICU driver module, interrupt will be generated for every single capture event - so all 4 capture events are triggered for edge counting, edge detection, timestamp calculation and signal measurements.

When a capture event occurs and capture register reads value, an interrupt flag will be raised for that event. The ISR in ICU module will recognize the the capture event and perform required steps based on the measurement mode (Please refer to 1) selected in configurator. For example, if Timestamp measurement mode is selected, the timestamp specific ISR will be called, required values will be stored in module, and interrupts will be cleared from there.

Back To Top

Time Unit Ticks

Refer 1 specifically section 7.1.3 of the specification for more details

All time units used within the API services of the ICU module shall be of the unit ticks.

Back To Top

Dynamic Behavior

The ICU Module can have two states: IC_STATUS_UINIT (before the module had been initialized with Icu_Init) and ICU_STATUS_INIT (after module has been initialized).

The ICU State (logical input state of ICU Channel) can be ICU_ACTIVE or ICU_IDLE. ICU_ACTIVE - Input state of an ICU Channel, and activation edge has been detected. ICU_IDLE - Input state of an ICU Channel, no activation edge had been detected since last call of Icu_GetInputState() or Icu_Init().

Design ID DES_ICU_001
Requirements Covered MCAL-4591

Back To Top

Directory Structure

The diagram below shows the overall files structure for the Icu driver.

Icu Directory Structure

Icu_Dir_Struct.png
ICU Directory Structure

Driver Implemented by

  • Icu.h, Icu_Priv.h : Shall implement the interface provided by the Icu driver
  • Icu_Irq.h Contains ISR function declaration.
  • Icu.c, Icu_Priv.c Icu_Irq.c : Shall implement the driver functionality

Example Application

  • Icu_Cfg.h: Shall implement the generated configuration for Pre-Compile variant
  • Icu_PBCfg.h: Shall be used for Post-Build variant
  • IcuApp.c and IcuApp_Startup.c: Shall implement the example application that demonstrates the use of the driver
Design ID DES_ICU_002
Requirements Covered MCAL-4569, MCAL-4570, MCAL-4571, MCAL-4572, MCAL-4573, MCAL-4574, MCAL-4575, MCAL-4576, MCAL-4577, MCAL-4578, MCAL-4579

Back To Top

Configurator

The AUTOSAR Icu Driver Specification details mandatory parameters that shall be configurable via the configurator. Please refer section 10 1 Error Checks are common for variants of devices and we can do this in xdm or generator code.

Design ID DES_ICU_003
Requirements Covered MCAL-4534, MCAL-4535, MCAL-4536, MCAL-4538, MCAL-4539, MCAL-4541, MCAL-4542, MCAL-4544, MCAL-4545, MCAL-4546, MCAL-4547, MCAL-4549, MCAL-4550, MCAL-4552, MCAL-4553, MCAL-4554, MCAL-4555, MCAL-4557, MCAL-4558, MCAL-4559, MCAL-4560, MCAL-4561, MCAL-4562, MCAL-4563, MCAL-4566, MCAL-4567

NON Standard configurable parameters

The design's specific configurable parameters are as follows:

Parameter Usage comment
IcuFunctionalClock This is the value of the System Clock freq
IcuDeviceVariant This shall allow integrators to select the device variant for which integration is being performed. This parameter shall be used by driver to impose device specific constraints. The user guide shall detail the device specific constraints
IcuClkPrescaler This parameter allows the selection of pre-scalar value.The prescaler stage is clocked with the ICU clock and acts as a clock divider for the time-base clock.
Design ID DES_ICU_004
Requirements Covered MCAL-5168, MCAL-5169, MCAL-5170

Back To Top

Variant Support

The driver shall support both VARIANT-PRE-COMPILE & VARIANT-POST-BUILD.

Back To Top

Error Classification

There are two types of errors in Icu module - Developement Erros and RunTime Errors.

Development Errors

AUTOSAR requires that API functions check the validity of their parameters and module status. The checks in table are internal parameter checks of the API functions. These checks are for development error reporting and can be enabled or disabled.

Design ID DES_ICU_005
Requirements Covered MCAL-4585, MCAL-4586

Development Error Reporting

The detection of development errors is configurable (ON / OFF) at pre-compile time. The switch ICU_DEV_ERROR_DETECT will activate or deactivate the detection of all development errors.

By default, development errors are reported to the DET using the service Det_ReportError(), if development error detection and reporting are enabled (i.e. checkboxes Development Mode and Development Error Reporting are checked).

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

Debugging support

Icu driver makes driver status available for debugging. The input channel status can be probed using the Icu_GetInputState() API.

Back To Top

Resource Behavior

  • Code Size : Implementation of this driver shall not exceed 40 kilo bytes of code and 5 KB of data section.
  • Stack Size : Worst case stack utilization shall not exceed 2 kilo bytes.

Back To Top

Low Level Definitions

The detailed API and interface description is available as part of 1 & 4. This section describes the API supported by the MCAL driver and the requirements covered by each of the API.

MACROS, Data Types & Structures

The sections below lists some of key data structures that shall be implemented and used in driver implementation.

Max Number Channels

Type Identifier Comments
uint32 ICU_MAX_NUM_CHANNELS Defines the maximum number of instances available in ICU module. This is specific to SoC being used (3 for J721E and J7200).

Icu_ModeType

Used to allow enabling/disabling of all interrupts which are not required for the ECU wakeup. This will only be set to ICU_MODE_NORMAL as wakeup capability is not supported by hardware. Please refer section 8.2.1 of 1.

Icu_ChannelType

Numeric identifier of an ICU Channel. Please refer section 8.2.2 of 1.

Icu_InputStateType

Input state of an ICU channel. Please refer section 8.2.3 of 1.

Icu_ConfigType

This type contains initialization data. Please refer section 8.2.4 of 1.

Icu_ActivationType

Definition of the type of activation of an ICU channel. Please refer section 8.2.5 of 1.

Icu_ValueType

Width of the buffer for timestamp ticks and measured elapsed timeticks. This will be 32-bit to match the hardware timer. Please refer section 8.2.6 of 1.

Icu_DutyCycleType

Type which shall contain the values, needed for calculating duty cycle. Please refer section 8.2.7 of 1.

Icu_IndexType

Icu Index time to abstract the reutn value of service Icu_GetTimestampIndex() Please refer section 8.2.8 of 1.

Icu_EdgeNumberType

Type to abstract the return value of the service Icu_GetEdgeNumbers(). Please refer section 8.2.9 of 1.

Icu_MeasurementModeType

Definition of the measurement mode type. Please refer section 8.2.10 of 1.

Icu_SignalMeasurementPropertyType

Definition of the measurement property type. Please refer section 8.2.11 of 1.

Icu_TimestampBufferType

Definition of the timestamp measurement property type. Please refer section 8.2.12 of 1.

APIs

For the standard APIs please refer 8.3 of 1. Sections below highlight other design considerations for the implementation.

Icu_Init

Refer section 8.3.1 of 1

Design ID DES_ICU_006
Requirements Covered MCAL-4610, MCAL-4611, MCAL-4612, MCAL-4613, MCAL-4614, MCAL-4616, MCAL-4617, MCAL-4618, MCAL-4619, MCAL-4620

Back To Top

Icu_Deinit

Refer section 8.3.2 of 1

Design ID DES_ICU_007
Requirements Covered MCAL-4621, MCAL-4622, MCAL-4623, MCAL-4624, MCAL-4625, MCAL-4626, MCAL-4627, MCAL-4628, MCAL-4629, MCAL-4630

Back To Top

Icu_SetActivationCondition

Refer 8.3.7 of 1

Design ID DES_ICU_008
Requirements Covered MCAL-4659, MCAL-4660, MCAL-4661, MCAL-4662, MCAL-4663, MCAL-4664

Back To Top

Icu_DisableNotification

Refer section 8.3.8 of 1

Design ID DES_ICU_009
Requirements Covered MCAL-4665, MCAL-4666, MCAL-4667, MCAL-4668

Back To Top

Icu_EnableNotification

Refer section 8.3.9 of 1

Design ID DES_ICU_010
Requirements Covered MCAL-4669, MCAL-4670, MCAL-4671, MCAL-4672

Back To Top

Icu_GetInputState

Refer section 8.3.10 of 1

Design ID DES_ICU_011
Requirements Covered MCAL-4673, MCAL-4674, MCAL-4675, MCAL-4676, MCAL-4677, MCAL-4678, MCAL-4679, MCAL-4680, MCAL-4681, MCAL-4682, MCAL-4683

Back To Top

Icu_StartTimestamp

Refer section 8.3.11 of 1

Design ID DES_ICU_012
Requirements Covered MCAL-4684, MCAL-4685, MCAL-4686, MCAL-4687, MCAL-4688, MCAL-4689, MCAL-4690, MCAL-4691, MCAL-4692, MCAL-4693, MCAL-4694, MCAL-4695, MCAL-4696, MCAL-4697, MCAL-4198, MCAL-4199

Back To Top

Icu_StopTimestamp

Refer section 8.3.12 of 1

Design ID DES_ICU_013
Requirements Covered MCAL-4700, MCAL-4701, MCAL-4702, MCAL-4703, MCAL-4704, MCAL-4705, MCAL-4706, MCAL-4707

Back To Top

Icu_GetTimestampIndex

Refer section 8.3.13 of 1

Design ID DES_ICU_014
Requirements Covered MCAL-4708, MCAL-4709, MCAL-4710, MCAL-4710, MCAL-4711, MCAL-4712, MCAL-4713, MCAL-47104, MCAL-4715, MCAL-4716

Back To Top

Icu_ResetEdgeCount

Refer section 8.3.14 of 1

Design ID DES_ICU_015
Requirements Covered MCAL-4717, MCAL-4719, MCAL-4720, MCAL-4718, MCAL-4721, MCAL-4722

Back To Top

Icu_EnableEdgeCount

Refer section 8.3.15 of 1

Design ID DES_ICU_016
Requirements Covered MCAL-4723, MCAL-4724, MCAL-4725, MCAL-4726, MCAL-4727, MCAL-4728, MCAL-4729, MCAL-4730

Back To Top

Icu_EnableEdgeDetection

Refer section 8.3.16 of 1

Design ID DES_ICU_017
Requirements Covered MCAL-4731, MCAL-4732, MCAL-4733, MCAL-4734, MCAL-4735, MCAL-4736, MCAL-4737, MCAL-4738

Back To Top

Icu_DisableEdgeDetection

Refer section 8.3.17 of 1

Design ID DES_ICU_018
Requirements Covered MCAL-4739, MCAL-4740, MCAL-4741, MCAL-4742, MCAL-4743, MCAL-4744

Back To Top

Icu_DisableEdgeCount

Refer section 8.3.18 of 1

Design ID DES_ICU_019
Requirements Covered MCAL-4745, MCAL-4746, MCAL-4747, MCAL-4748, MCAL-4749, MCAL-4750

Back To Top

Icu_GetEdgeNumbers

Refer section 8.3.19 of 1

Design ID DES_ICU_020
Requirements Covered MCAL-4751, MCAL-4752, MCAL-4753, MCAL-4754, MCAL-4755, MCAL-4756, MCAL-4757

Back To Top

Icu_StartSignalMeasurement

Refer section 8.3.20 of 1

Design ID DES_ICU_021
Requirements Covered MCAL-4758, MCAL-4759, MCAL-4760, MCAL-4761, MCAL-4762, MCAL-4763, MCAL-4764, MCAL-4765

Back To Top

Icu_StopSignalMeasurement

Refer section 8.3.21 of 1

Design ID DES_ICU_022
Requirements Covered MCAL-4766, MCAL-4767, MCAL-4768, MCAL-4769, MCAL-4770, MCAL-4771, MCAL-4772

Back To Top

Icu_GetTimeElapsed

Refer section 8.3.22 of 1

Design ID DES_ICU_023
Requirements Covered MCAL-4773, MCAL-4774, MCAL-4775, MCAL-4776, MCAL-4777, MCAL-4778, MCAL-4779, MCAL-4780, MCAL-4781, MCAL-4782, MCAL-4783, MCAL-4784

Back To Top

Icu_GetDutyCycleValues

Refer section 8.3.23 of 1

Design ID DES_ICU_024
Requirements Covered MCAL-4785, MCAL-4786, MCAL-4787, MCAL-4788, MCAL-4789, MCAL-4790, MCAL-4791, MCAL-4792, MCAL-4793, MCAL-4794

Back To Top

Icu_GetVersionInfo

Refer section 8.3.24 of 1

Design ID DES_ICU_025
Requirements Covered MCAL-4795, MCAL-4796

Back To Top

Global Variables

This design expects that implementation will require to use following global variables.

Variable Type Description Default Value
Icu_DrvObj Icu_DriverObjType Icu driver object -
Icu_DrvStatus uint8 Driver Status ICU_STATUS_UNINIT

Back To Top

Decision Analysis & Resolution (DAR)

Sections below list some of the important design decisions and rational behind those decision.

Signal Measurements API Design flow

DAR Criteria

Signal Measurements API could be implemented using either interrupt based or non-interrupt based functionality.

Available Alternatives

The most efficient(least time delay) method shall be chosen. Also, the method which complies best with AUTOSAR specification will be analyzed.

  • 1. Use Interrupt based functionality
    • Advantages:
      • A notification can be generated when the signal measurement information has been successfully captured.
      • Application need not take care to ensure that information has been captured before calling the data gathering API.
    • Disadvantages:
      • Some subsequent edges can be lost while processing the ISR.
      • The AUTOSAR specification does not mention ISR/notification handling for Signal Measurements functionality. If implemented through Interrupt functionality, it would be a deviation from AUTOSAR specificiation.
  • 2. Use non-Interrupt based functionality.
    • Advantages:
      • Easier implementation and simpler integration.
      • Runtime will be more efficient as ISR processing will be eliminated.
      • Code size will be reduced as the application will take care of the timing assumptions.
      • User given the flexibility to handle the delay as they wish in the application. This can be done using several means, one being added time delay.
      • This implementation complies best with AUTOSAR provided requirements.
    • Disadvantages:
      • Application needs to take care to add some delay after call of Icu_StartSignalMeasurement() API to ensure that there is sufficient time for the module to capture all required data.

Decision

Option 2 is selected as it gives best runtime performance. Most importantly, it complies best with AUTOSAR specified functionality.

Back To Top

Interrupt on Capture Registers

ECAP module has the ability to generate interrupts at each or only at a particular capture event. There can be total of 4 capture event interrupts (one for each capture register, CAP1 - CAP4).

DAR Criteria

The design the best complies with AUTOSAR specification shall be chosen.

Available Alternatives

  • 1. Generate interrupts at every 4th capture event (after all capture registers have been filled)
    • Advantages:
      • Reduced time in handling interrupts as the frequency will be reduced.
    • Disadvantages:
      • Interrupts will be generated only after every 4th event. Driver will have limitation to stick to multiples of 4 for edge counting, edge detection and timestamp operations.
      • Driver will be deviating from AUTOSAR specification if implemented using this method.
  • 2. Generate interrupts at every single capture event.
    • Advantages:
      • Easier implementation and simpler integration.
      • This method will meet all AUTOSAR specification requirements as there will be no limitation for how many edges are captured, etc.
    • Disadvantages:
      • Interrupt handling will take more time as every capture event will have to be handled.

Decision

Option 2 is chosen as it will ensure that there are no deviation from AUTOSAR specification.

Back To Top

Test Criteria

The sections below identify some of the aspects of design that would require emphasis during testing of this design implementation

  • Validating ECUC parameters
    • Validating ECUC Parameter: Configuration for each test case shall be generated by EB Tresos command line.

The sections below identify some of the aspects of design that would require emphasis during testing of this design implementation

  • ICU Signal Measurements : Duty Cycle, High Time, Low Time, Period Time
    • Test cases shall check the input signal wave and the signal measurements calculated by the ICU module match. The input signals can be tested using the MCAL EPWM module input.

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 19 Jan 2021 Nikki Shah First version Pending
0.2 24 Feb 2021 Nikki Shah Review Comments Addressed Approved