linux-sh.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Rafael J. Wysocki" <rafael@kernel.org>
To: Dmitry Osipenko <digetx@gmail.com>
Cc: "Thierry Reding" <thierry.reding@gmail.com>,
	"Jonathan Hunter" <jonathanh@nvidia.com>,
	"Lee Jones" <lee.jones@linaro.org>,
	"Rafael J . Wysocki" <rafael@kernel.org>,
	"Mark Brown" <broonie@kernel.org>,
	"Andrew Morton" <akpm@linux-foundation.org>,
	"Guenter Roeck" <linux@roeck-us.net>,
	"Russell King" <linux@armlinux.org.uk>,
	"Daniel Lezcano" <daniel.lezcano@linaro.org>,
	"Andy Shevchenko" <andriy.shevchenko@linux.intel.com>,
	"Ulf Hansson" <ulf.hansson@linaro.org>,
	"Catalin Marinas" <catalin.marinas@arm.com>,
	"Will Deacon" <will@kernel.org>, "Guo Ren" <guoren@kernel.org>,
	"Geert Uytterhoeven" <geert@linux-m68k.org>,
	"Greg Ungerer" <gerg@linux-m68k.org>,
	"Joshua Thompson" <funaho@jurai.org>,
	"Thomas Bogendoerfer" <tsbogend@alpha.franken.de>,
	"Greentime Hu" <green.hu@gmail.com>,
	"Vincent Chen" <deanbo422@gmail.com>,
	"James E.J. Bottomley" <James.Bottomley@hansenpartnership.com>,
	"Helge Deller" <deller@gmx.de>,
	"Michael Ellerman" <mpe@ellerman.id.au>,
	"Benjamin Herrenschmidt" <benh@kernel.crashing.org>,
	"Paul Mackerras" <paulus@samba.org>,
	"Paul Walmsley" <paul.walmsley@sifive.com>,
	"Palmer Dabbelt" <palmer@dabbelt.com>,
	"Albert Ou" <aou@eecs.berkeley.edu>,
	"Yoshinori Sato" <ysato@users.sourceforge.jp>,
	"Rich Felker" <dalias@libc.org>,
	"Thomas Gleixner" <tglx@linutronix.de>,
	"Ingo Molnar" <mingo@redhat.com>,
	"Borislav Petkov" <bp@alien8.de>,
	"Dave Hansen" <dave.hansen@linux.intel.com>,
	"the arch/x86 maintainers" <x86@kernel.org>,
	"H. Peter Anvin" <hpa@zytor.com>,
	"Boris Ostrovsky" <boris.ostrovsky@oracle.com>,
	"Juergen Gross" <jgross@suse.com>,
	"Stefano Stabellini" <sstabellini@kernel.org>,
	"Len Brown" <lenb@kernel.org>,
	"Santosh Shilimkar" <ssantosh@kernel.org>,
	"Krzysztof Kozlowski" <krzysztof.kozlowski@canonical.com>,
	"Linus Walleij" <linus.walleij@linaro.org>,
	"Chen-Yu Tsai" <wens@csie.org>,
	"Jonathan Neuschäfer" <j.neuschaefer@gmx.net>,
	"Tony Lindgren" <tony@atomide.com>,
	"Liam Girdwood" <lgirdwood@gmail.com>,
	"Philipp Zabel" <p.zabel@pengutronix.de>,
	"Vladimir Zapolskiy" <vz@mleia.com>,
	"Avi Fishman" <avifishman70@gmail.com>,
	"Tomer Maimon" <tmaimon77@gmail.com>,
	"Tali Perry" <tali.perry1@gmail.com>,
	"Patrick Venture" <venture@google.com>,
	"Nancy Yuen" <yuenn@google.com>,
	"Benjamin Fair" <benjaminfair@google.com>,
	"Pavel Machek" <pavel@ucw.cz>,
	"Linux ARM" <linux-arm-kernel@lists.infradead.org>,
	"Linux Kernel Mailing List" <linux-kernel@vger.kernel.org>,
	linux-csky@vger.kernel.org, linux-ia64@vger.kernel.org,
	linux-m68k@lists.linux-m68k.org, linux-mips@vger.kernel.org,
	linux-parisc@vger.kernel.org,
	linuxppc-dev <linuxppc-dev@lists.ozlabs.org>,
	linux-riscv@lists.infradead.org,
	"Linux-sh list" <linux-sh@vger.kernel.org>,
	xen-devel@lists.xenproject.org,
	"ACPI Devel Maling List" <linux-acpi@vger.kernel.org>,
	"Linux OMAP Mailing List" <linux-omap@vger.kernel.org>,
	openbmc@lists.ozlabs.org,
	linux-tegra <linux-tegra@vger.kernel.org>,
	"Linux PM" <linux-pm@vger.kernel.org>
