MCUSW
Wdg Design Document

Introduction

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. Wdg driver is part of the Microcontroller Drivers (block, shown above). Below shows the position of the Wdg driver in the AUTOSAR Architecture.

autosar_acrhitecture_wdg.png
AUTOSAR Architecture – WDG MCAL

WDG Overview

RTI(Real Time Interrupt) module supports three functional modes Counter mode, Capture mode & Windowed watchdog timer mode. Only Windowed watchdog timer mode is used to meet AUTOSAR WDG requirements.

The digital windowed watchdog generates an interrupt after a programmable period, if trigger is not serviced in the allowed time frame. TDA4x class of devices supports windowed watchdog timer where key can be only written in the configured window programmed through software. The watchdog opens a configurable time window in which it must be serviced. Any attempt to service the watchdog outside this time window, or a failure to service the watchdog in this time window, will cause the watchdog to generate a NMI interrupt.

Refer section (References) for more details on watchdog operation.

References

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

Requirements

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

Features Supported

Below listed are some of the key features that are supported

  • Initialization and configuration of WDG (configure window size, timeout value etc.)
  • Setting default mode(FAST/SLOW)
  • Service trigger via Wdg_Trigger API if called within the allowed time window.
  • Supports all instances of RTI present in MCU domain.
  • Supports additional configuration parameters, refer section (Implementation specific parameters (computed)) & (Wdg_RegisterReadback)
Design ID DES_WDG_001
Requirements Covered MCAL-955, 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-2572, MCAL-4472

Back To Top

caution.png

Features Not Supported / NON Compliance

  • [NON Compliance] Wdg_SetMode API is not supported. Due to hardware limitations, Mode and Timeout can’t be modified if watchdog is already running i.e only during initialization Mode and Timeout can be set.
  • OFF-Mode is not supported.
  • External Wdg driver : This driver is an internal, belongs to the Microcontroller Abstraction Layer whereas external watchdog driver belongs to the Onboard Device Abstraction Layer. So requirements w.r.o external watchdog are not implemented.
  • Standard AUTOSAR WDG specification 1, categorizes few BSW General Requirements as non-requirements, please refer MCAL-2634 for details
Design ID DES_WDG_002
Non Requirements MCAL-2566, MCAL-2568, MCAL-2570, MCAL-2574, MCAL-2583, MCAL-2584, MCAL-2585, MCAL-2586, MCAL-2588, MCAL-2600, MCAL-2611, MCAL-2612, MCAL-2613, MCAL-2614, MCAL-2615, MCAL-2616, MCAL-2617, MCAL-2618, MCAL-2619, MCAL-2620, MCAL-2621, MCAL-2634

Back To Top

Key Notes

  1. The trigger API Wdg_Trigger is non re-entrant as trigger API is expected to be called in only one thread context.
  2. The user has to take into account that the write to the RTIWDKEY register takes 3 RTI Interface CLK cycles. This needs to be considered for the WDG expiration calculation.
  3. If start time defined by the windowed watchdog configuration has been violated also causes interrupt. Start time violation indicates that the WDG is serviced before the service window was opened. Please refer (Fundamental Operation) and TRM, item 2 of (References) for more details.

Assumptions

Below listed 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 WDG module is expected to be enabled before calling any WDG module API.
  2. The WDG driver as such doesn’t perform any PRCM programming to get the functional clock.
  3. The clock-source selection for WDG is not performed by the WDG driver, other entities such as SBL, MCAL module MCU shall perform the same.
  4. Assumed that only one of the RTI instance is initiated per core at which driver is running.

Note that assumption 1 and 2 are specified by AUTOSAR WDG specification and 3 and 4 are device specific assumption.

Back To Top

Constraints

Some of the critical constraints of this design are listed below

Back To Top

Design Description

Fundamental Operation

