diff mbox series

[v20,2/4] eal: improve comments around power monitoring API

Message ID b30c6a9b4ec553dd9d6fec5327885c47419a8906.1611335511.git.anatoly.burakov@intel.com (mailing list archive)
State Accepted, archived
Delegated to: Thomas Monjalon
Headers show
Series Add PMD power management | expand

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Anatoly Burakov Jan. 22, 2021, 5:12 p.m. UTC
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 <anatoly.burakov@intel.com>
---
 .../include/generic/rte_power_intrinsics.h    | 20 ++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

Comments

Thomas Monjalon Jan. 29, 2021, 11:27 a.m. UTC | #1
22/01/2021 18:12, Anatoly Burakov:
> 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 <anatoly.burakov@intel.com>
> ---
>   * 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.

I think that's a lot better. Thank you.
Acked-by: Thomas Monjalon <thomas@monjalon.net>
diff mbox series

Patch

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.