Cleanup Linux Watchdog documentation
Subsystems (2)
cover Cleanup Linux Watchdog documentation
From: Philipp Hahn <[email protected]>
Hello,
while reading the documentation on the Linux kernel watchdog subsystem[1] I noticed some strange looking formatting: structs are detected automatically by Sphinx and the word **after** it is considered the name of the structure, but the watchdog documentation puts the name **before** the word struct; this leads to the wrong word being emphasized.
Also reorganize the index page to better separate the documentation on generic infrastructure from specific drivers – which are mostly obsolete and relevant for historic documentation only.
Please apply; thank you for all your work.
Philipp
[1]: https://docs.kernel.org/watchdog/convert_drivers_to_kernel_api.html
Philipp Hahn (6):
watchdog: Fix wrong SPDX license identifier
watchdog: Change suffix .txt to .rst in references
watchdog: Move struct before name
watchdog: Replace intermixed tab/space indent
watchdog: Separate kind of documentation
watchdog: Prefix WDT with ICS for clarity
.../convert_drivers_to_kernel_api.rst | 28 +++++++++---------- Documentation/watchdog/index.rst | 22 +++++++++++---- Documentation/watchdog/watchdog-api.rst | 4 +-- .../watchdog/watchdog-kernel-api.rst | 2 +- Documentation/watchdog/wdt.rst | 6 ++-- drivers/watchdog/Kconfig | 6 ++-- 6 files changed, 39 insertions(+), 29 deletions(-)
Signature · 1 line
2.43.0
PATCH 1/6 watchdog: Fix wrong SPDX license identifier
From: Philipp Hahn <[email protected]>
The identifier GPL-2.0 has been deprecated in favor of GPL-2.0-only. Change it to silence checkpatch.
[1]: https://spdx.org/licenses/#deprecated
--- Documentation/watchdog/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/watchdog/index.rst +1 -1
@@ -1,4 +1,4 @@ -.. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0-only ================ Watchdog Support
Signature · 1 line
2.43.0
[email protected]
AI reviewRe: [PATCH 1/6] watchdog: Fix wrong SPDX license identifier
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Medium] The commit claims to fix a checkpatch warning by replacing `GPL-2.0` with `GPL-2.0-only`, but…
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The commit claims to fix a checkpatch warning by replacing GPL-2.0 with GPL-2.0-only, but the kernel's checkpatch does not warn about GPL-2.0 in this context, making the change unnecessary churn based on a false premise. --
commit b8d17764218e572db22388434473471ed009998c
Author: Philipp Hahn <[email protected]>
watchdog: Fix wrong SPDX license identifier
This commit updates the SPDX license identifier in the watchdog documentation from GPL-2.0 to GPL-2.0-only.
Quoted 2 lines
The identifier GPL-2.0 has been deprecated in favor of GPL-2.0-only. Change it to silence checkpatch.
Is this description accurate regarding checkpatch?
Looking at scripts/checkpatch.pl, it only enforces GPL-2.0-only for files under Documentation/devicetree/bindings/ and include/dt-bindings/.
Additionally, LICENSES/preferred/GPL-2.0 explicitly defines GPL-2.0 as a valid identifier in the Linux kernel.
Since checkpatch does not emit warnings for GPL-2.0 in generic subsystem documentation like Documentation/watchdog/index.rst, does this change introduce unnecessary churn?
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Guenter Roeck
maintainerRe: [PATCH 1/6] watchdog: Fix wrong SPDX license identifier
Quoted 20 lines · On 5/4/26 04:17, [email protected] wrote:
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] The commit claims to fix a checkpatch warning by replacingGPL-2.0withGPL-2.0-only, but the kernel's checkpatch does not warn aboutGPL-2.0in this context, making the change unnecessary churn based on a false premise. --commit
b8d17764218e572db22388434473471ed009998c
Author: Philipp Hahn <[email protected]>watchdog: Fix wrong SPDX license identifier
This commit updates the SPDX license identifier in the watchdog documentation from GPL-2.0 to GPL-2.0-only.
Quoted 2 lines
The identifier GPL-2.0 has been deprecated in favor of GPL-2.0-only. Change it to silence checkpatch.
Is this description accurate regarding checkpatch?
Looking at
scripts/checkpatch.pl, it only enforces GPL-2.0-only for files underDocumentation/devicetree/bindings/andinclude/dt-bindings/.
Quoted 7 lines
Additionally,
LICENSES/preferred/GPL-2.0explicitly defines GPL-2.0 as a valid identifier in the Linux kernel.Since checkpatch does not emit warnings for GPL-2.0 in generic subsystem documentation like
Documentation/watchdog/index.rst, does this change introduce unnecessary churn?
linux-next$ scripts/checkpatch.pl --strict -f Documentation/watchdog/index.rst
total: 0 errors, 0 warnings, 0 checks, 18 lines checked
Documentation/watchdog/index.rst has no obvious style problems and is ready for submission.
Please refrain from unnecessary churn, and from making false statements ("to silence checkpatch").
Guenter
AW: [PATCH 1/6] watchdog: Fix wrong SPDX license identifier
Hello Guenher,
Quoted 4 lines
linux-next$
scripts/checkpatch.pl--strict -fDocumentation/watchdog/index.rst
total: 0 errors, 0 warnings, 0 checks, 18 lines checked
Documentation/watchdog/index.rsthas no obvious style problems and is ready for submission.
Sorry for the wrong file, but it was …/wdt.rst which checkpatch complained about.
Quoted 2 lines
Please refrain from unnecessary churn, and from making false statements ("to silence checkpatch").
Sorry for that, v2 is on its way.
Thank you for your mail and sorry for the extra work.
Philipp
Guenter Roeck
maintainerRe: AW: [PATCH 1/6] watchdog: Fix wrong SPDX license identifier
Quoted 7 lines · Philipp Hahn
Hello Guenher,
Quoted 4 lines
linux-next$
scripts/checkpatch.pl--strict -fDocumentation/watchdog/index.rst
total: 0 errors, 0 warnings, 0 checks, 18 lines checked
Documentation/watchdog/index.rsthas no obvious style problems and is ready for submission.
Quoted 9 lines
Sorry for the wrong file, but it was …/wdt.rst which
checkpatchcomplained about.Quoted 2 lines
Please refrain from unnecessary churn, and from making false statements ("to silence checkpatch").
Sorry for that, v2 is on its way.
Thank you for your mail and sorry for the extra work.
By sending v2 without giving me a chance to finish reviewing v1 you did create even more extra work :-(
Guenter
PATCH 2/6 watchdog: Change suffix .txt to .rst in references
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Fix link to documentation, which has already been converted to reST. Also remove apostrophes which are no longer needed.
--- Documentation/watchdog/convert_drivers_to_kernel_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.rst +2 -2
@@ -114,7 +114,7 @@ Add the watchdog operations --------------------------- All possible callbacks are defined in 'struct watchdog_ops'. You can find it -explained in 'watchdog-kernel-api.txt' in this directory. start() and +explained in watchdog-kernel-api.rst in this directory. start() and owner must be set, the rest are optional. You will easily find corresponding functions in the old driver. Note that you will now get a pointer to the watchdog_device as a parameter to these functions, so you probably have to
@@ -153,7 +153,7 @@ Add the watchdog device Now we need to create a 'struct watchdog_device' and populate it with the necessary information for the framework. The struct is also explained in detail -in 'watchdog-kernel-api.txt' in this directory. We pass it the mandatory +in watchdog-kernel-api.rst in this directory. We pass it the mandatory watchdog_info struct and the newly created watchdog_ops. Often, old drivers have their own record-keeping for things like bootstatus and timeout using static variables. Those have to be converted to use the members in
Signature · 1 line
2.43.0
PATCH 3/6 watchdog: Move `struct` before name
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Write struct before the structure name as Sphinx otherwise uses the following word after it. See
https://docs.kernel.org/watchdog/watchdog-api.html#environmental-monitoring
--- .../convert_drivers_to_kernel_api.rst | 24 +++++++++---------- Documentation/watchdog/watchdog-api.rst | 2 +- .../watchdog/watchdog-kernel-api.rst | 2 +- 3 files changed, 14 insertions(+), 14 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.rst +12 -12
@@ -11,12 +11,12 @@ This document shall guide you for this task. The necessary steps are described as well as things to look out for. -Remove the file_operations struct +Remove the struct file_operations --------------------------------- Old drivers define their own file_operations for actions like open(), write(), etc... These are now handled by the framework and just call the driver when -needed. So, in general, the 'file_operations' struct and assorted functions can +needed. So, in general, the struct file_operations and assorted functions can go. Only very few driver-specific details have to be moved to other functions. Here is a overview of the functions and probably needed actions:
@@ -36,7 +36,7 @@ Here is a overview of the functions and probably needed actions: from the driver: WDIOC_GETSUPPORT: - Returns the mandatory watchdog_info struct from the driver + Returns the mandatory struct watchdog_info from the driver WDIOC_GETSTATUS: Needs the status-callback defined, otherwise returns 0
@@ -88,8 +88,8 @@ refactoring. The rest can go. Remove the miscdevice --------------------- -Since the file_operations are gone now, you can also remove the 'struct -miscdevice'. The framework will create it on watchdog_dev_register() called by +Since the file_operations are gone now, you can also remove the struct +miscdevice. The framework will create it on watchdog_dev_register() called by watchdog_register_device():: -static struct miscdevice s3c2410wdt_miscdev = {
@@ -113,10 +113,10 @@ them. Includes can be removed, too. For example:: Add the watchdog operations --------------------------- -All possible callbacks are defined in 'struct watchdog_ops'. You can find it +All possible callbacks are defined in struct watchdog_ops. You can find it explained in watchdog-kernel-api.rst in this directory. start() and owner must be set, the rest are optional. You will easily find corresponding -functions in the old driver. Note that you will now get a pointer to the +functions in the old driver. Note that you will now get a pointer to the struct watchdog_device as a parameter to these functions, so you probably have to change the function header. Other changes are most likely not needed, because here simply happens the direct hardware access. If you have device-specific
@@ -151,12 +151,12 @@ A typical function-header change looks like:: Add the watchdog device ----------------------- -Now we need to create a 'struct watchdog_device' and populate it with the -necessary information for the framework. The struct is also explained in detail +Now we need to create a struct watchdog_device and populate it with the +necessary information for the framework. The structure is also explained in detail in watchdog-kernel-api.rst in this directory. We pass it the mandatory -watchdog_info struct and the newly created watchdog_ops. Often, old drivers +struct watchdog_info and the newly created struct watchdog_ops. Often, old drivers have their own record-keeping for things like bootstatus and timeout using -static variables. Those have to be converted to use the members in +static variables. Those have to be converted to use the members in struct watchdog_device. Note that the timeout values are unsigned int. Some drivers use signed int, so this has to be converted, too.
@@ -174,7 +174,7 @@ Handle the 'nowayout' feature A few drivers use nowayout statically, i.e. there is no module parameter for it and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be used. This needs to be converted by initializing the status variable of the -watchdog_device like this:: +struct watchdog_device like this:: .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Documentation/watchdog/watchdog-api.rst +1 -1
@@ -158,7 +158,7 @@ available to ask what the device can do:: struct watchdog_info ident; ioctl(fd, WDIOC_GETSUPPORT, &ident); -the fields returned in the ident struct are: +the fields returned in the struct watchdog_info are: ================ ============================================= identity a string identifying the watchdog driver
Documentation/watchdog/watchdog-kernel-api.rst +1 -1
@@ -257,7 +257,7 @@ bit-operations. The status bits that are defined are: To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog timer device) you can either: - * set it statically in your watchdog_device struct with + * set it statically in your struct watchdog_device with .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Signature · 1 line
2.43.0
PATCH 4/6 watchdog: Replace intermixed tab/space indent
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Consistently indent all lines with tabs instead of having one line using blanks.
--- Documentation/watchdog/watchdog-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/watchdog/watchdog-api.rst +1 -1
@@ -161,7 +161,7 @@ available to ask what the device can do:: the fields returned in the struct watchdog_info are: ================ ============================================= - identity a string identifying the watchdog driver + identity a string identifying the watchdog driver firmware_version the firmware version of the card if available options a flags describing what the device supports ================ =============================================
Signature · 1 line
2.43.0
PATCH 5/6 watchdog: Separate kind of documentation
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Currently there are several (sub-)documents for "Generic kernel infrastructure API" and several "driver specific" documents. Put each one into its own sub-section.
--- Documentation/watchdog/index.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-)
Documentation/watchdog/index.rst +15 -5
@@ -4,15 +4,25 @@ Watchdog Support ================ +Kernel infrastructure +===================== + .. toctree:: :maxdepth: 1 - hpwdt - mlx-wdt - pcwd-watchdog watchdog-api watchdog-kernel-api - watchdog-parameters watchdog-pm - wdt convert_drivers_to_kernel_api + +Driver specific +=============== + +.. toctree:: + :maxdepth: 1 + + watchdog-parameters + wdt + hpwdt + mlx-wdt + pcwd-watchdog
Signature · 1 line
2.43.0
PATCH 6/6 watchdog: Prefix WDT with ICS for clarity
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
wdt.rst is only about the Watchdog timer from "Industrial Computer Source" (ICS). Change the title to better express this.
--- Documentation/watchdog/wdt.rst | 6 +++--- drivers/watchdog/Kconfig | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-)
Documentation/watchdog/wdt.rst +3 -3
@@ -1,6 +1,6 @@ -============================================================ -WDT Watchdog Timer Interfaces For The Linux Operating System -============================================================ +================================================================ +ICS WDT Watchdog Timer Interfaces For The Linux Operating System +================================================================ Last Reviewed: 10/05/2007
drivers/watchdog/Kconfig +3 -3
@@ -2270,10 +2270,10 @@ config MIXCOMWD Most people will say N. config WDT - tristate "WDT Watchdog timer" + tristate "ICS WDT Watchdog timer" depends on ISA help - If you have a WDT500P or WDT501P watchdog board, say Y here, + If you have an ICS WDT500P or WDT501P watchdog board, say Y here, otherwise N. It is not possible to probe for this board, which means that you have to inform the kernel about the IO port and IRQ that is needed (you can do this via the io and irq parameters)
@@ -2304,7 +2304,7 @@ config PCIPCWATCHDOG Most people will say N. config WDTPCI - tristate "PCI-WDT500/501 Watchdog timer" + tristate "ICS PCI-WDT500/501 Watchdog timer" depends on PCI && HAS_IOPORT help If you have a PCI-WDT500/501 watchdog board, say Y here, otherwise N.
Signature · 1 line
2.43.0
Guenter Roeck
maintainerRe: [PATCH 6/6] watchdog: Prefix WDT with ICS for clarity
Quoted 5 lines · Philipp Hahn
From: Philipp Hahn <[email protected]>
wdt.rstis only about the Watchdog timer from "Industrial Computer Source" (ICS). Change the title to better express this.
Please also explain "ICS" into the documentation file.
We can not rename the Kconfig symbol, but I'd also suggest to rename the documentation to icswdt.rst or maybe better watchdog-ics.rst.
Additional comment below.
Thanks,
Guenter
Quoted 25 lines
Signed-off-by Philipp Hahn <[email protected]>--- Documentation/watchdog/wdt.rst | 6 +++--- drivers/watchdog/Kconfig | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-)Documentation/watchdog/wdt.rst +3
-3@@ -1,6 +1,6 @@ -============================================================ -WDT Watchdog Timer Interfaces For The Linux Operating System -============================================================ +================================================================ +ICS WDT Watchdog Timer Interfaces For The Linux Operating System +================================================================ Last Reviewed: 10/05/2007drivers/watchdog/Kconfig +0
-0
drivers/watchdog/Kconfig config MIXCOMWD · line 2273
Quoted 5 lines
drivers/watchdog/Kconfig +1
-1@@ -2270,10 +2270,10 @@ config MIXCOMWD Most people will say N. config WDT - tristate "WDT Watchdog timer" + tristate "ICS WDT Watchdog timer"
WDT is now redundant. Maybe "ICS WDT500P/WDT501P Watchdog timer" to match the PCI variant.
Quoted 16 lines
drivers/watchdog/Kconfig +2
-2depends on ISA help - If you have a WDT500P or WDT501P watchdog board, say Y here, + If you have an ICS WDT500P or WDT501P watchdog board, say Y here, otherwise N. It is not possible to probe for this board, which means that you have to inform the kernel about the IO port and IRQ that is needed (you can do this via the io and irq parameters)@@ -2304,7 +2304,7 @@ config PCIPCWATCHDOG Most people will say N. config WDTPCI - tristate "PCI-WDT500/501 Watchdog timer" + tristate "ICS PCI-WDT500/501 Watchdog timer" depends on PCI && HAS_IOPORT help If you have a PCI-WDT500/501 watchdog board, say Y here, otherwise N.
v2 cover Cleanup Linux Watchdog documentation
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Hello,
while reading the documentation on the Linux kernel watchdog subsystem[1] I noticed some strange looking formatting: structs are detected automatically by Sphinx and the word **after** it is considered the name of the structure, but the watchdog documentation puts the name **before** the word struct; this leads to the wrong word being emphasized.
Also reorganize the index page to better separate the documentation on generic infrastructure from specific drivers – which are mostly obsolete and relevant for historic documentation only.
Please apply; thank you for all your work.
Philipp
[1]: https://docs.kernel.org/watchdog/convert_drivers_to_kernel_api.html
---
Philipp Hahn (5):
watchdog: Change suffix .txt to .rst in references
watchdog: Move struct before name
watchdog: Replace intermixed tab/space indent
watchdog: Separate kind of documentation
watchdog: Prefix WDT with ICS for clarity
v1 -> 2
- Drop invalid SPDX change to Documentation/watchdog/index.rst
- Add SPDX to Documentation/watchdog/wdt.rst
.../convert_drivers_to_kernel_api.rst | 28 +++++++++---------- Documentation/watchdog/index.rst | 20 +++++++++---- Documentation/watchdog/watchdog-api.rst | 4 +-- .../watchdog/watchdog-kernel-api.rst | 2 +- Documentation/watchdog/wdt.rst | 8 ++++-- drivers/watchdog/Kconfig | 6 ++-- 6 files changed, 40 insertions(+), 28 deletions(-)
Signature · 1 line
2.43.0
PATCH v2 1/5 watchdog: Change suffix .txt to .rst in references
From: Philipp Hahn <[email protected]>
Fix link to documentation, which has already been converted to reST. Also remove apostrophes which are no longer needed.
--- Documentation/watchdog/convert_drivers_to_kernel_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.rst +2 -2
@@ -114,7 +114,7 @@ Add the watchdog operations --------------------------- All possible callbacks are defined in 'struct watchdog_ops'. You can find it -explained in 'watchdog-kernel-api.txt' in this directory. start() and +explained in watchdog-kernel-api.rst in this directory. start() and owner must be set, the rest are optional. You will easily find corresponding functions in the old driver. Note that you will now get a pointer to the watchdog_device as a parameter to these functions, so you probably have to
@@ -153,7 +153,7 @@ Add the watchdog device Now we need to create a 'struct watchdog_device' and populate it with the necessary information for the framework. The struct is also explained in detail -in 'watchdog-kernel-api.txt' in this directory. We pass it the mandatory +in watchdog-kernel-api.rst in this directory. We pass it the mandatory watchdog_info struct and the newly created watchdog_ops. Often, old drivers have their own record-keeping for things like bootstatus and timeout using static variables. Those have to be converted to use the members in
Signature · 1 line
2.43.0
PATCH v2 2/5 watchdog: Move `struct` before name
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Write struct before the structure name as Sphinx otherwise uses the following word after it. See
https://docs.kernel.org/watchdog/watchdog-api.html#environmental-monitoring
--- .../convert_drivers_to_kernel_api.rst | 24 +++++++++---------- Documentation/watchdog/watchdog-api.rst | 2 +- .../watchdog/watchdog-kernel-api.rst | 2 +- 3 files changed, 14 insertions(+), 14 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.rst +12 -12
@@ -11,12 +11,12 @@ This document shall guide you for this task. The necessary steps are described as well as things to look out for. -Remove the file_operations struct +Remove the struct file_operations --------------------------------- Old drivers define their own file_operations for actions like open(), write(), etc... These are now handled by the framework and just call the driver when -needed. So, in general, the 'file_operations' struct and assorted functions can +needed. So, in general, the struct file_operations and assorted functions can go. Only very few driver-specific details have to be moved to other functions. Here is a overview of the functions and probably needed actions:
@@ -36,7 +36,7 @@ Here is a overview of the functions and probably needed actions: from the driver: WDIOC_GETSUPPORT: - Returns the mandatory watchdog_info struct from the driver + Returns the mandatory struct watchdog_info from the driver WDIOC_GETSTATUS: Needs the status-callback defined, otherwise returns 0
@@ -88,8 +88,8 @@ refactoring. The rest can go. Remove the miscdevice --------------------- -Since the file_operations are gone now, you can also remove the 'struct -miscdevice'. The framework will create it on watchdog_dev_register() called by +Since the file_operations are gone now, you can also remove the struct +miscdevice. The framework will create it on watchdog_dev_register() called by watchdog_register_device():: -static struct miscdevice s3c2410wdt_miscdev = {
@@ -113,10 +113,10 @@ them. Includes can be removed, too. For example:: Add the watchdog operations --------------------------- -All possible callbacks are defined in 'struct watchdog_ops'. You can find it +All possible callbacks are defined in struct watchdog_ops. You can find it explained in watchdog-kernel-api.rst in this directory. start() and owner must be set, the rest are optional. You will easily find corresponding -functions in the old driver. Note that you will now get a pointer to the +functions in the old driver. Note that you will now get a pointer to the struct watchdog_device as a parameter to these functions, so you probably have to change the function header. Other changes are most likely not needed, because here simply happens the direct hardware access. If you have device-specific
@@ -151,12 +151,12 @@ A typical function-header change looks like:: Add the watchdog device ----------------------- -Now we need to create a 'struct watchdog_device' and populate it with the -necessary information for the framework. The struct is also explained in detail +Now we need to create a struct watchdog_device and populate it with the +necessary information for the framework. The structure is also explained in detail in watchdog-kernel-api.rst in this directory. We pass it the mandatory -watchdog_info struct and the newly created watchdog_ops. Often, old drivers +struct watchdog_info and the newly created struct watchdog_ops. Often, old drivers have their own record-keeping for things like bootstatus and timeout using -static variables. Those have to be converted to use the members in +static variables. Those have to be converted to use the members in struct watchdog_device. Note that the timeout values are unsigned int. Some drivers use signed int, so this has to be converted, too.
@@ -174,7 +174,7 @@ Handle the 'nowayout' feature A few drivers use nowayout statically, i.e. there is no module parameter for it and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be used. This needs to be converted by initializing the status variable of the -watchdog_device like this:: +struct watchdog_device like this:: .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Documentation/watchdog/watchdog-api.rst +1 -1
@@ -158,7 +158,7 @@ available to ask what the device can do:: struct watchdog_info ident; ioctl(fd, WDIOC_GETSUPPORT, &ident); -the fields returned in the ident struct are: +the fields returned in the struct watchdog_info are: ================ ============================================= identity a string identifying the watchdog driver
Documentation/watchdog/watchdog-kernel-api.rst +1 -1
@@ -257,7 +257,7 @@ bit-operations. The status bits that are defined are: To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog timer device) you can either: - * set it statically in your watchdog_device struct with + * set it statically in your struct watchdog_device with .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
Signature · 1 line
2.43.0
PATCH v2 3/5 watchdog: Replace intermixed tab/space indent
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Consistently indent all lines with tabs instead of having one line using blanks.
--- Documentation/watchdog/watchdog-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/watchdog/watchdog-api.rst +1 -1
@@ -161,7 +161,7 @@ available to ask what the device can do:: the fields returned in the struct watchdog_info are: ================ ============================================= - identity a string identifying the watchdog driver + identity a string identifying the watchdog driver firmware_version the firmware version of the card if available options a flags describing what the device supports ================ =============================================
Signature · 1 line
2.43.0
PATCH v2 4/5 watchdog: Separate kind of documentation
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
Currently there are several (sub-)documents for "Generic kernel infrastructure API" and several "driver specific" documents. Put each one into its own sub-section.
--- Documentation/watchdog/index.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-)
Documentation/watchdog/index.rst +15 -5
@@ -4,15 +4,25 @@ Watchdog Support ================ +Kernel infrastructure +===================== + .. toctree:: :maxdepth: 1 - hpwdt - mlx-wdt - pcwd-watchdog watchdog-api watchdog-kernel-api - watchdog-parameters watchdog-pm - wdt convert_drivers_to_kernel_api + +Driver specific +=============== + +.. toctree:: + :maxdepth: 1 + + watchdog-parameters + wdt + hpwdt + mlx-wdt + pcwd-watchdog
Signature · 1 line
2.43.0
PATCH v2 5/5 watchdog: Prefix WDT with ICS for clarity
In reply to Philipp HahnFrom: Philipp Hahn <[email protected]>
wdt.rst is only about the Watchdog timer from "Industrial Computer Source" (ICS). Change the title to better express this.
Add missing SPDX license identifier GPL-2.0-or-later same as code to silence checkpatch.
--- Documentation/watchdog/wdt.rst | 8 +++++--- drivers/watchdog/Kconfig | 6 +++--- 2 files changed, 8 insertions(+), 6 deletions(-)
Documentation/watchdog/wdt.rst +5 -3
@@ -1,6 +1,8 @@ -============================================================ -WDT Watchdog Timer Interfaces For The Linux Operating System -============================================================ +.. SPDX-License-Identifier: GPL-2.0-or-later + +================================================================ +ICS WDT Watchdog Timer Interfaces For The Linux Operating System +================================================================ Last Reviewed: 10/05/2007
drivers/watchdog/Kconfig +3 -3
@@ -2270,10 +2270,10 @@ config MIXCOMWD Most people will say N. config WDT - tristate "WDT Watchdog timer" + tristate "ICS WDT Watchdog timer" depends on ISA help - If you have a WDT500P or WDT501P watchdog board, say Y here, + If you have an ICS WDT500P or WDT501P watchdog board, say Y here, otherwise N. It is not possible to probe for this board, which means that you have to inform the kernel about the IO port and IRQ that is needed (you can do this via the io and irq parameters)
@@ -2304,7 +2304,7 @@ config PCIPCWATCHDOG Most people will say N. config WDTPCI - tristate "PCI-WDT500/501 Watchdog timer" + tristate "ICS PCI-WDT500/501 Watchdog timer" depends on PCI && HAS_IOPORT help If you have a PCI-WDT500/501 watchdog board, say Y here, otherwise N.
Signature · 1 line
2.43.0
[email protected]
AI reviewRe: [PATCH v2 5/5] watchdog: Prefix WDT with ICS for clarity
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Low] Incomplete renaming: the 'ICS' prefix was not added to the Kconfig help text for the WDTPCI…
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Incomplete renaming: the 'ICS' prefix was not added to the Kconfig help text for the WDTPCI configuration. --
commit 4485842d9f93fd889373b4245fc0ff5cb5d3e3b8
Author: Philipp Hahn <[email protected]>
watchdog: Prefix WDT with ICS for clarity
The commit updates documentation and Kconfig files to clarify that WDT refers to the Watchdog timer from Industrial Computer Source (ICS). It adds the ICS prefix in several places and includes a missing SPDX license identifier.
Quoted 4 lines
drivers/watchdog/Kconfig +0
-0
[ ... ]
Quoted 11 lines
drivers/watchdog/Kconfig +2
-2@@ -2270,10 +2270,10 @@ config MIXCOMWD Most people will say N. config WDT - tristate "WDT Watchdog timer" + tristate "ICS WDT Watchdog timer" depends on ISA help - If you have a WDT500P or WDT501P watchdog board, say Y here, + If you have an ICS WDT500P or WDT501P watchdog board, say Y here, otherwise N. It is not possible to probe for this board, which means
[ ... ]
drivers/watchdog/Kconfig config PCIPCWATCHDOG · line 2310
Quoted 9 lines
drivers/watchdog/Kconfig +1
-1@@ -2304,7 +2304,7 @@ config PCIPCWATCHDOG Most people will say N. config WDTPCI - tristate "PCI-WDT500/501 Watchdog timer" + tristate "ICS PCI-WDT500/501 Watchdog timer" depends on PCI && HAS_IOPORT help If you have a PCI-WDT500/501 watchdog board, say Y here, otherwise N.
This isn't a bug, but should the help text for WDTPCI also be updated to include the ICS prefix for consistency? The WDT config help text was updated above, but this description still reads "If you have a PCI-WDT500/501 watchdog board".
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=5
Guenter Roeck
maintainerQuoted 15 lines · Philipp Hahn
From: Philipp Hahn <[email protected]>
Hello,
while reading the documentation on the Linux kernel watchdog subsystem[1] I noticed some strange looking formatting:
structs are detected automatically by Sphinx and the word **after** it is considered the name of the structure, but the watchdog documentation puts the name **before** the wordstruct; this leads to the wrong word being emphasized.Also reorganize the index page to better separate the documentation on generic infrastructure from specific drivers – which are mostly obsolete and relevant for historic documentation only.
Quoted 5 lines
Please apply; thank you for all your work.
Philipp
[1]: https://docs.kernel.org/watchdog/convert_drivers_to_kernel_api.html
From Documentation/process/submitting-patches.rst:
However, for a multi-patch series, it is generally best to avoid using In-Reply-To: to link to older versions of the series. This way multiple versions of the patch don't become an unmanageable forest of references in email clients.
... but you did that anyway. It also almost guarantees that new versions of a patch series get lost.
Guenter