The Digital Watchdog Timer(DWT) generates reset after a programmable period, if not serviced within that period. In DWT, time-out boundary is configurable.In DWWD, along with configurable time-out boundary, the start time boundary is also configurable. The DWWD can generate Reset or Interrupt, if not serviced within window(Open Window) defined by start time and time-out boundary. Also the DWWD can generate Reset or Interrupt if serviced outside Open Window (i.e within Closed Window). Generation of Reset or Interrupt depends on the DWWD Reaction configuration. 

    DWWD Down Counter Overview :
    Upper 12 bit part of the down counter is configurable and
    remaining 13 bit are always 1.
    Minimum possible time-out value is 2^13 RTI clock cycles.
    Maximum possible time-out value is 2^25 RTI clock cycles.
    Example :
    The expiration time of the DWD Down Counter can be determined with following equation:
    texp= (RTI_DWDPRLD + 1) x 2^13 / RTI_FCLK
    where RTI_DWDPRLD(12 bit) = 0...4095 and RTI_FCLK is RTI functional frequency.
    RTI_FCLK : 32kHz
    12 bit preload value : 0x004
    25 bit preload value : 0x0009FFF
    time-out value(in RTI clock cycles) : 40959.
    time-out value(in seconds) : (40959 + 1) / 32000 = 1.28 seconds.

     DWWD Window Sizes Overview :
     (timeout value),(timeout value - 1),(timeout value - 2),........................3 2 1 0
   (100%)|___________________________Open Window_________________________|
    (50%)|         Closed Window         |_________________Open Window__ |
    (25%)|            Closed Window                        |___OW________|
  (12.5%)|                 Closed Window                          |__OW__|
  (6.25%)|                     Closed Window                        |_OW_|
 (3.125%)|                         Closed Window                      |OW|

WDG Configuration Sequence

wdg_design_driver_configuration_sequence.png
WatchDog Timer Configuration Sequence

Back To Top

Dynamic Behavior

States

As detailed in specification of 1, Driver will be in one of the following states.

  • WDG_UNINIT : Default state indicating a non-initialized module.
  • WDG_IDLE : Indicating initialization is successful.
  • WDG_BUSY : Indicating module is busy(during execution).
wdg_design_driver_state.png
Driver States

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

  • Wdg.h and Wdg_Priv.h: Shall implement the interface provided by the AUTOSAR
  • Wdg_Priv.c and Wdg_Priv.h: Shall implement the driver functionality
  • Wdg_Dbg.h: Shall contain debug variable declarations of the driver.

Example Application

  • Wdg_Cfg.h and Wdg_Cfg.c: Shall implement the generated configuration for pre-compile variant
  • Wdg_Lcfg.c: Shall implement the generated configuration for link-time variant
  • Wdg_PBcfg.c: Shall implement the generated configuration for post-build variant
  • WdgApp.c and WdgApp.h: Shall implement the example application that demonstrates the use of the driver
wdg_design_dir.png
Directory Structure
wdg_design_dir_detailed.png
Detailed Directory Structure
Design ID DES_WDG_003
Requirements Covered MCAL-2567, MCAL-2569

Back To Top

Configurator

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

Design ID DES_WDG_004
Requirements Covered MCAL-2544, MCAL-2545, MCAL-2546, MCAL-2547, MCAL-2548, MCAL-2549, MCAL-2550, MCAL-2552, MCAL-2553, MCAL-2554, MCAL-2555, MCAL-2556, MCAL-2558, MCAL-2559, MCAL-2560, MCAL-2561, MCAL-2562, MCAL-2563, MCAL-2564, MCAL-2565, MCAL-2557, MCAL-2551, MCAL-2571

NON Standard configurable parameters

Following lists this design’s specific configurable parameters

Parameter Usage comment
WdgReaction Watchdog reaction for timer expiration or incorrect service.0x5 = This is the default value. The windowed watchdog will cause a reset if the watchdog is serviced outside the time window defined by the configuration, or if the watchdog is not serviced at all. 0xA = The windowed watchdog will generate a non-maskable interrupt to the CPU if the watchdog is serviced outside the time window defined by the configuration, or if the watchdog is not serviced at all. Writing any other value will cause a system reset if the watchdog is serviced outside the time window.
WdgWindowSize Digital Windowed Watchdog Window Size. Selecting 100% enables standard watchdog (not windowed). WWDSIZE: 0x00000050 = 50%, WWDSIZE: 0x00000500 = 25%, WWDSIZE: 0x00005000 = 12.5%, WWDSIZE: 0x00050000 = 6.25%, WWDSIZE: 0x00500000 = 3.125%, WWDSIZE: Any other value = 3.125%
WdgTimeoutValue Watchdog timeout period in milli seconds.Watchdog generates a non-maskable interrupt to the CPU if the watchdog is serviced after this timeout period.
WdgDeviceVariant Select SOC variant.
WdgInstanceId Selects Watchdog HW instance id.
WdgRtiFrequency RTI Clock Frequency (Hz) used to calculate preload value during init time.
WdgRegisterReadbackApi Compile switch to enable / disable the Critical Registers Readback API

