[PATCH v5 00/21] Introduce power-off+restart call chain API

Dmitry Osipenko
2021-12-12T21:21:06Z

Problem
-------

SoC devices require power-off call chaining functionality from kernel.
We have a widely used restart chaining provided by restart notifier API,
but nothing for power-off.

Solution
--------

Introduce new API that provides both restart and power-off call chains.

Why combine restart with power-off? Because drivers often do both.
More practical to have API that provides both under the same roof.

The new API is designed with simplicity and extensibility in mind.
It's built upon the existing restart and reboot APIs. The simplicity
is in new helper functions that are convenient for drivers. The
extensibility is in the design that doesn't hardcode callback
arguments, making easy to add new parameters and remove old.

This is a third attempt to introduce the new API. First was made by
Guenter Roeck back in 2014, second was made by Thierry Reding in 2017.
In fact the work didn't stop and recently arm_pm_restart() was removed
from v5.14 kernel, which was a part of preparatory work started by
Guenter Roeck. I took into account experience and ideas from the
previous attempts, extended and polished them.

Adoption plan
-------------

This patchset introduces the new API. It also converts multiple drivers
and arch code to the new API to demonstrate how it all looks in practice.

The plan is:

1. Merge new API (patches 1-8). This API will co-exist with the old APIs.

2. Convert arch code to do_kernel_power_off() (patches 9-21).

3. Convert drivers and platform code to the new API.

4. Remove obsolete pm_power_off and pm_power_off_prepare variables.

5. Make restart-notifier API private to kernel/reboot.c once no users left.

6. Make uniqueness of the handlers' priority a mandatory requirement.

It's fully implemented here:

[1] https://github.com/grate-driver/linux/commits/sys-off-handler

For now I'm sending only the first 25 base patches out of ~180. It's
preferable to squash 1-2, partially 3 and 4 points of the plan into a
single patchset to ease and speed up applying of the rest of the patches.
Majority of drivers and platform patches depend on the base, hence they
will come later (and per subsystem), once base will land.

All [1] patches are compile-tested. Tegra and x86 ACPI patches are tested
on hardware. The remaining should be covered by unit tests (unpublished).

Results
-------

1. Devices can be powered off properly.

2. Global variables are removed from drivers.

3. Global pm_power_off and pm_power_off_prepare callback variables are
removed once all users are converted to the new API. The latter callback
is removed by patch #25 of this series.

4. Ambiguous call chain ordering is prohibited. See patch #5 which adds
verification of restart handlers priorities, ensuring that they are unique.

Changelog:

v5: - Dropped patches which cleaned up notifier/reboot headers, as was
requested by Rafael Wysocki.

- Dropped WARN_ON() from the code, as was requested by Rafael Wysocki.
Replaced it with pr_err() appropriately.

- Dropped *_notifier_has_unique_priority() functions and added
*_notifier_chain_register_unique_prio() instead, as was suggested
by Michał Mirosław and Rafael Wysocki.

- Dropped export of blocking_notifier_call_chain_is_empty() symbol,
as was suggested by Rafael Wysocki.

- Michał Mirosław suggested that will be better to split up patch
that adds the new API to ease reviewing, but Rafael Wysocki asked
not add more patches, so I kept it as a single patch.

