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.
23 * @b EXPERIMENTAL: this API may change without prior notice
25 * Monitor specific address for changes. This will cause the CPU to enter an
26 * architecture-defined optimized power state until either the specified
27 * memory address is written to, a certain TSC timestamp is reached, or other
28 * reasons cause the CPU to wake up.
30 * Additionally, an `expected` 64-bit value and 64-bit mask are provided. If
31 * mask is non-zero, the current value pointed to by the `p` pointer will be
32 * checked against the expected value, and if they match, the entering of
33 * optimized power state may be aborted.
35 * @warning It is responsibility of the user to check if this function is
36 * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
37 * Failing to do so may result in an illegal CPU instruction error.
40 * Address to monitor for changes.
41 * @param expected_value
42 * Before attempting the monitoring, the `p` address may be read and compared
43 * against this value. If `value_mask` is zero, this step will be skipped.
45 * The 64-bit mask to use to extract current value from `p`.
46 * @param tsc_timestamp
47 * Maximum TSC timestamp to wait for. Note that the wait behavior is
48 * architecture-dependent.
50 * Data size (in bytes) that will be used to compare expected value with the
51 * memory address. Can be 1, 2, 4 or 8. Supplying any other value will lead
52 * to undefined result.
55 static inline void rte_power_monitor(const volatile void *p,
56 const uint64_t expected_value, const uint64_t value_mask,
57 const uint64_t tsc_timestamp, const uint8_t data_sz);
61 * @b EXPERIMENTAL: this API may change without prior notice
63 * Monitor specific address for changes. This will cause the CPU to enter an
64 * architecture-defined optimized power state until either the specified
65 * memory address is written to, a certain TSC timestamp is reached, or other
66 * reasons cause the CPU to wake up.
68 * Additionally, an `expected` 64-bit value and 64-bit mask are provided. If
69 * mask is non-zero, the current value pointed to by the `p` pointer will be
70 * checked against the expected value, and if they match, the entering of
71 * optimized power state may be aborted.
73 * This call will also lock a spinlock on entering sleep, and release it on
76 * @warning It is responsibility of the user to check if this function is
77 * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
78 * Failing to do so may result in an illegal CPU instruction error.
81 * Address to monitor for changes.
82 * @param expected_value
83 * Before attempting the monitoring, the `p` address may be read and compared
84 * against this value. If `value_mask` is zero, this step will be skipped.
86 * The 64-bit mask to use to extract current value from `p`.
87 * @param tsc_timestamp
88 * Maximum TSC timestamp to wait for. Note that the wait behavior is
89 * architecture-dependent.
91 * Data size (in bytes) that will be used to compare expected value with the
92 * memory address. Can be 1, 2, 4 or 8. Supplying any other value will lead
93 * to undefined result.
95 * A spinlock that must be locked before entering the function, will be
96 * unlocked while the CPU is sleeping, and will be locked again once the CPU
100 static inline void rte_power_monitor_sync(const volatile void *p,
101 const uint64_t expected_value, const uint64_t value_mask,
102 const uint64_t tsc_timestamp, const uint8_t data_sz,
103 rte_spinlock_t *lck);
107 * @b EXPERIMENTAL: this API may change without prior notice
109 * Enter an architecture-defined optimized power state until a certain TSC
110 * timestamp is reached.
112 * @warning It is responsibility of the user to check if this function is
113 * supported at runtime using `rte_cpu_get_intrinsics_support()` API call.
114 * Failing to do so may result in an illegal CPU instruction error.
116 * @param tsc_timestamp
117 * Maximum TSC timestamp to wait for. Note that the wait behavior is
118 * architecture-dependent.
121 static inline void rte_power_pause(const uint64_t tsc_timestamp);
123 #endif /* _RTE_POWER_INTRINSIC_H_ */