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 31struct powercap_control_type; 32struct powercap_zone; 33struct 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 */ 52struct 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 */ 77struct 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 */ 110struct 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 */ 149struct 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 */ 188struct 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 */ 208struct powercap_zone_constraint { 209 int id; 210 struct powercap_zone *power_zone; 211 const 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*/ 225static 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*/ 239static 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*/ 265struct 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*/ 278int 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*/ 305struct 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 const 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*/ 322int powercap_unregister_zone(struct powercap_control_type *control_type, 323 struct powercap_zone *power_zone); 324 325#endif 326