MCUSW
Pwm Design Document

Introduction

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

  • Supported AUTOSAR Release : 4.3.1
  • Supported Configuration Variants : Pre-Compile & Post-Build
  • Vendor ID : PWM_VENDOR_ID (44)
  • Module ID : PWM_MODULE_ID (121)

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 software modules that interact with the Microcontroller and its internal peripherals directly. The PWM driver is a part of the microcontroller (peripheral) Driver module which is a part of the Basic Software. The figure below shows the position of the PWM driver in the AUTOSAR Architecture.

autosar_acrhitecture_pwm.png
AUTOSAR Architecture – PWM MCAL

PWM Overview

The PWM module implements an interface in C programming language for handling the PWM functionality of the device.This PWM driver takes care of initializing and de-initializing the PWM unit and offers services to:

  • Generate pulses with variable pulse width(Duty Cycle - can range from 0% to 100%)
  • Set parameters of a PWM channels waveform(Duty Cycle and Period)
  • Enable/Disable notifications
pwm_signal_description.png
PWM Signal Description

Hardware Overview

In this design, the PWM Functionality can be achieved by using either of two available IPs, the DM Timers, or EPWM module.

DM Timer

DM Timer available on the device are used. TDA4x class of devices includes multiple timers, some of the key features provided are listed below:

  • Free running 32 bit up counter
  • Auto reload mode (can be used for continuous counter operation)
  • Support dynamic Start / Stop counter operation
  • Programmable clock dividers (2n, where n = [0-8])
  • 2 timers modules could be operated in cascaded mode to provide 64bit counter
  • Programmable interrupt generation on overflow, compare and capture
  • Programmable clock source

There is Support for 3 basic functional modes Timer mode, Capture mode & Compare mode. Refer section 12.8.3 in 2 for more details on timer operation.

Timer pins can be configured to be used as PWM output pins. However, not all timer pins can be configured to be PWM output, please refer TRM for specific pins (section 12.8.3.1 in 2)

The following image shows the block diagram of Timer which can generate a PWM output:

pwm_timer_block_diagram.png
Timer Block Diagram

EPWM Module

The ePWM(enhanced) unit described here addresses these requirements by allocating all needed timing and control resources on a per PWM channel basis. Cross coupling or sharing of resources has been avoided; instead, the ePWM is built up from smaller single channel modules with separate resources and that can operate together as required to form a system. This modular approach results in easy understand of its operation quickly.

J7 family device include six instances of ePWM. The EPWM module represents one complete PWM channel composed of two PWM outputs: EPWMxA and EPWMxB. A given EPWM module functionality can be extended with the so called High-Resolution Pulse Width modulator.

In the further description the letter x within a signal or module name is used to indicate a generic EPWM instance on a device. For example, output signals EPWMxA and EPWMxB refer to the output signals from the EPWMx instance.

There are 6 instances of the EPWM integrated in the device. Each of the Enhanced Pulse Width Modulator (EPWM) includes an Enhanced High Resolution Modulator (HRPWM). The high-resolution functionality is implemented only on the EPWMxA output. EPWMxB output has conventional PWM capabilities. At system level the EPWM0 through EPWM5 integration features are listed below:

  • A 32-bit slave configuration port on the CBASS0 interconnect.
  • A single functional clock from PLLCTRL.
  • 2 hardware events per EPWM, that is a total of 12 events. From these events each EPWM:
  • generates 2 interrupts to the device COMPUTE_CLUSTER0, PRU_ICSSG0_INTC, PRU_ICSSG1_INTC and MAIN2MCU_INTRTR_PLS
  • A synchronization input/output daisy chain-like connection exists between the EPWM0 trough EPWM5.

The high-resolution pulse-width modulator (HRPWM) extends the time resolution capabilities of the conventionally derived digital pulse-width modulator (PWM). HRPWM is typically used when PWM resolution falls below ~9-10 bits. The key features of HRPWM are:

  • Extended time resolution capability with regards to falling edge.
  • Used in Duty cycle control methods.
  • Finer time granularity control or edge positioning using extensions to the Compare A.
  • Implemented using the A signal path of PWM, that is, on the EPWMxA output. EPWMxB output has conventional PWM capabilities.

![](pwm_epwm_block_diagram0.png "EPWM Block Diagram (Note: Unsupported features are grayed boxed.)")

References

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

Requirements

The PWM driver shall implement as per requirements detailed in 4, 1 and 3. It is recommended to refer 1 for clarification.

Features Supported

Below listed are some of the key features that are expected to be supported

  • Changing of frequency and duty cycle for a PWM channel at runtime besides the default configuration.
  • The PWM signal that can be generated is a square wave with variable duty cycle and period .
Design ID DES_PWM_001
Requirements Covered MCAL-965, MCAL-3503, MCAL-3509, MCAL-3511, MCAL-3536, MCAL-3537, MCAL-3538, MCAL-3539, MCAL-3540, MCAL-3554, MCAL-3510, MCAL-3631, MCAL-3535, MCAL-920, MCAL-921, MCAL-922, MCAL-923, MCAL-925,MCAL-929, MCAL-930, MCAL-932, MCAL-933, MCAL-937, MCAL-938, MCAL-939,MCAL-942, MCAL-947, MCAL-980, MCAL-945, MCAL-1056 , MCAL-3502, MCAL-3503, MCAL-3509, MCAL-3511, MCAL-3535, MCAL-3631, MCAL-4475

Back To Top

caution.png

