4.20. WDG

4.20.1. About This Document

Document Title	User Guide of MCAL WDG Driver
Document Version	Version 1.6
Company	Texas Instruments
Document Name	WDG User Guide

4.20.2. Revision History

Version	Date	Revision History	Status
Versiont 1.0	26 April 2022	Initial Release	Approved
Versiont 1.1	05 Aug 2022	Updated AM263 to AM263x	Approved
Versiont 1.2	23 Dec 2022	WDG Example application testing procedure is added	Approved
Versiont 1.3	8 May 2023	WDG Example application testing procedure updated	Approved
Versiont 1.4	12 Jun 2023	Updated as per HTML format.	Approved
Versiont 1.5	25 Aug 2023	Document release version column removed	Approved
Versiont 1.6	16 Jan 2024	Updated Assumptions and Dependencies	Approved

4.20.3. Table of contents

1. Acronyms and Definitions

2. Functional Overview

3. Deviations to requirements (Requirement Traceability)

4. Integration Details

5. API Description

6. Configuration Description

7. Memory mapping

8. Memory footprint

9. Performance

10. Example Usage

11. FAQ’s

12. Test Report

13. References

14. TI Disclaimer

4.20.4. Acronyms and Definitions

Acronyms and Definitions Used are presented in below table.

Acronyms	Descriptions
BSW	Basic Software
DET	Default Error Tracer
WDG	Watchdog Timer
MCU	Micro Controller Unit
OS	Operating System

4.20.5. Functional Overview

4.20.5.1. Brief Overview

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

Supported AUTOSAR Release	4.3.1
Supported Configuration Variants	Pre-Compile, Post-build & Link-Time
Vendor ID	WDG_VENDOR_ID (44)
Module ID	WDG_MODULE_ID (102)
Supported Platform	AM263x

The WDG driver depends on some other modules, like DET for error handling, OSEK/AUTOSAR OS for interrupt handling and the Mcu module for system clock settings.

4.20.5.1.1. Wdg Driver Architecture

The Wdg driver has architecture as shown in below figure from the AUTOSAR spec

Fig. 4.9 Figure : Wdg in AUTOSAR architecture

The WDG driver provides services for handling the watch dog timer on the microcontroller.

The WDG driver performs two main tasks, which are as follows:

1. Initialization of WDG

2. Reset WDG expiration time (trigger)

4.20.5.1.2. Initialization

The initialization covers the following steps

1. Set selected watchdog timer expiration time

2. Set selected trigger timeout

3. Set selected window size (Digital Windowed Watchdog)

4. Set selected mode (Fast or slow can be selected but cannot be switched runtime)

4.20.5.1.3. States

1. WDG_IDLE: This is indicating the module is initialized and not busy.

2. WDG_BUSY: This is indicating the module is busy.

4.20.5.2. Features Supported and Not Supported

Features Supported	Features Not Supported
Setting default mode and timeout during initialization.	Off mode not supported
Setting window size (Digital Windowed Watchdog).	Due to hardware limitations, Mode and Timeout can’t be modified if watchdog is running.
Enable watchdog timer
Service watchdog timer.

4.20.5.3. Assumptions

1. The clock and PLL configuration is outside driver and should be configured for proper WDG operation.

2. The Pin Muxing should be initialized before initializing the Wdg module.

4.20.5.4. Limitations

None

4.20.5.5. Design overview

Please refer SITARA MCU MCAL Architecture Document and MCAL: WDG Detailed Design Document provided as part of CSP.

4.20.5.6. File Structure

Static source C File Structure is defined below in the table.

File Name	Description
Wdg.c	Main part of the module functionality, implements the AUTOSAR APIs for WDG driver
Wdg_Priv.c and Wdg_Priv.h	platform specific internal file
Wdg.h	WDG module header file. Needs to be included by higher layers
Wdg_Irq.c and Wdg_Irq.h	WDG Interrupt service routine

Plugin structure is defined below in the table.

