pm_domain.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * pm_domain.h - Definitions and headers related to device power domains.
  4 *
  5 * Copyright (C) 2011 Rafael J. Wysocki <rjw@sisk.pl>, Renesas Electronics Corp.
  6 */
  7
  8#ifndef _LINUX_PM_DOMAIN_H
  9#define _LINUX_PM_DOMAIN_H
 10
 11#include <linux/device.h>
 12#include <linux/ktime.h>
 13#include <linux/mutex.h>
 14#include <linux/pm.h>
 15#include <linux/err.h>
 16#include <linux/of.h>
 17#include <linux/notifier.h>
 18#include <linux/spinlock.h>
 19#include <linux/cpumask_types.h>
 20#include <linux/time64.h>
 21
 22/*
 23 * Flags to control the behaviour when attaching a device to its PM domains.
 24 *
 25 * PD_FLAG_NO_DEV_LINK:		As the default behaviour creates a device-link
 26 *				for every PM domain that gets attached, this
 27 *				flag can be used to skip that.
 28 *
 29 * PD_FLAG_DEV_LINK_ON:		Add the DL_FLAG_RPM_ACTIVE to power-on the
 30 *				supplier and its PM domain when creating the
 31 *				device-links.
 32 *
 33 * PD_FLAG_REQUIRED_OPP:	Assign required_devs for the required OPPs. The
 34 *				index of the required OPP must correspond to the
 35 *				index in the array of the pd_names. If pd_names
 36 *				isn't specified, the index just follows the
 37 *				index for the attached PM domain.
 38 *
 39 * PD_FLAG_ATTACH_POWER_ON:	Power on the domain during attach.
 40 *
 41 * PD_FLAG_DETACH_POWER_OFF:	Power off the domain during detach.
 42 *
 43 */
 44#define PD_FLAG_NO_DEV_LINK		BIT(0)
 45#define PD_FLAG_DEV_LINK_ON		BIT(1)
 46#define PD_FLAG_REQUIRED_OPP		BIT(2)
 47#define PD_FLAG_ATTACH_POWER_ON		BIT(3)
 48#define PD_FLAG_DETACH_POWER_OFF	BIT(4)
 49
 50struct dev_pm_domain_attach_data {
 51	const char * const *pd_names;
 52	const u32 num_pd_names;
 53	const u32 pd_flags;
 54};
 55
 56struct dev_pm_domain_list {
 57	struct device **pd_devs;
 58	struct device_link **pd_links;
 59	u32 *opp_tokens;
 60	u32 num_pds;
 61};
 62
 63/*
 64 * Flags to control the behaviour of a genpd.
 65 *
 66 * These flags may be set in the struct generic_pm_domain's flags field by a
 67 * genpd backend driver. The flags must be set before it calls pm_genpd_init(),
 68 * which initializes a genpd.
 69 *
 70 * GENPD_FLAG_PM_CLK:		Instructs genpd to use the PM clk framework,
 71 *				while powering on/off attached devices.
 72 *
 73 * GENPD_FLAG_IRQ_SAFE:		This informs genpd that its backend callbacks,
 74 *				->power_on|off(), doesn't sleep. Hence, these
 75 *				can be invoked from within atomic context, which
 76 *				enables genpd to power on/off the PM domain,
 77 *				even when pm_runtime_is_irq_safe() returns true,
 78 *				for any of its attached devices. Note that, a
 79 *				genpd having this flag set, requires its
 80 *				masterdomains to also have it set.
 81 *
 82 * GENPD_FLAG_ALWAYS_ON:	Instructs genpd to always keep the PM domain
 83 *				powered on.
 84 *
 85 * GENPD_FLAG_ACTIVE_WAKEUP:	Instructs genpd to keep the PM domain powered
 86 *				on, in case any of its attached devices is used
 87 *				in the wakeup path to serve system wakeups.
 88 *
 89 * GENPD_FLAG_CPU_DOMAIN:	Instructs genpd that it should expect to get
 90 *				devices attached, which may belong to CPUs or
 91 *				possibly have subdomains with CPUs attached.
 92 *				This flag enables the genpd backend driver to
 93 *				deploy idle power management support for CPUs
 94 *				and groups of CPUs. Note that, the backend
 95 *				driver must then comply with the so called,
 96 *				last-man-standing algorithm, for the CPUs in the
 97 *				PM domain.
 98 *
 99 * GENPD_FLAG_RPM_ALWAYS_ON:	Instructs genpd to always keep the PM domain
100 *				powered on except for system suspend.
101 *
102 * GENPD_FLAG_MIN_RESIDENCY:	Enable the genpd governor to consider its
103 *				components' next wakeup when determining the
104 *				optimal idle state.
105 *
106 * GENPD_FLAG_OPP_TABLE_FW:	The genpd provider supports performance states,
107 *				but its corresponding OPP tables are not
108 *				described in DT, but are given directly by FW.
109 *
110 * GENPD_FLAG_DEV_NAME_FW:	Instructs genpd to generate an unique device name
111 *				using ida. It is used by genpd providers which
112 *				get their genpd-names directly from FW.
113 *
114 * GENPD_FLAG_NO_SYNC_STATE:	The ->sync_state() support is implemented in a
115 *				genpd provider specific way, likely through a
116 *				parent device node. This flag makes genpd to
117 *				skip its internal support for this.
118 *
119 * GENPD_FLAG_NO_STAY_ON:	For genpd OF providers a powered-on PM domain at
120 *				initialization is prevented from being
121 *				powered-off until the ->sync_state() callback is
122 *				invoked. This flag informs genpd to allow a
123 *				power-off without waiting for ->sync_state().
124 */
125#define GENPD_FLAG_PM_CLK	 (1U << 0)
126#define GENPD_FLAG_IRQ_SAFE	 (1U << 1)
127#define GENPD_FLAG_ALWAYS_ON	 (1U << 2)
128#define GENPD_FLAG_ACTIVE_WAKEUP (1U << 3)
129#define GENPD_FLAG_CPU_DOMAIN	 (1U << 4)
130#define GENPD_FLAG_RPM_ALWAYS_ON (1U << 5)
131#define GENPD_FLAG_MIN_RESIDENCY (1U << 6)
132#define GENPD_FLAG_OPP_TABLE_FW	 (1U << 7)
133#define GENPD_FLAG_DEV_NAME_FW	 (1U << 8)
134#define GENPD_FLAG_NO_SYNC_STATE (1U << 9)
135#define GENPD_FLAG_NO_STAY_ON	 (1U << 10)
136
137enum gpd_status {
138	GENPD_STATE_ON = 0,	/* PM domain is on */
139	GENPD_STATE_OFF,	/* PM domain is off */
140};
141
142enum genpd_notication {
143	GENPD_NOTIFY_PRE_OFF = 0,
144	GENPD_NOTIFY_OFF,
145	GENPD_NOTIFY_PRE_ON,
146	GENPD_NOTIFY_ON,
147};
148
149enum genpd_sync_state {
150	GENPD_SYNC_STATE_OFF = 0,
151	GENPD_SYNC_STATE_SIMPLE,
152	GENPD_SYNC_STATE_ONECELL,
153};
154
155struct dev_power_governor {
156	bool (*system_power_down_ok)(struct dev_pm_domain *domain);
157	bool (*power_down_ok)(struct dev_pm_domain *domain);
158	bool (*suspend_ok)(struct device *dev);
159};
160
161struct gpd_dev_ops {
162	int (*start)(struct device *dev);
163	int (*stop)(struct device *dev);
164};
165
166struct genpd_governor_data {
167	s64 max_off_time_ns;
168	bool max_off_time_changed;
169	ktime_t next_wakeup;
170	ktime_t next_hrtimer;
171	ktime_t last_enter;
172	bool reflect_residency;
173	bool cached_power_down_ok;
174	bool cached_power_down_state_idx;
175};
176
177struct genpd_power_state {
178	const char *name;
179	s64 power_off_latency_ns;
180	s64 power_on_latency_ns;
181	s64 residency_ns;
182	u64 usage;
183	u64 rejected;
184	u64 above;
185	u64 below;
186	struct fwnode_handle *fwnode;
187	u64 idle_time;
188	void *data;
189};
190
191struct genpd_lock_ops;
192struct opp_table;
193
194struct generic_pm_domain {
195	struct device dev;
196	struct dev_pm_domain domain;	/* PM domain operations */
197	struct list_head gpd_list_node;	/* Node in the global PM domains list */
198	struct list_head parent_links;	/* Links with PM domain as a parent */
199	struct list_head child_links;	/* Links with PM domain as a child */
200	struct list_head dev_list;	/* List of devices */
201	struct dev_power_governor *gov;
202	struct genpd_governor_data *gd;	/* Data used by a genpd governor. */
203	struct work_struct power_off_work;
204	struct fwnode_handle *provider;	/* Identity of the domain provider */
205	bool has_provider;
206	const char *name;
207	atomic_t sd_count;	/* Number of subdomains with power "on" */
208	enum gpd_status status;	/* Current state of the domain */
209	unsigned int device_count;	/* Number of devices */
210	unsigned int device_id;		/* unique device id */
211	unsigned int suspended_count;	/* System suspend device counter */
212	unsigned int prepared_count;	/* Suspend counter of prepared devices */
213	unsigned int performance_state;	/* Aggregated max performance state */
214	cpumask_var_t cpus;		/* A cpumask of the attached CPUs */
215	bool synced_poweroff;		/* A consumer needs a synced poweroff */
216	bool stay_on;			/* Stay powered-on during boot. */
217	enum genpd_sync_state sync_state; /* How sync_state is managed. */
218	int (*power_off)(struct generic_pm_domain *domain);
219	int (*power_on)(struct generic_pm_domain *domain);
220	struct raw_notifier_head power_notifiers; /* Power on/off notifiers */
221	struct opp_table *opp_table;	/* OPP table of the genpd */
222	int (*set_performance_state)(struct generic_pm_domain *genpd,
223				     unsigned int state);
224	struct gpd_dev_ops dev_ops;
225	int (*set_hwmode_dev)(struct generic_pm_domain *domain,
226			      struct device *dev, bool enable);
227	bool (*get_hwmode_dev)(struct generic_pm_domain *domain,
228			      struct device *dev);
229	int (*attach_dev)(struct generic_pm_domain *domain,
230			  struct device *dev);
231	void (*detach_dev)(struct generic_pm_domain *domain,
232			   struct device *dev);
233	unsigned int flags;		/* Bit field of configs for genpd */
234	struct genpd_power_state *states;
235	void (*free_states)(struct genpd_power_state *states,
236			    unsigned int state_count);
237	unsigned int state_count; /* number of states */
238	unsigned int state_idx; /* state that genpd will go to when off */
239	u64 on_time;
240	u64 accounting_time;
241	const struct genpd_lock_ops *lock_ops;
242	union {
243		struct mutex mlock;
244		struct {
245			spinlock_t slock;
246			unsigned long lock_flags;
247		};
248		struct {
249			raw_spinlock_t raw_slock;
250			unsigned long raw_lock_flags;
251		};
252	};
253};
254
255static inline struct generic_pm_domain *pd_to_genpd(struct dev_pm_domain *pd)
256{
257	return container_of(pd, struct generic_pm_domain, domain);
258}
259
260struct gpd_link {
261	struct generic_pm_domain *parent;
262	struct list_head parent_node;
263	struct generic_pm_domain *child;
264	struct list_head child_node;
265
266	/* Sub-domain's per-master domain performance state */
267	unsigned int performance_state;
268	unsigned int prev_performance_state;
269};
270
271struct gpd_timing_data {
272	s64 suspend_latency_ns;
273	s64 resume_latency_ns;
274	s64 effective_constraint_ns;
275	ktime_t	next_wakeup;
276	bool constraint_changed;
277	bool cached_suspend_ok;
278};
279
280struct pm_domain_data {
281	struct list_head list_node;
282	struct device *dev;
283};
284
285struct generic_pm_domain_data {
286	struct pm_domain_data base;
287	struct gpd_timing_data *td;
288	struct notifier_block nb;
289	struct notifier_block *power_nb;
290	int cpu;
291	unsigned int performance_state;
292	unsigned int default_pstate;
293	unsigned int rpm_pstate;
294	unsigned int opp_token;
295	bool hw_mode;
296	bool rpm_always_on;
297	void *data;
298};
299
300#ifdef CONFIG_PM_GENERIC_DOMAINS
301static inline struct generic_pm_domain_data *to_gpd_data(struct pm_domain_data *pdd)
302{
303	return container_of(pdd, struct generic_pm_domain_data, base);
304}
305
306static inline struct generic_pm_domain_data *dev_gpd_data(struct device *dev)
307{
308	return to_gpd_data(dev->power.subsys_data->domain_data);
309}
310
311int pm_genpd_add_device(struct generic_pm_domain *genpd, struct device *dev);
312int pm_genpd_remove_device(struct device *dev);
313int pm_genpd_add_subdomain(struct generic_pm_domain *genpd,
314			   struct generic_pm_domain *subdomain);
315int pm_genpd_remove_subdomain(struct generic_pm_domain *genpd,
316			      struct generic_pm_domain *subdomain);
317int pm_genpd_init(struct generic_pm_domain *genpd,
318		  struct dev_power_governor *gov, bool is_off);
319int pm_genpd_remove(struct generic_pm_domain *genpd);
320void pm_genpd_inc_rejected(struct generic_pm_domain *genpd,
321			   unsigned int state_idx);
322struct device *dev_to_genpd_dev(struct device *dev);
323int dev_pm_genpd_set_performance_state(struct device *dev, unsigned int state);
324int dev_pm_genpd_add_notifier(struct device *dev, struct notifier_block *nb);
325int dev_pm_genpd_remove_notifier(struct device *dev);
326void dev_pm_genpd_set_next_wakeup(struct device *dev, ktime_t next);
327ktime_t dev_pm_genpd_get_next_hrtimer(struct device *dev);
328void dev_pm_genpd_synced_poweroff(struct device *dev);
329int dev_pm_genpd_set_hwmode(struct device *dev, bool enable);
330bool dev_pm_genpd_get_hwmode(struct device *dev);
331int dev_pm_genpd_rpm_always_on(struct device *dev, bool on);
332bool dev_pm_genpd_is_on(struct device *dev);
333
334extern struct dev_power_governor simple_qos_governor;
335extern struct dev_power_governor pm_domain_always_on_gov;
336#ifdef CONFIG_CPU_IDLE
337extern struct dev_power_governor pm_domain_cpu_gov;
338#endif
339#else
340
341static inline struct generic_pm_domain_data *dev_gpd_data(struct device *dev)
342{
343	return ERR_PTR(-ENOSYS);
344}
345static inline int pm_genpd_add_device(struct generic_pm_domain *genpd,
346				      struct device *dev)
347{
348	return -ENOSYS;
349}
350static inline int pm_genpd_remove_device(struct device *dev)
351{
352	return -ENOSYS;
353}
354static inline int pm_genpd_add_subdomain(struct generic_pm_domain *genpd,
355					 struct generic_pm_domain *subdomain)
356{
357	return -ENOSYS;
358}
359static inline int pm_genpd_remove_subdomain(struct generic_pm_domain *genpd,
360					    struct generic_pm_domain *subdomain)
361{
362	return -ENOSYS;
363}
364static inline int pm_genpd_init(struct generic_pm_domain *genpd,
365				struct dev_power_governor *gov, bool is_off)
366{
367	return -ENOSYS;
368}
369static inline int pm_genpd_remove(struct generic_pm_domain *genpd)
370{
371	return -EOPNOTSUPP;
372}
373
374static inline void pm_genpd_inc_rejected(struct generic_pm_domain *genpd,
375					 unsigned int state_idx)
376{ }
377
378static inline struct device *dev_to_genpd_dev(struct device *dev)
379{
380	return ERR_PTR(-EOPNOTSUPP);
381}
382
383static inline int dev_pm_genpd_set_performance_state(struct device *dev,
384						     unsigned int state)
385{
386	return -EOPNOTSUPP;
387}
388
389static inline int dev_pm_genpd_add_notifier(struct device *dev,
390					    struct notifier_block *nb)
391{
392	return -EOPNOTSUPP;
393}
394
395static inline int dev_pm_genpd_remove_notifier(struct device *dev)
396{
397	return -EOPNOTSUPP;
398}
399
400static inline void dev_pm_genpd_set_next_wakeup(struct device *dev, ktime_t next)
401{ }
402
403static inline ktime_t dev_pm_genpd_get_next_hrtimer(struct device *dev)
404{
405	return KTIME_MAX;
406}
407static inline void dev_pm_genpd_synced_poweroff(struct device *dev)
408{ }
409
410static inline int dev_pm_genpd_set_hwmode(struct device *dev, bool enable)
411{
412	return -EOPNOTSUPP;
413}
414
415static inline bool dev_pm_genpd_get_hwmode(struct device *dev)
416{
417	return false;
418}
419
420static inline int dev_pm_genpd_rpm_always_on(struct device *dev, bool on)
421{
422	return -EOPNOTSUPP;
423}
424
425static inline bool dev_pm_genpd_is_on(struct device *dev)
426{
427	return false;
428}
429
430#define simple_qos_governor		(*(struct dev_power_governor *)(NULL))
431#define pm_domain_always_on_gov		(*(struct dev_power_governor *)(NULL))
432#endif
433
434#ifdef CONFIG_PM_GENERIC_DOMAINS_SLEEP
435void dev_pm_genpd_suspend(struct device *dev);
436void dev_pm_genpd_resume(struct device *dev);
437#else
438static inline void dev_pm_genpd_suspend(struct device *dev) {}
439static inline void dev_pm_genpd_resume(struct device *dev) {}
440#endif
441
442/* OF PM domain providers */
443struct of_device_id;
444
445typedef struct generic_pm_domain *(*genpd_xlate_t)(const struct of_phandle_args *args,
446						   void *data);
447
448struct genpd_onecell_data {
449	struct generic_pm_domain **domains;
450	unsigned int num_domains;
451	genpd_xlate_t xlate;
452};
453
454#ifdef CONFIG_PM_GENERIC_DOMAINS_OF
455int of_genpd_add_provider_simple(struct device_node *np,
456				 struct generic_pm_domain *genpd);
457int of_genpd_add_provider_onecell(struct device_node *np,
458				  struct genpd_onecell_data *data);
459void of_genpd_del_provider(struct device_node *np);
460int of_genpd_add_device(const struct of_phandle_args *args, struct device *dev);
461int of_genpd_add_subdomain(const struct of_phandle_args *parent_spec,
462			   const struct of_phandle_args *subdomain_spec);
463int of_genpd_remove_subdomain(const struct of_phandle_args *parent_spec,
464			      const struct of_phandle_args *subdomain_spec);
465struct generic_pm_domain *of_genpd_remove_last(struct device_node *np);
466int of_genpd_parse_idle_states(struct device_node *dn,
467			       struct genpd_power_state **states, int *n);
468void of_genpd_sync_state(struct device_node *np);
469
470int genpd_dev_pm_attach(struct device *dev);
471struct device *genpd_dev_pm_attach_by_id(struct device *dev,
472					 unsigned int index);
473struct device *genpd_dev_pm_attach_by_name(struct device *dev,
474					   const char *name);
475#else /* !CONFIG_PM_GENERIC_DOMAINS_OF */
476static inline int of_genpd_add_provider_simple(struct device_node *np,
477					struct generic_pm_domain *genpd)
478{
479	return -EOPNOTSUPP;
480}
481
482static inline int of_genpd_add_provider_onecell(struct device_node *np,
483					struct genpd_onecell_data *data)
484{
485	return -EOPNOTSUPP;
486}
487
488static inline void of_genpd_del_provider(struct device_node *np) {}
489
490static inline int of_genpd_add_device(const struct of_phandle_args *args,
491				      struct device *dev)
492{
493	return -ENODEV;
494}
495
496static inline int of_genpd_add_subdomain(const struct of_phandle_args *parent_spec,
497					 const struct of_phandle_args *subdomain_spec)
498{
499	return -ENODEV;
500}
501
502static inline int of_genpd_remove_subdomain(const struct of_phandle_args *parent_spec,
503					    const struct of_phandle_args *subdomain_spec)
504{
505	return -ENODEV;
506}
507
508static inline int of_genpd_parse_idle_states(struct device_node *dn,
509			struct genpd_power_state **states, int *n)
510{
511	return -ENODEV;
512}
513
514static inline void of_genpd_sync_state(struct device_node *np) {}
515
516static inline int genpd_dev_pm_attach(struct device *dev)
517{
518	return 0;
519}
520
521static inline struct device *genpd_dev_pm_attach_by_id(struct device *dev,
522						       unsigned int index)
523{
524	return NULL;
525}
526
527static inline struct device *genpd_dev_pm_attach_by_name(struct device *dev,
528							 const char *name)
529{
530	return NULL;
531}
532
533static inline
534struct generic_pm_domain *of_genpd_remove_last(struct device_node *np)
535{
536	return ERR_PTR(-EOPNOTSUPP);
537}
538#endif /* CONFIG_PM_GENERIC_DOMAINS_OF */
539
540#ifdef CONFIG_PM
541int dev_pm_domain_attach(struct device *dev, u32 flags);
542struct device *dev_pm_domain_attach_by_id(struct device *dev,
543					  unsigned int index);
544struct device *dev_pm_domain_attach_by_name(struct device *dev,
545					    const char *name);
546int dev_pm_domain_attach_list(struct device *dev,
547			      const struct dev_pm_domain_attach_data *data,
548			      struct dev_pm_domain_list **list);
549int devm_pm_domain_attach_list(struct device *dev,
550			       const struct dev_pm_domain_attach_data *data,
551			       struct dev_pm_domain_list **list);
552void dev_pm_domain_detach(struct device *dev, bool power_off);
553void dev_pm_domain_detach_list(struct dev_pm_domain_list *list);
554int dev_pm_domain_start(struct device *dev);
555void dev_pm_domain_set(struct device *dev, struct dev_pm_domain *pd);
556int dev_pm_domain_set_performance_state(struct device *dev, unsigned int state);
557#else
558static inline int dev_pm_domain_attach(struct device *dev, u32 flags)
559{
560	return 0;
561}
562static inline struct device *dev_pm_domain_attach_by_id(struct device *dev,
563							unsigned int index)
564{
565	return NULL;
566}
567static inline struct device *dev_pm_domain_attach_by_name(struct device *dev,
568							  const char *name)
569{
570	return NULL;
571}
572static inline int dev_pm_domain_attach_list(struct device *dev,
573				const struct dev_pm_domain_attach_data *data,
574				struct dev_pm_domain_list **list)
575{
576	return 0;
577}
578
579static inline int devm_pm_domain_attach_list(struct device *dev,
580					     const struct dev_pm_domain_attach_data *data,
581					     struct dev_pm_domain_list **list)
582{
583	return 0;
584}
585
586static inline void dev_pm_domain_detach(struct device *dev, bool power_off) {}
587static inline void dev_pm_domain_detach_list(struct dev_pm_domain_list *list) {}
588static inline int dev_pm_domain_start(struct device *dev)
589{
590	return 0;
591}
592static inline void dev_pm_domain_set(struct device *dev,
593				     struct dev_pm_domain *pd) {}
594static inline int dev_pm_domain_set_performance_state(struct device *dev,
595						      unsigned int state)
596{
597	return 0;
598}
599#endif
600
601#endif /* _LINUX_PM_DOMAIN_H */