Add the usual boilerplate license/copyright comment to reset.h (using
the text from reset.c), and document the existing functions.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 include/sysemu/reset.h | 79 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/include/sysemu/reset.h b/include/sysemu/reset.h
index 609e4d50c26..6aa11846a69 100644
--- a/include/sysemu/reset.h
+++ b/include/sysemu/reset.h
@@ -1,3 +1,29 @@
+/*
+ *  Reset handlers.
+ *
+ * Copyright (c) 2003-2008 Fabrice Bellard
+ * Copyright (c) 2016 Red Hat, Inc.
+ * Copyright (c) 2024 Linaro, Ltd.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
 #ifndef QEMU_SYSEMU_RESET_H
 #define QEMU_SYSEMU_RESET_H
 
@@ -5,9 +31,62 @@
 
 typedef void QEMUResetHandler(void *opaque);
 
+/**
+ * qemu_register_reset: Register a callback for system reset
+ * @func: function to call
+ * @opaque: opaque data to pass to @func
+ *
+ * Register @func on the list of functions which are called when the
+ * entire system is reset. The functions are called in the order in
+ * which they are registered.
+ *
+ * In general this function should not be used in new code where possible;
+ * for instance device model reset is better accomplished using the
+ * methods on DeviceState.
+ *
+ * It is not permitted to register or unregister reset functions from
+ * within the @func callback.
+ *
+ * We assume that the caller holds the BQL.
+ */
 void qemu_register_reset(QEMUResetHandler *func, void *opaque);
+
+/**
+ * qemu_register_reset_nosnapshotload: Register a callback for system reset
+ * @func: function to call
+ * @opaque: opaque data to pass to @func
+ *
+ * This is the same as qemu_register_reset(), except that @func is
+ * not called if the reason that the system is being reset is to
+ * put it into a clean state prior to loading a snapshot (i.e. for
+ * SHUTDOWN_CAUSE_SNAPSHOT_LOAD).
+ */
 void qemu_register_reset_nosnapshotload(QEMUResetHandler *func, void *opaque);
+
+/**
+ * qemu_unregister_reset: Unregister a system reset callback
+ * @func: function registered with qemu_register_reset()
+ * @opaque: the same opaque data that was passed to qemu_register_reset()
+ *
+ * Undo the effects of a qemu_register_reset(). The @func and @opaque
+ * must both match the arguments originally used with qemu_register_reset().
+ *
+ * We assume that the caller holds the BQL.
+ */
 void qemu_unregister_reset(QEMUResetHandler *func, void *opaque);
+
+/**
+ * qemu_devices_reset: Perform a complete system reset
+ * @reason: reason for the reset
+ *
+ * This function performs the low-level work needed to do a complete reset
+ * of the system (calling all the callbacks registered with
+ * qemu_register_reset()). It should only be called by the code in a
+ * MachineClass reset method.
+ *
+ * If you want to trigger a system reset from, for instance, a device
+ * model, don't use this function. Use qemu_system_reset_request().
+ */
 void qemu_devices_reset(ShutdownCause reason);
 
 #endif
-- 
2.34.1

Hi Peter,