Back To Top

Implementation specific parameters (computed)

Variant Support

The driver shall support all variants VARIANT-PRE-COMPILE, VARIANT-LINK-TIME and VARIANT-POST-BUILD

Design ID DES_WDG_005
Requirements Covered MCAL-2635, MCAL-2636, MCAL-2637, MCAL-2638, MCAL-2639, MCAL-2640, MCAL-2642

Back To Top

Dependency on other modules

In addition to dependencies listed in section 5 of 1, WDG driver shall depend on these modules to meet the required functionality. WDG uses RTI module present in the device to meet the required functionality.

This peripheral also requires 2 different clock to be operational, namely ICLK and FCLK.

SBL

  • ICLK: Is interface clock required for internal read/write registers 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: Is functional clock, used to operate the module. As detailed in section (Constraints), other entity would require to select the right clock source for the peripheral.

ESM

There is no direct reset signal generation from watchdog when it expires instead it generates an ESM interrupt. ESM module will signal ESM pin error and then external controller resets the SOC.

Design ID DES_WDG_006
Requirements Covered MCAL-2651, MCAL-2653

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)
API service used in wrong context (e.g. module not initialized). WDG_E_DRIVER_STATE 0x10
API service called with wrong / inconsistent parameter(s) WDG_E_PARAM_MODE 0x11
API service called with wrong / inconsistent parameter(s) WDG_E_PARAM_CONFIG 0x12
The passed timeout value is higher than the maximum timeout value WDG_E_PARAM_TIMEOUT 0x13
API is called with wrong pointer value (e.g. NULL pointer) WDG_E_PARAM_POINTER 0x14
Invalid configuration set selection WDG_E_INIT_FAILED 0x15

Error Detection

The detection of development errors is configurable (ON / OFF) at pre-compile time. The switch WdgDevErrorDetect will enable or disable the detection of all development errors.

Error notification (DET)

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

Back To Top

Runtime Errors

The following runtime/production errors shall be detectable by Wdg driver.

Type of Error Related Error code Value (Hex)
Setting a watchdog mode failed (during initialization or mode switch). WDG_E_MODE_FAILED Defined By Integrator
Initialization or watchdog mode switch failed because it would disable the watchdog though this is not allowed in this configuration WDG_E_DISABLE_REJECTED Defined By Integrator

Error notification (DEM)

All detected run time errors shall be reported via Dem_ReportErrorStatus() service of the Diagnostic Event Manager (DEM).

Design ID DES_WDG_008
Requirements Covered MCAL-2630, MCAL-2576, MCAL-2577, MCAL-2578, MCAL-2579, MCAL-2580, MCAL-2581, MCAL-2582

Back To Top

Resource Behavior

  • Code Size : WDG Implmentation shall not consume more than 30 Kilobytes for .text section and 2Kilobytes for .const section.
Design ID DES_WDG_009
Requirements Covered MCAL-2645
  • Stack Size : WDG Service AP'sI shall not consume more than 2 kilo-bytes of stack memory.
Design ID DES_WDG_010
Requirements Covered MCAL-2646

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

Wdg_ModeInfoType

Used to define watchdog hardware specific parameters per instance and the values of these are expected to be populated by configurator.