Features Not Supported / NON Compliance

  • [NON Compliance] APIs related to setting or getting power state of the device is not supported, as hardware itself doesn’t support this feature.
  • [NON Compliance] PwmMcuClockReferencePoint doesn’t refer to McuClockReferencePoint. Refer section (Constraints) for details.
  • PWM_FIXED_PERIOD_SHIFTED Pwm Channel Class type is not supported
  • Standard AUTOSAR PWM specification 1, categorizes few BSW General Requirements as non-requirements, please refer MCAL-3648 for details
  • Supports additional configuration parameters, refer section (Pwm_RegisterReadback)
  • Specifically to EPWM IP, DeadBand, Trip Zone and PWM Chopper sub-modules are bypassed.
Design ID DES_PWM_002
Non Requirements MCAL-3648,MCAL-3642,MCAL-3493,MCAL-3482,MCAL-3522,MCAL-3532,MCAL-3531, MCAL-3512,MCAL-3614,MCAL-3481,MCAL-3613,MCAL-3515,MCAL-3626,MCAL-3478, MCAL-3513,MCAL-3628,MCAL-3629,MCAL-3606,MCAL-3617,MCAL-3602,MCAL-3516, MCAL-3638,MCAL-3608,MCAL-3619,MCAL-3609,MCAL-3514,MCAL-3518,MCAL-3519, MCAL-3630,MCAL-3543,MCAL-3604,MCAL-3517,MCAL-3544,MCAL-3610,MCAL-3627, MCAL-3618,MCAL-3605,MCAL-3639,MCAL-3620,MCAL-3603,MCAL-3521,MCAL-3621, MCAL-3607,MCAL-3484,MCAL-3615,MCAL-3483,MCAL-3622,MCAL-3611,MCAL-3530, MCAL-3520,MCAL-3601,MCAL-3612,MCAL-3623,MCAL-3529,MCAL-3616,MCAL-3489, MCAL-3588,MCAL-3589,MCAL-3591,MCAL-3590,MCAL-3497

Back To Top

Assumptions

Below listed are assumed to 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 PWM module is expected to be on before calling any PWM module API.
  2. The PWM driver as such doesn’t perform any PRCM programming to get the functional clock.
  3. For EPWM IP, the modules executes at the system clock which is typically 125Mhz.
  4. The clock-source selection for PWM is not performed by the PWM driver, other entities such as SBL, MCAL module MCU shall perform the same.

Back To Top

Constraints

Some of the critical constraints of this design are listed below

  • In cases where MCU module is not employed (supported) to configure the clock source for PWM module (refer Assumptions sub-item 3). The PWM module configurator shall refer to MCU clock source as listed in specification.
  • EPWM module executes at the system clock which is typically 125Mhz.
  • The PWM SWS does not cover PWM emulation on general purpose I/O
  • Timer when configured for toggle mode with TCLR[11-10] TRG = 0x2 (overflow and match), and TCLR[7] SCPWM Bit = 1 for polarity Low, the first event that toggles the PWM line is an overflow event. If a match event occurs first,it does not toggle the PWM line
    Design ID DES_PWM_003
    Requirements Covered MCAL-3493, MCAL-3502

EPWM

Setting Prescalers: Period value(Num of ticks) which determines the period is calculated using below formula:

  • PRD = (TBCLK/PWM_FREQ) / 2.
  • TBCLK – Time base clock relative to the system clock.
  • PWM_FREQ – Required output frequency.
  • /2 – Because UpDown counter is selected.(Please refer DAR for more details). The TRM gives details on this formula.
  • TBCLK is derived from below formula.
  • TBCLK = SYS_CLK / (HSPCLKDIV x CLKDIV)
  • SYS_CLK – System Clock to the PWM which is 125Mhz.
  • CLKDIV – Time-base Clock Prescale Bits. These bits determine part of the time-base clock prescale value.

Actual Division Value = / ( 1 << CLKDIV) i.e

Actual Division Value CLKDIV Value
0x0 / 1
0x1 / 2
0x2 / 4
0x3 / 8
0x4 / 16
0x5 / 32
0x6 / 64
0x7 / 128
  • HSPCLKDIV – High-Speed Time-base Clock Prescale Bits. These bits determine part of the time-base clock prescale value.

Actual Division Value = / (HSPCLKDIV * 2) i.e

Actual Division Value HSPCLKDIV
0x0 / 1
0x1 / 2
0x2 / 4
0x3 / 6
0x4 / 8
0x5 / 10
0x6 / 12
0x7 / 14

There is a chance that period value calculated is fractional, and therefore required frequency cannot be achieved. The clock dividers need to be selected correctly to avoid such errors. Please refer to the excel sheet provided to derive the correct CLKDIV and HSPCLKDIV values. Using this excel, you can test prescaler combinations with required frequency and ensure that the "Difference" is 0. The Period value should be less than or equal to 65535 (16bit HW register size for period).

Find the excel sheet here: Period Calculator

Back To Top

Design Description

Fundamental Operation

Timer

The timer can be configured to provide a programmable PWM output. The timer PWM (POTIMERPWM) output pin can be configured to toggle on an event. The TCLR[11-10] TRG bit field determines on which register value the PWM pin toggles. Either overflow or both overflow and match can be selected to toggle the timer PWM pin when a compare condition occurs. TMAR, TLDR The internal overflow pulse is set each time the (0xFFFF FFFF – TLDR[31-0] LOAD_VALUE + 1) value is reached, and the internal match pulse is set when the counter reaches the value of TMAR. Depending on the value of the TCLR[12] PT bit and TCLR[11-10] TRG bit field, the timer provides pulse or PWM event on the output pin (POTIMERPWM). The TLDR and TMAR must keep values below the overflow value (0xFFFF FFFF) by at least two units. If the PWM trigger events are both overflow and match, the difference between the values kept in the TMAR and the value in the TLDR must be at least two units. When match event is used, the compare mode TCLR[6] CE bit must be set.

