From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id AE9C24C77; Fri, 3 May 2019 13:50:55 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 May 2019 04:50:54 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.60,425,1549958400"; d="scan'208";a="321118209" Received: from silpixa00399498.ir.intel.com (HELO silpixa00399498.ger.corp.intel.com) ([10.237.223.125]) by orsmga005.jf.intel.com with ESMTP; 03 May 2019 04:50:53 -0700 From: Anatoly Burakov To: dev@dpdk.org Cc: John McNamara , Marko Kovacevic , stable@dpdk.org Date: Fri, 3 May 2019 12:50:50 +0100 Message-Id: X-Mailer: git-send-email 2.17.1 In-Reply-To: References: In-Reply-To: References: Subject: [dpdk-dev] [PATCH 3/3] ipc: add warnings about correct API usage X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 03 May 2019 11:50:56 -0000 When handling synchronous or asynchronous requests, the reply must be sent explicitly even if the result of the operation is an error, to avoid the other side timing out. Make note of this in documentation explicitly. Cc: stable@dpdk.org Signed-off-by: Anatoly Burakov --- doc/guides/prog_guide/multi_proc_support.rst | 7 +++++++ lib/librte_eal/common/include/rte_eal.h | 15 +++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/doc/guides/prog_guide/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst index 665474a4c..b9758d3fb 100644 --- a/doc/guides/prog_guide/multi_proc_support.rst +++ b/doc/guides/prog_guide/multi_proc_support.rst @@ -309,6 +309,13 @@ If a response is required, a new ``rte_mp_msg`` message descriptor must be constructed and sent via ``rte_mp_reply()`` function, along with ``peer`` pointer. The resulting response will then be delivered to the correct requestor. +.. warning:: + Simply returning a value when processing a request callback will not send a + response to the request - it must always be explicitly sent even in case + of errors. Implementation of error signalling rests with the application, + there is no built-in way to indicate success or error for a request. Failing + to do so will cause the requestor to time out while waiting on a response. + Misc considerations ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/lib/librte_eal/common/include/rte_eal.h b/lib/librte_eal/common/include/rte_eal.h index 7db022532..82ee50fd5 100644 --- a/lib/librte_eal/common/include/rte_eal.h +++ b/lib/librte_eal/common/include/rte_eal.h @@ -226,6 +226,11 @@ struct rte_mp_reply { * As we create socket channel for primary/secondary communication, use * this function typedef to register action for coming messages. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @note No memory allocations should take place inside the callback. */ typedef int (*rte_mp_t)(const struct rte_mp_msg *msg, const void *peer); @@ -237,6 +242,11 @@ typedef int (*rte_mp_t)(const struct rte_mp_msg *msg, const void *peer); * this function typedef to register action for coming responses to asynchronous * requests. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @note No memory allocations should take place inside the callback. */ typedef int (*rte_mp_async_reply_t)(const struct rte_mp_msg *request, @@ -368,6 +378,11 @@ rte_mp_request_async(struct rte_mp_msg *req, const struct timespec *ts, * This function will send a reply message in response to a request message * received previously. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @param msg * The msg argument contains the customized message. * -- 2.17.1 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by dpdk.space (Postfix) with ESMTP id DFD73A0AC5 for ; Fri, 3 May 2019 13:51:16 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 7A2D45A44; Fri, 3 May 2019 13:50:59 +0200 (CEST) Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id AE9C24C77; Fri, 3 May 2019 13:50:55 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 May 2019 04:50:54 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.60,425,1549958400"; d="scan'208";a="321118209" Received: from silpixa00399498.ir.intel.com (HELO silpixa00399498.ger.corp.intel.com) ([10.237.223.125]) by orsmga005.jf.intel.com with ESMTP; 03 May 2019 04:50:53 -0700 From: Anatoly Burakov To: dev@dpdk.org Cc: John McNamara , Marko Kovacevic , stable@dpdk.org Date: Fri, 3 May 2019 12:50:50 +0100 Message-Id: X-Mailer: git-send-email 2.17.1 In-Reply-To: References: In-Reply-To: References: Subject: [dpdk-dev] [PATCH 3/3] ipc: add warnings about correct API usage X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Content-Type: text/plain; charset="UTF-8" Message-ID: <20190503115050.J6n3T1QStDbp9vhRi5tTOVhNvx35rVg-7Fo6XsMGyZ0@z> When handling synchronous or asynchronous requests, the reply must be sent explicitly even if the result of the operation is an error, to avoid the other side timing out. Make note of this in documentation explicitly. Cc: stable@dpdk.org Signed-off-by: Anatoly Burakov --- doc/guides/prog_guide/multi_proc_support.rst | 7 +++++++ lib/librte_eal/common/include/rte_eal.h | 15 +++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/doc/guides/prog_guide/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst index 665474a4c..b9758d3fb 100644 --- a/doc/guides/prog_guide/multi_proc_support.rst +++ b/doc/guides/prog_guide/multi_proc_support.rst @@ -309,6 +309,13 @@ If a response is required, a new ``rte_mp_msg`` message descriptor must be constructed and sent via ``rte_mp_reply()`` function, along with ``peer`` pointer. The resulting response will then be delivered to the correct requestor. +.. warning:: + Simply returning a value when processing a request callback will not send a + response to the request - it must always be explicitly sent even in case + of errors. Implementation of error signalling rests with the application, + there is no built-in way to indicate success or error for a request. Failing + to do so will cause the requestor to time out while waiting on a response. + Misc considerations ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/lib/librte_eal/common/include/rte_eal.h b/lib/librte_eal/common/include/rte_eal.h index 7db022532..82ee50fd5 100644 --- a/lib/librte_eal/common/include/rte_eal.h +++ b/lib/librte_eal/common/include/rte_eal.h @@ -226,6 +226,11 @@ struct rte_mp_reply { * As we create socket channel for primary/secondary communication, use * this function typedef to register action for coming messages. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @note No memory allocations should take place inside the callback. */ typedef int (*rte_mp_t)(const struct rte_mp_msg *msg, const void *peer); @@ -237,6 +242,11 @@ typedef int (*rte_mp_t)(const struct rte_mp_msg *msg, const void *peer); * this function typedef to register action for coming responses to asynchronous * requests. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @note No memory allocations should take place inside the callback. */ typedef int (*rte_mp_async_reply_t)(const struct rte_mp_msg *request, @@ -368,6 +378,11 @@ rte_mp_request_async(struct rte_mp_msg *req, const struct timespec *ts, * This function will send a reply message in response to a request message * received previously. * + * @note When handling IPC request callbacks, the reply must be sent even in + * cases of error handling. Simply retuning success or failure will *not* send + * a response to the requestor. Implementation of error signalling mechanism + * is up to the application. + * * @param msg * The msg argument contains the customized message. * -- 2.17.1