On Tue, Feb 20, 2024 at 04:06:17PM +0000, Peter Maydell wrote:
> Date: Tue, 20 Feb 2024 16:06:17 +0000
> From: Peter Maydell <peter.maydell@linaro.org>
> Subject: [PATCH 05/10] hw/core: Add documentation and license comments to
>  reset.h
> X-Mailer: git-send-email 2.34.1
> 
> Add the usual boilerplate license/copyright comment to reset.h (using
> the text from reset.c), and document the existing functions.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  include/sysemu/reset.h | 79 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 79 insertions(+)
> 
> diff --git a/include/sysemu/reset.h b/include/sysemu/reset.h
> index 609e4d50c26..6aa11846a69 100644
> --- a/include/sysemu/reset.h
> +++ b/include/sysemu/reset.h
> @@ -1,3 +1,29 @@
> +/*
> + *  Reset handlers.
> + *
> + * Copyright (c) 2003-2008 Fabrice Bellard
> + * Copyright (c) 2016 Red Hat, Inc.
> + * Copyright (c) 2024 Linaro, Ltd.

An additional question, when there is a new (notable) contribution to a
file, then it's time to add the company's copyright. Right?

> + *
> + * Permission is hereby granted, free of charge, to any person obtaining a copy
> + * of this software and associated documentation files (the "Software"), to deal
> + * in the Software without restriction, including without limitation the rights
> + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
> + * copies of the Software, and to permit persons to whom the Software is
> + * furnished to do so, subject to the following conditions:
> + *
> + * The above copyright notice and this permission notice shall be included in
> + * all copies or substantial portions of the Software.
> + *
> + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
> + * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
> + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
> + * THE SOFTWARE.
> + */
> +
>  #ifndef QEMU_SYSEMU_RESET_H
>  #define QEMU_SYSEMU_RESET_H
>  
> @@ -5,9 +31,62 @@
>  
>  typedef void QEMUResetHandler(void *opaque);
>  
> +/**
> + * qemu_register_reset: Register a callback for system reset
> + * @func: function to call
> + * @opaque: opaque data to pass to @func
> + *
> + * Register @func on the list of functions which are called when the
> + * entire system is reset. The functions are called in the order in
> + * which they are registered.
> + *
> + * In general this function should not be used in new code where possible;
> + * for instance device model reset is better accomplished using the

s/for instance device/for instance, device/

> + * methods on DeviceState.
> + *
> + * It is not permitted to register or unregister reset functions from
> + * within the @func callback.
> + *
> + * We assume that the caller holds the BQL.

HMM, what does BQL stand for?

Others LGTM.
Reviewed-by: Zhao Liu <zhao1.liu@intel.com>

On Mon, 26 Feb 2024 at 14:13, Zhao Liu <zhao1.liu@intel.com> wrote:
>
> Hi Peter,
>
> On Tue, Feb 20, 2024 at 04:06:17PM +0000, Peter Maydell wrote:
> > Date: Tue, 20 Feb 2024 16:06:17 +0000
> > From: Peter Maydell <peter.maydell@linaro.org>
> > Subject: [PATCH 05/10] hw/core: Add documentation and license comments to
> >  reset.h
> > X-Mailer: git-send-email 2.34.1
> >
> > Add the usual boilerplate license/copyright comment to reset.h (using
> > the text from reset.c), and document the existing functions.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > ---
> >  include/sysemu/reset.h | 79 ++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 79 insertions(+)
> >
> > diff --git a/include/sysemu/reset.h b/include/sysemu/reset.h
> > index 609e4d50c26..6aa11846a69 100644
> > --- a/include/sysemu/reset.h
> > +++ b/include/sysemu/reset.h
> > @@ -1,3 +1,29 @@
> > +/*
> > + *  Reset handlers.
> > + *
> > + * Copyright (c) 2003-2008 Fabrice Bellard
> > + * Copyright (c) 2016 Red Hat, Inc.
> > + * Copyright (c) 2024 Linaro, Ltd.
>
> An additional question, when there is a new (notable) contribution to a
> file, then it's time to add the company's copyright. Right?

It's OK to do that; it's not obligatory. If you're contributing
on behalf of a company you should generally follow whatever
that company's policies are for copyright lines etc in open
source projects.

> > + * We assume that the caller holds the BQL.
>
> HMM, what does BQL stand for?

"Big QEMU Lock", the one you get via BQL_LOCK_GUARD().
BQL is the standard abbreviation -- we already use it
extensively both in comments in include/ and in docs/devel/.

-- PMM

On 2/20/24 06:06, Peter Maydell wrote:
> Add the usual boilerplate license/copyright comment to reset.h (using
> the text from reset.c), and document the existing functions.
> 
> Signed-off-by: Peter Maydell<peter.maydell@linaro.org>
> ---
>   include/sysemu/reset.h | 79 ++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 79 insertions(+)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

r~