include/sysemu/reset.h

   1 /*
   2  *  Reset handlers.
   3  *
   4  * Copyright (c) 2003-2008 Fabrice Bellard
   5  * Copyright (c) 2016 Red Hat, Inc.
   6  * Copyright (c) 2024 Linaro, Ltd.
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  21  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  24  * THE SOFTWARE.
  25  */
  26
  27 #ifndef QEMU_SYSEMU_RESET_H
  28 #define QEMU_SYSEMU_RESET_H
  29
  30 #include "qapi/qapi-events-run-state.h"
  31
  32 typedef void QEMUResetHandler(void *opaque);
  33
  34 /**
  35  * qemu_register_resettable: Register an object to be reset
  36  * @obj: object to be reset: it must implement the Resettable interface
  37  *
  38  * Register @obj on the list of objects which will be reset when the
  39  * simulation is reset. These objects will be reset in the order
  40  * they were added, using the three-phase Resettable protocol,
  41  * so first all objects go through the enter phase, then all objects
  42  * go through the hold phase, and then finally all go through the
  43  * exit phase.
  44  *
  45  * It is not permitted to register or unregister reset functions or
  46  * resettable objects from within any of the reset phase methods of @obj.
  47  *
  48  * We assume that the caller holds the BQL.
  49  */
  50 void qemu_register_resettable(Object *obj);
  51
  52 /**
  53  * qemu_unregister_resettable: Unregister an object to be reset
  54  * @obj: object to unregister
  55  *
  56  * Remove @obj from the list of objects which are reset when the
  57  * simulation is reset. It must have been previously added to
  58  * the list via qemu_register_resettable().
  59  *
  60  * We assume that the caller holds the BQL.
  61  */
  62 void qemu_unregister_resettable(Object *obj);
  63
  64 /**
  65  * qemu_register_reset: Register a callback for system reset
  66  * @func: function to call
  67  * @opaque: opaque data to pass to @func
  68  *
  69  * Register @func on the list of functions which are called when the
  70  * entire system is reset. Functions registered with this API and
  71  * Resettable objects registered with qemu_register_resettable() are
  72  * handled together, in the order in which they were registered.
  73  * Functions registered with this API are called in the 'hold' phase
  74  * of the 3-phase reset.
  75  *
  76  * In general this function should not be used in new code where possible;
  77  * for instance, device model reset is better accomplished using the
  78  * methods on DeviceState.
  79  *
  80  * It is not permitted to register or unregister reset functions or
  81  * resettable objects from within the @func callback.
  82  *
  83  * We assume that the caller holds the BQL.
  84  */
  85 void qemu_register_reset(QEMUResetHandler *func, void *opaque);
  86
  87 /**
  88  * qemu_register_reset_nosnapshotload: Register a callback for system reset
  89  * @func: function to call
  90  * @opaque: opaque data to pass to @func
  91  *
  92  * This is the same as qemu_register_reset(), except that @func is
  93  * not called if the reason that the system is being reset is to
  94  * put it into a clean state prior to loading a snapshot (i.e. for
  95  * SHUTDOWN_CAUSE_SNAPSHOT_LOAD).
  96  */
  97 void qemu_register_reset_nosnapshotload(QEMUResetHandler *func, void *opaque);
  98
  99 /**
 100  * qemu_unregister_reset: Unregister a system reset callback
 101  * @func: function registered with qemu_register_reset()
 102  * @opaque: the same opaque data that was passed to qemu_register_reset()
 103  *
 104  * Undo the effects of a qemu_register_reset(). The @func and @opaque
 105  * must both match the arguments originally used with qemu_register_reset().
 106  *
 107  * We assume that the caller holds the BQL.
 108  */
 109 void qemu_unregister_reset(QEMUResetHandler *func, void *opaque);
 110
 111 /**
 112  * qemu_devices_reset: Perform a complete system reset
 113  * @reason: reason for the reset
 114  *
 115  * This function performs the low-level work needed to do a complete reset
 116  * of the system (calling all the callbacks registered with
 117  * qemu_register_reset() and resetting all the Resettable objects registered
 118  * with qemu_register_resettable()). It should only be called by the code in a
 119  * MachineClass reset method.
 120  *
 121  * If you want to trigger a system reset from, for instance, a device
 122  * model, don't use this function. Use qemu_system_reset_request().
 123  */
 124 void qemu_devices_reset(ShutdownCause reason);
 125
 126 #endif