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

[Petr Vorel]

> 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`):

> + *
> + * - **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)
* Z

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:).

Otherwise LGTM.
Reviewed-by: Petr Vorel <pvorel@suse.cz>

Kind regards,
Petr