Plugin Structure	Descriptions
Wdg_Cfg.h	Contains the base addresses, Precompile switches, Macros for channels, counters etc.
Wdg_PBcfg.c	Contains all channels Post-Build Configuration parameters
Wdg_Cfg.c	Contains all channels Pre-Compile Configuration parameters

The below diagram shows the files structure for the Wdg driver.

fig4 :WDG header file include structure

4.20.6. Deviations to requirements (Requirement Traceability)

4.20.6.1. Module Requirements

Please refer Software Product Specification document provided as part of CSP.

4.20.6.2. Deviation of requirements against AUTOSAR specification requirements

Will be updated in future release

4.20.7. Integration Details

4.20.7.1. Dependency on Other Software Modules

4.20.7.1.1. MCU

The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL.

4.20.7.1.2. OS

An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table. The WDG module may use AUTOSAR OS to suspend and restore global interrupts.

4.20.7.1.3. SchM

There are no exclusive areas.

4.20.7.1.4. Critical Sections

There are no critical sections.

4.20.7.1.5. DEM

By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus(). The DEM is enabled if the DemEventParameterRefs container is defined.

4.20.7.2. Error Handling module

4.20.7.2.1. DET

By default, production code related errors are reported to the DET using the service Det_ReportError(). If development error reporting is enabled (i.e. pre-compile parameter WDG_DEV_ERROR_DETECT== STD_ON). The reported service IDs identify the services which are described in 3.4. The following table presents the service IDs and the related services:

The errors reported to DET and DEM are described in the following table

Type of Error	Relevance	Related Error Code	Value
API service used in wrong context (e.g. module not initialized).	Development	WDG_E_DRIVER_STATE	0x10
API service called with wrong / inconsistent parameter(s)	Development	WDG_E_PARAM_MODE	0x11
API service called with wrong / inconsistent parameter(s)	Development	WDG_E_PARAM_CONFIG	0x12
The passed timeout value is higher than the max timeout value.	Development	WDG_E_PARAM_TIMEOUT	0x13
API is called with wrong pointer value (e.g. NULL pointer)	Development	WDG_E_PARAM_POINTER	0x14

4.20.7.2.2. Parameter Checking

AUTOSAR requires that API functions check the validity of their parameters. The checks are described in spec and are done as internal parameter checks of the API functions. These checks are for development error reporting and can be en/dis-abled separately. Refer to the configuration chapter where the en/dis-abling of the checks is described. En/dis-abling of single checks is an addition to the AUTOSAR standard which requires to en/dis-able the complete parameter checking via the parameter WDG_DEV_ERROR_DETECT. The following table shows which parameter checks are performed on which services:

Services	Wdg_Init	Wdg_SetMode	Wdg_SetTriggerCondition	Wdg_GetVersionInfo	Wdg_Trigger
WDG_E_DRIVER_STATE		X			X
WDG_E_PARAM_MODE		X
WDG_E_PARAM_CONFIG
WDG_E_PARAM_TIMEOUT			X
WDG_E_PARAM_POINTER	X			X
WDG_E_MODE_FAILED	X
WDG_E_DISABLE_REJECTED	X

4.20.7.2.3. Production Code Error Reporting

By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus(). The errors reported to DEM are described in the following table:

	ErrorCode	Description
Assigned by DEM	WDG_E_MODE_FAILED	This error is raised when setting the watchdog mode fails.
Assigned by DEM	WDG_E_DISABLE_REJECTED	Initialization or watchdog mode switch failed because it would disable the watchdog though this is not allowed in this configuration.
Assigned by DEM	WDG_E_HARDWARE_ERROR	This error is raised when register write failure occurs. (Hardware Failure)

4.20.7.2.4. Callback Function

The WDG driver does not provide any call back functions.

4.20.7.3. Hardware - Software - ISR API name mapping

None

4.20.7.4. Scheduling Strategy

None

4.20.8. API Description

4.20.8.1. Description of the API’s

Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.

4.20.8.2. API’s with Service ID

The following table presents the service IDs and the related services:

