eal: improve power monitor API comments

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>
Acked-by: Thomas Monjalon <thomas@monjalon.net>

diff --git a/lib/librte_eal/include/generic/rte_power_intrinsics.h b/lib/librte_eal/include/generic/rte_power_intrinsics.h
index 5960c48..dddca3d 100644 (file)
--- 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.