The following sequence of steps needs to be performed, before the timer can be started

  • Timer is programmed as configured (in continuous mode or Autoreload mode)
  • The initial count of the counter TCLR needs to be loaded
  • The reload register (TLDR) needs to be loaded
  • The timer is started and the counter (register TCRR), starts counting on every pulse
    • As depicted in above figure, TCRR has moved w.r.t to TLDR
gpt_design_timer_expired.png
Timer expired
  • When the timer expires, the TCRR is loaded with value present in TLDR as show above
  • An interrupt can be triggered at this point

For generating a PWM signal from the timer interrupts, the following cases w.r.t. duty cycle are considered:

Case 1: Duty cycle of 0%

  • The output will be the inverse of the configured polarity parameter. For example, if the polarity is configured as LOW, the PWM signal will always be HIGH.

CASE 2: Duty cycle of 100%

  • The output will be equal to the configured polarity parameter. For example, if the polarity is configured as LOW, the PWM signal will always be LOW.

Case 3: Duty cycle of 50%

  • When the When a duty cycle of 50% for a PWM signal is required, both the time that the pulse remains HIGH and LOW is equal. In this case, the timer is operated in overflow mode alone (without compare). In one cycle of the PWM signal, the timer should generate an interrupt twice. Hence, the overflow rate for the timer (OVF_Rate) is half the period of the PWM signal required. The load value for TLDR register can be calculated using the following formula: 

       OVF_Rate = (0xFFFF FFFF – TLDR + 1) × (timer-functional clock period) × PS

    where

    • OVF_Rate = (PWM Period /2 )
    • Timer-functional clock period is the period of the input clock to the timer
    • PS is the Prescaler Clock Ratio Value used to divide the timer counter input clock frequency as shown below:
pwm_timer_prescalar.png
Prescaler Clock Ratio Values

Case 4: 0%< Duty cycle < 100%

  • When PWM signal with 0%< duty cycle < 100% for a is required, the timer is operated in overflow and match mode (with compare). In one cycle of the PWM signal, the timer generates an interrupt twice, one when the match condition is met and one when overflow is triggered as shown in the figure below.Hence, in this scenario, the overflow rate for the timer (OVF_Rate) is same as the period of the PWM signal required.

    pwm_timer_func.png
    Generation of PWM signal using Timer

    The load value for TLDR and TMAR registers can be calculated using the following formula: 

    OVF_Rate = (0xFFFF FFFF – TLDR + 1) × (timer-functional clock period) × PS
OVF_Rate * (1- (Dutycyle/100)) = (0xFFFF FFFF – TMAR + 1) × (timer-functional clock period) × PS

    where

    • OVF_Rate = (PWM Period )
    • Timer-functional clock period is the period of the input clock to the timer
    • PS is the Prescaler Clock Ratio Value.

    Two example cases are shown in the following figure. The TCLR[7] SCPWM bit is set to 0 in one case and to 1 in the other case. To obtain the desired wave form, start the counter at 0xFFFF FFFE value (to ensure an overflow first) or adjust the line polarity (TCLR[7] SCPWM bit).

    pwm_from_timer.png
    Timing Diagram for PWM through Timer

    NOTE

    • The Functional frequency range dictates the usage of posted and non-posted write modes for the timer. Incase of posted mode of operation, If a write access is pending for a register, reading from this register does not yield a correct result. Software synchronization must be used to avoid incorrect results. Functional frequency range: freq(timer clock) < freq(interface clock)/4.

EPWM

pwm_epwm_submodules.png
EPWM Submodules

EPWM Module in J721E/J7200 consist of submodules:

Time-base (TB)

  • Scale the time-base clock (TBCLK) relative to the system clock (FICLK).
  • Configure the PWM time-base counter (TBCNT) frequency or period.
  • Time-base counter mode selection:
    1. count-up mode: used for asymmetric PWM
    2. count-down mode: used for asymmetric PWM
    3. count-up-and-down mode: used for symmetric PWM
  • Configure the time-base phase relative to another EPWM module.
  • Synchronize the time-base counter between modules through hardware or software.
  • Configure the direction (up or down) of the time-base counter after a synchronization event.
  • Configure how the time-base counter will behave when the device is halted by an emulator.
  • Specify the source for the synchronization output of the EPWM module:
    1. Synchronization input signal
    2. Time-base counter equal to zero
    3. Time-base counter equal to counter-compare B (CMPB)
    4. No output synchronization signal generated.

Counter-compare (CC)

  • Specify the PWM duty cycle for output EPWMxA and/or output EPWMxB
  • Specify the time at which switching events occur on the EPWMxA or EPWMxB output

Action-qualifier (AQ)

  • Controls how the two outputs EPWMxA and EPWMxB behave when a particular event occurs.
  • Possible actions are: Set High, Clear Low, Toggle and Do nothing.
  • Specify the type of action taken when a time-base or counter-compare submodule event occurs:
    1. No action taken
    2. Output EPWMxA and/or EPWMxB switched high
    3. Output EPWMxA and/or EPWMxB switched low
    4. Output EPWMxA and/or EPWMxB toggled
  • Force the PWM output state through software control
  • Configure and control the PWM dead-band through software

