From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <dev-bounces@dpdk.org> Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C8BBBA0032; Tue, 12 Jul 2022 01:04:53 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id AC2F840687; Tue, 12 Jul 2022 01:04:53 +0200 (CEST) Received: from mail-pl1-f175.google.com (mail-pl1-f175.google.com [209.85.214.175]) by mails.dpdk.org (Postfix) with ESMTP id 17F9F40684 for <dev@dpdk.org>; Tue, 12 Jul 2022 01:04:52 +0200 (CEST) Received: by mail-pl1-f175.google.com with SMTP id j12so5706130plj.8 for <dev@dpdk.org>; Mon, 11 Jul 2022 16:04:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20210112.gappssmtp.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=MbPOfgrXvNjqKQgIgGRpUUt4ni2hcCgjMXVYX5bNrug=; b=0H71KKDTqlJXfT63qhEBX9p/KLALNB3IEN6F5v6Y0J6vbemsMvOXfxmEaf6A2MKMpM XaZm5GypLNBhhgjk0B0BZhLXFXA6axSaHz/raitGnhik4oodV21dJk/TWDvba2UM35W2 +A/AvXzxOrSiG0ppz4ujyXKz5ssIIf34oH8bjhkAIwvC4SU2QHcWiE/Du7uCPMMS1afq Lt7hjZj5yQlVb8xeoSqaJXaNZ5QF67yzPqho8emu74hMIClS3EHYrVfTpK/jkITYpkIF xJex3rdqELxlQRO0dtGMJ4DKsa8igQF67nq/pwYj9TzFIWy78QYYZbzP2VJzEsPt6p7f WfUw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=MbPOfgrXvNjqKQgIgGRpUUt4ni2hcCgjMXVYX5bNrug=; b=3qRFVAa080CJDsGbMfScfVf6ZD5ympm/pHlmkWkkA27nhyWJtEtC4HJiK4Cun85F5R itvXyyEkLkEG83cuxXAx2Le9fXX68Mq7HehNplXT5kWJNvdKad6vxLCxdj93OIoGash5 kTLfkE19Sv0Ah0v+nh5UoqxeX7BSjGXi5Y0ZsonWIGV1BCKdn8VLXKNArgqhNUH7vhQ0 CudiFRY5Y+PYw+prCsZsIDi/fY+I6/4ZljDJrknZ6ovp0/ktTuvIgbjL8184olSGm07i j9kdZHHOdCFk8nbSm9IHaqOmG5ttcS3pVPdfnR9+YobucSpGbMF0iiyks4+h9ZYlBeNi BpQg== X-Gm-Message-State: AJIora8pVxjsxM1bApleTIaMbLke3z8MhgNVSSaaFGpZUaduV/GSUZ9j qtwxh8Rh9ry33m40uANOYY6V5RdqhYGpeA== X-Google-Smtp-Source: AGRyM1tBJbhTQSOM6yQ11byOFDZkNoy5WjnF2o9gmfqOM3eoG49DPyLauynx4iXLPNgqVDCTD4Uubw== X-Received: by 2002:a17:90a:f686:b0:1ef:831d:fd48 with SMTP id cl6-20020a17090af68600b001ef831dfd48mr773334pjb.183.1657580690844; Mon, 11 Jul 2022 16:04:50 -0700 (PDT) Received: from hermes.local (204-195-112-199.wavecable.com. [204.195.112.199]) by smtp.gmail.com with ESMTPSA id c8-20020a170903234800b0016c09e23b18sm5304531plh.154.2022.07.11.16.04.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 Jul 2022 16:04:50 -0700 (PDT) From: Stephen Hemminger <stephen@networkplumber.org> To: dev@dpdk.org Cc: Stephen Hemminger <stephen@networkplumber.org>, Tyler Retzlaff <roretzla@linux.microsoft.com>, Chengwen Feng <fengchengwen@huawei.com>, Anatoly Burakov <anatoly.burakov@intel.com> Subject: [PATCH v4] doc/eal: add signal safety warning Date: Mon, 11 Jul 2022 16:04:48 -0700 Message-Id: <20220711230448.557715-1-stephen@networkplumber.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220705204401.158650-1-stephen@networkplumber.org> References: <20220705204401.158650-1-stephen@networkplumber.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions <dev.dpdk.org> List-Unsubscribe: <https://mails.dpdk.org/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://mails.dpdk.org/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <https://mails.dpdk.org/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> Errors-To: dev-bounces@dpdk.org 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> --- v4 - add more functions and clarify v3 - mistake (ignore it) .../prog_guide/env_abstraction_layer.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index 67842ae27207..35fbebe1be04 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -818,6 +818,76 @@ 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 Posix API defines an async-signal-safe function as one that can be safely + called from with a signal handler. Many DPDK functions are non-reentrant and + therefore are unsafe to call from a signal handler. + + 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. For example, calling ``rte_mempool_lookup()`` from a signal + would deadlock if the signal happened during previous call ``rte_mempool`` + routines. + + Other functions are not signal safe because they use one or more + library routines that are not themselves signal safe. + For example, calling ``rte_panic()`` is not safe in a signal handler + because it uses ``rte_log()`` and ``rte_log()`` calls the + ``syslog()`` library function which is in the list of + signal safe functions in + `Signal-Safety manual page <https://man7.org/linux/man-pages/man7/signal-safety.7.html>`_. + + The set of functions that are expected to be async-signal-safe in DPDK + is shown in the following table. The functions not otherwise noted + are not async-signal-safe. + +.. csv-table:: **Signal Safe Functions** + :header: "Function" + :widths: 32 + + rte_dump_stack + rte_eal_get_lcore_state + rte_eal_get_runtime_dir + rte_eal_has_hugepages + rte_eal_has_pci + rte_eal_lcore_role + rte_eal_process_type + rte_eal_using_phys_addrs + rte_get_hpet_cycles + rte_get_hpet_hz + rte_get_main_lcore + rte_get_next_lcore + rte_get_tsc_hz + rte_hypervisor_get + rte_hypervisor_get_name + rte_lcore_count + rte_lcore_cpuset + rte_lcore_has_role + rte_lcore_index + rte_lcore_is_enabled + rte_lcore_to_cpu_id + rte_lcore_to_socket_id + rte_log_get_global_level + rte_log_get_level + rte_memory_get_nchannel + rte_memory_get_nrank + rte_reciprocal_value + rte_reciprocal_value_u64 + rte_socket_count + rte_socket_id + rte_socket_id_by_idx + rte_strerror + rte_strscpy + rte_strsplit + rte_sys_gettid + rte_uuid_compare + rte_uuid_is_null + rte_uuid_parse + rte_uuid_unparse + + cgroup control ~~~~~~~~~~~~~~ -- 2.35.1