include/linux/powercap.h

   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
  19 struct powercap_control_type;
  20 struct powercap_zone;
  21 struct 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  */
  40 struct 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  */
  64 struct 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  */
  97 struct 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  */
 136 struct 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  */
 175 struct 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  */
 195 struct 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 */
 212 static 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 */
 226 static 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 */
 252 struct 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 */
 265 int 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 */
 292 struct 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 */
 309 int powercap_unregister_zone(struct powercap_control_type *control_type,
 310                                 struct powercap_zone *power_zone);
 311
 312 #endif