[PATCH] doc/eal: add signal safety warning

[Mattias Rönnblom]

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 at 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