Service ID	Service
0x00	Wdg_Init
0x01	Wdg_SetMode
0x03	Wdg_SetTriggerCondition
0x04	Wdg_GetVersionInfo
0x05	Wdg_Trigger

4.20.8.3. Description on Non Standard API’s

Wdg_RegisterReadback API–This function is non-autosar based and is used to read the data in the registers of Wdg if we keep Wdg_REGISTER_READBACK_API Macro as ON.

4.20.9. Configuration Description

4.20.9.1. Configuration Variants

The Wdg is configured through GUI in Post-Build ,Pre-Compile Variants and Link Time Variants.

Variants	Generated Files
PostBuild	Wdg_PBcfg.c , Wdg_Cfg.h
Pre-Compile	Wdg_Cfg.c , Wdg_Cfg.h
Link-Time	Wdg_Lcfg.c , Wdg_Cfg.h

4.20.9.2. Parameter Description

4.20.9.2.1. Standard Configuration

Standard Parameters	Description	Default Value	Range	Unit
WDG_E_DISABLE_REJECTED	Reference to the DemEventParameter which shall be issued when the error “Initialization or mode switch failed because it would disable the watchdog” has occurred.	FALSE	0..1	Boolean
WDG_E_MODE_FAILED	Setting a watchdog mode failed (during initialization or mode switch)	FALSE	0..1	Boolean
WdgDevErrorDetect	Switches the development error detection and notification on or off.	FALSE	0..1	Boolean
WdgDisableAllowed	Compile switch to allow / forbid disabling the watchdog driver during runtime.	FALSE	0..1	Boolean
WdgIndex	Specifies the InstanceId of this module instance. If only one instance is present it shall have the Id 0.	0	0 .. 255	Integer
WdgInitialTimeout	The initial timeout (sec) for the trigger condition to be initialized during Init function.	0	0 .. 65.535]	Integer
WdgMaxTimeout	The maximum timeout (sec) to which the watchdog trigger condition can be initialized.	0	0 .. 65.535]	Integer
WdgVersionInfoApi	Compile switch to enable / disable the version information API	TRUE	0..1	Boolean
WdgDefaultMode	Default mode for watchdog driver initialization.	WDGIF_FAST_MODE	Wdg_ModeInfoType	Enumeration
WdgInstanceId	Watchdog HW instance id. 0 - R5F0_0, 1 - R5F0_1, 2 - R5F1_0, 3 - R5F1_1	0	0..3	Integer
WdgTriggerMode	Watchdog trigger mode (toggle/window/both)	WDG_WINDOW	WdgTriggerMode	Enumeration

4.20.9.2.2. IP Specific Configuration

Standard Parameters	Description	Default Value	Range	Unit/Datatype
WdgWindowSize	The Digital Windowed Watchdog window size. Selecting 100% enables standard watchdod	WINDOW_SIZE_100_PERCENT	Wdg_WindowSize	Enumeration
WdgRegisterReadbackApi	Compile switch to enable / disable the Register Readback API	FALSE	0..1	Boolean
WdgRtiFrequency	RTI Clock Frequency (MHz)	200	0..200	MHz
WdgPreloadValue	Watchdog preload value to be set in RTIDWDPRLD register. Expiration time is calculated using this function: texp = (WdgPreloadValue + 1) x 2^13 / RTICLK1	4095	0..4095	ms
WdgDeviceVariant	Select SOC AM263x variant	AM263x	AM263x
WdgReaction	Watchdog reaction for timer expiration or incorrect service.	WDG_GENERATE_RESET	Wdg_Reaction	Enumeration
WDG_E_HARDWARE_ERROR	This error is raised when Hardware failed detected	NULL	NA	NA

4.20.10. Memory mapping

