From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id BCA92A0A0A; Fri, 22 Jan 2021 18:12:57 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 477BF14105F; Fri, 22 Jan 2021 18:12:29 +0100 (CET) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by mails.dpdk.org (Postfix) with ESMTP id 262F8141045 for ; Fri, 22 Jan 2021 18:12:22 +0100 (CET) IronPort-SDR: O/HSncM9WkZl1Y5sMhMhxfBl+i2hepsga9twqyqs5Mg17wvFFnsmmrW3bJHj7Z5I36oHL6C4nv z36Zkd7wF5og== X-IronPort-AV: E=McAfee;i="6000,8403,9872"; a="176901759" X-IronPort-AV: E=Sophos;i="5.79,367,1602572400"; d="scan'208";a="176901759" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 22 Jan 2021 09:12:21 -0800 IronPort-SDR: AXxt5gAaV/fhKAfD3sMQB3LD5SMaV/SqFv0/1yYw+KuVZXw+Zf1khLCpK4nyNkF/09Db7GqlJL trHROkLUA0rA== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.79,367,1602572400"; d="scan'208";a="571191484" Received: from silpixa00399498.ir.intel.com (HELO silpixa00399498.ger.corp.intel.com) ([10.237.222.179]) by orsmga005.jf.intel.com with ESMTP; 22 Jan 2021 09:12:20 -0800 From: Anatoly Burakov To: dev@dpdk.org Cc: thomas@monjalon.net Date: Fri, 22 Jan 2021 17:12:15 +0000 Message-Id: X-Mailer: git-send-email 2.25.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v20 2/4] eal: improve comments around power monitoring API X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 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" Currently, the API documentation is ambiguous as to what happens when certain conditions are met. Document the behavior explicitly, as well as fix some typos and outdated comments. Fixes: 6a17919b0e2a ("eal: change power intrinsics API") Signed-off-by: Anatoly Burakov --- .../include/generic/rte_power_intrinsics.h | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/lib/librte_eal/include/generic/rte_power_intrinsics.h b/lib/librte_eal/include/generic/rte_power_intrinsics.h index 5960c48c80..dddca3d41c 100644 --- a/lib/librte_eal/include/generic/rte_power_intrinsics.h +++ b/lib/librte_eal/include/generic/rte_power_intrinsics.h @@ -35,17 +35,20 @@ struct rte_power_monitor_cond { /** * @warning - * @b EXPERIMENTAL: this API may change without prior notice + * @b EXPERIMENTAL: this API may change without prior notice. * * Monitor specific address for changes. This will cause the CPU to enter an * architecture-defined optimized power state until either the specified * memory address is written to, a certain TSC timestamp is reached, or other * reasons cause the CPU to wake up. * - * Additionally, an `expected` 64-bit value and 64-bit mask are provided. If - * mask is non-zero, the current value pointed to by the `p` pointer will be - * checked against the expected value, and if they match, the entering of - * optimized power state may be aborted. + * Additionally, an expected value (`pmc->val`), mask (`pmc->mask`), and data + * size (`pmc->size`) are provided in the `pmc` power monitoring condition. If + * the mask is non-zero, the current value pointed to by the `pmc->addr` pointer + * will be read and compared against the expected value, and if they match, the + * entering of optimized power state will be aborted. This is intended to + * prevent the CPU from entering optimized power state and waiting on a write + * that has already happened by the time this API is called. * * @warning It is responsibility of the user to check if this function is * supported at runtime using `rte_cpu_get_intrinsics_support()` API call. @@ -67,11 +70,14 @@ int rte_power_monitor(const struct rte_power_monitor_cond *pmc, /** * @warning - * @b EXPERIMENTAL: this API may change without prior notice + * @b EXPERIMENTAL: this API may change without prior notice. * * Wake up a specific lcore that is in a power optimized state and is monitoring * an address. * + * @note It is safe to call this function if the lcore in question is not + * sleeping. The function will have no effect. + * * @note This function will *not* wake up a core that is in a power optimized * state due to calling `rte_power_pause`. * @@ -83,7 +89,7 @@ int rte_power_monitor_wakeup(const unsigned int lcore_id); /** * @warning - * @b EXPERIMENTAL: this API may change without prior notice + * @b EXPERIMENTAL: this API may change without prior notice. * * Enter an architecture-defined optimized power state until a certain TSC * timestamp is reached. -- 2.25.1