On Wed, Oct 27, 2021 at 11:18 PM Dmitry Osipenko <digetx@xxxxxxxxx> 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@xxxxxxxxx>
---
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;
+};
