Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: how to use auto monitor feature to keep the chip alive #2543

Merged
merged 5 commits into from Dec 18, 2020
Merged

Documentation: how to use auto monitor feature to keep the chip alive #2543

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
49be7c6
Documentation: how to use auto monitor feature to keep the chip alive
saramonteiro Nov 13, 2020
ce9376f
Apply 1 suggestion(s) to 1 file(s)
saramonteiro Nov 27, 2020
01e1137
Apply 1 suggestion(s) to 1 file(s)
saramonteiro Nov 27, 2020
e0732c9
Apply suggestions from code review
saramonteiro Dec 15, 2020
6fce6ee
Update Documentation/components/drivers/character/watchdog.rst
davids5 Dec 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
49 changes: 48 additions & 1 deletion Documentation/components/drivers/character/watchdog.rst
View file
Open in desktop
Expand Up @@ -153,4 +153,51 @@ This command registers an user callback that will be triggered on timeout. It re

.. c:macro:: WDIOC_KEEPALIVE

This command resets the watchdog timer ("ping", "pet the dog", "feed the dog").
This command resets the watchdog timer AKA '**ping**", "**kick**", "**pet**", "**feed**" the dog".

Using the Auto-monitor feature to reset the watch dog,
------------------------------------------------------

The auto-monitor provides an OS-internal mechanism to automatically start and repeatedly reset the watchdog.

To enable it, follow the next instructions:

1. Select a Watchdog Timer Instance

To select the wdt browse in the ``menuconfig`` using the following path:

Go into menu :menuselection:`System Type --> <Chip> Peripheral Selection` and press :kbd:`Enter`. Then select one watchdog timer.

2. Enable the Auto-monitor option

Go into menu :menuselection:`Device Drivers --> Timer Driver Support` and press :kbd:`Enter`. Then enable:

- [x] Watchdog Timer Support

Then press :kbd:`Enter` again to enter into the Watchdog Timer Support menu. And finally enable the Auto-monitor option:

- [x] Auto-monitor

After selecting the option you may want to configure some parameters:

* **Timeout**: It is the watchdog timer expiration time in seconds.
* **Keep a live interval**: This is the interval in which the watchdog will be fed. It is in seconds. It can't be bigger than the timeout. If this interval is equal to timeout interval, than this interval will automatically change to half timeout.
* **Keep alive by**: This is a choice to determine who is going to feed the dog. There are 4 possible choices that are described as follows.

``Capture callback``: This choice registers a watchdog timer callback to reset the watchdog every time it expires, i.e., on timeout.

``Timer callback``: This choice also uses a timer callback to reset the watchdog, but it will reset the watchdog every "keep a live interval".

``Worker callback``: This choice uses the Low Priority Work Queue to reset the watchog every "keep a live interval". This choice depends on having the Low Priority Work Queue enabled.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not really need Low Priority Work Queue:

  1. If only high work enable, the high work queue is used
  2. otherwise the low work queue is used

This is because, low work queue will map to low work queue if only high work queue is enabled.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hum, so I'll change and add it as follows:

Worker callback: This choice uses a Work Queue to reset the watchdog every "keep a live interval". This choice depends on having the Low or High Priority Work Queue enabled.
If only the High Priority Work Queue is enabled, this one will be used, otherwise Low Priority Work Queue is used.

What do you think?

BTW, I thought it was only LPWORK because of the configuration:

      work_queue(LPWORK, &upper->work, watchdog_automonitor_worker,
                 upper, WATCHDOG_AUTOMONITOR_PING_INTERVAL);

I didn't know the LPWORK was replaced by the HPWORK in case the latter was enabled and the former was not.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why invent terms? Keep alive -> Watchdog Reset interval

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@saramonteiro yes, it's accurate now, thanks.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@davids5 I did not create terms like "Keep alive" and "pet the dog" or "ping".
Actually I just used the terms I saw in drivers/timers/watchdog.c and in include/nuttx/timers/watchdog.h
For example, the ioctl that feeds the dog is actually named WDIOC_KEEPALIVE.
My main goal with this PR is to document the WDT related features sticking to the current terms used in the source code.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xiaoxiang781216 thank you! =)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@davids5 I did not create terms like "Keep alive" and "pet the dog" or "ping".
Actually I just used the terms I saw in drivers/timers/watchdog.c and in include/nuttx/timers/watchdog.h
For example, the ioctl that feeds the dog is actually named WDIOC_KEEPALIVE.
My main goal with this PR is to document the WDT related features sticking to the current terms used in the source code.

Fare enough.


So, before enabling it, go into menu :menuselection:`RTOS Features --> Work queue support` and press :kbd:`Enter`.

- [x] Low priority (kernel) worker thread

``Idle callback``: This choice sets an Idle callback to feed the dog. It depends on the PM module, because this callback is triggered by the PM state change. To enable it do the following:

Go into menu :menuselection:`Device Drivers` and enable:

- [x] Power Management Support

After selecting one of these choices, the chip will keep itself alive by one of these options.