Memory Mapping Sections	WDG_CODE	WDG_CODE_ISR	WDG_VAR_NO_INIT	WDG_VAR_ZERO_INIT	WDG_PBCFG	WDG_PBCFG_ROOT
WDG_START_SEC_VAR_INIT_UNSPECIFIED(.bss) WDG _STOP_SEC_VAR_INIT_UNSPECIFIED				x
WDG _START_SEC_CODE_APPL(.text) WDG _STOP_SEC_CODE_APPL		x
WDG _START_SEC_VAR_UNSPECIFIED(.data) WDG _STOP_SEC_VAR_UNSPECIFIED			x
WDG _START_SEC_CODE(.text) WDG _STOP_SEC_CODE	x
WDG_START_SEC_PBCFG(.data) WDG_STOP_SEC_PBCFG					x
WDG_START_SEC_PBCFG_ROOT(.const) WDG_STOP_SEC_PBCFG_ROOT						x

4.20.11. Memory footprint

Please refer Memory Footprint for more details.

4.20.12. Performance

None

4.20.13. Example Usage

4.20.13.1. Steps to build and run example

1. WDG example application demonstrates the MCAL WDG driver features, which is referred from folder <MCAL_ROOT>/examples/WDG.

2. This application can be built from the build folder by giving “gmake –s wdg_app PLATFORM=am263” command in command prompt.

3. Once the build is completed we get an appimage file, which is flashed in am263x controller and executed.

4. To Flash the appimage at the respective memory location as the SBL expects, path of the appimage file is provided in “default_sbl_qspi” file in “..<MCU_PLUS_SDK_INSTALLATION>toolsbootsbl_prebuiltam263x-cc”

5. Set the boot mode of board to UART mode.(UART boot mode: 1000)

6. Open command prompt at the path “..<MCU_PLUS_SDK_INSTALLATION>toolsboot" and provide command as follows: “python uart_uniflash.py -p COM<x> –cfg=sbl_prebuilt/am263x-cc/default_sbl_qspi.cfg” Here <x> depicts the COM PORT number where hardware is connected to system, which can be detected from device manager

7. Once the appimage is flashed after the command is executed, change the boot mode of board to QSPI mode.(QSPI boot mode: 0010)

8. Open the terminal to get the expected application log after doing hard reset on board.

9. Verify that the application produces the correct results as expected shown below.

4.20.13.2. Document external set up Information

None

4.20.13.3. Flow of the example application

1. Default Example program is configured in Non-Maskable Interrupt method (WDT will trigger interrupt when counter becomes zero).

2. WDT window reaction can be changed to “reset” through configuration (EB Tresos).

3. In example, service interval is 25ms and service count is 100. So, every 25ms core will service the WDT for 100 times (25*100 = 2500 ms).

4. WDG is integrated with WDG in order to service WDG.

5. WDG_SetTriggerCondition API is servicing WDG by passing non zero timeout value

6. Then after it will raise an interrupt and interrupt will run (WDT_Isr() function). In ISR function core reset will occurs and start running program again automatically.

7. It checks for reset reason, if reset happened due to WDT then “Test Passed”

8. In Reset window reaction mode, after counter reaches to zero POR(Power ON Reset) happens.

4.20.13.4. Example Logs

WDG_APP: Sample Application - STARTS !!!

WDG MCAL Version Info
---------------------
Vendor ID           : 44
Module ID           : 102
SW Major Version    : 9
SW Minor Version    : 1
SW Patch Version    : 0

----------------------------------------------------------------------------------
Starting WDG test  !!!
----------------------------------------------------------------------------------
Service Count 100
Service Interval 25 milliseconds
------------------------------------------
Trigger Value = 2500 milliseconds
------------------------------------------
Maximum Service Interval 74 milliseconds
Initializing channels
Post-Build variant is being used .
Reset Reason 2
Test Passed!!
WDG Stack Usage: 800 bytes
------------------------------------------

4.20.14. FAQ’s

Will be updated in future release

4.20.15. Test Report

Please refer AM26x WDG Driver Test Case Report provided as part of CSP.

4.20.16. References

AUTOSAR_SWS_WatchdogDriver

Technical Reference Manual

4.20.17. TI Disclaimer

Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.

TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.

Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.

TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.

Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265