lib/power/rte_power_pmd_mgmt.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2020 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_POWER_PMD_MGMT_H
   6 #define _RTE_POWER_PMD_MGMT_H
   7
   8 /**
   9  * @file
  10  * RTE PMD Power Management
  11  */
  12
  13 #include <stdint.h>
  14
  15 #include <rte_log.h>
  16 #include <rte_power.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /**
  23  * PMD Power Management Type
  24  */
  25 enum rte_power_pmd_mgmt_type {
  26         /** Use power-optimized monitoring to wait for incoming traffic */
  27         RTE_POWER_MGMT_TYPE_MONITOR = 1,
  28         /** Use power-optimized sleep to avoid busy polling */
  29         RTE_POWER_MGMT_TYPE_PAUSE,
  30         /** Use frequency scaling when traffic is low */
  31         RTE_POWER_MGMT_TYPE_SCALE,
  32 };
  33
  34 /**
  35  * @warning
  36  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
  37  *
  38  * Enable power management on a specified Ethernet device Rx queue and lcore.
  39  *
  40  * @note This function is not thread-safe.
  41  *
  42  * @warning This function must be called when all affected Ethernet queues are
  43  *   stopped and no Rx/Tx is in progress!
  44  *
  45  * @param lcore_id
  46  *   The lcore the Rx queue will be polled from.
  47  * @param port_id
  48  *   The port identifier of the Ethernet device.
  49  * @param queue_id
  50  *   The queue identifier of the Ethernet device.
  51  * @param mode
  52  *   The power management scheme to use for specified Rx queue.
  53  * @return
  54  *   0 on success
  55  *   <0 on error
  56  */
  57 __rte_experimental
  58 int
  59 rte_power_ethdev_pmgmt_queue_enable(unsigned int lcore_id,
  60                 uint16_t port_id, uint16_t queue_id,
  61                 enum rte_power_pmd_mgmt_type mode);
  62
  63 /**
  64  * @warning
  65  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
  66  *
  67  * Disable power management on a specified Ethernet device Rx queue and lcore.
  68  *
  69  * @note This function is not thread-safe.
  70  *
  71  * @warning This function must be called when all affected Ethernet queues are
  72  *   stopped and no Rx/Tx is in progress!
  73  *
  74  * @param lcore_id
  75  *   The lcore the Rx queue is polled from.
  76  * @param port_id
  77  *   The port identifier of the Ethernet device.
  78  * @param queue_id
  79  *   The queue identifier of the Ethernet device.
  80  * @return
  81  *   0 on success
  82  *   <0 on error
  83  */
  84 __rte_experimental
  85 int
  86 rte_power_ethdev_pmgmt_queue_disable(unsigned int lcore_id,
  87                 uint16_t port_id, uint16_t queue_id);
  88
  89 /**
  90  * @warning
  91  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
  92  *
  93  * Set a emptypoll_max to specified value. Used to specify the number of empty
  94  * polls to wait before entering sleep state.
  95  *
  96  * @param max
  97  *   The value to set emptypoll_max to.
  98  */
  99 __rte_experimental
 100 void
 101 rte_power_pmd_mgmt_set_emptypoll_max(unsigned int max);
 102
 103 /**
 104  * @warning
 105  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 106  *
 107  * Get the current value of emptypoll_max.
 108  *
 109  * @return
 110  *   The current emptypoll_max value
 111  */
 112 __rte_experimental
 113 unsigned int
 114 rte_power_pmd_mgmt_get_emptypoll_max(void);
 115
 116 /**
 117  * @warning
 118  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 119  *
 120  * Set the pause_duration. Used to adjust the pause mode callback duration.
 121  *
 122  * @note Duration must be greater than zero.
 123  *
 124  * @param duration
 125  *   The value to set pause_duration to.
 126  * @return
 127  *   0 on success
 128  *   <0 on error
 129  */
 130 __rte_experimental
 131 int
 132 rte_power_pmd_mgmt_set_pause_duration(unsigned int duration);
 133
 134 /**
 135  * @warning
 136  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 137  *
 138  * Get the current value of pause_duration.
 139  *
 140  * @return
 141  *   The current pause_duration value.
 142  */
 143 __rte_experimental
 144 unsigned int
 145 rte_power_pmd_mgmt_get_pause_duration(void);
 146
 147 /**
 148  * @warning
 149  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 150  *
 151  * Set the min frequency to be used for frequency scaling or zero to use defaults.
 152  *
 153  * @note Supported by: Pstate mode.
 154  *
 155  * @param lcore
 156  *   The ID of the lcore to set the min frequency for.
 157  * @param min
 158  *   The value, in KiloHertz, to set the minimum frequency to.
 159  * @return
 160  *   0 on success
 161  *   <0 on error
 162  */
 163 __rte_experimental
 164 int
 165 rte_power_pmd_mgmt_set_scaling_freq_min(unsigned int lcore, unsigned int min);
 166
 167 /**
 168  * @warning
 169  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 170  *
 171  * Set the max frequency to be used for frequency scaling or zero to use defaults.
 172  *
 173  * @note Supported by: Pstate mode.
 174  *
 175  * @param lcore
 176  *   The ID of the lcore to set the max frequency for.
 177  * @param max
 178  *   The value, in KiloHertz, to set the maximum frequency to.
 179  *   If 'max' is 0, it is considered 'not set'.
 180  * @return
 181  *   0 on success
 182  *   <0 on error
 183  */
 184 __rte_experimental
 185 int
 186 rte_power_pmd_mgmt_set_scaling_freq_max(unsigned int lcore, unsigned int max);
 187
 188 /**
 189  * @warning
 190  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 191  *
 192  * Get the current configured min frequency used for frequency scaling.
 193  *
 194  * @note Supported by: Pstate mode.
 195  *
 196  * @param lcore
 197  *   The ID of the lcore to get the min frequency for.
 198  * @return
 199  *   0 if no value has been configured via the 'set' API.
 200  *   >0 if a minimum frequency has been configured. Value is the minimum frequency
 201  *   , in KiloHertz, used for frequency scaling.
 202  *   <0 on error
 203  */
 204 __rte_experimental
 205 int
 206 rte_power_pmd_mgmt_get_scaling_freq_min(unsigned int lcore);
 207
 208 /**
 209  * @warning
 210  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
 211  *
 212  * Get the current configured max frequency used for frequency scaling.
 213  *
 214  * @note Supported by: Pstate mode.
 215  *
 216  * @param lcore
 217  *   The ID of the lcore to get the max frequency for.
 218  * @return
 219  *   0 if no value has been configured via the 'set' API.
 220  *   >0 if a maximum frequency has been configured. Value is the maximum frequency
 221  *   , in KiloHertz, used for frequency scaling.
 222  *   <0 on error
 223  */
 224 __rte_experimental
 225 int
 226 rte_power_pmd_mgmt_get_scaling_freq_max(unsigned int lcore);
 227
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232 #endif