From nobody Sat Jun 20 18:38:35 2026 Received: from mail-pl1-f176.google.com (mail-pl1-f176.google.com [209.85.214.176]) (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 8FB3238A73C for ; Sat, 11 Apr 2026 15:09:31 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.176 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775920172; cv=none; b=N9ke21S26PbHTrcpqImBkf8NMZJWvIOkg9JqIidsVQ4UWpZ0Dy5bgtNjnq3PYsUUO2QcogUD5vUq1+/W+/ljEPWGuCeOg94Srczz82CuEDMwJHH/luDOZg9f/js4kSl73FNgLakd4dByngZvfVaea7UM0+X5kRLNhHTncUrf2oo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775920172; c=relaxed/simple; bh=lwKz3S60lPfR/UruL7HyqieQfuBV1mhLCaYlQ+cddJE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=eQVZZIyxv588j9HLWuVKVCjTIgTM++ONKLnu5u1dJ5jgU1Kueb/mhY2GFGmnmjXOIO1KRcMwbo1v1rvScsx/QxX/EpdFPmJrl6/zMQtX0+OF/7mV6LXrRRHaGBZT+ykWMo3Jgjnxc0KmU0/2RMYrsPiQOyrRYHYQuMZsVmREL38= 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=ohBjPBHy; arc=none smtp.client-ip=209.85.214.176 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="ohBjPBHy" Received: by mail-pl1-f176.google.com with SMTP id d9443c01a7336-2aae4816912so20559015ad.2 for ; Sat, 11 Apr 2026 08:09:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1775920171; x=1776524971; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=DZ/+0gdfc0R4BMhHn3bRqzxYcwGAO2dazgMq5MOhcqM=; b=ohBjPBHylU15tWrWXX/wXpW3XlFOgB4Ro7Gh+5X+ZB1zfsMlSUlN7SLiy0+GiDRbbf oNaKyuUb56nApujgm4xQ+aSGceuDiV7a/se3acP5c5U69/uoZk5soUARHWdPAbzdbasV ubqgZZbS+UbYVTWVMTXPPNATWMeB9gyxjmrk0fK5tFQYQB/8/kB0QNVP0XLuQBX/IOcL xIkbth8wHLLk5xDv2ZUKEugedWBLo15Xsghhp2xK93tJNJ+SvTJFVCxsBQshiAujNbBd XZcKJO6jpLKRyBywU0xnpYUW4anxQm6+/KoolS3cxzxihKH2I4efB8LmtOX7Q+DwSZZb q41w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1775920171; x=1776524971; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=DZ/+0gdfc0R4BMhHn3bRqzxYcwGAO2dazgMq5MOhcqM=; b=VW+KE7vPz/RTSQZK74Y9LP/ayYk2KQK02FZpXBqU+5rbrEcefsui5hPRREVYGRJ3qa 6NmS1t10TPaI+Y/eSZ+jixgMoLVLQIT45xYWmHY0WunCA8HN6JvUMTEvpT473yb082GF sMID7XIRawRq6mI3v9dvDOr6k0Je1tjUQEVIc8/6W+wVbN6YMqH+y1g0pMwVUfuT9bG/ 164Sj0roaLQtjgjBegYSxRMptp14vvG2zBVo5PUi10+WERQ3YEGCfmzSOOb7THYJBZAP TkkVA5LfMtIBlO5o3LHA2+WSdLo+KPGfURVNqVFgGjVW5bqI5mxT2a2mMQppiqEm/G/k j8+w== X-Forwarded-Encrypted: i=1; AJvYcCW0t5xyhwQsbqLOqCcwMNNRDlY2M/vMu9LbteLQ2Cu9rhPPC7WCw306gwk68KIsq+vmFIac5Ozg6kJCfQ4=@vger.kernel.org X-Gm-Message-State: AOJu0Yx/UXABJAxKLioNKW5D7LmyMw6di10KQ9WZhJ1ytIPIEVm4lUH+ /akivJRI2pmhgqgpdzdKFyIhR30TxnRxjQsm5QmzzdsJcTflke7jFsyNK1Wd5ZqI X-Gm-Gg: AeBDieuleLNvbjFen4hQmGfbbIyvqHqVK5Q0ssIP3/ZYvWPwlMh1gGFO48iRbIY7iTF KHx8dtWoRmJxCZ6SY2fxAQCd9CTrK5cpqAUEbuqzp4jDnDfFMqG5gsPACu8a17gIq6rhRWqxaom D9COUl7TFAcD/bZNn3JwwCHtHQZR/S6eJr188oFd8QOVWatPI5vyTQzn/7pShmS+adGdV0qX2N1 EJ7LG9DrVyhM9PM8Tflb31LL0wV6pJklnKzb8vWifkFtvwaFrkWmdega7PEPP9XQTGsoTaF34bP wiq9tAKt8UbtK6FpShlVIaXUFFL5PHN4wkK+Op7vXvW+Dg54Y0NEpgwuXtJKaPXILI+Bo34eDvk xmf89Cg1K9IIGpairn84zHC7tnTAqgRMOO3ntbrgrx7Ue9QwyrfhB/Bg7Oi1OW89BH7Zfj9QGXk DoTlvY5/nG7Q37wdj+dMt+CRhPg1pF+UdrwxNYTxNaFxEM X-Received: by 2002:a17:903:2c04:b0:2b2:4fcc:2687 with SMTP id d9443c01a7336-2b2d5a49c8cmr71870425ad.31.1775920170865; Sat, 11 Apr 2026 08:09:30 -0700 (PDT) Received: from tech-Alienware-m15-R6.. ([122.171.18.84]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-2b2d4f431c3sm58526515ad.79.2026.04.11.08.09.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 11 Apr 2026 08:09:30 -0700 (PDT) From: Sunny Patel To: Jonathan Corbet Cc: Wim Van Sebroeck , Guenter Roeck , Shuah Khan , linux-watchdog@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Sunny Patel Subject: [PATCH v2] Documentation: Refactored watchdog old doc Date: Sat, 11 Apr 2026 20:39:14 +0530 Message-ID: <20260411150922.20536-1-nueralspacetech@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <3e25ae54-e62d-484e-8d90-4f7825705e4f@roeck-us.net> References: <3e25ae54-e62d-484e-8d90-4f7825705e4f@roeck-us.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 --- Changes in v2: - Fixed typos: "tiemout" -> "timeout", "characted" -> "character" - Fixed "small number if legacy" -> "of legacy" - Fixed capitalization: "New Drivers" -> "New drivers", "USE" -> "Use" - Fixed spacing: "WDIOS_DISABLECARD,this" -> "WDIOS_DISABLECARD, this" - Fixed double spaces in two places - Added missing newline at end of file - Rewrote commit message Documentation/watchdog/watchdog-api.rst | 59 +++++++++++++++++++++---- 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchd= og/watchdog-api.rst index 78e228c272cf..3e9021a79671 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 @@ -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,7 +144,7 @@ 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 timeout 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 @@ -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 this, closing the device disables the watchdog +unconditionally. + + =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 +.. deprecated:: + ``WDIOC_GETTEMP`` is not implemented by the watchdog core. 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,22 @@ 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`` stops the watchdog timer. The driver will cease +pinging the hardware watchdog, allowing a controlled shutdown without +a forced reboot. This is equivalent to the watchdog being disarmed. + +``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. + +.. deprecated:: + ``WDIOS_TEMPPANIC`` is not implemented by the watchdog core and is only + present in a small number of legacy drivers. New drivers should not + implement it. --=20 2.43.0