From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pf1-f174.google.com (mail-pf1-f174.google.com [209.85.210.174]) (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 F31DC46BF for ; Thu, 19 Mar 2026 05:30:32 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.174 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773898234; cv=none; b=Fjt7Uz9vkzkgqxH7IXLL++AH1HOkSh3VWVE4cnfUipphP3Bjmet7BomBocBnIS+01a3jrdTPsNRYzqDsrnbs0YFARABcbm2OEcBy74dcLUqlHXphWLOcNxgIGZMIqO4CcUOma+XN3SvDQiNx50WthfwLEhxImRZsTt5PbvKYWIQ= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1773898234; c=relaxed/simple; bh=Ek61n9huulxfy9S4sfy2ex57jC6nZwtJWxjTvqgzVBs=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type; b=j+e9aP6BssTL3pu0VyzyHpl1TV26XpI7j0AK/21qj1numKF5jmETbZUqG8boIxHcthrW+JCTSPyFovpZ4Xrm1O18adSzjfqSCbN/mHbltXrQpGk9Svd4PeLKtyMjvOCul2HhYiQpgp32GvVGDGm3ji/57AelTymQrMyOLrg/a/k= 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=FeITeWls; arc=none smtp.client-ip=209.85.210.174 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="FeITeWls" Received: by mail-pf1-f174.google.com with SMTP id d2e1a72fcca58-82a655cfab5so660044b3a.1 for ; Wed, 18 Mar 2026 22:30:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1773898232; x=1774503032; 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=4ugIXPnzqH1xh+AHf3bQwoI+E5lGp+P/M5xBeU3v2KE=; b=FeITeWlsgeeSfTVO0t9pCnpcUWoGGc0ZWCqfbPlIi8IIWXuEjChMVvrXwsVCLKt4Sx 8jXgzP+gWaqYcNkKGWKQynJGj7bz03PI7WGCe+2ENIqonJXR8GX2DgwEj/Irfj6MmjPz ItuzEFh0+r53AD111qUWGlAYeAV1USfFxzqe+mJvxn6g0ALeybL2/sQ864uio3TOYI1p jQYe9mCnbBejP0YnIouimp0wu+DK1oxQzUNhSZ+zhS6JbYgUOB9e8Z3BuitLJdhuj16q BppI6M8J97KzCh5E7zUBWLcrXzmsEM7ijGyeCYl7C+T0qs2v5igt3R0XFB7bQwPo4l9D UTFw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1773898232; x=1774503032; 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=4ugIXPnzqH1xh+AHf3bQwoI+E5lGp+P/M5xBeU3v2KE=; b=aOOtHaNfTy/kJ7pPB+bUN/M0eM2ToohH/xQVv5y9AKmhL2C1iYgKjuhh/KgdvNHD56 r5wZEa98Ja1tr9MVa+mBR+UkRfvjrbFMc3T0l06nVZvuAWIe4ALi+cTIiRzmft7V7qh7 Scy+Uz3iSktCuhCCA6+ki7DA21zG7R7r1qgU7hMpR6Fdt8FTJzJeSjE9pJwEpcecChHI FOWwYE45ANR40ZvLKFCEy9CH1Ii7x28/nr9HxHn0XCfwdtALzPGnHm6sgeXmPs4EZyZn wOVQ1BBlwYYCYTzaCdak/qBckX7xtnYC9JWf/2hvonXQNDReOP2d+PSgzn58urdVQ//K RrSA== X-Gm-Message-State: AOJu0YyUFhAIwyjTEmV/z4ok6Ch7WGOpWIg8i4pzBFrGPBjkjHezYIwj R8uYqvPVMc1ML4VFPuQGy0DCoSma8At6praCN4zAdIHE9WfH19+9fWgECgBQOA== X-Gm-Gg: ATEYQzxwx4kNx/3TNdNC7jOTh0nmOmhhcTO1KBXH8VK+khri+Vi+uxgSHvvJLNUWlva /xh3ctnCoYuujj8JqesYtw3Z/ptvYjBD8013LXyYUsUR7Vmi+CYQ+qJPz+TH5FEkrZaDxZiNbXG ohqmwxhh+FZ5s52tbkJ/PyG4qTA4/K56K0H6pIDo2WVb95WdO+XAXV3XWOvwDp08MJ0x5GoEtuS X5hk62vgHhDZlXxGgkl/COozK9b/kRu1pgnCxmOgxKtJ6EXl4K5Le6s9moh1ocUx7y/jmByDPUc 1dSPwya3zqBuVnSjMEUsplpRKaAXhb8KuhBqXmLdliBz98JH0Q9F7tcAAIHJpkvw65wRIoR9nfo 7xbFuww0/do5N8GCNS3rXoUbouQEO6sQLWmkaCbkiyZbiPxfdK6ofZXykyZ8rD2yW70PrRj3UeK A+fdfVhP0n0yks5Si7HPdFH5aFmZ2lY6eCrPbMzOHrh2FhN0GEMNTuw9GdzB7B0xAwENnmWjUIL Hc= X-Received: by 2002:a05:6a00:12e1:b0:829:837b:9068 with SMTP id d2e1a72fcca58-82a6af0da63mr5364651b3a.29.1773898232159; Wed, 18 Mar 2026 22:30:32 -0700 (PDT) Received: from mi-HP-ProDesk-680-G6-PCI-Microtower-PC.mioffice.cn ([43.224.245.226]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-82a6b532155sm5488403b3a.7.2026.03.18.22.30.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 18 Mar 2026 22:30:31 -0700 (PDT) From: zhidao su X-Google-Original-From: zhidao su To: sched-ext@lists.linux.dev Cc: linux-kernel@vger.kernel.org, tj@kernel.org, void@manifault.com, arighi@nvidia.com, changwoo@igalia.com, peterz@infradead.org, mingo@redhat.com, zhidao su Subject: [PATCH 1/2] sched_ext: Documentation: Document events sysfs file and module parameters Date: Thu, 19 Mar 2026 13:30:25 +0800 Message-ID: <20260319053026.447892-1-suzhidao@xiaomi.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: 8bit Two categories of sched_ext diagnostics are currently undocumented: 1. Per-scheduler events sysfs file Each active BPF scheduler exposes a set of diagnostic counters at /sys/kernel/sched_ext//events. These counters are defined (with detailed comments) in kernel/sched/ext_internal.h but have no corresponding documentation in sched-ext.rst. BPF scheduler developers must read kernel source to understand what each counter means. Add a description of the events file, an example of its output, and a brief explanation of every counter. 2. Module parameters kernel/sched/ext.c registers two parameters under the sched_ext. prefix (slice_bypass_us, bypass_lb_intv_us) via module_param_cb() with MODULE_PARM_DESC() strings, but sched-ext.rst makes no mention of them. Users who need to tune bypass-mode behavior have no in-tree documentation to consult. Add a "Module Parameters" section documenting both knobs: their default values, valid ranges (taken from the set_*() validators in ext.c), and the note from the source that they are primarily for debugging. No functional changes. Signed-off-by: zhidao su --- Documentation/scheduler/sched-ext.rst | 68 +++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst index f4f7d8f4f9e4..6fc7e720a956 100644 --- a/Documentation/scheduler/sched-ext.rst +++ b/Documentation/scheduler/sched-ext.rst @@ -93,6 +93,55 @@ scheduler has been loaded): # cat /sys/kernel/sched_ext/enable_seq 1 +Each running scheduler also exposes a per-scheduler ``events`` file under +``/sys/kernel/sched_ext//events`` that tracks diagnostic +counters. Each counter occupies one ``name value`` line: + +.. code-block:: none + + # cat /sys/kernel/sched_ext/simple/events + SCX_EV_SELECT_CPU_FALLBACK 0 + SCX_EV_DISPATCH_LOCAL_DSQ_OFFLINE 0 + SCX_EV_DISPATCH_KEEP_LAST 123 + SCX_EV_ENQ_SKIP_EXITING 0 + SCX_EV_ENQ_SKIP_MIGRATION_DISABLED 0 + SCX_EV_REENQ_IMMED 0 + SCX_EV_REENQ_LOCAL_REPEAT 0 + SCX_EV_REFILL_SLICE_DFL 456789 + SCX_EV_BYPASS_DURATION 0 + SCX_EV_BYPASS_DISPATCH 0 + SCX_EV_BYPASS_ACTIVATE 0 + SCX_EV_INSERT_NOT_OWNED 0 + SCX_EV_SUB_BYPASS_DISPATCH 0 + +The counters are described in ``kernel/sched/ext_internal.h``; briefly: + +* ``SCX_EV_SELECT_CPU_FALLBACK``: ops.select_cpu() returned a CPU unusable by + the task and the core scheduler silently picked a fallback CPU. +* ``SCX_EV_DISPATCH_LOCAL_DSQ_OFFLINE``: a local-DSQ dispatch was redirected + to the global DSQ because the target CPU went offline. +* ``SCX_EV_DISPATCH_KEEP_LAST``: a task continued running because no other + task was available (only when ``SCX_OPS_ENQ_LAST`` is not set). +* ``SCX_EV_ENQ_SKIP_EXITING``: an exiting task was dispatched to the local DSQ + directly, bypassing ops.enqueue() (only when ``SCX_OPS_ENQ_EXITING`` is not set). +* ``SCX_EV_ENQ_SKIP_MIGRATION_DISABLED``: a migration-disabled task was + dispatched to its local DSQ directly (only when + ``SCX_OPS_ENQ_MIGRATION_DISABLED`` is not set). +* ``SCX_EV_REENQ_IMMED``: a task dispatched with ``SCX_ENQ_IMMED`` was + re-enqueued because the target CPU was not available for immediate execution. +* ``SCX_EV_REENQ_LOCAL_REPEAT``: a reenqueue of the local DSQ triggered + another reenqueue; recurring counts indicate incorrect ``SCX_ENQ_REENQ`` + handling in the BPF scheduler. +* ``SCX_EV_REFILL_SLICE_DFL``: a task's time slice was refilled with the + default value (``SCX_SLICE_DFL``). +* ``SCX_EV_BYPASS_DURATION``: total nanoseconds spent in bypass mode. +* ``SCX_EV_BYPASS_DISPATCH``: number of tasks dispatched while in bypass mode. +* ``SCX_EV_BYPASS_ACTIVATE``: number of times bypass mode was activated. +* ``SCX_EV_INSERT_NOT_OWNED``: attempted to insert a task into a DSQ not owned + by this scheduler; such attempts are silently ignored. +* ``SCX_EV_SUB_BYPASS_DISPATCH``: tasks dispatched from sub-scheduler bypass + DSQs (only relevant with ``CONFIG_EXT_SUB_SCHED``). + ``tools/sched_ext/scx_show_state.py`` is a drgn script which shows more detailed information: @@ -441,6 +490,25 @@ Where to Look scheduling. Tasks with CPU affinity are direct-dispatched in FIFO order; all others are scheduled in user space by a simple vruntime scheduler. +Module Parameters +================= + +sched_ext exposes two module parameters under the ``sched_ext.`` prefix that +control bypass-mode behaviour. These knobs are primarily for debugging; there +is usually no reason to change them during normal operation. They can be read +and written at runtime (mode 0600) via +``/sys/module/sched_ext/parameters/``. + +``sched_ext.slice_bypass_us`` (default: 5000 µs) + The time slice assigned to all tasks when the scheduler is in bypass mode, + i.e. during BPF scheduler load, unload, and error recovery. Valid range is + 100 µs to 100 ms. + +``sched_ext.bypass_lb_intv_us`` (default: 500000 µs) + The interval at which the bypass-mode load balancer redistributes tasks + across CPUs. Set to 0 to disable load balancing during bypass mode. Valid + range is 0 to 10 s. + ABI Instability =============== -- 2.43.0