Event-trigger (ET)

  • Enable the EPWM events that will trigger an interrupt.
  • Specify the rate at which events cause triggers (every occurrence or every second or third occurrence)
  • Poll, set, or clear event flags
  • Manages the events generated by the time-base submodule and the counter-compare submodule to generate an aggregated interrupt request.
  • An event can be be of the following:
    1. Time-base counter equal to 0.
    2. Time-base counter equal to period.
    3. Time-base counter equal to the compare A or B register when timer is incr/decr

High-Resolution PWM (HRPWM)

  • Enable extended time resolution capabilities with regards to falling edge.
  • Configure finer time granularity control or edge positioning.
  • Once the EPWM has been configured to provide conventional PWM of a given frequency and polarity, the HRPWM is configured by programming the control HR control register.
  • Typical low-frequency PWM operations (below 250kHz) may not require the HRPWM capabilities.
  • HRPWM is based on micro edge positioner (MEP) technology. MEP logic is capable of positioning an edge finely by sub-diving one coarse system clock of a conventional PWM generator. This driver assumes a MEP value of 180 ps.
pwm_epwm_waveform_3.png
EPWM Waveform : Duty Cycle vs Compare Period Registers
pwm_epwm_waveform_1.png
EPWM Waveform : Up/Down Counter Example

Back To Top

Dynamic Behavior

States for Timer

As the PWM module is implemeted using a timer, as detailed in section 7.1 of 5, a timer would be in one of the following states. Initialized, running, stopped, expired. The diagram below shows transitions of states:

gpt_design_timer_state.png
Timer States : Sourced from TIMER AUTOSAR Spec

States for EPWM

Back To Top

Time Unit Ticks

Refer 1 specifically section 7.2 of the specification for more details All time units used within the API services of the PWM module shall be of the unit ticks.

Design ID DES_PWM_004
Requirements Covered MCAL-3511

Back To Top

Duty Cycle Resolution and Scaling

Refer 1 specifically section 7.7 of the specification for more details The width of the duty cycle parameter is 16 Bits and the parameter follows the following scaling scheme:

  • 0x0000 means 0%.
  • 0x8000 means 100%. 0x8000 gives the highest resolution while allowing 100% duty cycle to be represented with a 16 bit value.

As an implementation guide, the following source code example is given: 

AbsoluteDutyCycle =((uint32)AbsolutePeriodTime * RelativeDutyCycle) >> 15;
Design ID DES_PWM_005
Requirements Covered MCAL-3533,MCAL-3534

Back To Top

Directory Structure

The directory structure is as depicted in figures below, the source files can be categorized under “Driver Implementation” and “Example Application”

Driver Implemented by

  • Pwm.h and Pwm_Irq.h: Shall implement the interface provided by the driver
  • Pwm.c, Pwm_Irq.c, Pwm_Gptimer.c, Pwm_Ehrpwm.c Pwm_Priv.c and Pwm_Priv.h: Shall implement the driver functionality
  • Pwm_Priv.c will act as an abstraction layer. Based on the IP configuration chosen, the respective API will be called.
  • Gptimer specific API are present in Pwm_Gptimer.c, while EPWM specific are present in Pwm_Ehrpwm.c.
pwm_driver_dir0.png
Directory Structure of Driver
pwm_design_dir.png
Directory Structure
Design ID DES_PWM_006
Requirements Covered MCAL-3503,MCAL-3507,MCAL-3506,MCAL-3504,MCAL-3508,MCAL-3505

Back To Top

Configurator

The AUTOSAR PWM Driver Specification details mandatory parameters that shall be configurable via the configurator. Please refer section 10 of 1

Design ID DES_PWM_007
Requirements Covered MCAL-3474,MCAL-3475,MCAL-3476,MCAL-3477,MCAL-3478,MCAL-3479,MCAL-3480, MCAL-3481,MCAL-3482,MCAL-3483,MCAL-3484,MCAL-3485,MCAL-3486,MCAL-3487, MCAL-3488,MCAL-3489,MCAL-3490,MCAL-3491,MCAL-3492,MCAL-3493,MCAL-3494, MCAL-3495,MCAL-3496,MCAL-3497,MCAL-3498,MCAL-3499,MCAL-3500,MCAL-3501, MCAL-3652, MCAL-4479

NON Standard configurable parameters

The design's specific configurable parameters are as follows:

Parameter Usage comment
PwmDeviceVariant 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
PwmFunctionalClock This is the value of the System clock frequency in Hz
PwmTypeofInterruptFunction This parameter allows the selection of Type of ISR function
PwmEnableRegisterReadbackApi This parameter enables the API to readback PWM critical registers
PwmClkPrescaler This parameter allows the selection of pre-scalar value.The prescaler stage is clocked with the pwm clock and acts as a clock divider for the time-base clock.
PwmPolarity This parameter stores the initial polarity configured for a channel
PwmIdleState This parameter stores whether the channel is in idle state
PwmDefaultOSCounterId This parameter stores Default Os Counter Id if node reference to OsCounter ref PwmOsCounterRef is not set
PwmOsCounterRef This parameter contains a reference to the OsCounter, which is used by the Timer driver
PwmTimeoutDuration This parameter contains the Timer timeout upper limit
Design ID DES_PWM_008
Requirements Covered MCAL-3653, MCAL-3654, MCAL-3660, MCAL-3657, MCAL-3752 ,MCAL-3753, MCAL-3754, MCAL-3655

EPWM specific parameters:

