mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-09-21 12:11:49 +08:00
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>
This commit is contained in:
parent
b8e4b0529d
commit
8b7e0a6c44
@ -124,6 +124,7 @@ Subsystem-specific APIs
|
||||
pps
|
||||
ptp
|
||||
pwm
|
||||
pwrseq
|
||||
regulator
|
||||
reset
|
||||
rfkill
|
||||
|
95
Documentation/driver-api/pwrseq.rst
Normal file
95
Documentation/driver-api/pwrseq.rst
Normal file
@ -0,0 +1,95 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0-only
|
||||
.. Copyright 2024 Linaro Ltd.
|
||||
|
||||
====================
|
||||
Power Sequencing API
|
||||
====================
|
||||
|
||||
:Author: Bartosz Golaszewski
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
This framework is designed to abstract complex power-up sequences that are
|
||||
shared between multiple logical devices in the linux kernel.
|
||||
|
||||
The intention is to allow consumers to obtain a power sequencing handle
|
||||
exposed by the power sequence provider and delegate the actual requesting and
|
||||
control of the underlying resources as well as to allow the provider to
|
||||
mitigate any potential conflicts between multiple users behind the scenes.
|
||||
|
||||
Glossary
|
||||
--------
|
||||
|
||||
The power sequencing API uses a number of terms specific to the subsystem:
|
||||
|
||||
Unit
|
||||
|
||||
A unit is a discreet chunk of a power sequence. For instance one unit may
|
||||
enable a set of regulators, another may enable a specific GPIO. Units can
|
||||
define dependencies in the form of other units that must be enabled before
|
||||
it itself can be.
|
||||
|
||||
Target
|
||||
|
||||
A target is a set of units (composed of the "final" unit and its
|
||||
dependencies) that a consumer selects by its name when requesting a handle
|
||||
to the power sequencer. Via the dependency system, multiple targets may
|
||||
share the same parts of a power sequence but ignore parts that are
|
||||
irrelevant.
|
||||
|
||||
Descriptor
|
||||
|
||||
A handle passed by the pwrseq core to every consumer that serves as the
|
||||
entry point to the provider layer. It ensures coherence between different
|
||||
users and keeps reference counting consistent.
|
||||
|
||||
Consumer interface
|
||||
==================
|
||||
|
||||
The consumer API is aimed to be as simple as possible. The driver interested in
|
||||
getting a descriptor from the power sequencer should call pwrseq_get() and
|
||||
specify the name of the target it wants to reach in the sequence after calling
|
||||
pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and
|
||||
the consumer can request the powering down of its target with
|
||||
pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()
|
||||
will have any effect as there may be multiple users of the underlying resources
|
||||
who may keep them active.
|
||||
|
||||
Provider interface
|
||||
==================
|
||||
|
||||
The provider API is admittedly not nearly as straightforward as the one for
|
||||
consumers but it makes up for it in flexibility.
|
||||
|
||||
Each provider can logically split the power-up sequence into descrete chunks
|
||||
(units) and define their dependencies. They can then expose named targets that
|
||||
consumers may use as the final point in the sequence that they wish to reach.
|
||||
|
||||
To that end the providers fill out a set of configuration structures and
|
||||
register with the pwrseq subsystem by calling pwrseq_device_register().
|
||||
|
||||
Dynamic consumer matching
|
||||
-------------------------
|
||||
|
||||
The main difference between pwrseq and other linux kernel providers is the
|
||||
mechanism for dynamic matching of consumers and providers. Every power sequence
|
||||
provider driver must implement the `match()` callback and pass it to the pwrseq
|
||||
core when registering with the subsystems.
|
||||
|
||||
When a client requests a sequencer handle, the core will call this callback for
|
||||
every registered provider and let it flexibly figure out whether the proposed
|
||||
client device is indeed its consumer. For example: if the provider binds to the
|
||||
device-tree node representing a power management unit of a chipset and the
|
||||
consumer driver controls one of its modules, the provider driver may parse the
|
||||
relevant regulator supply properties in device tree and see if they lead from
|
||||
the PMU to the consumer.
|
||||
|
||||
API reference
|
||||
=============
|
||||
|
||||
.. kernel-doc:: include/linux/pwrseq/provider.h
|
||||
:internal:
|
||||
|
||||
.. kernel-doc:: drivers/power/sequencing/core.c
|
||||
:export:
|
@ -18201,6 +18201,7 @@ M: Bartosz Golaszewski <brgl@bgdev.pl>
|
||||
L: linux-pm@vger.kernel.org
|
||||
S: Maintained
|
||||
T: git git://git.kernel.org/pub/scm/linux/kernel/git/brgl/linux.git
|
||||
F: Documentation/driver-api/pwrseq.rst
|
||||
F: drivers/power/sequencing/
|
||||
F: include/linux/pwrseq/
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user