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 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
  25                                *   against this value.
  26                                */
  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
  32                           *   an error.
  33                           */
  34 };
  35
  36 /**
  37  * @warning
  38  * @b EXPERIMENTAL: this API may change without prior notice.
  39  *
  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.
  44  *
  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.
  52  *
  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.
  55  *
  56  * @param pmc
  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.
  61  *
  62  * @return
  63  *   0 on success
  64  *   -EINVAL on invalid parameters
  65  *   -ENOTSUP if unsupported
  66  */
  67 __rte_experimental
  68 int rte_power_monitor(const struct rte_power_monitor_cond *pmc,
  69                 const uint64_t tsc_timestamp);
  70
  71 /**
  72  * @warning
  73  * @b EXPERIMENTAL: this API may change without prior notice.
  74  *
  75  * Wake up a specific lcore that is in a power optimized state and is monitoring
  76  * an address.
  77  *
  78  * @note It is safe to call this function if the lcore in question is not
  79  *   sleeping. The function will have no effect.
  80  *
  81  * @note This function will *not* wake up a core that is in a power optimized
  82  *   state due to calling `rte_power_pause`.
  83  *
  84  * @param lcore_id
  85  *   Lcore ID of a sleeping thread.
  86  */
  87 __rte_experimental
  88 int rte_power_monitor_wakeup(const unsigned int lcore_id);
  89
  90 /**
  91  * @warning
  92  * @b EXPERIMENTAL: this API may change without prior notice.
  93  *
  94  * Enter an architecture-defined optimized power state until a certain TSC
  95  * timestamp is reached.
  96  *
  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.
  99  *
 100  * @param tsc_timestamp
 101  *   Maximum TSC timestamp to wait for. Note that the wait behavior is
 102  *   architecture-dependent.
 103  *
 104  * @return
 105  *   0 on success
 106  *   -EINVAL on invalid parameters
 107  *   -ENOTSUP if unsupported
 108  */
 109 __rte_experimental
 110 int rte_power_pause(const uint64_t tsc_timestamp);
 111
 112 #endif /* _RTE_POWER_INTRINSIC_H_ */