Merge branch 'fix/edma' into fixes
[firefly-linux-kernel-4.4.55.git] / 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