1 .. SPDX-License-Identifier: GPL-2.0-only 1 .. SPDX-License-Identifier: GPL-2.0-only
2 .. Copyright 2024 Linaro Ltd. 2 .. Copyright 2024 Linaro Ltd.
3 3
4 ==================== 4 ====================
5 Power Sequencing API 5 Power Sequencing API
6 ==================== 6 ====================
7 7
8 :Author: Bartosz Golaszewski 8 :Author: Bartosz Golaszewski
9 9
10 Introduction 10 Introduction
11 ============ 11 ============
12 12
13 This framework is designed to abstract complex 13 This framework is designed to abstract complex power-up sequences that are
14 shared between multiple logical devices in the 14 shared between multiple logical devices in the linux kernel.
15 15
16 The intention is to allow consumers to obtain 16 The intention is to allow consumers to obtain a power sequencing handle
17 exposed by the power sequence provider and del 17 exposed by the power sequence provider and delegate the actual requesting and
18 control of the underlying resources as well as 18 control of the underlying resources as well as to allow the provider to
19 mitigate any potential conflicts between multi 19 mitigate any potential conflicts between multiple users behind the scenes.
20 20
21 Glossary 21 Glossary
22 -------- 22 --------
23 23
24 The power sequencing API uses a number of term 24 The power sequencing API uses a number of terms specific to the subsystem:
25 25
26 Unit 26 Unit
27 27
28 A unit is a discreet chunk of a power sequ 28 A unit is a discreet chunk of a power sequence. For instance one unit may
29 enable a set of regulators, another may en 29 enable a set of regulators, another may enable a specific GPIO. Units can
30 define dependencies in the form of other u 30 define dependencies in the form of other units that must be enabled before
31 it itself can be. 31 it itself can be.
32 32
33 Target 33 Target
34 34
35 A target is a set of units (composed of th 35 A target is a set of units (composed of the "final" unit and its
36 dependencies) that a consumer selects by i 36 dependencies) that a consumer selects by its name when requesting a handle
37 to the power sequencer. Via the dependency 37 to the power sequencer. Via the dependency system, multiple targets may
38 share the same parts of a power sequence b 38 share the same parts of a power sequence but ignore parts that are
39 irrelevant. 39 irrelevant.
40 40
41 Descriptor 41 Descriptor
42 42
43 A handle passed by the pwrseq core to ever 43 A handle passed by the pwrseq core to every consumer that serves as the
44 entry point to the provider layer. It ensu 44 entry point to the provider layer. It ensures coherence between different
45 users and keeps reference counting consist 45 users and keeps reference counting consistent.
46 46
47 Consumer interface 47 Consumer interface
48 ================== 48 ==================
49 49
50 The consumer API is aimed to be as simple as p 50 The consumer API is aimed to be as simple as possible. The driver interested in
51 getting a descriptor from the power sequencer 51 getting a descriptor from the power sequencer should call pwrseq_get() and
52 specify the name of the target it wants to rea 52 specify the name of the target it wants to reach in the sequence after calling
53 pwrseq_power_up(). The descriptor can be relea 53 pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and
54 the consumer can request the powering down of 54 the consumer can request the powering down of its target with
55 pwrseq_power_off(). Note that there is no guar 55 pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()
56 will have any effect as there may be multiple 56 will have any effect as there may be multiple users of the underlying resources
57 who may keep them active. 57 who may keep them active.
58 58
59 Provider interface 59 Provider interface
60 ================== 60 ==================
61 61
62 The provider API is admittedly not nearly as s 62 The provider API is admittedly not nearly as straightforward as the one for
63 consumers but it makes up for it in flexibilit 63 consumers but it makes up for it in flexibility.
64 64
65 Each provider can logically split the power-up 65 Each provider can logically split the power-up sequence into descrete chunks
66 (units) and define their dependencies. They ca 66 (units) and define their dependencies. They can then expose named targets that
67 consumers may use as the final point in the se 67 consumers may use as the final point in the sequence that they wish to reach.
68 68
69 To that end the providers fill out a set of co 69 To that end the providers fill out a set of configuration structures and
70 register with the pwrseq subsystem by calling 70 register with the pwrseq subsystem by calling pwrseq_device_register().
71 71
72 Dynamic consumer matching 72 Dynamic consumer matching
73 ------------------------- 73 -------------------------
74 74
75 The main difference between pwrseq and other l 75 The main difference between pwrseq and other linux kernel providers is the
76 mechanism for dynamic matching of consumers an 76 mechanism for dynamic matching of consumers and providers. Every power sequence
77 provider driver must implement the `match()` c 77 provider driver must implement the `match()` callback and pass it to the pwrseq
78 core when registering with the subsystems. 78 core when registering with the subsystems.
79 79
80 When a client requests a sequencer handle, the 80 When a client requests a sequencer handle, the core will call this callback for
81 every registered provider and let it flexibly 81 every registered provider and let it flexibly figure out whether the proposed
82 client device is indeed its consumer. For exam 82 client device is indeed its consumer. For example: if the provider binds to the
83 device-tree node representing a power manageme 83 device-tree node representing a power management unit of a chipset and the
84 consumer driver controls one of its modules, t 84 consumer driver controls one of its modules, the provider driver may parse the
85 relevant regulator supply properties in device 85 relevant regulator supply properties in device tree and see if they lead from
86 the PMU to the consumer. 86 the PMU to the consumer.
87 87
88 API reference 88 API reference
89 ============= 89 =============
90 90
91 .. kernel-doc:: include/linux/pwrseq/provider. 91 .. kernel-doc:: include/linux/pwrseq/provider.h
92 :internal: 92 :internal:
93 93
94 .. kernel-doc:: drivers/power/sequencing/core. 94 .. kernel-doc:: drivers/power/sequencing/core.c
95 :export: 95 :export:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.