- Added temporary "weak" stub for pm_power_off() which fixes linkage
failure once symbol is removed from arch/* code. Previously I missed
this problem because was only compile-testing object files.

v4: - Made a very minor improvement to doc comments, clarifying couple
default values.

- Corrected list of emails recipient by adding Linus, Sebastian,
Philipp and more NDS people. Removed bouncing emails.

- Added acks that were given to v3.

v3: - Renamed power_handler to sys_off_handler as was suggested by
Rafael Wysocki.

- Improved doc-comments as was suggested by Rafael Wysocki. Added more
doc-comments.

- Implemented full set of 180 patches which convert whole kernel in
accordance to the plan, see link [1] above. Slightly adjusted API to
better suit for the remaining converted drivers.

* Added unregister_sys_off_handler() that is handy for a couple old
platform drivers.

* Dropped devm_register_trivial_restart_handler(), 'simple' variant
is enough to have.

- Improved "Add atomic/blocking_notifier_has_unique_priority()" patch,
as was suggested by Andy Shevchenko. Also replaced down_write() with
down_read() and factored out common notifier_has_unique_priority().

- Added stop_chain field to struct restart_data and reboot_prep_data
after discovering couple drivers wanting that feature.

- Added acks that were given to v2.

v2: - Replaced standalone power-off call chain demo-API with the combined
power-off+restart API because this is what drivers want. It's a more
comprehensive solution.

- Converted multiple drivers and arch code to the new API. Suggested by
Andy Shevchenko. I skimmed through the rest of drivers, verifying that
new API suits them. The rest of the drivers will be converted once we
will settle on the new API, otherwise will be too many patches here.

- v2 API doesn't expose notifier to users and require handlers to
have unique priority. Suggested by Guenter Roeck.

- v2 API has power-off chaining disabled by default and require
drivers to explicitly opt-in to the chaining. This preserves old
behaviour for existing drivers once they are converted to the new
API.

Dmitry Osipenko (21):
notifier: Add blocking_notifier_call_chain_is_empty()
notifier: Add atomic/blocking_notifier_chain_register_unique_prio()
reboot: Print error message if restart handler has duplicated priority
kernel: Add combined power-off+restart handler call chain API
ARM: Use do_kernel_power_off()
csky: Use do_kernel_power_off()
riscv: Use do_kernel_power_off()
arm64: Use do_kernel_power_off()
parisc: Use do_kernel_power_off()
xen/x86: Use do_kernel_power_off()
powerpc: Use do_kernel_power_off()
m68k: Switch to new sys-off handler API
sh: Use do_kernel_power_off()
x86: Use do_kernel_power_off()
ia64: Use do_kernel_power_off()
mips: Use do_kernel_power_off()
nds32: Use do_kernel_power_off()
memory: emif: Use kernel_can_power_off()
ACPI: power: Switch to sys-off handler API
regulator: pfuze100: Use devm_register_sys_off_handler()
reboot: Remove pm_power_off_prepare()

arch/arm/kernel/reboot.c | 4 +-
arch/arm64/kernel/process.c | 3 +-
arch/csky/kernel/power.c | 6 +-
arch/ia64/kernel/process.c | 4 +-
arch/m68k/emu/natfeat.c | 3 +-
arch/m68k/include/asm/machdep.h | 1 -
arch/m68k/kernel/process.c | 5 +-
arch/m68k/kernel/setup_mm.c | 1 -
arch/m68k/kernel/setup_no.c | 1 -
arch/m68k/mac/config.c | 4 +-
arch/mips/kernel/reset.c | 3 +-
arch/nds32/kernel/process.c | 3 +-
arch/parisc/kernel/process.c | 4 +-
arch/powerpc/kernel/setup-common.c | 4 +-
arch/powerpc/xmon/xmon.c | 3 +-
arch/riscv/kernel/reset.c | 12 +-
arch/sh/kernel/reboot.c | 3 +-
arch/x86/kernel/reboot.c | 4 +-
arch/x86/xen/enlighten_pv.c | 4 +-
drivers/acpi/sleep.c | 25 +-
drivers/memory/emif.c | 2 +-
drivers/regulator/pfuze100-regulator.c | 38 +-
include/linux/notifier.h | 7 +
include/linux/pm.h | 1 -
include/linux/reboot.h | 265 +++++++++++-
kernel/notifier.c | 100 ++++-
kernel/power/hibernate.c | 2 +-
kernel/reboot.c | 574 ++++++++++++++++++++++++-
28 files changed, 968 insertions(+), 118 deletions(-)

--
2.33.1