From patchwork Wed Jan 20 11:50:27 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Burakov, Anatoly" X-Patchwork-Id: 86972 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id DA1B8A0A05; Wed, 20 Jan 2021 12:50:46 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 92D0C140D24; Wed, 20 Jan 2021 12:50:38 +0100 (CET) Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by mails.dpdk.org (Postfix) with ESMTP id 964A6140D1B for ; Wed, 20 Jan 2021 12:50:35 +0100 (CET) IronPort-SDR: Vg8ye3VjjQKirF71Aka2C3VcW2wSVOYNihWlHj6uG0q3XtUdfGo0d2PYYCYBBSHoQ18LiDZT6U ygRxduwqtntA== X-IronPort-AV: E=McAfee;i="6000,8403,9869"; a="178313181" X-IronPort-AV: E=Sophos;i="5.79,361,1602572400"; d="scan'208";a="178313181" Received: from fmsmga006.fm.intel.com ([10.253.24.20]) by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 20 Jan 2021 03:50:35 -0800 IronPort-SDR: CZGXp0K7pyrLPGRZSGjchERbwoMXjNAn6unSW8qHcbnV+A+nF2wLrF4Fhq3bFXDRt0eHWyT+5u R/0xhp3ocrEw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.79,361,1602572400"; d="scan'208";a="571319262" Received: from silpixa00399498.ir.intel.com (HELO silpixa00399498.ger.corp.intel.com) ([10.237.222.179]) by fmsmga006.fm.intel.com with ESMTP; 20 Jan 2021 03:50:34 -0800 From: Anatoly Burakov To: dev@dpdk.org Cc: thomas@monjalon.net Date: Wed, 20 Jan 2021 11:50:27 +0000 Message-Id: X-Mailer: git-send-email 2.25.1 In-Reply-To: References: MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH v19 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.