MCUSW
Pwm User Guide

Introduction

This document details AUTOSAR BSW PWM module implementation

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

The PWM module initializes, configures and controls the internal hardware to realize PWM driver as detailed in AUTOSAR BSW PWM Driver Specification. The PWM functionality is realized through the DM Timers available on the device. Following section highlights key aspects of this implementation, which would be of interest to an integrator.


Pwm Driver Architecture/Design

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


Functional Description

Clock Source to timers

Programming of clock source for the PWM 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 the 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
    

Back To Top


Pwm Channel ID , Instance mapping and ISR mapping

The Pwm module is implemented using the DM timer instances on the device. All timer instances are supported by this driver implementation (Timers in Main Domain & MCU Domain).The following table lists the mapping between instance of timer and PwmChannelId of the configurator.

caution.png

When the GPTimer and PWM mdoule configurations are loaded in the configurator, if a particular Timer instance is already configured use by the GPTimer module, an error is reported.

PwmChannelId Timer Instance Associated ISR (if notification is enabled)
0 MCU TIMER 0 Pwm_Ch1Isr
1 MCU TIMER 1 Pwm_Ch2Isr
2 MCU TIMER 2 Pwm_Ch3Isr
3 MCU TIMER 3 Pwm_Ch4Isr
4 TIMER 0 Pwm_Ch5Isr
5 TIMER 1 Pwm_Ch7Isr
. . .
. . .
15 TIMER 11 Pwm_Ch16Isr

Back To Top


Configuration

The Pwm Driver implementation supports multiple configuration variants (refer section Introduction), the driver expects generated Pwm_Cfg.h to be present as (File Structure). Please refer (Build) to specify path to generated configuration. The associated timer configuration generated files Pwm_Cfg.c and Pwm_PBcfg.c to be present as show (File Structure)

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


Variance / Deviation from the specification

APIs related to power state

APIs related to setting or getting power state of the device is not supported, as the hardware itself doesn’t support this feature.

Back To Top


PwmMcuClockReference

To configure the clock source for Pwm (Timer hardware), one would have to access/configure common registers. It’s recommended that clock sources for the Pwm (Timer hardware) are done in SBL / Start up code.


PWM_FIXED_PERIOD_SHIFTED

The PWM_FIXED_PERIOD_SHIFTED, Pwm Channel Class type is not supported in this implementation.


Implementation Specific Configurations

This driver implementation introduces below listed configurable options

Back To Top


PwmDeviceVariant

Name PwmDeviceVariant
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. Based on the family, the number of instances of Timer module supported could vary.
Container Name PwmDriverConfiguration
Type Enumeration
Range AM65xx, TDA4x, etc… (new family of devices could be added in future)
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top


PwmTypeofInterruptFunction

Name PwmTypeofInterruptFunction
Description Specifies category of ISR.
Container Name PwmDriverConfiguration
Type Enumeration
Range PWM_ISR_CAT1 & PWM_ISR_CAT2
Value Configuration Class VARIANT-PRE-COMPILE
Note This implementation has been validated with PWM_ISR_CAT1 only

Back To Top


PwmDefaultOSCounterId

Name PwmDefaultOSCounterId
Description Specifies the OS counter to be used by the driver. All wait operations (wait for hardware timer module reset to complete) are time bound. This implementation uses OS calls (GetCounterValue () & GetElapsedValue ()) to get current and elapsed time to establish time bound operation. In cases where a constant value is returned / OS call is not operational, the time bound operation cannot be realized.
Container Name PwmDriverConfiguration
Type Boolean
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top


PwmEnableRegisterReadbackApi

Name PwmEnableRegisterReadbackApi
Description Adds / Removes service API Pwm_RegisterReadback ()
Safety feature : Some of the critical registers (corruption of which
could potentially break functionality of the Pwm/Timer)
The expected usage: Periodically this service API is invoked and
checked for data-consistency. i.e. the values of members of structure
Pwm_RegisterReadbackType is not expected to change.
Also refer (@ref ug_pwm_functional_i_cfg_s_api_imp)
Container Name PwmConfigurationOfOptApiServices
Type Boolean
Value Configuration Class VARIANT-PRE-COMPILE

Back To Top


PwmClkPrescaler

Name PwmClkPrescaler
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 PwmChannelConfigSet
Type uint8
Range 0 to 7
Value Configuration Class VARIANT-PRE-COMPILE & VARIANT-POST-BUILD

Back To Top


PwmPolarity

