lib/librte_power/rte_power.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2013 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  *
  33  */
  34
  35 #ifndef _RTE_POWER_H
  36 #define _RTE_POWER_H
  37
  38 /**
  39  * @file
  40  * RTE Power Management
  41  */
  42
  43 #include <rte_common.h>
  44 #include <rte_byteorder.h>
  45 #include <rte_log.h>
  46 #include <rte_string_fns.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 #define RTE_POWER_INVALID_FREQ_INDEX (~0)
  53
  54 /**
  55  * Initialize power management for a specific lcore. It will check and set the
  56  * governor to userspace for the lcore, get the available frequencies, and
  57  * prepare to set new lcore frequency.
  58  *
  59  * @param lcore_id
  60  *  lcore id.
  61  *
  62  * @return
  63  *  - 0 on success.
  64  *  - Negative on error.
  65  */
  66 int rte_power_init(unsigned lcore_id);
  67
  68 /**
  69  * Exit power management on a specific lcore. It will set the governor to which
  70  * is before initialized.
  71  *
  72  * @param lcore_id
  73  *  lcore id.
  74  *
  75  * @return
  76  *  - 0 on success.
  77  *  - Negative on error.
  78  */
  79 int rte_power_exit(unsigned lcore_id);
  80
  81 /**
  82  * Get the available frequencies of a specific lcore. The return value will be
  83  * the minimal one of the total number of available frequencies and the number
  84  * of buffer. The index of available frequencies used in other interfaces
  85  * should be in the range of 0 to this return value.
  86  * It should be protected outside of this function for threadsafe.
  87  *
  88  * @param lcore_id
  89  *  lcore id.
  90  * @param freqs
  91  *  The buffer array to save the frequencies.
  92  * @param num
  93  *  The number of frequencies to get.
  94  *
  95  * @return
  96  *  The number of available frequencies.
  97  */
  98 uint32_t rte_power_freqs(unsigned lcore_id, uint32_t *freqs, uint32_t num);
  99
 100 /**
 101  * Return the current index of available frequencies of a specific lcore. It
 102  * will return 'RTE_POWER_INVALID_FREQ_INDEX = (~0)' if error.
 103  * It should be protected outside of this function for threadsafe.
 104  *
 105  * @param lcore_id
 106  *  lcore id.
 107  *
 108  * @return
 109  *  The current index of available frequencies.
 110  */
 111 uint32_t rte_power_get_freq(unsigned lcore_id);
 112
 113 /**
 114  * Set the new frequency for a specific lcore by indicating the index of
 115  * available frequencies.
 116  * It should be protected outside of this function for threadsafe.
 117  *
 118  * @param lcore_id
 119  *  lcore id.
 120  * @param index
 121  *  The index of available frequencies.
 122  *
 123  * @return
 124  *  - 1 on success with frequency changed.
 125  *  - 0 on success without frequency chnaged.
 126  *  - Negative on error.
 127  */
 128 int rte_power_set_freq(unsigned lcore_id, uint32_t index);
 129
 130 /**
 131  * Scale up the frequency of a specific lcore according to the available
 132  * frequencies.
 133  * It should be protected outside of this function for threadsafe.
 134  *
 135  * @param lcore_id
 136  *  lcore id.
 137  *
 138  * @return
 139  *  - 1 on success with frequency changed.
 140  *  - 0 on success without frequency chnaged.
 141  *  - Negative on error.
 142  */
 143 int rte_power_freq_up(unsigned lcore_id);
 144
 145 /**
 146  * Scale down the frequency of a specific lcore according to the available
 147  * frequencies.
 148  * It should be protected outside of this function for threadsafe.
 149  *
 150  * @param lcore_id
 151  *  lcore id.
 152  *
 153  * @return
 154  *  - 1 on success with frequency changed.
 155  *  - 0 on success without frequency chnaged.
 156  *  - Negative on error.
 157  */
 158 int rte_power_freq_down(unsigned lcore_id);
 159
 160 /**
 161  * Scale up the frequency of a specific lcore to the highest according to the
 162  * available frequencies.
 163  * It should be protected outside of this function for threadsafe.
 164  *
 165  * @param lcore_id
 166  *  lcore id.
 167  *
 168  * @return
 169  *  - 1 on success with frequency changed.
 170  *  - 0 on success without frequency chnaged.
 171  *  - Negative on error.
 172  */
 173 int rte_power_freq_max(unsigned lcore_id);
 174
 175 /**
 176  * Scale down the frequency of a specific lcore to the lowest according to the
 177  * available frequencies.
 178  * It should be protected outside of this function for threadsafe.
 179  *
 180  * @param lcore_id
 181  *  lcore id.
 182  *
 183  * @return
 184  *  - 1 on success with frequency changed.
 185  *  - 0 on success without frequency chnaged.
 186  *  - Negative on error.
 187  */
 188 int rte_power_freq_min(unsigned lcore_id);
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif
 193
 194 #endif