From nobody Thu Oct 2 20:27:53 2025 Received: from mail-pf1-f170.google.com (mail-pf1-f170.google.com [209.85.210.170]) (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 4EFC02F49F2 for ; Fri, 12 Sep 2025 10:13:39 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.170 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757672021; cv=none; b=nA+cdZVP0/0r7tFM5DU3OeidARpzZ+YvLcrL756dK1CGKXkzo7JLqO69gewcWjiez/OP+O9GnMAS0P2xYQ0Bx7IMHk6+KIXtjEW+d5gn2P0864fbiyZBZbkTLFa7zwSFbH+aEtSWXetLpZQZh5qWL1yJVxImGqO5ZFFh22bcJQk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757672021; c=relaxed/simple; bh=L9AjRhWN6K9GCJF/+6ZwgVizRNTCCmqDO7KY/KLz4NY=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=b6KsgR60AwuP4ivMvA776YOPLhx7KZZ7m0mTF0hc9FEGmlVRiwMbN22qhS7Wr97la70rboRn/isQ2S8hFm08wU4RvXRJ1tPML+ZQ4QkbPyRxFg1nm8PJ81qIDmsoOb1EdPMm/Mcl3Z/R7j2GzjNw9Y9Qi9q2hr5cYDZJfnGl6fw= 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=mFcT3Mu+; arc=none smtp.client-ip=209.85.210.170 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="mFcT3Mu+" Received: by mail-pf1-f170.google.com with SMTP id d2e1a72fcca58-772627dd50aso3215363b3a.1 for ; Fri, 12 Sep 2025 03:13:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1757672019; x=1758276819; 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=bn+/3FE5CmsLxOS0M5YahrLvDpar54OOYFHjkWGVE7o=; b=mFcT3Mu+4XaIgX/307J8T/feRXCtKSlmr8rq0uqDMPSSn0EAMlJuXBWFXCfHAsdedC K7rbCAdFHZ3qgXKwj2p9tN6m1WyJQdJfLLW2jk8po1Qd60supsMKC3EbZCJdh7kcFPNz mfRFESI/s+5fLJeU/QPjbnI2HddOBTQjRR4+6ARjuTZVsouZU1N73kj6dp2IJUJFnv3z NsrkmHRBsrp2gDc7JaFgGds1iXFyKyI8GgFtlsUpsIlBnrzMjjcX7ZPqfAq7yAQwCEih Ssp02dAy6oK/bzgNpnzABus6U4OfFaWsV7R4u9jHT9yKmszlSTZkS8tOed28cT0Mv1vH oMkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1757672019; x=1758276819; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=bn+/3FE5CmsLxOS0M5YahrLvDpar54OOYFHjkWGVE7o=; b=tLgQwbyccTsw2Almr3ZTRkZdBw1xbEFdoVtEI/neQ5AvQwP8wG4o2w8g0ytORD9tpD SO/TBI4xh1N8gvZvWWHbRtP3RT9UcMr6zGQLvUwbr1EkcsQa5MGs7U87ke1qYHr+DhQ2 qYPLSReYsyDAMRMVO+iZ950yhDc9pbfSMM6NH5q7CdlJ+lowtGRAxo5B3bDnAPm4t9Tm 6lzqZjUzLQ5PTX6UQXJL9vJ+N+TslrIFQXNFOqtLv+YfVtbUS2oLwupP+Qh8dNUoQL2a peQTwY17ABFoWUEsJB5OZdn+ftYzYRWppXDEL++9oOrvmN6eC/5x5arIhLy1Jo48s2Qe yL4g== X-Forwarded-Encrypted: i=1; AJvYcCWSEdQNZhwvDKELAhqikqVwHVZdasPnX2Z7GF5nVcVAkVAu77nZsz8qzkX68MO4zNaCYZ7zvzpdEj0wHOM=@vger.kernel.org X-Gm-Message-State: AOJu0YzkDOzqEsA8U1Rb+RK8K3LLfWpDSrLG/Pmj66iZrNrGwKuYZ5Xp AuTiC1aRJwkxbrtVPdSU5SqNeHpTWUytJecECQf2cH6l2Q+UfoKHsKCK X-Gm-Gg: ASbGncvuIvTYSlJ4owP4fklRNFo7wxBq/LxHl1yrcA9Lq4pLY7dtmPRRUtcF3n/wBQU njW3+OK7NIJW9a5lkf5yQrVrcSxZpQWVG3dO6vzlBwaqqDSssyKdQowkK3DJqKdmvZCOD5CRFkd F8N61cYMzp8Rs02e4clngOAHTBfFVWPMmrHj+Qb4BaVYzjzJ62xQ13Opq/qLgdsdLo8pHROnldD jOi2UuAzcryrKfnel33B+r5VCWxT2ylrfT1qbIeYLxq75OfyeuVNBFTJy1XVi6ahb1srTTfNJZo LyMU8LXRMbYTkemhJjTIRcUaXWkS/N+G3/NLyp374udxxwlhx9CKBY1/cZCDY6hpPWOovuzljw9 O5IqaX50O4fiwRXeagvCqFhaLMCsOfuZfc54eZBmM3xzqUPPTiZjGrXYC X-Google-Smtp-Source: AGHT+IE9hLw78GXki+Z9/2VgA5oux+LKfhhFZu5WvV1JUasShceVOJ3liaB3nQw7f//NCPosPLRn+w== X-Received: by 2002:a17:902:ef46:b0:246:571:4b51 with SMTP id d9443c01a7336-25d2da1100dmr32684915ad.29.1757672018598; Fri, 12 Sep 2025 03:13:38 -0700 (PDT) Received: from localhost ([185.49.34.62]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-25c37293f0asm45182095ad.43.2025.09.12.03.13.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 12 Sep 2025 03:13:37 -0700 (PDT) From: Jinchao Wang To: Andrew Morton , Masami Hiramatsu , Peter Zijlstra , Mike Rapoport , Alexander Potapenko , Jonathan Corbet , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , x86@kernel.org, "H. Peter Anvin" , Juri Lelli , Vincent Guittot , Dietmar Eggemann , Steven Rostedt , Ben Segall , Mel Gorman , Valentin Schneider , Arnaldo Carvalho de Melo , Namhyung Kim , Mark Rutland , Alexander Shishkin , Jiri Olsa , Ian Rogers , Adrian Hunter , "Liang, Kan" , David Hildenbrand , Lorenzo Stoakes , "Liam R. Howlett" , Vlastimil Babka , Suren Baghdasaryan , Michal Hocko , Nathan Chancellor , Nick Desaulniers , Bill Wendling , Justin Stitt , Kees Cook , Alice Ryhl , Sami Tolvanen , Miguel Ojeda , Masahiro Yamada , Rong Xu , Naveen N Rao , David Kaplan , Andrii Nakryiko , Jinjie Ruan , Nam Cao , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-perf-users@vger.kernel.org, linux-mm@kvack.org, llvm@lists.linux.dev, Andrey Ryabinin , Andrey Konovalov , Dmitry Vyukov , Vincenzo Frascino , kasan-dev@googlegroups.com, "David S. Miller" , Mathieu Desnoyers , linux-trace-kernel@vger.kernel.org Cc: Jinchao Wang Subject: [PATCH v4 20/21] docs: add KStackWatch document Date: Fri, 12 Sep 2025 18:11:30 +0800 Message-ID: <20250912101145.465708-21-wangjinchao600@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20250912101145.465708-1-wangjinchao600@gmail.com> References: <20250912101145.465708-1-wangjinchao600@gmail.com> 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" Add a new documentation file for KStackWatch, explaining its purpose, motivation, key features, configuration format, module parameters, implementation notes, limitations, and testing instructions. Signed-off-by: Jinchao Wang --- Documentation/dev-tools/kstackwatch.rst | 94 +++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 Documentation/dev-tools/kstackwatch.rst diff --git a/Documentation/dev-tools/kstackwatch.rst b/Documentation/dev-to= ols/kstackwatch.rst new file mode 100644 index 000000000000..f741de08ca56 --- /dev/null +++ b/Documentation/dev-tools/kstackwatch.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +KStackWatch: Kernel Stack Watch +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Overview +=3D=3D=3D=3D=3D=3D=3D=3D +KStackWatch is a lightweight debugging tool designed to detect +kernel stack corruption in real time. It helps developers capture the +moment corruption occurs, rather than only observing a later crash. + +Motivation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Stack corruption may originate in one function but manifest much later +with no direct call trace linking the two. This makes such issues +extremely difficult to diagnose. KStackWatch addresses this by combining +hardware breakpoints with kprobe and fprobe instrumentation, monitoring +stack canaries or local variables at the point of corruption. + +Key Features +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +- Lightweight overhead: + Minimal runtime cost, preserving bug reproducibility. +- Real-time detection: + Detect stack corruption immediately. +- Flexible configuration: + Control via a procfs interface. +- Depth filtering: + Optional recursion depth tracking per task. + +Configuration +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +The control file is created at:: + + /proc/kstackwatch + +To configure, write a string in the following format:: + + function+ip_offset[+depth] [local_var_offset:local_var_len] + - function : name of the target function + - ip_offset : instruction pointer offset within the function + - depth : recursion depth to watch, starting from 0 + - local_var_offset : offset from the stack pointer at function+ip_offs= et + - local_var_len : length of the local variable(1,2,4,8) + +Fields +------ +- ``function``: + Name of the target function to watch. +- ``ip_offset``: + Instruction pointer offset within the function. +- ``depth`` (optional): + Maximum recursion depth for the watch. +- ``local_var_offset:local_var_len`` (optional): + A region of a local variable to monitor, relative to the stack pointer. + If not given, KStackWatch monitors the stack canary by default. + +Examples +-------- +1. Watch the canary at the entry of ``canary_test_write``:: + + echo 'canary_test_write+0x12' > /proc/kstackwatch + +2. Watch a local variable of 8 bytes at offset 0 in + ``silent_corruption_victim``:: + + echo 'silent_corruption_victim+0x7f 0:8' > /proc/kstackwatch + +Module Parameters +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +``panic_on_catch`` (bool) + - If true, trigger a kernel panic immediately on detecting stack + corruption. + - Default is false (log a message only). + +Implementation Notes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +- Hardware breakpoints are preallocated at watch start. +- Function exit is monitored using ``fprobe``. +- Per-task depth tracking is used to handle recursion across scheduling. +- The procfs interface allows dynamic reconfiguration at runtime. +- Active state is cleared before applying new settings. + +Limitations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +- Only one active watch can be configured at a time (singleton). +- Local variable offset and size must be known in advance. + +Testing +=3D=3D=3D=3D=3D=3D=3D +KStackWatch includes a companion test module (`kstackwatch_test`) and +a helper script (`kstackwatch_test.sh`) to exercise different stack +corruption scenarios: --=20 2.43.0