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