Re: [LTP] [PATCH v2 1/2] doc: Document process_state

Cyril Hrubis
2026-01-06T12:46:55Z

Hi!
> > Signed-off-by: Cyril Hrubis <chrubis@suse.cz>
> > ---
> > doc/developers/api_c_tests.rst | 5 ++++
> > include/tst_process_state.h | 55 +++++++++++++++++++++-------------
> > 2 files changed, 40 insertions(+), 20 deletions(-)
>
> > New in v2.
>
> > diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> > index 2ca0f0464..13fc8651b 100644
> > --- a/doc/developers/api_c_tests.rst
> > +++ b/doc/developers/api_c_tests.rst
> > @@ -43,6 +43,11 @@ Kernel
> > .. kernel-doc:: ../../include/tst_kernel.h
> > .. kernel-doc:: ../../include/tst_kvercmp.h
>
> > +Process state
> > +-------------
> > +
> > +.. kernel-doc:: ../../include/tst_process_state.h
> > +
> > NUMA
> > ----
> > .. kernel-doc:: ../../include/tst_numa.h
> > diff --git a/include/tst_process_state.h b/include/tst_process_state.h
> > index b1d83e109..3691bba7a 100644
> > --- a/include/tst_process_state.h
> > +++ b/include/tst_process_state.h
> > @@ -15,39 +15,54 @@
>
> > #ifdef TST_TEST_H__
>
> > -/*
> > - * Waits for process state change.
> > +/**
> > + * TST_PROCESS_STATE_WAIT() - Waits for a process state change.
> > + *
> > + * Polls `/proc/$PID/state` for a process state changes.
> > *
> > - * The state is one of the following:
> > + * @pid: A process pid.
> > + * @state: A state to wait for.
> > + * @msec_timeout: A timeout for the wait.
> > *
> > - * R - process is running
> > - * S - process is sleeping
> > - * D - process sleeping uninterruptibly
> > - * Z - zombie process
> > - * T - process is traced
> > + * Possible process states:
> Maybe: use link to https://man7.org/linux/man-pages/man1/ps.1.html ?
>
> -* Possible process states:
> +* Possible process states (see :man1:`ps`):

1. We do not have man1 defined in exlinks in conf.py

2. Even if added there exlinks does not seem work from documentation
generated from headers

> > + *
> > + * - **R** Process is running.
> > + * - **S** Process is sleeping.
> > + * - **D** Process sleeping uninterruptibly.
> > + * - **Z** Zombie process.
> > + * - **T** Process is traced.
> > + * - **t** Tracing stopped.
> > + * - **X** Process id dead.
>
> Process state is outdated, man ps(1) lists:
>
> D uninterruptible sleep (usually I/O)
> I idle kernel thread
> R running or runnable (on run queue)
> S interruptible sleep (waiting for an
> event to complete)
> T stopped by job control signal
> t stopped by debugger during the tracing
> W paging (not valid since Linux 2.6)
> X dead (should never be seen)
> Z defunct (“zombie”) process, terminated
> but not reaped by its parent
>
> We miss:
> * I (from kernel 4.2, maybe not relevant when we use it for a child which
> is userspace)
> * W (irrelevant as it is not valid)

Indeed these are not relevent for us.

> * Z

Zombie process is described in the list.

> Also, do we want specify the process states in both TST_PROCESS_STATE_WAIT() and
> TST_THREAD_STATE_WAIT(), or just specify it in one and mention in the other that
> they specify it? (via :ref: or c:func:).

Again, none of the :ref: or c:func: is working in docs generate from
headers.

--
Cyril Hrubis
chrubis@suse.cz