From abc0cade20f09f12f7c57c238306e8d730a10bb7 Mon Sep 17 00:00:00 2001 From: Anatoly Burakov Date: Fri, 22 Jan 2021 17:12:15 +0000 Subject: [PATCH] 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 Acked-by: Thomas Monjalon --- .../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.20.1