Parameter Usage comment
PwmOutputChSelect PWM Output Channel select EPWMxA or EPWMxB or Both. Both Outputs available with same duty cycle, period and polarity.
PwmHSClkPrescaler This parameter allows the selection of High Speed pre-scalar value. The High Speed prescaler stage is clocked with the pwm clock and acts as a clock divider for the time-base clock. High-Speed Time-base Clock Prescale Bits.
PwmEnableHighRes This parameter will be a switch to enable or disable high resolution (HRPWM) capability of EPWM module.

Standard Config which will be used to differentiate between Gptimer and EHRPWM mode of operation.

Parameter Usage comment
PwmIndex Specifies the InstanceId of this module instance.
  • 0 - EPWM will be used (Default), 1 - Gptimer will be used

Output Channel Structure:

  • EpwmOuputCh - to choose between the channel A, B or both.
  • EPWM_OUTPUT_CH_A - Output channel A
  • EPWM_OUTPUT_CH_B - Output channel B
  • EPWM_OUTPUT_CH_BOTH_A_AND_B - Both Output channel A and B

Back To Top

Variant Support

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

Design ID DES_PWM_009
Requirements Covered MCAL-3647, MCAL-3647

Back To Top

Dependency on other modules

In addition to dependencies listed in section 5 of 1, PWM driver shall depend on these modules to realize the required functionality. PWM uses Timer hardware present in the device to realize the functionality, this peripheral requires 2 different clock to be operational, namely ICLK and FCLK.

SBL

  • ICLK: Interface clock required for internal operation of the peripheral. This is not expected to change and typically programmed by SBL, please refer the device specific manual for details and valid value.
  • FCLK: Functional clock, used to drive the counter of the timer module. As per AUTOSAR PWM module specification 1, the PWM driver shall refer MCU Clock reference point. As detailed in section (Constraints), other entity would require to select the right clock source for the peripheral.

Back To Top

Error Classification

Errors are classified in two categories, development error and runtime / production error.

Development Errors

Type of Error Related Error code Value (Hex) Refer Req
API Pwm_Init service called with wrong parameter PWM_E_PARAM_CONFIG 0x10 MCAL-3523
API service used without module initialization PWM_E_UNINIT 0x11 MCAL-3524
API service used with an invalid channel Identifier PWM_E_PARAM_CHANNEL 0x12 MCAL-3525
Usage of unauthorized PWM service on PWM channel configured a fixed period PWM_E_PERIOD_UNCHANGEABLE 0x13 MCAL-3526
API Pwm_Init service called while the PWM driver has already been initialised PWM_E_ALREADY_INITIALIZED 0x14 MCAL-3527
API Pwm_GetVersionInfo is called with a NULL parameter. PWM_E_PARAM_POINTER 0x15 MCAL-3528
Design ID DES_PWM_010
Requirements Covered MCAL-3523, MCAL-3524, MCAL-3525, MCAL-3526, MCAL-3527, MCAL-3528, MCAL-4480, MCAL-4481

Error Detection

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

Error notification (DET)

All detected development errors are reported to Det_ReportError service of the Development Error Tracer (DET).

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.
Design ID DES_PWM_011
Requirements Covered MCAL-3649
  • Stack Size : Worst case stack utilization shall not exceed 2 kilo bytes.
Design ID DES_PWM_012
Requirements Covered MCAL-3650

Back To Top

Supporting PWM for AUTOSAR versioned 4.4.0

This PWM design is based on the requirements specification for AUTOSAR versioned 4.2.1 and sections below highlight some of the critical changes that would be required between these two versions.

Note that this design doesn’t comprehend or account for other versions of AUTOSAR.

Deleted

Probably easiest of all to implement. The following have been removed from the requirements specification for AUTOSAR versioned 4.4.0:

  • [MCAL-3523] : Developement error classification : PWM_E_PARAM_CONFIG
  • [MCAL-3528] : Developement error classification : PWM_E_PARAM_POINTER
  • [MCAL-3553] : If development error detection is enabled for the Pwm module, the function Pwm_Init shall raise development error PWM_E_PARAM_CONFIG if ConfigPtr is a null pointer.
  • [MCAL-3556] : For pre-compile and link time configuration variants, a NULL pointer s hall be passed to the initialization routine
  • [MCAL-3557] : related to above point In this case the check for this NULL pointer has to be omitted.
  • [MCAL-3625] : The function Pwm_GetVersionInfo shall be configurable On/Off by the configuration parameter: PwmVersionInfoApi {PWM_VERSION_INFO_API
  • [MCAL-3642] : If development error detection for the Pwm module is enabled, and a development error occurs, then the corresponding PWM function shall return PWM_LOW for the function Pwm_GetOutputState
  • [MCAL-3646] : VARIANT-PRE-COMPILE (Pre Compile) is limited to pre-compile configuration parameters only.
  • [MCAL-3647] :VARIANT-POST-BUILD includes a mix of pre-compile, link time and post build configuration parameters. Also, note that Directory structure would require an update for the removal of the following:
  • [MCAL-3504] : Pwm.h shall include Pwm_Cfg.h
  • [MCAL-3505] : Pwm_Lcfg.c shall include Pwm.h and Pwm_Memmap.h.
  • [MCAL-3507] :Pwm_PBcfg.c shall include Pwm_MemMap.h and Pwm.h)

Added

The following changes have been added in the configurator in the requirements specification for AUTOSAR versioned 4.4.0

  • Module : Configuration of Pwm Module
  • PwmEcucPartitionRef : this requirement is still in draft state
  • PwmKernelEcucPartitionRef : this requirement is still in draft state
  • PwmChannelEcucPartitionRef : this requirement is still in draft state

