1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2020 Intel Corporation
5 #ifndef _RTE_POWER_INTRINSIC_H_
6 #define _RTE_POWER_INTRINSIC_H_
10 #include <rte_compat.h>
11 #include <rte_spinlock.h>
15 * Advanced power management operations.
17 * This file define APIs for advanced power management,
18 * which are architecture-dependent.
21 struct rte_power_monitor_cond {
22 volatile void *addr; /**< Address to monitor for changes */
23 uint64_t val; /**< If the `mask` is non-zero, location pointed
24 * to by `addr` will be read and compared
27 uint64_t mask; /**< 64-bit mask to extract value read from `addr` */
28 uint8_t size; /**< Data size (in bytes) that will be used to compare
29 * expected value (`val`) with data read from the
30 * monitored memory location (`addr`). Can be 1, 2,
31 * 4, or 8. Supplying any other value will result in
38 * @b EXPERIMENTAL: this API may change without prior notice.
40 * Monitor specific address for changes. This will cause the CPU to enter an
41 * architecture-defined optimized power state until either the specified
42 * memory address is written to, a certain TSC timestamp is reached, or other
43 * reasons cause the CPU to wake up.
45 * Additionally, an expected value (`pmc->val`), mask (`pmc->mask`), and data
46 * size (`pmc->size`) are provided in the `pmc` power monitoring condition. If
47 * the mask is non-zero, the current value pointed to by the `pmc->addr` pointer
48 * will be read and compared against the expected value, and if they match, the
49 * entering of optimized power state will be aborted. This is intended to
50 * prevent the CPU from entering optimized power state and waiting on a write
51 * that has already happened by the time this API is called.
53 * @warning It is responsibility of the user to check if this function is
54 * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
57 * The monitoring condition structure.
58 * @param tsc_timestamp
59 * Maximum TSC timestamp to wait for. Note that the wait behavior is
60 * architecture-dependent.
64 * -EINVAL on invalid parameters
65 * -ENOTSUP if unsupported
68 int rte_power_monitor(const struct rte_power_monitor_cond *pmc,
69 const uint64_t tsc_timestamp);
73 * @b EXPERIMENTAL: this API may change without prior notice.
75 * Wake up a specific lcore that is in a power optimized state and is monitoring
78 * @note It is safe to call this function if the lcore in question is not
79 * sleeping. The function will have no effect.
81 * @note This function will *not* wake up a core that is in a power optimized
82 * state due to calling `rte_power_pause`.
85 * Lcore ID of a sleeping thread.
88 int rte_power_monitor_wakeup(const unsigned int lcore_id);
92 * @b EXPERIMENTAL: this API may change without prior notice.
94 * Enter an architecture-defined optimized power state until a certain TSC
95 * timestamp is reached.
97 * @warning It is responsibility of the user to check if this function is
98 * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
100 * @param tsc_timestamp
101 * Maximum TSC timestamp to wait for. Note that the wait behavior is
102 * architecture-dependent.
106 * -EINVAL on invalid parameters
107 * -ENOTSUP if unsupported
110 int rte_power_pause(const uint64_t tsc_timestamp);
112 #endif /* _RTE_POWER_INTRINSIC_H_ */