96 lines · plain
1.. SPDX-License-Identifier: GPL-2.0-only2.. Copyright 2024 Linaro Ltd.3 4====================5Power Sequencing API6====================7 8:Author: Bartosz Golaszewski9 10Introduction11============12 13This framework is designed to abstract complex power-up sequences that are14shared between multiple logical devices in the linux kernel.15 16The intention is to allow consumers to obtain a power sequencing handle17exposed by the power sequence provider and delegate the actual requesting and18control of the underlying resources as well as to allow the provider to19mitigate any potential conflicts between multiple users behind the scenes.20 21Glossary22--------23 24The power sequencing API uses a number of terms specific to the subsystem:25 26Unit27 28 A unit is a discreet chunk of a power sequence. For instance one unit may29 enable a set of regulators, another may enable a specific GPIO. Units can30 define dependencies in the form of other units that must be enabled before31 it itself can be.32 33Target34 35 A target is a set of units (composed of the "final" unit and its36 dependencies) that a consumer selects by its name when requesting a handle37 to the power sequencer. Via the dependency system, multiple targets may38 share the same parts of a power sequence but ignore parts that are39 irrelevant.40 41Descriptor42 43 A handle passed by the pwrseq core to every consumer that serves as the44 entry point to the provider layer. It ensures coherence between different45 users and keeps reference counting consistent.46 47Consumer interface48==================49 50The consumer API is aimed to be as simple as possible. The driver interested in51getting a descriptor from the power sequencer should call pwrseq_get() and52specify the name of the target it wants to reach in the sequence after calling53pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and54the consumer can request the powering down of its target with55pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off()56will have any effect as there may be multiple users of the underlying resources57who may keep them active.58 59Provider interface60==================61 62The provider API is admittedly not nearly as straightforward as the one for63consumers but it makes up for it in flexibility.64 65Each provider can logically split the power-up sequence into descrete chunks66(units) and define their dependencies. They can then expose named targets that67consumers may use as the final point in the sequence that they wish to reach.68 69To that end the providers fill out a set of configuration structures and70register with the pwrseq subsystem by calling pwrseq_device_register().71 72Dynamic consumer matching73-------------------------74 75The main difference between pwrseq and other linux kernel providers is the76mechanism for dynamic matching of consumers and providers. Every power sequence77provider driver must implement the `match()` callback and pass it to the pwrseq78core when registering with the subsystems.79 80When a client requests a sequencer handle, the core will call this callback for81every registered provider and let it flexibly figure out whether the proposed82client device is indeed its consumer. For example: if the provider binds to the83device-tree node representing a power management unit of a chipset and the84consumer driver controls one of its modules, the provider driver may parse the85relevant regulator supply properties in device tree and see if they lead from86the PMU to the consumer.87 88API reference89=============90 91.. kernel-doc:: include/linux/pwrseq/provider.h92 :internal:93 94.. kernel-doc:: drivers/power/sequencing/core.c95 :export:96