[v2] doc/eal: add signal safety warning
Checks
Commit Message
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@networkplumber.org>
Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
Acked-by: Chengwen Feng <fengchengwen@huawei.com>
---
doc/guides/prog_guide/env_abstraction_layer.rst | 15 +++++++++++++++
1 file changed, 15 insertions(+)
Comments
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@networkplumber.org>
> Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
> Acked-by: Chengwen Feng <fengchengwen@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?
Note: the use of [#] is probably limited to a single usage in the page?
> +
> +.. 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.
On Mon, 11 Jul 2022 23:15:26 +0200
Thomas Monjalon <thomas@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@networkplumber.org>
> > Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
> > Acked-by: Chengwen Feng <fengchengwen@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.
On Mon, 11 Jul 2022 23:15:26 +0200
Thomas Monjalon <thomas@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@networkplumber.org>
> > Acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
> > Acked-by: Chengwen Feng <fengchengwen@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?
>
> Note: the use of [#] is probably limited to a single usage in the page?
Yes. this is true, please apply this patch.
It is not safe to call functions that do any of the following:
printf
malloc
according to Linux async-signal-safe documentation
And because these all have locking or equivalent atomic the following
in DPDK are unsafe.
rte_ring
rte_timer
rte_spinlock, rte_rwlock, ...
any PMD operations
@@ -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.
+
+.. 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.
+
+
cgroup control
~~~~~~~~~~~~~~