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

[Cyril Hrubis]

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