The following changes have been added in the requirements specification for AUTOSAR versioned 4.4.0 :

  • Development Error Types Added
  • Runtime Error Types Added
  • Service name: Pwm_SetDutyCycle (in draft state) as MCAL-3565 has been made obsolete
  • Service name: Pwm_SetPeriodAndDuty (in draft state) as MCAL-3573 has been made obsolete
  • Service name: Pwm_SetOutputToIdle (in draft state) as MCAL-3581 has been made obsolete
  • [MCAL-3642] :If Pwm_GetOutputState is called before module initialization,or with an invalid channel, it shall return PWM_LOW
  • Service name: Pwm_DisableNotification (draft) please check MCAL-3592 made obsolete
  • Service name: Pwm_EnableNotification (draft) please check MCAL-3596 made obsolete
  • In DRAFT The PWM module shall reject configurations with partition mappings which are not supported by the implementation
  • In DRAFT The ECUC partitions referenced by PwmKernelEcucPartitionRef shall be a subset of the ECUC partitions referenced by PwmEcucPartitionRef

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

Maximum number of channels

Type Identifier Comments
uint32 PWM_MAX_CHANNELS Defines the maximum number of channels that are configured. Its required that configurations for all channel specified is valid.

Pwm_ChannelType

Used to specify the numeric identifier for a channel, please refer section 8.2.1 of 1

Pwm_PeriodType

Used to specify the period of a PWM channel, refer section 8.2.2 of 1

Pwm_OutputStateType

Used to specify the Output state of a PWM channel, refer section 8.2.3 of 1

Pwm_EdgeNotificationType

Enumeration used to specify the type of edge notification of a PWM channel. Refer section 8.2.4 of 1

Pwm_ChannelClassType

Enumeration used to specify the class of a PWM channel, whether the period is fixed or not. Refer section 8.2.5 of 1

Pwm_ConfigType

Hardware dependent structure used to specify the initial data for the PWM driver. Refer section 8.2.6 of 1

Pwm_RegisterReadbackType

Name IP Type Range Comments
pwmRev GPT uint32 0 to 0xFFFFFFFF H/W version identifier, will not change for a given SoC
pwmTtgr GPT uint32 0 to 0xFFFFFFFF Shall always read 0xFFFFFFFF
pwmTimerSynCtrl GPT uint32 0 to 0xFFFFFFFF Interface control register, will read 0x00000000
pwmTbCtl EPWM uint16 0 to 0xFFFF Time base Control register
pwmTbPhs EPWM uint16 0 to 0xFFFF Time base Counter Phase register
pwmTbCnt EPWM uint16 0 to 0xFFFF Time base Counter Register
Design ID DES_PWM_013
Requirements Covered MCAL-3536, MCAL-3537 ,MCAL-3538, MCAL-3539, MCAL-3540, MCAL-3541, MCAL-3542,MCAL-3662

APIs

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

Pwm_Init

Refer section 8.3.1 of 1

Design ID DES_PWM_014
Requirements Covered MCAL-3553, MCAL-3554, MCAL-3555, MCAL-3558, MCAL-3545, MCAL-3546, MCAL-3547, MCAL-3548, MCAL-3551, MCAL-3552, MCAL-3556, MCAL-3549,MCAL-3550

Back To Top

Pwm_DeInit

Refer section 8.3.2 of 1

Design ID DES_PWM_015
Requirements Covered MCAL-3560, MCAL-3559, MCAL-3561,MCAL-3562,MCAL-3563, MCAL-3564,MCAL-3643, MCAL-3640, MCAL-3641, MCAL-3642

Back To Top

Pwm_SetDutyCycle

Refer section 8.3.3 of 1

Design ID DES_PWM_016
Requirements Covered MCAL-3565,MCAL-3566, MCAL-3567,MCAL-3568,MCAL-3569, MCAL-3533,MCAL-3534,MCAL-3570,MCAL-3643, MCAL-3645, MCAL-3640, MCAL-3641,MCAL-3642,MCAL-3571,MCAL-3572

Back To Top

Pwm_SetPeriodAndDuty

Refer section 8.3.4 of 1

Design ID DES_PWM_017
Requirements Covered MCAL-3573,MCAL-3574,MCAL-3575, MCAL-3576,MCAL-3533 ,MCAL-3534,MCAL-3643, MCAL-3644, MCAL-3645, MCAL-3640, MCAL-3641, MCAL-3642,MCAL-3577,MCAL-3578,MCAL-3579, MCAL-3580

Back To Top

Pwm_SetOutputToIdle

Refer section 8.3.5 of 1

Design ID DES_PWM_018
Requirements Covered MCAL-3581, MCAL-3582, MCAL-3583, MCAL-3584, MCAL-3585 MCAL-3586,MCAL-3587

Back To Top

Pwm_DisableNotification

Refer section 8.3.7 of 1

Design ID DES_PWM_019
Requirements Covered MCAL-3592,MCAL-3593,MCAL-3594,MCAL-3595, MCAL-3643, MCAL-3645, MCAL-3640, MCAL-3641, MCAL-3642

Back To Top

Pwm_EnableNotification

Refer section 8.3.8 of 1

Design ID DES_PWM_020
Requirements Covered MCAL-3596, MCAL-3597,MCAL-3598, MCAL-3599,MCAL-3600, MCAL-3643, MCAL-3645, MCAL-3640, MCAL-3641, MCAL-3642

Back To Top

Pwm_GetVersionInfo

Refer section 8.3.13 of 1

Design ID DES_PWM_021
Requirements Covered MCAL-3624

Back To Top

Pwm_RegisterReadback

