mirror of
https://github.com/torvalds/linux.git
synced 2026-10-08 11:36:02 +02:00
d51fc9d4cd
The way power sequencing works means that a call to pwrseq_power_on() does not necessarily result in the pwrseq target being powered-on at that time: it may have already been powered on before. Similarly: a call to pwrseq_power_off() does not have to result in an actual powering off of resources: there may still be other users that requested a power-on before. We will also introduce the concept of "non-controllable" pwrseq targets soon which further increases the disconnect between the naming convention and the actual semantics. What consumers of pwrseq descriptors actually do is: they *vote* for a powering on of a given target or retract that vote. These operations could be called get/put in line with runtime PM but this could become confusing since we already provide pwrseq_get/put() for a different purpose. pwrseq_vote_on/off() also have been rejected as unusual in the tree. Change the name of the two functions to pwrseq_enable/disable() which better reflects their purpose and semantics and also mirrors other enable-counted resources like regulators and clocks. No functional change intended. If at any point users need to know *when* the exact power event happens, we can provide that information in the form of a notifier. Acked-by: Jeff Johnson <jeff.johnson@oss.qualcomm.com> Acked-by: Bjorn Helgaas <bhelgaas@google.com> Acked-by: Manivannan Sadhasivam <manivannan.sadhasivam@oss.qualcomm.com> Acked-by: Alessio Belle <alessio.belle@imgtec.com> # imagination Link: https://patch.msgid.link/20260731-pwrseq-vote-rename-v3-1-44e60b8be053@oss.qualcomm.com Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>
96 lines
3.6 KiB
ReStructuredText
96 lines
3.6 KiB
ReStructuredText
.. 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 discrete 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_enable(). The descriptor can be released by calling pwrseq_put() and
|
|
the consumer can request the powering down of its target with
|
|
pwrseq_disable(). Note that there is no guarantee that pwrseq_disable()
|
|
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 discrete 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:
|