Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'pwrseq-updates-for-v6.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux
Pull power sequencing updates from Bartosz Golaszewski:
"There's one change adding support for a new PMU model and another
adding documentation for the subsystem which probably should have been
part of the initial commit but better late than never:
- add support for the new PMU variant inside the WCN6855 chipset
- add documentation for the subsystem"
* tag 'pwrseq-updates-for-v6.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux:
Documentation: add a driver API doc for the power sequencing subsystem
power: sequencing: qcom-wcn: add support for the WCN6855 PMU
+108
+1
Documentation/driver-api/index.rst
+1
Documentation/driver-api/index.rst
+95
Documentation/driver-api/pwrseq.rst
+95
Documentation/driver-api/pwrseq.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-only
2
+
.. Copyright 2024 Linaro Ltd.
3
+
4
+
====================
5
+
Power Sequencing API
6
+
====================
7
+
8
+
:Author: Bartosz Golaszewski
9
+
10
+
Introduction
11
+
============
12
+
13
+
This framework is designed to abstract complex power-up sequences that are
14
+
shared between multiple logical devices in the linux kernel.
15
+
16
+
The intention is to allow consumers to obtain a power sequencing handle
17
+
exposed by the power sequence provider and delegate the actual requesting and
18
+
control of the underlying resources as well as to allow the provider to
19
+
mitigate any potential conflicts between multiple users behind the scenes.
20
+
21
+
Glossary
22
+
--------
23
+
24
+
The power sequencing API uses a number of terms specific to the subsystem:
25
+
26
+
Unit
27
+
28
+
A unit is a discreet chunk of a power sequence. For instance one unit may
29
+
enable a set of regulators, another may enable a specific GPIO. Units can
30
+
define dependencies in the form of other units that must be enabled before
31
+
it itself can be.
32
+
33
+
Target
34
+
35
+
A target is a set of units (composed of the "final" unit and its
36
+
dependencies) that a consumer selects by its name when requesting a handle
37
+
to the power sequencer. Via the dependency system, multiple targets may
38
+
share the same parts of a power sequence but ignore parts that are
39
+
irrelevant.
40
+
41
+
Descriptor
42
+
43
+
A handle passed by the pwrseq core to every consumer that serves as the
44
+
entry point to the provider layer. It ensures coherence between different
45
+
users and keeps reference counting consistent.
46
+
47
+
Consumer interface
48
+
==================
49
+
50
+
The consumer API is aimed to be as simple as possible. The driver interested in
51
+
getting a descriptor from the power sequencer should call pwrseq_get() and
52
+
specify the name of the target it wants to reach in the sequence after calling
53
+
pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and
54
+
the consumer can request the powering down of its target with
55
+
pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()
56
+
will have any effect as there may be multiple users of the underlying resources
57
+
who may keep them active.
58
+
59
+
Provider interface
60
+
==================
61
+
62
+
The provider API is admittedly not nearly as straightforward as the one for
63
+
consumers but it makes up for it in flexibility.
64
+
65
+
Each provider can logically split the power-up sequence into descrete chunks
66
+
(units) and define their dependencies. They can then expose named targets that
67
+
consumers may use as the final point in the sequence that they wish to reach.
68
+
69
+
To that end the providers fill out a set of configuration structures and
70
+
register with the pwrseq subsystem by calling pwrseq_device_register().
71
+
72
+
Dynamic consumer matching
73
+
-------------------------
74
+
75
+
The main difference between pwrseq and other linux kernel providers is the
76
+
mechanism for dynamic matching of consumers and providers. Every power sequence
77
+
provider driver must implement the `match()` callback and pass it to the pwrseq
78
+
core when registering with the subsystems.
79
+
80
+
When a client requests a sequencer handle, the core will call this callback for
81
+
every registered provider and let it flexibly figure out whether the proposed
82
+
client device is indeed its consumer. For example: if the provider binds to the
83
+
device-tree node representing a power management unit of a chipset and the
84
+
consumer driver controls one of its modules, the provider driver may parse the
85
+
relevant regulator supply properties in device tree and see if they lead from
86
+
the PMU to the consumer.
87
+
88
+
API reference
89
+
=============
90
+
91
+
.. kernel-doc:: include/linux/pwrseq/provider.h
92
+
:internal:
93
+
94
+
.. kernel-doc:: drivers/power/sequencing/core.c
95
+
:export:
+1
MAINTAINERS
+1
MAINTAINERS
+11
drivers/power/sequencing/pwrseq-qcom-wcn.c
+11
drivers/power/sequencing/pwrseq-qcom-wcn.c
···
198
198
.gpio_enable_delay_ms = 100,
199
199
};
200
200
201
+
static const struct pwrseq_qcom_wcn_pdata pwrseq_wcn6855_of_data = {
202
+
.vregs = pwrseq_qca6390_vregs,
203
+
.num_vregs = ARRAY_SIZE(pwrseq_qca6390_vregs),
204
+
.pwup_delay_ms = 50,
205
+
.gpio_enable_delay_ms = 5,
206
+
};
207
+
201
208
static const char *const pwrseq_wcn7850_vregs[] = {
202
209
"vdd",
203
210
"vddio",
···
327
320
{
328
321
.compatible = "qcom,qca6390-pmu",
329
322
.data = &pwrseq_qca6390_of_data,
323
+
},
324
+
{
325
+
.compatible = "qcom,wcn6855-pmu",
326
+
.data = &pwrseq_wcn6855_of_data,
330
327
},
331
328
{
332
329
.compatible = "qcom,wcn7850-pmu",