As noted from previous implementation, the timer 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 Pwm_RegisterReadback Can potentially be turned OFF
Syntax Std_ReturnType Pwm_RegisterReadback(Pwm_ChannelType PwmChannel, Pwm_RegisterReadbackType * RegRbPtr) Pwm_RegisterReadbackType defines the type, that holds critical values, refer below
Service ID 0x0F
Sync / Async Sync
Reentrancy Non Reentrant
Parameter in PwmChannel Identifies a unique valid channel
Parameters out RegRbPtr A pointer of type Pwm_RegisterReadbackType, which holds the read back values
Return Value Standard return type E_OK or E_NOT_OK in case of invalid channel id

The critical register listed is a recommendation and implementation shall determine appropriate registers.

This service could potentially be turned OFF in the configurator.

Design ID DES_PWM_022
Requirements Covered MCAL-3662,MCAL-3656

Back To Top

Global Variables

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

Variable Type Description Default Value
Pwm_DrvStatus uint8 PWM driver status PWM_STATUS_UNINIT
Pwm_ChObj Pwm_ChObjType PWM channel object -

Back To Top

Safety Analysis

EPWM Module

The following tests can be applied as diagnostics for this module (to provide diagnostic coverage on a specific function):

  • 1. Software Test of Basic functionality including error tests: Application can use the Pwm_EnableNotification() API to verify correct frequency by counting the number of interrupts received in particular time period. Reference example will be provided in MCAL package. The Unit Test framework will be used to check basic functionality, as well as negative tests by injecting errors.
  • 2. Information redundancy techniques: Application can implement this using GPIO inputs used as interrupts. The interrupts can be timestamped to provide a check on the pulse widths.
  • 3. Monitoring by eCAP: Application can use external eCAP module to monitor the PWM outputs.
  • 4. Periodic software readback of static configuration registers: The driver will internally readback the configured registers to ensure correct value has been set.
  • 5. Software readback of written configuration: The driver provides a Pwm_RegisterReadback() API that application can use to check configured register value. Reference example will be provided in MCAL package during later release.

GPTimer Module

The following tests can be applied as diagnostics for this module (to provide diagnostic coverage on a specific function):

  • 1. 1oo2 Voting Using a Second Timer: Application can use other time based modules on the device to periodically check and perform diagnostic on main counter. Example of other external time based modules include PMU (Performance Monitoring Unit), Timer Manager Module and Global Timebase Counter (GTC).
  • 2. Software Test of Basic Functionality including error tests: Application can use the Pwm_EnableNotification() API to verify correct frequency by counting the number of interrupts received in particular time period. Reference example will be provided in MCAL package. The Unit Test framework will be used to check basic functionality, as well as negative tests by injecting errors.
  • 3. Software readback of written configuration: The driver provides a Pwm_RegisterReadback() API that application can use to check configured register value. Reference example will be provided in MCAL package during later release.
  • 4. Periodic software readback of static configuration registers: The driver will internally readback the configured registers to ensure correct value has been set.
  • 5. Analog-to-Digital Converter Information redundancy techniques: Information redundancy techniques can be applied via software as an additional runtime diagnostic on ADC conversion. This can be done by application to filter and perform plausibility check to ensure converted values are in expected range.

Back To Top

Decision Analysis & Resolution (DAR)

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

Timer Mode configuration in Overflow Only Mode for Duty cycle of 50%

The PWM signal generation when duty cycle is 50% and 0% < duty cycle < 100% can be done in the following ways:

  • Configure the timer in overflow only mode in the case where the duty cycle is 50%. In this case, the overflow rate of the timer is kept at half the desired PWM period. When 0% < duty cycle < 100%, the timer is configured in overflow and compare mode with overflow rate kept at the desired period of PWM signal and the formulas given in (Fundamental Operation) are used to calculate the compare and reload register values.
  • Configure the timer in overflow and compare mode always irrespective of duty cycle and the overflow rate is kept at the PWM period and in the case of 50% duty cycle, the compare register TMAR can be kept at half the reload register value.

DAR Criteria

The PWM signal generation from the timer should be optimized.

Available Alternatives

  • Use timer in either Overflow Mode or ( Overflow and Compare Mode) configuration depending on duty cycle
    • Advantages:
      • Incase of 50% duty cycle, only the overflow register condition needs to be checked to generate the interrrupts and PWM signal.
    • Disadvantages:
      • Seperate one time Mode configuration depending on the duty cycle needs to be done in software.
  • Use of Timer in compare and overflow Mode configurations irrespective of duty cycle
    • Advantages:
      • No need to have seperate Mode configuration of timer for different duty cycles. Timer can be configured in overflow and compare mode.
    • Disadvantages:
      • In 50% duty cycle, register compare to TMAR register needs to be performed continuously to detect the compare condition.

Decision

The PWM module is more efficeintly implemented by operating timer in overflow mode alone when duty cycle of 50% is required as this avoids the continuous register compare to TMAR to generate the trigger at compare condition. The configuration to overflow or overflow and compare in different duty cycles needs to be done one time, and is a lesser overhead.

Design ID DES_PWM_023
Requirements Covered MCAL-3533,MCAL-3534

Integration of GpTimer and EPWM

The PWM module instance can use either Gptimer hardware or the EPWM hardware IP as the source for signal creation. The most efficient way of integrating both IP into PWM module has to be analyzed.

DAR Criteria

The PWM driver implementation and interface should be simple and user friendly. The user should be able to choose which one to use.

