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 "hw/resettable.h" 31 #include "qapi/qapi-events-run-state.h" 32 33 typedef void QEMUResetHandler(void *opaque); 34 35 /** 36 * qemu_register_resettable: Register an object to be reset 37 * @obj: object to be reset: it must implement the Resettable interface 38 * 39 * Register @obj on the list of objects which will be reset when the 40 * simulation is reset. These objects will be reset in the order 41 * they were added, using the three-phase Resettable protocol, 42 * so first all objects go through the enter phase, then all objects 43 * go through the hold phase, and then finally all go through the 44 * exit phase. 45 * 46 * It is not permitted to register or unregister reset functions or 47 * resettable objects from within any of the reset phase methods of @obj. 48 * 49 * We assume that the caller holds the BQL. 50 */ 51 void qemu_register_resettable(Object *obj); 52 53 /** 54 * qemu_unregister_resettable: Unregister an object to be reset 55 * @obj: object to unregister 56 * 57 * Remove @obj from the list of objects which are reset when the 58 * simulation is reset. It must have been previously added to 59 * the list via qemu_register_resettable(). 60 * 61 * We assume that the caller holds the BQL. 62 */ 63 void qemu_unregister_resettable(Object *obj); 64 65 /** 66 * qemu_register_reset: Register a callback for system reset 67 * @func: function to call 68 * @opaque: opaque data to pass to @func 69 * 70 * Register @func on the list of functions which are called when the 71 * entire system is reset. Functions registered with this API and 72 * Resettable objects registered with qemu_register_resettable() are 73 * handled together, in the order in which they were registered. 74 * Functions registered with this API are called in the 'hold' phase 75 * of the 3-phase reset. 76 * 77 * In general this function should not be used in new code where possible; 78 * for instance, device model reset is better accomplished using the 79 * methods on DeviceState. 80 * 81 * It is not permitted to register or unregister reset functions or 82 * resettable objects from within the @func callback. 83 * 84 * We assume that the caller holds the BQL. 85 */ 86 void qemu_register_reset(QEMUResetHandler *func, void *opaque); 87 88 /** 89 * qemu_register_reset_nosnapshotload: Register a callback for system reset 90 * @func: function to call 91 * @opaque: opaque data to pass to @func 92 * 93 * This is the same as qemu_register_reset(), except that @func is 94 * not called if the reason that the system is being reset is to 95 * put it into a clean state prior to loading a snapshot (i.e. for 96 * SHUTDOWN_CAUSE_SNAPSHOT_LOAD). 97 */ 98 void qemu_register_reset_nosnapshotload(QEMUResetHandler *func, void *opaque); 99 100 /** 101 * qemu_unregister_reset: Unregister a system reset callback 102 * @func: function registered with qemu_register_reset() 103 * @opaque: the same opaque data that was passed to qemu_register_reset() 104 * 105 * Undo the effects of a qemu_register_reset(). The @func and @opaque 106 * must both match the arguments originally used with qemu_register_reset(). 107 * 108 * We assume that the caller holds the BQL. 109 */ 110 void qemu_unregister_reset(QEMUResetHandler *func, void *opaque); 111 112 /** 113 * qemu_devices_reset: Perform a complete system reset 114 * @reason: type of the reset 115 * 116 * This function performs the low-level work needed to do a complete reset 117 * of the system (calling all the callbacks registered with 118 * qemu_register_reset() and resetting all the Resettable objects registered 119 * with qemu_register_resettable()). It should only be called by the code in a 120 * MachineClass reset method. 121 * 122 * If you want to trigger a system reset from, for instance, a device 123 * model, don't use this function. Use qemu_system_reset_request(). 124 */ 125 void qemu_devices_reset(ResetType type); 126 127 #endif 128