linux/include/linux/powercap.h
<<
>>
Prefs
   1/* SPDX-License-Identifier: GPL-2.0-only */
   2/*
   3 * powercap.h: Data types and headers for sysfs power capping interface
   4 * Copyright (c) 2013, Intel Corporation.
   5 */
   6
   7#ifndef __POWERCAP_H__
   8#define __POWERCAP_H__
   9
  10#include <linux/device.h>
  11#include <linux/idr.h>
  12
  13/*
  14 * A power cap class device can contain multiple powercap control_types.
  15 * Each control_type can have multiple power zones, which can be independently
  16 * controlled. Each power zone can have one or more constraints.
  17 */
  18
  19struct powercap_control_type;
  20struct powercap_zone;
  21struct powercap_zone_constraint;
  22
  23/**
  24 * struct powercap_control_type_ops - Define control type callbacks
  25 * @set_enable:         Enable/Disable whole control type.
  26 *                      Default is enabled. But this callback allows all zones
  27 *                      to be in disable state and remove any applied power
  28 *                      limits. If disabled power zone can only be monitored
  29 *                      not controlled.
  30 * @get_enable:         get Enable/Disable status.
  31 * @release:            Callback to inform that last reference to this
  32 *                      control type is closed. So it is safe to free data
  33 *                      structure associated with this control type.
  34 *                      This callback is mandatory if the client own memory
  35 *                      for the control type.
  36 *
  37 * This structure defines control type callbacks to be implemented by client
  38 * drivers
  39 */
  40struct powercap_control_type_ops {
  41        int (*set_enable) (struct powercap_control_type *, bool mode);
  42        int (*get_enable) (struct powercap_control_type *, bool *mode);
  43        int (*release) (struct powercap_control_type *);
  44};
  45
  46/**
  47 * struct powercap_control_type - Defines a powercap control_type
  48 * @dev:                device for this control_type
  49 * @idr:                idr to have unique id for its child
  50 * @nr_zones:           counter for number of zones of this type
  51 * @ops:                Pointer to callback struct
  52 * @lock:               mutex for control type
  53 * @allocated:          This is possible that client owns the memory
  54 *                      used by this structure. In this case
  55 *                      this flag is set to false by framework to
  56 *                      prevent deallocation during release process.
  57 *                      Otherwise this flag is set to true.
  58 * @node:               linked-list node
  59 *
  60 * Defines powercap control_type. This acts as a container for power
  61 * zones, which use same method to control power. E.g. RAPL, RAPL-PCI etc.
  62 * All fields are private and should not be used by client drivers.
  63 */
  64struct powercap_control_type {
  65        struct device dev;
  66        struct idr idr;
  67        int nr_zones;
  68        const struct powercap_control_type_ops *ops;
  69        struct mutex lock;
  70        bool allocated;
  71        struct list_head node;
  72};
  73
  74/**
  75 * struct powercap_zone_ops - Define power zone callbacks
  76 * @get_max_energy_range_uj:    Get maximum range of energy counter in
  77 *                              micro-joules.
  78 * @get_energy_uj:              Get current energy counter in micro-joules.
  79 * @reset_energy_uj:            Reset micro-joules energy counter.
  80 * @get_max_power_range_uw:     Get maximum range of power counter in
  81 *                              micro-watts.
  82 * @get_power_uw:               Get current power counter in micro-watts.
  83 * @set_enable:                 Enable/Disable power zone controls.
  84 *                              Default is enabled.
  85 * @get_enable:                 get Enable/Disable status.
  86 * @release:                    Callback to inform that last reference to this
  87 *                              control type is closed. So it is safe to free
  88 *                              data structure associated with this
  89 *                              control type. Mandatory, if client driver owns
  90 *                              the power_zone memory.
  91 *
  92 * This structure defines zone callbacks to be implemented by client drivers.
  93 * Client drives can define both energy and power related callbacks. But at
  94 * the least one type (either power or energy) is mandatory. Client drivers
  95 * should handle mutual exclusion, if required in callbacks.
  96 */
  97struct powercap_zone_ops {
  98        int (*get_max_energy_range_uj) (struct powercap_zone *, u64 *);
  99        int (*get_energy_uj) (struct powercap_zone *, u64 *);
 100        int (*reset_energy_uj) (struct powercap_zone *);
 101        int (*get_max_power_range_uw) (struct powercap_zone *, u64 *);
 102        int (*get_power_uw) (struct powercap_zone *, u64 *);
 103        int (*set_enable) (struct powercap_zone *, bool mode);
 104        int (*get_enable) (struct powercap_zone *, bool *mode);
 105        int (*release) (struct powercap_zone *);
 106};
 107
 108#define POWERCAP_ZONE_MAX_ATTRS         6
 109#define POWERCAP_CONSTRAINTS_ATTRS      8
 110#define MAX_CONSTRAINTS_PER_ZONE        10
 111/**
 112 * struct powercap_zone- Defines instance of a power cap zone
 113 * @id:                 Unique id
 114 * @name:               Power zone name.
 115 * @control_type_inst:  Control type instance for this zone.
 116 * @ops:                Pointer to the zone operation structure.
 117 * @dev:                Instance of a device.
 118 * @const_id_cnt:       Number of constraint defined.
 119 * @idr:                Instance to an idr entry for children zones.
 120 * @parent_idr:         To remove reference from the parent idr.
 121 * @private_data:       Private data pointer if any for this zone.
 122 * @zone_dev_attrs:     Attributes associated with this device.
 123 * @zone_attr_count:    Attribute count.
 124 * @dev_zone_attr_group: Attribute group for attributes.
 125 * @dev_attr_groups:    Attribute group store to register with device.
 126 * @allocated:          This is possible that client owns the memory
 127 *                      used by this structure. In this case
 128 *                      this flag is set to false by framework to
 129 *                      prevent deallocation during release process.
 130 *                      Otherwise this flag is set to true.
 131 * @constraints:        List of constraints for this zone.
 132 *
 133 * This defines a power zone instance. The fields of this structure are
 134 * private, and should not be used by client drivers.
 135 */
 136struct powercap_zone {
 137        int id;
 138        char *name;
 139        void *control_type_inst;
 140        const struct powercap_zone_ops *ops;
 141        struct device dev;
 142        int const_id_cnt;
 143        struct idr idr;
 144        struct idr *parent_idr;
 145        void *private_data;
 146        struct attribute **zone_dev_attrs;
 147        int zone_attr_count;
 148        struct attribute_group dev_zone_attr_group;
 149        const struct attribute_group *dev_attr_groups[2]; /* 1 group + NULL */
 150        bool allocated;
 151        struct powercap_zone_constraint *constraints;
 152};
 153
 154/**
 155 * struct powercap_zone_constraint_ops - Define constraint callbacks
 156 * @set_power_limit_uw:         Set power limit in micro-watts.
 157 * @get_power_limit_uw:         Get power limit in micro-watts.
 158 * @set_time_window_us:         Set time window in micro-seconds.
 159 * @get_time_window_us:         Get time window in micro-seconds.
 160 * @get_max_power_uw:           Get max power allowed in micro-watts.
 161 * @get_min_power_uw:           Get min power allowed in micro-watts.
 162 * @get_max_time_window_us:     Get max time window allowed in micro-seconds.
 163 * @get_min_time_window_us:     Get min time window allowed in micro-seconds.
 164 * @get_name:                   Get the name of constraint
 165 *
 166 * This structure is used to define the constraint callbacks for the client
 167 * drivers. The following callbacks are mandatory and can't be NULL:
 168 *  set_power_limit_uw
 169 *  get_power_limit_uw
 170 *  set_time_window_us
 171 *  get_time_window_us
 172 *  get_name
 173 *  Client drivers should handle mutual exclusion, if required in callbacks.
 174 */
 175struct powercap_zone_constraint_ops {
 176        int (*set_power_limit_uw) (struct powercap_zone *, int, u64);
 177        int (*get_power_limit_uw) (struct powercap_zone *, int, u64 *);
 178        int (*set_time_window_us) (struct powercap_zone *, int, u64);
 179        int (*get_time_window_us) (struct powercap_zone *, int, u64 *);
 180        int (*get_max_power_uw) (struct powercap_zone *, int, u64 *);
 181        int (*get_min_power_uw) (struct powercap_zone *, int, u64 *);
 182        int (*get_max_time_window_us) (struct powercap_zone *, int, u64 *);
 183        int (*get_min_time_window_us) (struct powercap_zone *, int, u64 *);
 184        const char *(*get_name) (struct powercap_zone *, int);
 185};
 186
 187/**
 188 * struct powercap_zone_constraint- Defines instance of a constraint
 189 * @id:                 Instance Id of this constraint.
 190 * @power_zone:         Pointer to the power zone for this constraint.
 191 * @ops:                Pointer to the constraint callbacks.
 192 *
 193 * This defines a constraint instance.
 194 */
 195struct powercap_zone_constraint {
 196        int id;
 197        struct powercap_zone *power_zone;
 198        const struct powercap_zone_constraint_ops *ops;
 199};
 200
 201
 202/* For clients to get their device pointer, may be used for dev_dbgs */
 203#define POWERCAP_GET_DEV(power_zone)    (&power_zone->dev)
 204
 205/**
 206* powercap_set_zone_data() - Set private data for a zone
 207* @power_zone:  A pointer to the valid zone instance.
 208* @pdata:       A pointer to the user private data.
 209*
 210* Allows client drivers to associate some private data to zone instance.
 211*/
 212static inline void powercap_set_zone_data(struct powercap_zone *power_zone,
 213                                                void *pdata)
 214{
 215        if (power_zone)
 216                power_zone->private_data = pdata;
 217}
 218
 219/**
 220* powercap_get_zone_data() - Get private data for a zone
 221* @power_zone:  A pointer to the valid zone instance.
 222*
 223* Allows client drivers to get private data associate with a zone,
 224* using call to powercap_set_zone_data.
 225*/
 226static inline void *powercap_get_zone_data(struct powercap_zone *power_zone)
 227{
 228        if (power_zone)
 229                return power_zone->private_data;
 230        return NULL;
 231}
 232
 233/**
 234* powercap_register_control_type() - Register a control_type with framework
 235* @control_type:        Pointer to client allocated memory for the control type
 236*                       structure storage. If this is NULL, powercap framework
 237*                       will allocate memory and own it.
 238*                       Advantage of this parameter is that client can embed
 239*                       this data in its data structures and allocate in a
 240*                       single call, preventing multiple allocations.
 241* @control_type_name:   The Name of this control_type, which will be shown
 242*                       in the sysfs Interface.
 243* @ops:                 Callbacks for control type. This parameter is optional.
 244*
 245* Used to create a control_type with the power capping class. Here control_type
 246* can represent a type of technology, which can control a range of power zones.
 247* For example a control_type can be RAPL (Running Average Power Limit)
 248* IntelĀ® 64 and IA-32 Processor Architectures. The name can be any string
 249* which must be unique, otherwise this function returns NULL.
 250* A pointer to the control_type instance is returned on success.
 251*/
 252struct powercap_control_type *powercap_register_control_type(
 253                                struct powercap_control_type *control_type,
 254                                const char *name,
 255                                const struct powercap_control_type_ops *ops);
 256
 257/**
 258* powercap_unregister_control_type() - Unregister a control_type from framework
 259* @instance:    A pointer to the valid control_type instance.
 260*
 261* Used to unregister a control_type with the power capping class.
 262* All power zones registered under this control type have to be unregistered
 263* before calling this function, or it will fail with an error code.
 264*/
 265int powercap_unregister_control_type(struct powercap_control_type *instance);
 266
 267/* Zone register/unregister API */
 268
 269/**
 270* powercap_register_zone() - Register a power zone
 271* @power_zone:  Pointer to client allocated memory for the power zone structure
 272*               storage. If this is NULL, powercap framework will allocate
 273*               memory and own it. Advantage of this parameter is that client
 274*               can embed this data in its data structures and allocate in a
 275*               single call, preventing multiple allocations.
 276* @control_type: A control_type instance under which this zone operates.
 277* @name:        A name for this zone.
 278* @parent:      A pointer to the parent power zone instance if any or NULL
 279* @ops:         Pointer to zone operation callback structure.
 280* @no_constraints: Number of constraints for this zone
 281* @const_ops:   Pointer to constraint callback structure
 282*
 283* Register a power zone under a given control type. A power zone must register
 284* a pointer to a structure representing zone callbacks.
 285* A power zone can be located under a parent power zone, in which case @parent
 286* should point to it.  Otherwise, if @parent is NULL, the new power zone will
 287* be located directly under the given control type
 288* For each power zone there may be a number of constraints that appear in the
 289* sysfs under that zone as attributes with unique numeric IDs.
 290* Returns pointer to the power_zone on success.
 291*/
 292struct powercap_zone *powercap_register_zone(
 293                        struct powercap_zone *power_zone,
 294                        struct powercap_control_type *control_type,
 295                        const char *name,
 296                        struct powercap_zone *parent,
 297                        const struct powercap_zone_ops *ops,
 298                        int nr_constraints,
 299                        const struct powercap_zone_constraint_ops *const_ops);
 300
 301/**
 302* powercap_unregister_zone() - Unregister a zone device
 303* @control_type:        A pointer to the valid instance of a control_type.
 304* @power_zone:  A pointer to the valid zone instance for a control_type
 305*
 306* Used to unregister a zone device for a control_type.  Caller should
 307* make sure that children for this zone are unregistered first.
 308*/
 309int powercap_unregister_zone(struct powercap_control_type *control_type,
 310                                struct powercap_zone *power_zone);
 311
 312#endif
 313