Available Alternatives

  • 1. Use PWM Driver Index as the differentiation factor
    • Advantages:
      • The user can choose which driver instance they want to run (0 for EPWM and 1 for GPT).
      • This can be provided as a configurable parameter. User has the flexibility to choose.
      • Easier implementation and simpler integration.
      • Compatible with the Pre-Compile and Post_Build variants.
      • Code size will be reduced as only the needed IP libraries will be included.
    • Disadvantages:
      • N/A
  • 2. Have EPWM as default selected
    • When all EPWM channels are used up, start using the GPT Channels
    • Advantages:
      • Can use different channels at runtime.
      • GPTimer will be kept free and would be available for other applications.
    • Disadvantages:
      • Incompatible with configurator model as Channel ID cannot change at runtime.
      • User not given the flexibility, and would make the design more complicated.

Decision

Option 1 is chosen as it is most compatible with the configurator and also will make the integration simpler. As mentioned above, the PwmIndex (PWM_INSTANCE_ID) variable will be used as the configuration parameter to choose between EPWM(default) or Gptimer. PWM_Priv.c will call the respective API (will be differentiated using the PWM_INSTNACE_ID).

EHRPWM internal step size

HRPWM is based on micro edge positioner (MEP) technology. MEP logic is capable of positioning an edge finely by sub-diving one coarse system clock of a conventional PWM generator.

DAR Criteria

The PWM driver implementation should avoid any failure risks.

Available Alternatives

  • 1. The driver should assume the MEP to be 180ps for all scenarios.
    • Advantages:
      • This will avoid any failures that come with varied MEP values if user is given freedom to choose.
      • Will make the driver more stable.
    • Disadvantages:
      • Driver will only support fixed MEP value.
  • 2. The driver should give the user to select the MEP step size.
    • Advantages:
      • User has freedom to choose the MEP value.
    • Disadvantages:
      • Will make driver complicated and prone to user error.

Decision

Option 1 is chosen. Typically MEP scale factor is calibrated in hardware. However, the current hardware does not have an in-built calibration/diagnostic module, so different MEP values cannot be analyzed at run-time. Keeping a fixed MEP value which is suggested by datasheet (180ps) would make the driver functionality simple and stable.

Support each EPWM Output as a PWM Channel

The PWM module instance is composed of two PWM outputs: EPWMxA and EPWMxB. It is possible to consider each output as one channel. In this way we can support 12 PWM outputs in case of J721E/J7200 simultaneously.

DAR Criteria

The PWM driver implementation and interface should be easily controllable.

Available Alternatives

  • 1. Link each HW PWM instance as 1 individual PWM Channel
    • Advantages:
      • It is possible to link only one output of each instance as one individual PWM Channel.
      • Each PWM output is independent and frequency, duty cycle and polarity can be controlled independently.
    • Disadvantages:
      • In this way we can support only 6 PWM outputs in case of J721E/J7200 simultaneously.
      • Interrupt can be generated only for one of the event output either EPWMxA or EPWMxB since each instance has only one interrupt line.
  • 2. Link each HW PWM instance output(EPWMxA or EPWMxB) as 1 individual PWM Channel
    • Advantages:
      • Each instance consists of two outputs(EPWMxA and EPWMxB) and can be considered as individual PWM Channels.
      • Each instance outputs can have a different duty cycle and polarity.
      • In this way we can support 12 PWM outputs in case of J721E/J7200 simultaneously.
    • Disadvantages:
      • Each instance outputs are not independent. If frequency is changed for channel(EPWMxA) then it will be applied for 2nd channel also(EPWMxB).
      • Interrupt can be generated only for one of the event output either EPWMxA or EPWMxB since each instance has only one interrupt line.

Decision

Typically in PWM use cases, it is recommended to have independent outputs so that you can control frequency, duty cycle and polarity can be independently. Even AUTOSAR provides API’s to change frequency independently for each channel. So option 1 is decided for implementation.

Some of the other hardware/driver specific decisions taken are listed below.

  • If the default period is configured to zero during driver initialization, then the output shall be zero (zero percent duty-cycle).
  • Always UpDown Counter mode is selected to achieve symmetrical PWM output.
  • Interrupt notification is generated only for one of the event output either EPWMxA or EPWMxB, whichever is selected, since each instance has only one interrupt line.
  • If interface parameter outputCh is selected as EPWM_OUTPUT_CH_BOTH_A_AND_B then dual outputs of each instance will be available. i.e same EPWMxA output is also available in EPWMxB signal with same configured frequency, duty cycle and polarity. Interrupt notification is generated only for EPWMxA output if this option is selected.

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

  • PWM Wave generation : Polarities
    • Test cases shall check the generation of PWM wave based on different initial polarities configured. This will be verified on the CRO.
  • PWM Wave generation : Duty Cycle, Period and Input clock frequency
    • Test cases shall perform equivalence class test and ensure different duty cycles, periods for a PWM signal can be supported based on input clock frequencies.
    • Test cases should also check for conditions where the PWM parameters are reconfigured while the timer is running.
  • PWM Wave generation :Reset (Period = 0)
    • Test cases should check the behaviour on reset and with Period = 0
  • PWM Multiple Instances
    • Configure multiple PWM instances with duty cycle of 75% and 25%, reset and vary the duty cycles to ensure that the re-entrancy is maintained.

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 25 Feb 2019 Vibha Pant First version Pending Review
0.2 26 Feb 2019 Vibha Pant Review Comments Addressed Approved
0.3 8 Jul 2020 Nikki Shah EPWM Addition Pending Review
0.4 10 Jul 2020 Nikki Shah Review Comments Addressed Loop for Review
0.5 3 Nov 2020 Nikki Shah Review Comments Addressed Approved