View source for Watchdog timers on AM335x boards

== Watchdog timers on AM335x boards ==


=== Overview of this article ===

This article is meant to be a starting point for people to learn setup the watchdog timer on IGEP0033 AQUILA COM MODULE boards.

=== Feedback and Contributing ===

Creating articles in the wiki is a collaborative process, at any point, if you see a mistake you can contribute to this article.

Please, use the discussion tab for user comments. This is useful to separate page content and the discussion thereof and also, if you don't want to give normal users the right to edit the page but still want user contributed notes.

Editing permissions are restricted to registered users. [http://www.igep.biz Register in the main IGEP site] and you will have single sign-on. 

Consult the [http://www.mediawiki.org/wiki/Help:Contents User's Guide] for information on using the wiki software. 

There is a set of [[Wiki contribution guidelines]].


=== Aquila watchdog overview ===

Texas Instruments' AM3354 processor has one 32bits watchdog timer. 

Watchdogs are special files which, when opened, count time while there's no writing on them. Whenever a process writes data on that files or uses ''KEEP_ALIVE ioctl'' on them, they reset the timer. But if timer reaches the timeout value between writings, then watchdog forces the microprocessor to reboot, as it detects it as that process is freezing.


=== Watchdog timers under Linux kernel ===

The following documentation from [http://www.kernel.org kernel.org] can give you more information about the watchdogs:
* [http://www.kernel.org/doc/Documentation/watchdog/watchdog-api.txt Linux Watchdog driver API.]
* [http://www.kernel.org/doc/Documentation/watchdog/src Watchdog related example programs.]

Compile the ''watchdog-simple.c'' source code with your board's compiler. This is the application we will use demonstrate the basical watchdog functionality.

With this tiny piece of software, we can enable, and tick the watchdog card. First, we will run it to see the typical behaviour: 

 $ watchdog-simple
 
As the program ticks the card (writes on it every 10 seconds), the watchdog observes normal activity and doesn't reset the board.

Now we will modify the code in order to avoid the ticking, and only enabling the watchdog to count. For that purpose, we will comment or erase all the code inside the ''while loop'', obtaining  an infinite loop that makes nothing (which simulates the system freezing).

 $ watchdog-simple
 
After the timer reaches the timeout value, the board resets on itself.

=== Adding configuration parameters and flags ===

The watchdog can be configured by editing the underlying device parameters of special files. It can easily be implemented inside our simple test with ''ioctl()''.

====Timeout====

Default timeout for AM3354's watchdog is 60 seconds, but we can change the timeout value by adding the following lines to our main function, before the ''while'' loop:

 int timeout = 45;
 ioctl(fd, WDIOC_SETTIMEOUT, &timeout);
 printf("The timeout was set to %d seconds\n", timeout);

Please, note that you may include some header files in order to compile the program succesfully:
 #include <sys/ioctl.h>
 #include <linux/watchdog.h>

We can also request the timeout value by using the following commands:

 ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
 printf("The timeout value is %d seconds\n", timeout);

====Pretimeout====

The AM3354's watchdog timer doesn't support pretimeout, so we can't set it.

====Time left====

Sitara's watchdog can't show the amount of time that's remaining before rebooting the machine.

====Environmental Monitoring====

To learn about all the characteristics available for our watchdog timer, we can use ''ioctl'' it with the following command, which will fill the watchdog_info structure with the WDT identification and its Firmware version, as well as some flags with extra information about available options:

 struct watchdog_info ident;
 ioctl(fd, WDIOC_GETSUPPORT, &ident);
 
 printf("\n%s\n%d\n%d\n", ident.identity, ident.firmware_version, ident.options);

If we add this lines to our program, we will see something like this:

 OMAP Watchdog
 0
 32896

In order to decrypt the options integer, we must apply a bitwise AND operation between it and the different watchdog options flags. With a simple conditional we can print if a flag is activated, so we will know which functionalities does our watchdog support. We can do it like this:

 if (ident.options & WDIOF_SETTIMEOUT) printf("SET_TIMEOUT\n");

For further information on WD parameters, please refer to [http://www.kernel.org/doc/Documentation/watchdog/watchdog-api.txt Linux Watchdog driver API.]

-----

[[Category:Software]]