From nobody Mon Jun 15 10:46:57 2026 Received: from mail-pf1-f178.google.com (mail-pf1-f178.google.com [209.85.210.178]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9020937DEAA for ; Mon, 13 Apr 2026 04:12:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776053553; cv=none; b=am2kFbQGwaFTia25lTNlc3KrIL52vvALof7WbaGaCzz8/qpDnk+kELOJOBqJBTTB44WFiOJsH3kiaRbd5PEgMOiutzLsUUgRsDcA10kZmMHzP+lsf+MOpCVxZHK7btyNp4yUCBTjcchd2VpT77RRZ9Da/ZXp4VarvEBLJBeWoW0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1776053553; c=relaxed/simple; bh=Nfx8SY0UEvaq6+gSxlXjMVt/bs4KEn/ejYgsUpz3yFU=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type; b=kkp32lrOg/cVEEpTt3UWsnVzFC4TNI/OEImYVU7c4vKJ5Bmgf8esYOKa1fMH5adiUhJ2LS6V9Sy0cIw5+/r5+FYTmk56y3KlgF4MhmAagQFjWLmfFv4s7BOt2wCYhpA5MF2BBq7FqqNmIhMEAqd3HBucj+bTCgCByxIRLZ4NcP0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=PVt1hTfd; arc=none smtp.client-ip=209.85.210.178 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="PVt1hTfd" Received: by mail-pf1-f178.google.com with SMTP id d2e1a72fcca58-82748257f5fso2132594b3a.1 for ; Sun, 12 Apr 2026 21:12:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1776053544; x=1776658344; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=EiR3khxQhFmDzcy0QJGcEyjroXltDHGy0h+uzT9wKzQ=; b=PVt1hTfdiTbS4jYbHQY1h6aJn5MhPlqg4nuCk7bYFfKjFsGgt1UOzV91D5wChlKE1H 4sPhNmMdF5zqI4izWGIAWx+nRXcdsyxkKE3sqmIc6Kf0B3a+Ep9ttoyR6BN/1qNXSluy ukazZiOuHc0gsi0pOV03bhR7Liy5m1DkbiQ621onz96DByGNz8R/R3Amr9Ltqsv29J8i /EzpmrTMzy+1qLJTI9ySQPib9H7tokrejir3Jeljk49NZXjiyHiA0urzwAYmR+LdpHL7 XUQzZAU34C0tnQkVt3oVWFTEpYg/aN/+gMskdXSR6VKtx2rxEK9RXKLWxN23Rh9dPST8 EK6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1776053544; x=1776658344; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=EiR3khxQhFmDzcy0QJGcEyjroXltDHGy0h+uzT9wKzQ=; b=m1BLvEYFTv/KljF8VhJFrgGGgYgepnwjomDgALAqzbmpZgYhj9cOHwueIjv45N0SFQ 4R6WcpQra2tgSsc6fQFQvZt6TUHOOXFa7QWdC3aQdW93E3GKQTGid59Qi4BLMN0Zbygo uHE4vOqv5PizCnlJrOID9Lni0JJ+VR19VwdOtcF/ni7+V6RHtg66wOOOULB6yAm4ZhxR grzSPiLSexw0JVhVH2vPCHjJc2IHDCxpVEVodpNW61X7k2E2iSGNRu+BbK53yNOfEcvK sFOX+8uLg5WYUmh22wTE0DJZ1c2YeZFsLUAN5IC6RhjNBFJMJKMK9bDbpThqjIpj3tiy Ug/w== X-Forwarded-Encrypted: i=1; AFNElJ9rEpLDLsceigyFCQImsozEBKKYqFJyk6sQFrdbUaMvPJwh6VlihLaQyJv+njW8uFPbxMNZgPRU26+2HQY=@vger.kernel.org X-Gm-Message-State: AOJu0YzsbtYHxLZpEWqxs+eaCXmKItMqkY5dnYSu+Ay5ma3Xtk3O3so/ KGMwIGG+TmDaEe8WkelvMeFPupGHxieuvsLLLlyx6KRT+/4FbBPe26gN X-Gm-Gg: AeBDieswP2IMXxrLeeO1rygVk396Kz035PCmXtlv20PoUW15UF/6MHAODOX3JA2Pi+t c4N0KVhIIDlcr78ZN/uKl+eaSKzLu3iL/yTmeLLjxEsgw+HZlPKKMI2oVTY4CuglnEak8Dp4EOl BeguWpbAnyi0TWswWqt2svRd8BO522hDmbxWhoy8Ax049Zp5OT3IdjAbEO7xwhzWci7VXC58SI3 JrSIPiBmFKeOEllh3429iRwty1hdmPlbiioDWGiDHRYCBps5UwltHoahivg6iyKufkIsHohEOGo lBDkEROAHAzL792ZZXX5jJLFfFXpE1sGbccK01xxX8sbtHkB+RQOYiR/trFGH2bm9GsdvrL+WEa fVuUpKGAJDc24eBd1QogSY1lcchKzJpICpHhzDMJzYXq0YFA0HthR92cSuxehzkt2/g/4w7trME DEjJso7a/wBnLCKZn9RMH3ALxnLurjI5xj8jEDUTmaQBh0 X-Received: by 2002:a05:6a20:1e42:b0:3a0:21ed:7e66 with SMTP id adf61e73a8af0-3a021ed7f66mr1782966637.25.1776053543674; Sun, 12 Apr 2026 21:12:23 -0700 (PDT) Received: from tech-Alienware-m15-R6.. ([122.171.18.84]) by smtp.gmail.com with ESMTPSA id 41be03b00d2f7-c79219c618asm8578587a12.18.2026.04.12.21.12.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 12 Apr 2026 21:12:23 -0700 (PDT) From: Sunny Patel To: linux-doc@vger.kernel.org Cc: linux-watchdog@vger.kernel.org, linux-kernel@vger.kernel.org, corbet@lwn.net, wim@linux-watchdog.org, linux@roeck-us.net, rdunlap@infradead.org, Sunny Patel Subject: [PATCH v5] Documentation: Refactored watchdog old doc Date: Mon, 13 Apr 2026 09:41:55 +0530 Message-ID: <20260413041215.10362-1-nueralspacetech@gmail.com> X-Mailer: git-send-email 2.43.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Mark WDIOC_GETTEMP and WDIOS_TEMPPANIC as deprecated since neither is implemented by the watchdog core and both are only present in a small number of legacy drivers. Add documentation for previously undocumented status bits WDIOF_MAGICCLOSE and WDIOF_ALARMONLY in the options field. Add documentation for WDIOF_PRETIMEOUT and WDIOF_SETTIMEOUT status bits describing their respective ioctls. Fix the following issues in existing documentation: - Remove version-specific reference to Linux 2.4.18 from the GETTIMEOUT ioctl description - Fix duplicate "was is" in printf format strings - Replace [FIXME] placeholder with proper descriptions for WDIOS_DISABLECARD, WDIOS_ENABLECARD and WDIOS_TEMPPANIC Signed-off-by: Sunny Patel Reviewed-by: Guenter Roeck --- Changes in v5: - Fixed WDIOC_GETTIMELEFT printf statement to correctly reference=20 "timeleft" instead of "timeout". =20 Changes in v4: - Fixed WDIOS_DISABLECARD description: corrected inverted logic =E2=80=94 the ioctl disables the hardware timer entirely rather than stopping pings. Clarified that userspace, not the kernel driver, is primarily responsible for pinging under normal operation. Documentation/watchdog/watchdog-api.rst | 65 +++++++++++++++++++++---- 1 file changed, 55 insertions(+), 10 deletions(-) diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchd= og/watchdog-api.rst index 78e228c272cf..736436a68f65 100644 --- a/Documentation/watchdog/watchdog-api.rst +++ b/Documentation/watchdog/watchdog-api.rst @@ -2,7 +2,7 @@ The Linux Watchdog driver API =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D =20 -Last reviewed: 10/05/2007 +Last reviewed: 04/08/2026 =20 =20 =20 @@ -42,7 +42,7 @@ activates as soon as /dev/watchdog is opened and will reb= oot unless the watchdog is pinged within a certain time, this time is called the timeout or margin. The simplest way to ping the watchdog is to write some data to the device. So a very simple watchdog daemon would look -like this source file: see samples/watchdog/watchdog-simple.c +like this source file: see samples/watchdog/watchdog-simple.c =20 A more advanced driver could for example check that a HTTP server is still responding before doing the write call to ping the watchdog. @@ -106,11 +106,10 @@ the requested one due to limitation of the hardware:: This example might actually print "The timeout was set to 60 seconds" if the device has a granularity of minutes for its timeout. =20 -Starting with the Linux 2.4.18 kernel, it is possible to query the -current timeout using the GETTIMEOUT ioctl:: +It is also possible to get the current timeout with the GETTIMEOUT ioctl:: =20 ioctl(fd, WDIOC_GETTIMEOUT, &timeout); - printf("The timeout was is %d seconds\n", timeout); + printf("The timeout is %d seconds\n", timeout); =20 Pretimeouts =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -133,7 +132,7 @@ seconds. Setting a pretimeout to zero disables it. There is also a get function for getting the pretimeout:: =20 ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout); - printf("The pretimeout was is %d seconds\n", timeout); + printf("The pretimeout is %d seconds\n", timeout); =20 Not all watchdog drivers will support a pretimeout. =20 @@ -145,12 +144,12 @@ before the system will reboot. The WDIOC_GETTIMELEFT = is the ioctl that returns the number of seconds before reboot:: =20 ioctl(fd, WDIOC_GETTIMELEFT, &timeleft); - printf("The timeout was is %d seconds\n", timeleft); + printf("The timeleft is %d seconds\n", timeleft); =20 Environmental monitoring =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -All watchdog drivers are required return more information about the system, +All watchdog drivers are required to return more information about the sys= tem, some do temperature, fan and power level monitoring, some can tell you the reason for the last reboot of the system. The GETSUPPORT ioctl is available to ask what the device can do:: @@ -227,12 +226,33 @@ The watchdog saw a keepalive ping since it was last q= ueried. WDIOF_SETTIMEOUT Can set/get the timeout =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The watchdog can do pretimeouts. +The watchdog supports timeout set/get via the WDIOC_SETTIMEOUT and +WDIOC_GETTIMEOUT ioctls. =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +The watchdog supports a pretimeout, a warning interrupt that fires before +the actual reboot timeout. Use WDIOC_SETPRETIMEOUT and WDIOC_GETPRETIMEOUT +to set/get the pretimeout. + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + WDIOF_MAGICCLOSE Supports magic close char + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver supports the Magic Close feature. The watchdog is only disabled +if the character 'V' is written to /dev/watchdog before the file descriptor +is closed. Without writing 'V' before closing, the watchdog remains active +and will trigger a reboot after the timeout expires. + + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + WDIOF_ALARMONLY Not a reboot watchdog + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The watchdog will not reboot the system when it expires. Instead it +triggers a management or other external alarm. Userspace should not +rely on a system reboot occurring. =20 For those drivers that return any bits set in the option field, the GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current @@ -254,6 +274,11 @@ returned value is the temperature in degrees Fahrenhei= t:: int temperature; ioctl(fd, WDIOC_GETTEMP, &temperature); =20 +.. note:: + ``WDIOC_GETTEMP`` is not implemented by the watchdog core and is + considered deprecated. It is only supported by a small number of + legacy drivers. New drivers should not implement it. + Finally the SETOPTIONS ioctl can be used to control some aspects of the cards operation:: =20 @@ -268,4 +293,24 @@ The following options are available: WDIOS_TEMPPANIC Kernel panic on temperature trip =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -[FIXME -- better explanations] +``WDIOS_DISABLECARD`` disables the hardware watchdog timer entirely, +allowing a controlled system shutdown without triggering a reboot. +Userspace is responsible for pinging the watchdog under normal +operation; this ioctl stops the underlying hardware timer so that +the absence of pings no longer causes a system reset. + +``WDIOS_ENABLECARD`` starts the watchdog timer. If the watchdog was +previously stopped via ``WDIOS_DISABLECARD``, this will re-enable it. The +hardware watchdog will begin counting down from the configured timeout. + +``WDIOS_TEMPPANIC`` enables temperature-based kernel panic. When set, +the driver will call ``panic()`` (or ``kernel_power_off()`` on some +drivers) if the hardware temperature sensor exceeds its threshold, +rather than only setting the ``WDIOF_OVERHEAT`` status bit. Support +for this option is driver-specific; not all watchdog drivers implement +temperature monitoring. + +.. note:: + ``WDIOS_TEMPPANIC`` is not implemented by the watchdog core and is + considered deprecated. It is only present in a small number of + legacy drivers. New drivers should not implement it. --=20 2.43.0