X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=lib%2Flibrte_power%2Frte_power.h;h=bbbde4dfb4f60989dfb1c0a7a0089fd9528070f5;hb=8bccf4774c3007726b45b73318732ea29dc435ce;hp=9c1419ea04c5328a03148119c332a022f0dabd76;hpb=3031749c2df04a63cdcef186dcce3781e61436e8;p=dpdk.git diff --git a/lib/librte_power/rte_power.h b/lib/librte_power/rte_power.h index 9c1419ea04..bbbde4dfb4 100644 --- a/lib/librte_power/rte_power.h +++ b/lib/librte_power/rte_power.h @@ -1,34 +1,5 @@ -/*- - * BSD LICENSE - * - * Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * * Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * * Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * * Neither the name of Intel Corporation nor the names of its - * contributors may be used to endorse or promote products derived - * from this software without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright(c) 2010-2014 Intel Corporation */ #ifndef _RTE_POWER_H @@ -48,12 +19,61 @@ extern "C" { #endif -#define RTE_POWER_INVALID_FREQ_INDEX (~0) +/* Power Management Environment State */ +enum power_management_env {PM_ENV_NOT_SET, PM_ENV_ACPI_CPUFREQ, PM_ENV_KVM_VM, + PM_ENV_PSTATE_CPUFREQ}; /** - * Initialize power management for a specific lcore. It will check and set the - * governor to userspace for the lcore, get the available frequencies, and - * prepare to set new lcore frequency. + * @warning + * @b EXPERIMENTAL: this API may change, or be removed, without prior notice + * + * Check if a specific power management environment type is supported on a + * currently running system. + * + * @param env + * The environment type to check support for. + * + * @return + * - 1 if supported + * - 0 if unsupported + * - -1 if error, with rte_errno indicating reason for error. + */ +__rte_experimental +int rte_power_check_env_supported(enum power_management_env env); + +/** + * Set the default power management implementation. If this is not called prior + * to rte_power_init(), then auto-detect of the environment will take place. + * It is thread safe. New env can be set only in uninitialized state + * (thus rte_power_unset_env must be called if different env was already set). + * + * @param env + * env. The environment in which to initialise Power Management for. + * + * @return + * - 0 on success. + * - Negative on error. + */ +int rte_power_set_env(enum power_management_env env); + +/** + * Unset the global environment configuration. + * This can only be called after all threads have completed. + */ +void rte_power_unset_env(void); + +/** + * Get the default power management implementation. + * + * @return + * power_management_env The configured environment. + */ +enum power_management_env rte_power_get_env(void); + +/** + * Initialize power management for a specific lcore. If rte_power_set_env() has + * not been called then an auto-detect of the environment will start and + * initialise the corresponding resources. * * @param lcore_id * lcore id. @@ -62,11 +82,11 @@ extern "C" { * - 0 on success. * - Negative on error. */ -int rte_power_init(unsigned lcore_id); +int rte_power_init(unsigned int lcore_id); /** - * Exit power management on a specific lcore. It will set the governor to which - * is before initialized. + * Exit power management on a specific lcore. This will call the environment + * dependent exit function. * * @param lcore_id * lcore id. @@ -75,14 +95,12 @@ int rte_power_init(unsigned lcore_id); * - 0 on success. * - Negative on error. */ -int rte_power_exit(unsigned lcore_id); +int rte_power_exit(unsigned int lcore_id); /** - * Get the available frequencies of a specific lcore. The return value will be - * the minimal one of the total number of available frequencies and the number - * of buffer. The index of available frequencies used in other interfaces - * should be in the range of 0 to this return value. - * It should be protected outside of this function for threadsafe. + * Get the available frequencies of a specific lcore. + * Function pointer definition. Review each environments + * specific documentation for usage. * * @param lcore_id * lcore id. @@ -94,12 +112,15 @@ int rte_power_exit(unsigned lcore_id); * @return * The number of available frequencies. */ -uint32_t rte_power_freqs(unsigned lcore_id, uint32_t *freqs, uint32_t num); +typedef uint32_t (*rte_power_freqs_t)(unsigned int lcore_id, uint32_t *freqs, + uint32_t num); + +extern rte_power_freqs_t rte_power_freqs; /** - * Return the current index of available frequencies of a specific lcore. It - * will return 'RTE_POWER_INVALID_FREQ_INDEX = (~0)' if error. - * It should be protected outside of this function for threadsafe. + * Return the current index of available frequencies of a specific lcore. + * Function pointer definition. Review each environments + * specific documentation for usage. * * @param lcore_id * lcore id. @@ -107,12 +128,15 @@ uint32_t rte_power_freqs(unsigned lcore_id, uint32_t *freqs, uint32_t num); * @return * The current index of available frequencies. */ -uint32_t rte_power_get_freq(unsigned lcore_id); +typedef uint32_t (*rte_power_get_freq_t)(unsigned int lcore_id); + +extern rte_power_get_freq_t rte_power_get_freq; /** * Set the new frequency for a specific lcore by indicating the index of * available frequencies. - * It should be protected outside of this function for threadsafe. + * Function pointer definition. Review each environments + * specific documentation for usage. * * @param lcore_id * lcore id. @@ -121,70 +145,161 @@ uint32_t rte_power_get_freq(unsigned lcore_id); * * @return * - 1 on success with frequency changed. - * - 0 on success without frequency chnaged. + * - 0 on success without frequency changed. + * - Negative on error. + */ +typedef int (*rte_power_set_freq_t)(unsigned int lcore_id, uint32_t index); + +extern rte_power_set_freq_t rte_power_set_freq; + +/** + * Function pointer definition for generic frequency change functions. Review + * each environments specific documentation for usage. + * + * @param lcore_id + * lcore id. + * + * @return + * - 1 on success with frequency changed. + * - 0 on success without frequency changed. * - Negative on error. */ -int rte_power_set_freq(unsigned lcore_id, uint32_t index); +typedef int (*rte_power_freq_change_t)(unsigned int lcore_id); /** * Scale up the frequency of a specific lcore according to the available * frequencies. - * It should be protected outside of this function for threadsafe. + * Review each environments specific documentation for usage. * * @param lcore_id * lcore id. * * @return * - 1 on success with frequency changed. - * - 0 on success without frequency chnaged. + * - 0 on success without frequency changed. * - Negative on error. */ -int rte_power_freq_up(unsigned lcore_id); +extern rte_power_freq_change_t rte_power_freq_up; /** * Scale down the frequency of a specific lcore according to the available * frequencies. - * It should be protected outside of this function for threadsafe. + * Review each environments specific documentation for usage. * * @param lcore_id * lcore id. * * @return * - 1 on success with frequency changed. - * - 0 on success without frequency chnaged. + * - 0 on success without frequency changed. * - Negative on error. */ -int rte_power_freq_down(unsigned lcore_id); + +extern rte_power_freq_change_t rte_power_freq_down; /** * Scale up the frequency of a specific lcore to the highest according to the * available frequencies. - * It should be protected outside of this function for threadsafe. + * Review each environments specific documentation for usage. * * @param lcore_id * lcore id. * * @return * - 1 on success with frequency changed. - * - 0 on success without frequency chnaged. + * - 0 on success without frequency changed. * - Negative on error. */ -int rte_power_freq_max(unsigned lcore_id); +extern rte_power_freq_change_t rte_power_freq_max; /** * Scale down the frequency of a specific lcore to the lowest according to the * available frequencies. - * It should be protected outside of this function for threadsafe. + * Review each environments specific documentation for usage.. * * @param lcore_id * lcore id. * * @return * - 1 on success with frequency changed. - * - 0 on success without frequency chnaged. + * - 0 on success without frequency changed. + * - Negative on error. + */ +extern rte_power_freq_change_t rte_power_freq_min; + +/** + * Query the Turbo Boost status of a specific lcore. + * Review each environments specific documentation for usage.. + * + * @param lcore_id + * lcore id. + * + * @return + * - 1 Turbo Boost is enabled for this lcore. + * - 0 Turbo Boost is disabled for this lcore. + * - Negative on error. + */ +extern rte_power_freq_change_t rte_power_turbo_status; + +/** + * Enable Turbo Boost for this lcore. + * Review each environments specific documentation for usage.. + * + * @param lcore_id + * lcore id. + * + * @return + * - 0 on success. + * - Negative on error. + */ +extern rte_power_freq_change_t rte_power_freq_enable_turbo; + +/** + * Disable Turbo Boost for this lcore. + * Review each environments specific documentation for usage.. + * + * @param lcore_id + * lcore id. + * + * @return + * - 0 on success. + * - Negative on error. + */ +extern rte_power_freq_change_t rte_power_freq_disable_turbo; + +/** + * Power capabilities summary. + */ +struct rte_power_core_capabilities { + RTE_STD_C11 + union { + uint64_t capabilities; + RTE_STD_C11 + struct { + uint64_t turbo:1; /**< Turbo can be enabled. */ + uint64_t priority:1; /**< SST-BF high freq core */ + }; + }; +}; + +/** + * Returns power capabilities for a specific lcore. + * Function pointer definition. Review each environments + * specific documentation for usage. + * + * @param lcore_id + * lcore id. + * @param caps + * pointer to rte_power_core_capabilities object. + * + * @return + * - 0 on success. * - Negative on error. */ -int rte_power_freq_min(unsigned lcore_id); +typedef int (*rte_power_get_capabilities_t)(unsigned int lcore_id, + struct rte_power_core_capabilities *caps); + +extern rte_power_get_capabilities_t rte_power_get_capabilities; #ifdef __cplusplus }