hw: Define new device_class_set_legacy_reset()

Define a device_class_set_legacy_reset() function which
sets the DeviceClass::reset field. This serves two purposes:
 * it makes it clearer to the person writing code that
   DeviceClass::reset is now legacy and they should look for
   the new alternative (which is Resettable)
 * it makes it easier to rename the reset field (which in turn
   makes it easier to find places that call it)

The Coccinelle script can be used to automatically convert code that
was doing an open-coded assignment to DeviceClass::reset to call
device_class_set_legacy_reset() instead.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20240830145812.1967042-7-peter.maydell@linaro.org

3 files changed, 48 insertions, 0 deletions

diff --git a/hw/core/qdev.c b/hw/core/qdev.c
index cf81158..5182785 100644
--- a/hw/core/qdev.c
+++ b/hw/core/qdev.c
@@ -844,6 +844,11 @@ static void device_class_init(ObjectClass *class, void *data)
                                    offsetof(DeviceState, parent_bus), NULL, 0);
 }
 
+void device_class_set_legacy_reset(DeviceClass *dc, DeviceReset dev_reset)
+{
+    dc->reset = dev_reset;
+}
+
 void device_class_set_parent_realize(DeviceClass *dc,
                                      DeviceRealize dev_realize,
                                      DeviceRealize *parent_realize)
diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h
index 18c7845..ade85c3 100644
--- a/include/hw/qdev-core.h
+++ b/include/hw/qdev-core.h
@@ -953,6 +953,19 @@ void device_class_set_parent_realize(DeviceClass *dc,
                                      DeviceRealize dev_realize,
                                      DeviceRealize *parent_realize);
 
+/**
+ * device_class_set_legacy_reset(): set the DeviceClass::reset method
+ * @dc: The device class
+ * @dev_reset: the reset function
+ *
+ * This function sets the DeviceClass::reset method. This is widely
+ * used in existing code, but new code should prefer to use the
+ * Resettable API as documented in docs/devel/reset.rst.
+ * In addition, devices which need to chain to their parent class's
+ * reset methods or which need to be subclassed must use Resettable.
+ */
+void device_class_set_legacy_reset(DeviceClass *dc,
+                                   DeviceReset dev_reset);
 
 /**
  * device_class_set_parent_unrealize() - set up for chaining unrealize fns
diff --git a/scripts/coccinelle/device-reset.cocci b/scripts/coccinelle/device-reset.cocci
new file mode 100644
index 0000000..510042a
--- /dev/null
+++ b/scripts/coccinelle/device-reset.cocci
@@ -0,0 +1,30 @@
+// Convert opencoded DeviceClass::reset assignments to calls to
+// device_class_set_legacy_reset()
+//
+// Copyright Linaro Ltd 2024
+// This work is licensed under the terms of the GNU GPLv2 or later.
+//
+// spatch --macro-file scripts/cocci-macro-file.h \
+//        --sp-file scripts/coccinelle/device-reset.cocci \
+//        --keep-comments --smpl-spacing --in-place --include-headers --dir hw
+//
+// For simplicity we assume some things about the code we're modifying
+// that happen to be true for all our targets:
+//  * all cpu_class_set_parent_reset() callsites have a 'DeviceClass *dc' local
+//  * the parent reset field in the target CPU class is 'parent_reset'
+//  * no reset function already has a 'dev' local
+
+@@
+identifier dc, resetfn;
+@@
+  DeviceClass *dc;
+  ...
+- dc->reset = resetfn;
++ device_class_set_legacy_reset(dc, resetfn);
+@@
+identifier dc, resetfn;
+@@
+  DeviceClass *dc;
+  ...
+- dc->reset = &resetfn;
++ device_class_set_legacy_reset(dc, resetfn);