include/linux/powercap.h

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