powercap.h 12 KB

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