From 268dbf187963b0e1b8b9208e69cb5d929af64c2d Mon Sep 17 00:00:00 2001
From: hanzhijian <hanzhijian@zepp.com>
Date: Tue, 26 May 2026 21:04:39 +0800
Subject: [PATCH] Documentation: Document taskset command.

Fill the taskset application reference page with source-backed usage,
configuration, forms, examples, and notes.  The documented command forms and
mask constraints come from apps/system/taskset/taskset.c and the enabling
configuration comes from apps/system/taskset/Kconfig.

Signed-off-by: hanzj <han.zhijiang@zte.com.cn>
---
 .../applications/system/taskset/index.rst     | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/Documentation/applications/system/taskset/index.rst b/Documentation/applications/system/taskset/index.rst
index 1859bc60a98a8..66958856780d2 100644
--- a/Documentation/applications/system/taskset/index.rst
+++ b/Documentation/applications/system/taskset/index.rst
@@ -1,3 +1,83 @@
 ===========================
 ``taskset`` Taskset Command
 ===========================
+
+Overview
+========
+
+The ``taskset`` command displays or changes the CPU affinity mask for a
+running task, or starts a command after applying an affinity mask to the
+``taskset`` process.  It is intended for SMP configurations where tasks can
+be constrained to a subset of CPUs.
+
+The mask argument is a decimal CPU affinity bit mask.  Bit 0 selects CPU 0,
+bit 1 selects CPU 1, and so on.  The command accepts masks greater than zero
+and less than ``1 << CONFIG_SMP_NCPUS``.
+
+Configuration
+=============
+
+Enable the application with ``CONFIG_SYSTEM_TASKSET``.  This option depends
+on ``CONFIG_SMP`` and ``CONFIG_SYSTEM_SYSTEM``.
+
+The program name, task priority, and stack size are controlled by:
+
+- ``CONFIG_SYSTEM_TASKSET_PROGNAME``
+- ``CONFIG_SYSTEM_TASKSET_PRIORITY``
+- ``CONFIG_SYSTEM_TASKSET_STACKSIZE``
+
+Usage
+=====
+
+.. code-block:: console
+
+   taskset <mask> <command> [args ...]
+   taskset -p [mask] <pid>
+   taskset -h
+
+Forms
+=====
+
+``taskset <mask> <command> [args ...]``
+  Applies ``mask`` to the ``taskset`` process and then runs ``command`` with
+  any remaining arguments through ``system()``.
+
+``taskset -p <pid>``
+  Prints the current CPU affinity mask for ``pid``.
+
+``taskset -p <mask> <pid>``
+  Sets the CPU affinity mask for ``pid`` and then prints the task's current
+  mask.
+
+``taskset -h``
+  Prints command usage.
+
+Examples
+========
+
+Show the current affinity mask for task ID 4:
+
+.. code-block:: console
+
+   nsh> taskset -p 4
+   pid 4's current affinity mask: 0x2
+
+Set task ID 4 to affinity mask 3 and print the resulting mask:
+
+.. code-block:: console
+
+   nsh> taskset -p 3 4
+   pid 4's current affinity mask: 0x3
+
+Start ``busyloop`` after applying affinity mask 1 to the command process:
+
+.. code-block:: console
+
+   nsh> taskset 1 busyloop &
+
+Notes
+=====
+
+The command reports scheduler affinity errors on standard error.  The exact
+set of valid mask values depends on ``CONFIG_SMP_NCPUS`` for the target
+configuration.