tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: add a driver API doc for the power sequencing subsystem
Describe what the subsystem does, how the consumers and providers work
and add API reference generated from kerneldocs.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240821100818.13763-1-brgl@bgdev.pl
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
+97
+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