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>
---
doc/guides/prog_guide/env_abstraction_layer.rst | 13 +++++++++++++
1 file changed, 13 insertions(+)
Comments
On Fri, Jun 10, 2022 at 08:23:43AM -0700, Stephen Hemminger wrote:
> 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>
> ---
> doc/guides/prog_guide/env_abstraction_layer.rst | 13 +++++++++++++
> 1 file changed, 13 insertions(+)
>
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 5f0748fba1c0..36ab4b5ba9b6 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
> - with affinity restricted to 2-3, the Control Threads will end up on
> CPU 2 (main lcore, which is the default when no CPU is available).
>
> +Signal Safety
> +~~~~~~~~~~~~~
> +
> +The DPDK functions in general can not be safely called from a signal handler.
> +Most functions are not async-signal-safe because they can acquire locks
> +and other resources that make them nonrentrant.
> +
> +To avoid problems with unsafe functions, can be avoided if required
^^^^^^^^^^^^^^^^^^^^^^^^^
above doesn't quite read right for me, maybe a missing word / needs
re-wording?
> +signals are blocked and a mechanism such as signalfd (Linux) is used
> +to convert the asynchronous signals into messages that are processed
> +by a EAL thread.
> +
> +
> .. _known_issue_label:
>
> Known Issues
> --
> 2.35.1
On Fri, 10 Jun 2022 15:53:34 -0700
Tyler Retzlaff <roretzla@linux.microsoft.com> wrote:
> On Fri, Jun 10, 2022 at 08:23:43AM -0700, Stephen Hemminger wrote:
> > 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>
> > ---
> > doc/guides/prog_guide/env_abstraction_layer.rst | 13 +++++++++++++
> > 1 file changed, 13 insertions(+)
> >
> > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> > index 5f0748fba1c0..36ab4b5ba9b6 100644
> > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > @@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
> > - with affinity restricted to 2-3, the Control Threads will end up on
> > CPU 2 (main lcore, which is the default when no CPU is available).
> >
> > +Signal Safety
> > +~~~~~~~~~~~~~
> > +
> > +The DPDK functions in general can not be safely called from a signal handler.
> > +Most functions are not async-signal-safe because they can acquire locks
> > +and other resources that make them nonrentrant.
> > +
> > +To avoid problems with unsafe functions, can be avoided if required
> ^^^^^^^^^^^^^^^^^^^^^^^^^
>
> above doesn't quite read right for me, maybe a missing word / needs
> re-wording?
Yes, will reword that
On Fri, Jun 10, 2022 at 08:23:43AM -0700, Stephen Hemminger wrote:
> 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>
> ---
> doc/guides/prog_guide/env_abstraction_layer.rst | 13 +++++++++++++
> 1 file changed, 13 insertions(+)
>
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 5f0748fba1c0..36ab4b5ba9b6 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
> - with affinity restricted to 2-3, the Control Threads will end up on
> CPU 2 (main lcore, which is the default when no CPU is available).
>
> +Signal Safety
> +~~~~~~~~~~~~~
> +
> +The DPDK functions in general can not be safely called from a signal handler.
> +Most functions are not async-signal-safe because they can acquire locks
> +and other resources that make them nonrentrant.
> +
> +To avoid problems with unsafe functions, can be avoided if required
> +signals are blocked and a mechanism such as signalfd (Linux) is used
> +to convert the asynchronous signals into messages that are processed
> +by a EAL thread.
> +
> +
> .. _known_issue_label:
>
> Known Issues
> --
> 2.35.1
On 2022/6/11 7:42, Tyler Retzlaff wrote:
> On Fri, Jun 10, 2022 at 08:23:43AM -0700, Stephen Hemminger wrote:
>> 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 | 13 +++++++++++++
>> 1 file changed, 13 insertions(+)
>>
>> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
>> index 5f0748fba1c0..36ab4b5ba9b6 100644
>> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
>> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
>> @@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
>> - with affinity restricted to 2-3, the Control Threads will end up on
>> CPU 2 (main lcore, which is the default when no CPU is available).
>>
>> +Signal Safety
>> +~~~~~~~~~~~~~
>> +
>> +The DPDK functions in general can not be safely called from a signal handler.
>> +Most functions are not async-signal-safe because they can acquire locks
>> +and other resources that make them nonrentrant.
>> +
>> +To avoid problems with unsafe functions, can be avoided if required
>> +signals are blocked and a mechanism such as signalfd (Linux) is used
>> +to convert the asynchronous signals into messages that are processed
>> +by a EAL thread.
>> +
>> +
>> .. _known_issue_label:
>>
>> Known Issues
>> --
>> 2.35.1
>
> .
>
On 2022-06-10 17:23, Stephen Hemminger wrote:
> 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>
> ---
> doc/guides/prog_guide/env_abstraction_layer.rst | 13 +++++++++++++
> 1 file changed, 13 insertions(+)
>
> diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
> index 5f0748fba1c0..36ab4b5ba9b6 100644
> --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> @@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
> - with affinity restricted to 2-3, the Control Threads will end up on
> CPU 2 (main lcore, which is the default when no CPU is available).
>
> +Signal Safety
> +~~~~~~~~~~~~~
> +
> +The DPDK functions in general can not be safely called from a signal handler.
> +Most functions are not async-signal-safe because they can acquire locks
> +and other resources that make them nonrentrant.
> +
> +To avoid problems with unsafe functions, can be avoided if required
> +signals are blocked and a mechanism such as signalfd (Linux) is used
> +to convert the asynchronous signals into messages that are processed
> +by a EAL thread.
> +
Should we instead actually try to figure out what part of the API is and
should remain async-signal-safe? And then say "nothing else is".
Without an exhaustive list, we will leave the user to guessing, or going
into the current implementation to find out if a particular function is
currently async-signal-safe. When that code changes in a future
supposed-to-be-backward-compatible DPDK release, the application will break.
> +
> .. _known_issue_label:
>
> Known Issues
@@ -732,6 +732,19 @@ controlled with tools like taskset (Linux) or cpuset (FreeBSD),
- with affinity restricted to 2-3, the Control Threads will end up on
CPU 2 (main lcore, which is the default when no CPU is available).
+Signal Safety
+~~~~~~~~~~~~~
+
+The DPDK functions in general can not be safely called from a signal handler.
+Most functions are not async-signal-safe because they can acquire locks
+and other resources that make them nonrentrant.
+
+To avoid problems with unsafe functions, can be avoided if required
+signals are blocked and a mechanism such as signalfd (Linux) is used
+to convert the asynchronous signals into messages that are processed
+by a EAL thread.
+
+
.. _known_issue_label:
Known Issues