* which are architecture-dependent.
*/
+struct rte_power_monitor_cond {
+ volatile void *addr; /**< Address to monitor for changes */
+ uint64_t val; /**< If the `mask` is non-zero, location pointed
+ * to by `addr` will be read and compared
+ * against this value.
+ */
+ uint64_t mask; /**< 64-bit mask to extract value read from `addr` */
+ uint8_t size; /**< Data size (in bytes) that will be used to compare
+ * expected value (`val`) with data read from the
+ * monitored memory location (`addr`). Can be 1, 2,
+ * 4, or 8. Supplying any other value will result in
+ * an error.
+ */
+};
+
/**
* @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_features()` API call.
- * Failing to do so may result in an illegal CPU instruction error.
+ * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
*
- * @param p
- * Address to monitor for changes.
- * @param expected_value
- * Before attempting the monitoring, the `p` address may be read and compared
- * against this value. If `value_mask` is zero, this step will be skipped.
- * @param value_mask
- * The 64-bit mask to use to extract current value from `p`.
+ * @param pmc
+ * The monitoring condition structure.
* @param tsc_timestamp
* Maximum TSC timestamp to wait for. Note that the wait behavior is
* architecture-dependent.
- * @param data_sz
- * Data size (in bytes) that will be used to compare expected value with the
- * memory address. Can be 1, 2, 4 or 8. Supplying any other value will lead
- * to undefined result.
+ *
+ * @return
+ * 0 on success
+ * -EINVAL on invalid parameters
+ * -ENOTSUP if unsupported
*/
__rte_experimental
-static inline void rte_power_monitor(const volatile void *p,
- const uint64_t expected_value, const uint64_t value_mask,
- const uint64_t tsc_timestamp, const uint8_t data_sz);
+int rte_power_monitor(const struct rte_power_monitor_cond *pmc,
+ const uint64_t tsc_timestamp);
/**
* @warning
- * @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.
+ * @b EXPERIMENTAL: this API may change without prior notice.
*
- * 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.
+ * Wake up a specific lcore that is in a power optimized state and is monitoring
+ * an address.
*
- * This call will also lock a spinlock on entering sleep, and release it on
- * waking up the CPU.
+ * @note It is safe to call this function if the lcore in question is not
+ * sleeping. The function will have no effect.
*
- * @warning It is responsibility of the user to check if this function is
- * supported at runtime using `rte_cpu_get_features()` API call.
- * Failing to do so may result in an illegal CPU instruction error.
+ * @note This function will *not* wake up a core that is in a power optimized
+ * state due to calling `rte_power_pause`.
*
- * @param p
- * Address to monitor for changes.
- * @param expected_value
- * Before attempting the monitoring, the `p` address may be read and compared
- * against this value. If `value_mask` is zero, this step will be skipped.
- * @param value_mask
- * The 64-bit mask to use to extract current value from `p`.
- * @param tsc_timestamp
- * Maximum TSC timestamp to wait for. Note that the wait behavior is
- * architecture-dependent.
- * @param data_sz
- * Data size (in bytes) that will be used to compare expected value with the
- * memory address. Can be 1, 2, 4 or 8. Supplying any other value will lead
- * to undefined result.
- * @param lck
- * A spinlock that must be locked before entering the function, will be
- * unlocked while the CPU is sleeping, and will be locked again once the CPU
- * wakes up.
+ * @param lcore_id
+ * Lcore ID of a sleeping thread.
*/
__rte_experimental
-static inline void rte_power_monitor_sync(const volatile void *p,
- const uint64_t expected_value, const uint64_t value_mask,
- const uint64_t tsc_timestamp, const uint8_t data_sz,
- rte_spinlock_t *lck);
+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.
*
* @warning It is responsibility of the user to check if this function is
- * supported at runtime using `rte_cpu_get_features()` API call.
- * Failing to do so may result in an illegal CPU instruction error.
+ * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
*
* @param tsc_timestamp
* Maximum TSC timestamp to wait for. Note that the wait behavior is
* architecture-dependent.
+ *
+ * @return
+ * 0 on success
+ * -EINVAL on invalid parameters
+ * -ENOTSUP if unsupported
*/
__rte_experimental
-static inline void rte_power_pause(const uint64_t tsc_timestamp);
+int rte_power_pause(const uint64_t tsc_timestamp);
#endif /* _RTE_POWER_INTRINSIC_H_ */
git.droids-corp.org / dpdk.git / blobdiff