Type Variable Name Comments
uint32 reaction Reaction type: 0x5 - This value causes a reset if the watchdog is serviced outside the time window defined by the configuration, or if the watchdog is not serviced at all. 0xA - The windowed watchdog will generate a non-maskable interrupt to the CPU if the watchdog is serviced outside the time window defined by the configuration, or if the watchdog is not serviced at all.
uint32 windowSize Digital Windowed Watchdog Window Size. Selecting 100% enables standard watchdog (not windowed). WWDSIZE: 0x00000050 = 50%, WWDSIZE: 0x00000500 = 25%, WWDSIZE: 0x00005000 = 12.5%, WWDSIZE: 0x00050000 = 6.25%, WWDSIZE: 0x00500000 = 3.125%, WWDSIZE: Any other value = 3.125%
uint32 timeOutVal Watchdog timeout period in milli seconds.Watchdog generates a non-maskable interrupt or reset to the CPU if the watchdog is serviced after this timeout period.
Design ID DES_WDG_011
Requirements Covered MCAL-2601, MCAL-2635, MCAL-2636, MCAL-2637

Back To Top

Wdg_ConfigType

Refer section 8.2.1 of 1 Used for pointers to structures holding configuration data provided to the Wdg module initialization routine for configuration of the module and watchdog hardware.

Type Variable Name Comments
WdgIf_ModeType defaultMode Default watchdog mode(WDGIF_FAST_MODE/WDGIF_SLOW_MODE)
Wdg_ModeInfoType fastModeCfg Contains fast mode hardware specific configuration.(Wdg_ModeInfoType)
Wdg_ModeInfoType slowModeCfg Contains slow mode hardware specific configuration.(Wdg_ModeInfoType)
Design ID DES_WDG_012
Requirements Covered MCAL-2602

Back To Top

Wdg_ConfigType_PC

Used to define Pre-Compile parameters populated by configurator.

Type Variable Name Comments
uint16 instanceId Hardware Instance Id
uint32 initialTimeOut The initial timeout (seconds) for the trigger condition to be initialized during Init function. It shall be not larger than WdgMaxTimeout.
Design ID DES_WDG_013
Requirements Covered MCAL-2639, MCAL-2552

Back To Top

Wdg_RegisterReadbackType

Name Type Range Comments
rtiDwdCtrl uint32 0 to 0xFFFFFFFF Digital Watchdog Control, To Enable DWD
rtiDwdprld uint32 0 to 0xFFFFFFFF Digital Watchdog Preload Value
rtiWdStatus uint32 0 to 0xFFFFFFFF Digital Watchdog Status Register
rtiWdKey uint32 0 to 0xFFFFFFFF Digital Watchdog Key Register
rtiWwdRxnCtrl uint32 0 to 0xFFFFFFFF Digital Windowed Watchdog Reaction
rtiWwdSizeCtrl uint32 0 to 0xFFFFFFFF Digital Windowed Watchdog Window Size

Back To Top

API's

For the standard API's please refer 8.3 of 1. Sections below also highlight other design considerations for the implementation.

Wdg_Init

Refer section 8.3.1 of 1

Design ID DES_WDG_014
Requirements Covered MCAL-2603, MCAL-2604, MCAL-2605, MCAL-2606, MCAL-2607 MCAL-2608, MCAL-2609, MCAL-2610

Back To Top

Wdg_SetTriggerCondition

Refer section 8.3.3 of 1

Design ID DES_WDG_015
Requirements Covered MCAL-2622, MCAL-2623, MCAL-2624, MCAL-2625, MCAL-2626, MCAL-2627

Back To Top

Wdg_GetVersionInfo

Refer section 8.3.4 of 1

Design ID DES_WDG_016
Requirements Covered MCAL-2628, MCAL-2629

Back To Top

Wdg_Trigger

Design ID DES_WDG_017
Requirements Covered MCAL-2593, MCAL-2587, MCAL-2589, MCAL-2590, MCAL-2591, MCAL-2592, MCAL-2594, MCAL-2595, MCAL-2596, MCAL-2644, MCAL-2647, MCAL-2573, MCAL-2575
Service Name Wdg_Trigger
Description Trigger routine which should be called by application periodically
Syntax void Wdg_Trigger(void)
Service ID 0x05

Back To Top

Wdg_RegisterReadback

As noted from previous implementation, the wdg configuration registers could be potentially 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. Constraint: Should be called only after module initialization

