[PATCH v2] doc/eal: add signal safety warning

[Stephen Hemminger]

On Mon, 11 Jul 2022 23:15:26 +0200
Thomas Monjalon <thomas at monjalon.net> wrote:

> 05/07/2022 22:44, Stephen Hemminger:
> > The DPDK is not designed to be used from a signal handler.
> > Add a notice in the documentation describing this limitation,
> > similar to Linux signal-safety manual page.
> > 
> > Bugzilla ID: 1030
> > Signed-off-by: Stephen Hemminger <stephen at networkplumber.org>
> > Acked-by: Tyler Retzlaff <roretzla at linux.microsoft.com>
> > Acked-by: Chengwen Feng <fengchengwen at huawei.com>
> > ---
> >  doc/guides/prog_guide/env_abstraction_layer.rst | 15 +++++++++++++++
> >  1 file changed, 15 insertions(+)
> > 
> > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> > index 67842ae27207..de7ee92bba39 100644
> > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > @@ -818,6 +818,21 @@ Known Issues
> >  
> >    The debug statistics of rte_ring, rte_mempool and rte_timer are not supported in an unregistered non-EAL pthread.
> >  
> > ++ signal safety
> > +
> > +  The DPDK library is not designed to be async-signal-safe.
> > +  Except where explicitly stated otherwise [#]_, the DPDK functions are nonreentrant and are unsafe to call from a signal handler.
> > +
> > +.. [#] Only the function ``rte_dump_stack()`` can safely be called from signal handler in this version of DPDK.  
> 
> Really? Are you sure?

There are some trivial ones that are signal safe that are pure functions.
Like the bitfield and string functions.

But any function that matters such as rte_log, rte_mbuf, rte_mempool,
and any driver function are going to be problematic.

> 
> Note: the use of [#] is probably limited to a single usage in the page?

Isn't it supposed to autonumber?

> 
> > +
> > +.. note::
> > +  The kinds of issues that make DPDK functions unsafe can be understood when
> > +  one considers that much of the code in DPDK uses locks and other shared
> > +  resources. If a device driver holding a ``rte_spinlock`` is interrupted
> > +  by a signal and control operation is then performed that would acquire
> > +  the same lock, a deadlock would result.  
> 
> I find this note quite confusing.

I based it off what signal-safety says. Yes it really is that bad.