Name PwmPolarity
Description This parameter stores the initial polarity configured for a channel
Container Name PwmChannelConfigSet
Type Enummeration
Range PWM_HIGH, PWM_LOW
Value Configuration Class VARIANT-PRE-COMPILE & VARIANT-POST-BUILD

Back To Top


PwmIdleState

Name PwmIdleState
Description This parameter stores the initial polarity configured for a channel
Container Name PwmChannelConfigSet
Type Enummeration
Range PWM_HIGH , PWM_LOW
Value Configuration Class VARIANT-PRE-COMPILE & VARIANT-POST-BUILD

Back To Top


Non Standard Service APIs


Pwm_RegisterReadback

To protect HW from un-intended re-configuration (corrupted / fault hardware), some of the critical registers are read periodically and checked. By an entity outside the driver, the values of these registers are not expected to change. This is an optional service API, which can be turned OFF (refer section PwmEnableRegisterReadbackApi)

Service Name Pwm_RegisterReadback
Syntax void Pwm_RegisterReadback (Pwm_ChannelType PwmChannel, Pwm_RegisterReadbackType * RegRbPtr)
Service ID[hex] 0x0F
Sync/Async Synchronous
Reentrancy Reentrant (but not for the same timer channel)
Parameters (in) PwmChannel : Numeric identifier of the PWM channel
Parameters (inout) RegRbPtr : Pointer of type Pwm_RegisterReadbackType
Parameters (out) None
Return Value E_OK: Register read back has been done E_NOT_OK: Register read back failed (if channel is not initialized or RegRbPtr is NULL_PTR
Description Reads the important registers of the hardware unit and returns the value in the structure.

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 Pwm channel with notification enabled, an ISR requires to be registered. The Interrupt number associated with instance of the Timer is detailed in TRM (also, please refer the demo application). Please refer PwmApp_InterruptConfig () in Pwm demo application.

Some of the Timer interrupts are not routed/mapped to this core, these interrupts would require additional programming to route these to this core. Please refer PwmApp_InterruptConfig () in Pwm demo application.

Refer section (Pwm 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

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 PWM_CODE PWM_VAR_INIT PWM_VAR_NOINIT PWM_CONST PWM_CONFIG
PWM_START_SEC_VAR_INIT_UNSPECIFIED (.data) USED
PWM_DATA_INIT_32_SECTION USED
PWM_TEXT_SECTION USED
PWM_DATA_NO_INIT_UNSPECIFIED_SECTION USED
PWM_CONST_32_SECTION USED
PWM_ISR_TEXT_SECTION USED
PWM_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


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_Pwm_PWM_EXCLUSIVE_AREA_0 (), SchM_Exit_Pwm_PWM_EXCLUSIVE_AREA_0 () to enter critical section and exit.

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

Back To Top


File Structure

pwm_design_dir_detailed.png
Detailed Directory Structure
  1. Driver implemented by : Pwm.h, Pwm_Irq.h, Pwm.c, Pwm_Gptimer.c, Pwm_Priv.c ,Pwm_Irq.c and Pwm_Priv.h
  2. Example Configuration by : Pwm_Cfg.h, Pwm_Cfg.c and Pwm_PBcfg.c
  3. Example Application by : PwmApp.c and PwmApp.h

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 (Pwm.h File Structure) lists the SID

Back To Top


Error codes

Type of Error Related Error code Value (Hex)
API Pwm_Init service called with wrong parameter PWM_E_PARAM_CONFIG 0x10
API service used without module initialization PWM_E_UNINIT 0x11
API service used with an invalid channel Identifier PWM_E_PARAM_CHANNEL 0x12
Usage of unauthorized PWM service on PWM channel configured a fixed period PWM_E_PERIOD_UNCHANGEABLE 0x13
API Pwm_Init service called while the PWM driver has already been initialised PWM_E_ALREADY_INITIALIZED 0x14
API Pwm_GetVersionInfo is called with a NULL parameter. PWM_E_PARAM_POINTER 0x15

Back To Top


API Description

The AUTOSAR BSW PWM Driver specification details the APIs required for Pwm Driver. Please refer to (Low Level Definitions) for detailed API description. APIs related to setting/ getting the power state are not implemented, please refer to (Variance / Deviation from the specification). Also refer to (Non Standard Service APIs) for non-standard APIs which are included in this implemented.

Refer API Documentation for details

Back To Top


Example Application

The example application demonstrate use of Pwm module, the list below identifies key steps performed the example. The configuration file is present at (File Structure) The timer pin 1 on J19 on the AM65xx Evm Board Rev E2/E3 can be probed to check the output PWM signales. The timer pins will change based on the EVM used, support only for AM65xx Evm Board Rev E2/E3 currently.

  • Initializes “Result Status Flag”
  • PwmApp_Startup ()
    • Initialize board for pin mux
    • Initialize the control mmr registers for timer io muxing
    • Clear any pre-running timers
    • Builds interrupt list and registers ISR for the enabled Pwm channel
    • Sets up clock sources for the timer modules
  • PwmApp_mainTest ()
    • Initialize and start PWM module
    • Set duty cycle to 80% (if API is enabled)
    • Set output to idle state (if API is enabled)
    • Enable the channel again using Set period and duty (if API is enabled)
    • Enables Notification and check the notifications received in 10 secs (if notification is enabled)
    • Disable notification (if notification is enabled)
    • Wait for Timer expiry (if not in one shot mode)
    • De-initialize and Stop Pwm
  • Checks for error status, stack corruption and prints result

Back To Top


Example Log

DRA80X

        PWM_APP: Sample Application - STARTS !!!
 
        PWM_APP: PWM MCAL Version Info
        ---------------------
        PWM_APP: Vendor ID           : 44
        PWM_APP: Module ID           : 121
        PWM_APP: SW Major Version    : 0
        PWM_APP: SW Minor Version    : 1
        PWM_APP: SW Patch Version    : 0
        
        PWM_APP: Variant - Pre Compile being used !!!
        
        PWM_APP: PWM Channel Initialized 
        PWM_APP: PWM Duty cycle: 50% , PWM Period: 1 sec
        PWM_APP: Probe TIMER in Main domain(J19 Pin 1)in AM65xx EVM
        PWM_APP: This example waits for 10 seconds please probe
        
        PWM_APP: Changing the Duty cycle from 50% to 80% 
        
        PWM_APP: This example waits for 10 seconds Please probe
        
        PWM_APP: Setting Output to Idle state 
        PWM_APP: This example waits for 10 seconds Please probe
        
        PWM_APP: Changing PWM Period from 1s to 500 ms and Duty Cycle to 50%
        
        PWM_APP: This example waits for 10 seconds Please probe
        
        PWM_APP: Enabling Notifications for PWM channel
        PWM_APP: This example waits for 10 seconds please probe
        PWM_APP: Pwm Isr Count: 20 
        
        
        PWM_APP: Disabling Notifications for PWM channel
        
        PWM_APP: PWM De-initialized
        PWM_APP: Pwm Stack Usage 768 bytes
        PWM_APP: PWM Test Passed!!!

J721E

        PWM_APP: Sample Application - STARTS !!!
         
        PWM_APP: PWM MCAL Version Info
        ---------------------
        PWM_APP: Vendor ID           : 44
        PWM_APP: Module ID           : 121
        PWM_APP: SW Major Version    : 0
        PWM_APP: SW Minor Version    : 1
        PWM_APP: SW Patch Version    : 0
         
        PWM_APP: Variant - Pre Compile being used !!!
         
        PWM_APP: PWM Channel Initialized 
        PWM_APP: PWM Duty cycle: 50 Percent, PWM Period: 1 sec
        PWM_APP: Probe TIMER in Main domain(Test Point TP97)in J721E EVM
        PWM_APP: This example waits for 10 seconds please probe
         
        PWM_APP: Changing the Duty cycle from 50 Percent to 80 Percent 
        PWM_APP: This example waits for 10 seconds Please probe
         
        PWM_APP: Setting Output to Idle state 
        PWM_APP: This example waits for 10 seconds Please probe
         
        PWM_APP: Changing PWM Period from 1s to 500 ms and Duty Cycle to 50%
        PWM_APP: This example waits for 10 seconds Please probe
         
        PWM_APP: Enabling Notifications for PWM channelPWM_APP: This example waits for 10 seconds please probe
        PWM_APP: Pwm Isr Count: 8 
         
        PWM_APP: Disabling Notifications for PWM channel 
        PWM_APP: PWM De-initialized
        PWM_APP: Pwm Stack Usage 792 bytes
        PWM_APP: PWM Test Passed!!!

Back To Top


References

Back To Top


Document Revision History

Revision Date Author Description Status
0.1 03 April 2019 Vibha Pant First version Pending Review
0.2 15 April 2019 Vibha Pant Addressed review comments Approved
0.3 16 Oct 2018 Sujith S Added Logs from J721E testing Approved