Subject: Re: [PATCH v2 08/45] kernel: Add combined power-off+restart handler call chain API
Date: Thu, 28 Oct 2021 11:59:18 +0200	[thread overview]
Message-ID: <CAJZ5v0gpu2ezMhWr=grg6M8aWAx58DQozbXHoZaiPqUaZxJi4Q@mail.gmail.com> (raw)
In-Reply-To: <20211027211715.12671-9-digetx@gmail.com>

On Wed, Oct 27, 2021 at 11:18 PM Dmitry Osipenko <digetx@gmail.com> wrote:
>
> SoC platforms often have multiple options of how to perform system's
> power-off and restart operations. Meanwhile today's kernel is limited to
> a single option. Add combined power-off+restart handler call chain API,
> which is inspired by the restart API. The new API provides both power-off
> and restart functionality.
>
> The old pm_power_off method will be kept around till all users are
> converted to the new API.
>
> Current restart API will be replaced by the new unified API since
> new API is its superset. The restart functionality of the power-handler
> API is built upon the existing restart-notifier APIs.
>
> In order to ease conversion to the new API, convenient helpers are added
> for the common use-cases. They will reduce amount of boilerplate code and
> remove global variables. These helpers preserve old behaviour for cases
> where only one power-off handler is executed, this is what existing
> drivers want, and thus, they could be easily converted to the new API.
> Users of the new API should explicitly enable power-off chaining by
> setting corresponding flag of the power_handler structure.
>
> Signed-off-by: Dmitry Osipenko <digetx@gmail.com>
> ---
>  include/linux/reboot.h   | 176 +++++++++++-
>  kernel/power/hibernate.c |   2 +-
>  kernel/reboot.c          | 601 ++++++++++++++++++++++++++++++++++++++-
>  3 files changed, 768 insertions(+), 11 deletions(-)
>
> diff --git a/include/linux/reboot.h b/include/linux/reboot.h
> index b7fa25726323..0ec835338c27 100644
> --- a/include/linux/reboot.h
> +++ b/include/linux/reboot.h
> @@ -8,10 +8,16 @@
>
>  struct device;
>
> -#define SYS_DOWN       0x0001  /* Notify of system down */
> -#define SYS_RESTART    SYS_DOWN
> -#define SYS_HALT       0x0002  /* Notify of system halt */
> -#define SYS_POWER_OFF  0x0003  /* Notify of system power off */
> +enum reboot_prepare_mode {
> +       SYS_DOWN = 1,           /* Notify of system down */
> +       SYS_RESTART = SYS_DOWN,
> +       SYS_HALT,               /* Notify of system halt */
> +       SYS_POWER_OFF,          /* Notify of system power off */
> +};
> +
> +#define RESTART_PRIO_RESERVED          0
> +#define RESTART_PRIO_DEFAULT           128
> +#define RESTART_PRIO_HIGH              192
>
>  enum reboot_mode {
>         REBOOT_UNDEFINED = -1,
> @@ -49,6 +55,167 @@ int register_restart_handler(struct notifier_block *);
>  int unregister_restart_handler(struct notifier_block *);
>  void do_kernel_restart(char *cmd);
>
> +/*
> + * Unified poweroff + restart API.
> + */
> +
> +#define POWEROFF_PRIO_RESERVED         0
> +#define POWEROFF_PRIO_PLATFORM         1
> +#define POWEROFF_PRIO_DEFAULT          128
> +#define POWEROFF_PRIO_HIGH             192
> +#define POWEROFF_PRIO_FIRMWARE         224

Also I'm wondering why these particular numbers were chosen, here and above?

> +
> +enum poweroff_mode {
> +       POWEROFF_NORMAL = 0,
> +       POWEROFF_PREPARE,
> +};
> +
> +struct power_off_data {
> +       void *cb_data;
> +};
> +
> +struct power_off_prep_data {
> +       void *cb_data;
> +};
> +
> +struct restart_data {
> +       void *cb_data;
> +       const char *cmd;
> +       enum reboot_mode mode;
> +};
> +
> +struct reboot_prep_data {
> +       void *cb_data;
> +       const char *cmd;
> +       enum reboot_prepare_mode mode;
> +};
> +
> +struct power_handler_private_data {
> +       struct notifier_block reboot_prep_nb;
> +       struct notifier_block power_off_nb;
> +       struct notifier_block restart_nb;
> +       void (*trivial_power_off_cb)(void);
> +       void (*simple_power_off_cb)(void *data);
> +       void *simple_power_off_cb_data;
> +       bool registered;
> +};
> +
> +/**
> + * struct power_handler - Machine power-off + restart handler
> + *
> + * Describes power-off and restart handlers which are invoked by kernel
> + * to power off or restart this machine.  Supports prioritized chaining for
> + * both restart and power-off handlers.  Callback's priority must be unique.
> + * Intended to be used by device drivers that are responsible for restarting
> + * and powering off hardware which kernel is running on.
> + *
> + * Struct power_handler can be static.  Members of this structure must not be
> + * altered while handler is registered.
> + *
> + * Fill the structure members and pass it to register_power_handler().
> + */
> +struct power_handler {
> +       /**
> +        * @cb_data:
> +        *
> +        * User data included in callback's argument.
> +        */

And here I would document the structure fields in the main kerneldoc
comment above.

As is, it is a bit hard to grasp the whole definition.

> +       void *cb_data;
> +
> +       /**
> +        * @power_off_cb:
> +        *
> +        * Callback that should turn off machine.  Inactive if NULL.
> +        */
> +       void (*power_off_cb)(struct power_off_data *data);
> +
> +       /**
> +        * @power_off_prepare_cb:
> +        *
> +        * Power-off preparation callback.  All power-off preparation callbacks
> +        * are invoked before @restart_cb.  Inactive if NULL.
> +        */
> +       void (*power_off_prepare_cb)(struct power_off_prep_data *data);
> +
> +       /**
> +        * @power_off_priority:
> +        *
> +        * Power-off callback priority, must be unique.  Zero value is
> +        * reassigned to default priority.  Inactive if @power_off_cb is NULL.
> +        */
> +       int power_off_priority;
> +
> +       /**
> +        * @power_off_chaining_allowed:
> +        *
> +        * False if callbacks execution should stop when @power_off_cb fails
> +        * to power off machine.  True if further lower priority power-off
> +        * callback should be executed.
> +        */
> +       bool power_off_chaining_allowed;
> +
> +       /**
> +        * @restart_cb:
> +        *
> +        * Callback that should reboot machine.  Inactive if NULL.
> +        */
> +       void (*restart_cb)(struct restart_data *data);
> +
> +       /**
> +        * @restart_priority:
> +        *
> +        * Restart callback priority, must be unique.  Zero value is reassigned
> +        * to default priority.  Inactive if @restart_cb is NULL.
> +        */
> +       int restart_priority;
> +
> +       /**
> +        * @reboot_prepare_cb:
> +        *
> +        * Reboot preparation callback.  All reboot preparation callbacks are
> +        * invoked before @restart_cb.  Inactive if NULL.
> +        */
> +       void (*reboot_prepare_cb)(struct reboot_prep_data *data);
> +
> +       /**
> +        * @priv:
> +        *
> +        * Internal data.  Shouldn't be touched.
> +        */
> +       const struct power_handler_private_data priv;
> +};

  parent reply	other threads:[~2021-10-28  9:59 UTC|newest]

Thread overview: 71+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-27 21:16 [PATCH v2 00/45] Introduce power-off+restart call chain API Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 01/45] notifier: Remove extern annotation from function prototypes Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 02/45] notifier: Add blocking_notifier_call_chain_empty() Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 03/45] notifier: Add atomic/blocking_notifier_has_unique_priority() Dmitry Osipenko
2021-10-28 11:00   ` Andy Shevchenko
2021-10-28 21:32     ` Dmitry Osipenko
2021-10-28 23:28       ` Dmitry Osipenko
2021-10-28 22:10     ` Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 04/45] reboot: Correct typo in a comment Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 05/45] reboot: Warn if restart handler has duplicated priority Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 06/45] reboot: Warn if unregister_restart_handler() fails Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 07/45] reboot: Remove extern annotation from function prototypes Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 08/45] kernel: Add combined power-off+restart handler call chain API Dmitry Osipenko
2021-10-28  9:53   ` Rafael J. Wysocki
2021-10-28 21:36     ` Dmitry Osipenko
2021-10-28  9:59   ` Rafael J. Wysocki [this message]
2021-10-28 21:58     ` Dmitry Osipenko
2021-10-28 21:59     ` Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 09/45] xen/x86: Use do_kernel_power_off() Dmitry Osipenko
2021-10-28  7:35   ` Juergen Gross
2021-10-27 21:16 ` [PATCH v2 10/45] ARM: " Dmitry Osipenko
2021-10-28 12:04   ` Russell King (Oracle)
2021-10-27 21:16 ` [PATCH v2 11/45] arm64: " Dmitry Osipenko
2021-11-01 13:28   ` Catalin Marinas
2021-10-27 21:16 ` [PATCH v2 12/45] csky: " Dmitry Osipenko
2021-11-01  1:57   ` Guo Ren
2021-10-27 21:16 ` [PATCH v2 13/45] ia64: " Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 14/45] mips: " Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 15/45] nds32: " Dmitry Osipenko
2021-10-28 12:20   ` Greentime Hu
2021-10-27 21:16 ` [PATCH v2 16/45] parisc: " Dmitry Osipenko
2021-10-28  6:38   ` Helge Deller
2021-10-27 21:16 ` [PATCH v2 17/45] powerpc: " Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 18/45] riscv: " Dmitry Osipenko
2021-10-27 23:09   ` Palmer Dabbelt
2021-10-27 21:16 ` [PATCH v2 19/45] sh: " Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 20/45] x86: " Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 21/45] m68k: Switch to new power-handler API Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 22/45] memory: emif: Use kernel_can_power_off() Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 23/45] ACPI: power: Switch to power-handler API Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 24/45] regulator: pfuze100: Use devm_register_power_handler() Dmitry Osipenko
2021-10-28 11:59   ` Mark Brown
2021-10-27 21:16 ` [PATCH v2 25/45] reboot: Remove pm_power_off_prepare() Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 26/45] soc/tegra: pmc: Utilize power-handler API to power off Nexus 7 properly Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 27/45] mfd: ntxec: Use devm_register_power_handler() Dmitry Osipenko
2021-11-06 20:54   ` Jonathan Neuschäfer
2021-11-07 16:53     ` Dmitry Osipenko
2021-11-07 17:08       ` Guenter Roeck
2021-11-07 17:16         ` Dmitry Osipenko
2021-11-07 17:32           ` Guenter Roeck
2021-11-07 17:42             ` Dmitry Osipenko
2021-11-08 11:22               ` Jonathan Neuschäfer
2021-11-08 11:36                 ` Dmitry Osipenko
2021-11-10 10:43                   ` Jonathan Neuschäfer
2021-11-10 13:38                     ` Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 28/45] mfd: rn5t618: " Dmitry Osipenko
2021-11-29 11:55   ` Lee Jones
2021-11-29 12:04     ` Dmitry Osipenko
2021-10-27 21:16 ` [PATCH v2 29/45] mfd: acer-a500: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 30/45] mfd: ene-kb3930: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 31/45] mfd: axp20x: Use register_simple_power_off_handler() Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 32/45] mfd: retu: Use devm_register_simple_power_off_handler() Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 33/45] mfd: rk808: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 34/45] mfd: palmas: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 35/45] mfd: max8907: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 36/45] mfd: tps6586x: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 37/45] mfd: tps65910: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 38/45] mfd: max77620: " Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 39/45] mfd: dm355evm_msp: Use devm_register_trivial_power_off_handler() Dmitry Osipenko
2021-10-27 21:17 ` [PATCH v2 40/45] mfd: twl4030: " Dmitry Osipenko
2021-10-28 22:05 ` [PATCH v2 00/45] Introduce power-off+restart call chain API Dmitry Osipenko

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAJZ5v0gpu2ezMhWr=grg6M8aWAx58DQozbXHoZaiPqUaZxJi4Q@mail.gmail.com' \
    --to=rafael@kernel.org \
    --cc=James.Bottomley@hansenpartnership.com \
    --cc=akpm@linux-foundation.org \
    --cc=andriy.shevchenko@linux.intel.com \
    --cc=aou@eecs.berkeley.edu \
    --cc=avifishman70@gmail.com \
    --cc=benh@kernel.crashing.org \
    --cc=benjaminfair@google.com \
    --cc=boris.ostrovsky@oracle.com \
    --cc=bp@alien8.de \
    --cc=broonie@kernel.org \
    --cc=catalin.marinas@arm.com \
    --cc=dalias@libc.org \
    --cc=daniel.lezcano@linaro.org \
    --cc=dave.hansen@linux.intel.com \
    --cc=deanbo422@gmail.com \
    --cc=deller@gmx.de \
    --cc=digetx@gmail.com \
    --cc=funaho@jurai.org \
    --cc=geert@linux-m68k.org \
    --cc=gerg@linux-m68k.org \
    --cc=green.hu@gmail.com \
    --cc=guoren@kernel.org \
    --cc=hpa@zytor.com \
    --cc=j.neuschaefer@gmx.net \
    --cc=jgross@suse.com \
    --cc=jonathanh@nvidia.com \
    --cc=krzysztof.kozlowski@canonical.com \
    --cc=lee.jones@linaro.org \
    --cc=lenb@kernel.org \
    --cc=lgirdwood@gmail.com \
    --cc=linus.walleij@linaro.org \
    --cc=linux-acpi@vger.kernel.org \
    --cc=linux-arm-kernel@lists.infradead.org \
    --cc=linux-csky@vger.kernel.org \
    --cc=linux-ia64@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-m68k@lists.linux-m68k.org \
    --cc=linux-mips@vger.kernel.org \
    --cc=linux-omap@vger.kernel.org \
    --cc=linux-parisc@vger.kernel.org \
    --cc=linux-pm@vger.kernel.org \
    --cc=linux-riscv@lists.infradead.org \
    --cc=linux-sh@vger.kernel.org \
    --cc=linux-tegra@vger.kernel.org \
    --cc=linux@armlinux.org.uk \
    --cc=linux@roeck-us.net \
    --cc=linuxppc-dev@lists.ozlabs.org \
    --cc=mingo@redhat.com \
    --cc=mpe@ellerman.id.au \
    --cc=openbmc@lists.ozlabs.org \
    --cc=p.zabel@pengutronix.de \
    --cc=palmer@dabbelt.com \
    --cc=paul.walmsley@sifive.com \
    --cc=paulus@samba.org \
    --cc=pavel@ucw.cz \
    --cc=ssantosh@kernel.org \
    --cc=sstabellini@kernel.org \
    --cc=tali.perry1@gmail.com \
    --cc=tglx@linutronix.de \
    --cc=thierry.reding@gmail.com \
    --cc=tmaimon77@gmail.com \
    --cc=tony@atomide.com \
    --cc=tsbogend@alpha.franken.de \
    --cc=ulf.hansson@linaro.org \
    --cc=venture@google.com \
    --cc=vz@mleia.com \
    --cc=wens@csie.org \
    --cc=will@kernel.org \
    --cc=x86@kernel.org \
    --cc=xen-devel@lists.xenproject.org \
    --cc=ysato@users.sourceforge.jp \
    --cc=yuenn@google.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).