Description Comments
Service Name Wdg_RegisterReadback Can potentially be turned OFF
Design ID DES_WDG_018
Requirements Covered MCAL-2643
Syntax Std_ReturnType Wdg_RegisterReadback(P2VAR(Wdg_RegisterReadbackType, AUTOMATIC, WDG_APPL_DATA) regRbPtr) Wdg_RegisterReadbackType defines the type, that holds critical values, refer below
Service ID 0x06
Sync / Async Sync
Reentrancy Non Reentrant
Parameter in None None
Parameters out regRbPtr A pointer of type Wdg_RegisterReadbackType, which holds the read back values
Return Value Standard return type E_OK or E_NOT_OK in case of DET error

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

This service could potentially be turned OFF in the configurator.

Back To Top

Global Variables

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

Variable Type Description Default Value
Wdg_DrvStatus Wdg_StatusType Initialization status of the driver is maintained WDG_UNINIT
Wdg_DrvObj Wdg_DriverObjType WDG driver object, local to the implementation and scope shall NOT be limited to Wdg.c Undefined
Design ID DES_WDG_019
Requirements Covered SWS_BSW_00130

Back To Top

Decision Analysis & Resolution (DAR)

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

Watchdog SOC Reset Functionality

The watchdog hardware generates a violation interrupt or ESM interrupt after a programmable period, if no correct key sequence is written to the RTI watchdog key register.

DAR Criteria

Guarantee reset on watchdog expiry and minimal software load on CPU.

Available Alternatives

  • CPU Interrupt Mode. RTI expires (AUTOSAR Core) -> R5F Interrupt -> Safety R5F -> DMSC -> Reset Core
    • Advantages:
      • Simple to implement.
      • No dependency on external modules
    • Disadvantages:
      • If CPU is not able to execute the ISR(eg DDR,OCMC Failure) reset may not occur.
  • ESM Interrupt Mode RTI expires (AUTOSAR Core) -> ESM Interrupt -> ESM pin Error -> External controller resets the whole SoC
    • Advantages:
      • No overhead to CPU.
    • Disadvantages:
      • Dependency on external module to reset the core.

Decision

Recommended to use ESM interrupt mode. ESM will make sure to signal the severe device failure if interrupt occurs.

Watchdog Service Routine

The routine servicing a watchdog shall be implemented as an interrupt routine driven by a hardware timer/GPT.Refer SWS_Wdg_00166 AUTOSAR WDG specification 1.

DAR Criteria

There should be no dependency on external module.

Available Alternatives

  • Driven by Hardware Timer.
    • Advantages:
      • Guarantees timing constraints required for windowed watchdog conditions.
    • Disadvantages:
      • Dependency on external module.
  • Driven by Application Periodically
    • Advantages:
      • No dependency on external module.
    • Disadvantages:
      • Application need to take care of the latency by calling service API within the time window.

Decision

To avoid dependency on the external module Wdg_Trigger API is provided which should be called by application periodically.

Design ID DES_WDG_020
Requirements Covered MCAL-2651, MCAL-2652, MCAL-2653

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

  • Timeout
    • Test cases shall ensure watchdog generates ESM interrupts and thereby reset occurs for the configured timeout value.
    • Also test with different set of timeout values(Equivalence partition test).
  • State Transitions
    • Test cases shall exercise all state transitions as detailed in section (States)
  • Modes
    • Test cases shall ensure watchdog support both fast/slow modes.
  • Trigger Condition
    • Test cases shall ensure driver test with different set of trigger condition timeout values(Equivalence partition test).
  • Window Sizes
    • Test cases shall ensure watchdog operation test with all window sizes that hardware supports.
  • Window Violation Test
    • Test cases shall ensure watchdog start time violation test.
  • Test for all instances
    • Test cases shall ensure watchdog operation for all the RTI instances supported.
  • Test for different clock sources
    • Test cases shall ensure watchdog operation for all the RTI clock sources supported.

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 30th Nov 2018 Sunil M S First version Pending Review
1.0 6th Dec 2018 Sunil M S Addressed Review Comments Intranet Link Approved