lib/librte_eal/include/generic/rte_power_intrinsics.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2020 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_POWER_INTRINSIC_H_
   6 #define _RTE_POWER_INTRINSIC_H_
   7
   8 #include <inttypes.h>
   9
  10 #include <rte_compat.h>
  11 #include <rte_spinlock.h>
  12
  13 /**
  14  * @file
  15  * Advanced power management operations.
  16  *
  17  * This file define APIs for advanced power management,
  18  * which are architecture-dependent.
  19  */
  20
  21 /**
  22  * @warning
  23  * @b EXPERIMENTAL: this API may change without prior notice
  24  *
  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.
  29  *
  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.
  34  *
  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.
  38  *
  39  * @param p
  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.
  44  * @param value_mask
  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.
  49  * @param data_sz
  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.
  53  */
  54 __rte_experimental
  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);
  58
  59 /**
  60  * @warning
  61  * @b EXPERIMENTAL: this API may change without prior notice
  62  *
  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.
  67  *
  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.
  72  *
  73  * This call will also lock a spinlock on entering sleep, and release it on
  74  * waking up the CPU.
  75  *
  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.
  79  *
  80  * @param p
  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.
  85  * @param value_mask
  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.
  90  * @param data_sz
  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.
  94  * @param lck
  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
  97  *   wakes up.
  98  */
  99 __rte_experimental
 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);
 104
 105 /**
 106  * @warning
 107  * @b EXPERIMENTAL: this API may change without prior notice
 108  *
 109  * Enter an architecture-defined optimized power state until a certain TSC
 110  * timestamp is reached.
 111  *
 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.
 115  *
 116  * @param tsc_timestamp
 117  *   Maximum TSC timestamp to wait for. Note that the wait behavior is
 118  *   architecture-dependent.
 119  */
 120 __rte_experimental
 121 static inline void rte_power_pause(const uint64_t tsc_timestamp);
 122
 123 #endif /* _RTE_POWER_INTRINSIC_H_ */