qdev: add "hotpluggable" property to Device
[qemu.git] / include / hw / qdev-core.h
1 #ifndef QDEV_CORE_H
2 #define QDEV_CORE_H
3
4 #include "qemu/queue.h"
5 #include "qemu/option.h"
6 #include "qemu/typedefs.h"
7 #include "qemu/bitmap.h"
8 #include "qom/object.h"
9 #include "hw/irq.h"
10 #include "qapi/error.h"
11 #include "hw/hotplug.h"
12
13 enum {
14 DEV_NVECTORS_UNSPECIFIED = -1,
15 };
16
17 #define TYPE_DEVICE "device"
18 #define DEVICE(obj) OBJECT_CHECK(DeviceState, (obj), TYPE_DEVICE)
19 #define DEVICE_CLASS(klass) OBJECT_CLASS_CHECK(DeviceClass, (klass), TYPE_DEVICE)
20 #define DEVICE_GET_CLASS(obj) OBJECT_GET_CLASS(DeviceClass, (obj), TYPE_DEVICE)
21
22 typedef enum DeviceCategory {
23 DEVICE_CATEGORY_BRIDGE,
24 DEVICE_CATEGORY_USB,
25 DEVICE_CATEGORY_STORAGE,
26 DEVICE_CATEGORY_NETWORK,
27 DEVICE_CATEGORY_INPUT,
28 DEVICE_CATEGORY_DISPLAY,
29 DEVICE_CATEGORY_SOUND,
30 DEVICE_CATEGORY_MISC,
31 DEVICE_CATEGORY_MAX
32 } DeviceCategory;
33
34 typedef int (*qdev_initfn)(DeviceState *dev);
35 typedef int (*qdev_event)(DeviceState *dev);
36 typedef void (*qdev_resetfn)(DeviceState *dev);
37 typedef void (*DeviceRealize)(DeviceState *dev, Error **errp);
38 typedef void (*DeviceUnrealize)(DeviceState *dev, Error **errp);
39
40 struct VMStateDescription;
41
42 /**
43 * DeviceClass:
44 * @props: Properties accessing state fields.
45 * @realize: Callback function invoked when the #DeviceState:realized
46 * property is changed to %true. The default invokes @init if not %NULL.
47 * @unrealize: Callback function invoked when the #DeviceState:realized
48 * property is changed to %false.
49 * @init: Callback function invoked when the #DeviceState::realized property
50 * is changed to %true. Deprecated, new types inheriting directly from
51 * TYPE_DEVICE should use @realize instead, new leaf types should consult
52 * their respective parent type.
53 * @hotpluggable: indicates if #DeviceClass is hotpluggable, available
54 * as readonly "hotpluggable" property of #DeviceState instance
55 *
56 * # Realization #
57 * Devices are constructed in two stages,
58 * 1) object instantiation via object_initialize() and
59 * 2) device realization via #DeviceState:realized property.
60 * The former may not fail (it might assert or exit), the latter may return
61 * error information to the caller and must be re-entrant.
62 * Trivial field initializations should go into #TypeInfo.instance_init.
63 * Operations depending on @props static properties should go into @realize.
64 * After successful realization, setting static properties will fail.
65 *
66 * As an interim step, the #DeviceState:realized property is set by deprecated
67 * functions qdev_init() and qdev_init_nofail().
68 * In the future, devices will propagate this state change to their children
69 * and along busses they expose.
70 * The point in time will be deferred to machine creation, so that values
71 * set in @realize will not be introspectable beforehand. Therefore devices
72 * must not create children during @realize; they should initialize them via
73 * object_initialize() in their own #TypeInfo.instance_init and forward the
74 * realization events appropriately.
75 *
76 * The @init callback is considered private to a particular bus implementation
77 * (immediate abstract child types of TYPE_DEVICE). Derived leaf types set an
78 * "init" callback on their parent class instead.
79 *
80 * Any type may override the @realize and/or @unrealize callbacks but needs
81 * to call the parent type's implementation if keeping their functionality
82 * is desired. Refer to QOM documentation for further discussion and examples.
83 *
84 * <note>
85 * <para>
86 * If a type derived directly from TYPE_DEVICE implements @realize, it does
87 * not need to implement @init and therefore does not need to store and call
88 * #DeviceClass' default @realize callback.
89 * For other types consult the documentation and implementation of the
90 * respective parent types.
91 * </para>
92 * </note>
93 */
94 typedef struct DeviceClass {
95 /*< private >*/
96 ObjectClass parent_class;
97 /*< public >*/
98
99 DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX);
100 const char *fw_name;
101 const char *desc;
102 Property *props;
103
104 /*
105 * Shall we hide this device model from -device / device_add?
106 * All devices should support instantiation with device_add, and
107 * this flag should not exist. But we're not there, yet. Some
108 * devices fail to instantiate with cryptic error messages.
109 * Others instantiate, but don't work. Exposing users to such
110 * behavior would be cruel; this flag serves to protect them. It
111 * should never be set without a comment explaining why it is set.
112 * TODO remove once we're there
113 */
114 bool cannot_instantiate_with_device_add_yet;
115 bool hotpluggable;
116
117 /* callbacks */
118 void (*reset)(DeviceState *dev);
119 DeviceRealize realize;
120 DeviceUnrealize unrealize;
121
122 /* device state */
123 const struct VMStateDescription *vmsd;
124
125 /* Private to qdev / bus. */
126 qdev_initfn init; /* TODO remove, once users are converted to realize */
127 qdev_event unplug;
128 qdev_event exit; /* TODO remove, once users are converted to unrealize */
129 const char *bus_type;
130 } DeviceClass;
131
132 /**
133 * DeviceState:
134 * @realized: Indicates whether the device has been fully constructed.
135 *
136 * This structure should not be accessed directly. We declare it here
137 * so that it can be embedded in individual device state structures.
138 */
139 struct DeviceState {
140 /*< private >*/
141 Object parent_obj;
142 /*< public >*/
143
144 const char *id;
145 bool realized;
146 QemuOpts *opts;
147 int hotplugged;
148 BusState *parent_bus;
149 int num_gpio_out;
150 qemu_irq *gpio_out;
151 int num_gpio_in;
152 qemu_irq *gpio_in;
153 QLIST_HEAD(, BusState) child_bus;
154 int num_child_bus;
155 int instance_id_alias;
156 int alias_required_for_version;
157 };
158
159 #define TYPE_BUS "bus"
160 #define BUS(obj) OBJECT_CHECK(BusState, (obj), TYPE_BUS)
161 #define BUS_CLASS(klass) OBJECT_CLASS_CHECK(BusClass, (klass), TYPE_BUS)
162 #define BUS_GET_CLASS(obj) OBJECT_GET_CLASS(BusClass, (obj), TYPE_BUS)
163
164 struct BusClass {
165 ObjectClass parent_class;
166
167 /* FIXME first arg should be BusState */
168 void (*print_dev)(Monitor *mon, DeviceState *dev, int indent);
169 char *(*get_dev_path)(DeviceState *dev);
170 /*
171 * This callback is used to create Open Firmware device path in accordance
172 * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus
173 * bindings can be found at http://playground.sun.com/1275/bindings/.
174 */
175 char *(*get_fw_dev_path)(DeviceState *dev);
176 void (*reset)(BusState *bus);
177 /* maximum devices allowed on the bus, 0: no limit. */
178 int max_dev;
179 };
180
181 typedef struct BusChild {
182 DeviceState *child;
183 int index;
184 QTAILQ_ENTRY(BusChild) sibling;
185 } BusChild;
186
187 #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler"
188
189 /**
190 * BusState:
191 * @hotplug_device: link to a hotplug device associated with bus.
192 */
193 struct BusState {
194 Object obj;
195 DeviceState *parent;
196 const char *name;
197 int allow_hotplug;
198 HotplugHandler *hotplug_handler;
199 int max_index;
200 QTAILQ_HEAD(ChildrenHead, BusChild) children;
201 QLIST_ENTRY(BusState) sibling;
202 };
203
204 struct Property {
205 const char *name;
206 PropertyInfo *info;
207 int offset;
208 uint8_t bitnr;
209 uint8_t qtype;
210 int64_t defval;
211 int arrayoffset;
212 PropertyInfo *arrayinfo;
213 int arrayfieldsize;
214 };
215
216 struct PropertyInfo {
217 const char *name;
218 const char *legacy_name;
219 const char **enum_table;
220 int (*parse)(DeviceState *dev, Property *prop, const char *str);
221 int (*print)(DeviceState *dev, Property *prop, char *dest, size_t len);
222 ObjectPropertyAccessor *get;
223 ObjectPropertyAccessor *set;
224 ObjectPropertyRelease *release;
225 };
226
227 typedef struct GlobalProperty {
228 const char *driver;
229 const char *property;
230 const char *value;
231 QTAILQ_ENTRY(GlobalProperty) next;
232 } GlobalProperty;
233
234 /*** Board API. This should go away once we have a machine config file. ***/
235
236 DeviceState *qdev_create(BusState *bus, const char *name);
237 DeviceState *qdev_try_create(BusState *bus, const char *name);
238 int qdev_init(DeviceState *dev) QEMU_WARN_UNUSED_RESULT;
239 void qdev_init_nofail(DeviceState *dev);
240 void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
241 int required_for_version);
242 void qdev_unplug(DeviceState *dev, Error **errp);
243 int qdev_simple_unplug_cb(DeviceState *dev);
244 void qdev_machine_creation_done(void);
245 bool qdev_machine_modified(void);
246
247 qemu_irq qdev_get_gpio_in(DeviceState *dev, int n);
248 void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin);
249
250 BusState *qdev_get_child_bus(DeviceState *dev, const char *name);
251
252 /*** Device API. ***/
253
254 /* Register device properties. */
255 /* GPIO inputs also double as IRQ sinks. */
256 void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n);
257 void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n);
258
259 BusState *qdev_get_parent_bus(DeviceState *dev);
260
261 /*** BUS API. ***/
262
263 DeviceState *qdev_find_recursive(BusState *bus, const char *id);
264
265 /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */
266 typedef int (qbus_walkerfn)(BusState *bus, void *opaque);
267 typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque);
268
269 void qbus_create_inplace(void *bus, size_t size, const char *typename,
270 DeviceState *parent, const char *name);
271 BusState *qbus_create(const char *typename, DeviceState *parent, const char *name);
272 /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion,
273 * < 0 if either devfn or busfn terminate walk somewhere in cursion,
274 * 0 otherwise. */
275 int qbus_walk_children(BusState *bus,
276 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
277 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
278 void *opaque);
279 int qdev_walk_children(DeviceState *dev,
280 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
281 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
282 void *opaque);
283
284 void qdev_reset_all(DeviceState *dev);
285
286 /**
287 * @qbus_reset_all:
288 * @bus: Bus to be reset.
289 *
290 * Reset @bus and perform a bus-level ("hard") reset of all devices connected
291 * to it, including recursive processing of all buses below @bus itself. A
292 * hard reset means that qbus_reset_all will reset all state of the device.
293 * For PCI devices, for example, this will include the base address registers
294 * or configuration space.
295 */
296 void qbus_reset_all(BusState *bus);
297 void qbus_reset_all_fn(void *opaque);
298
299 /* This should go away once we get rid of the NULL bus hack */
300 BusState *sysbus_get_default(void);
301
302 char *qdev_get_fw_dev_path(DeviceState *dev);
303
304 /**
305 * @qdev_machine_init
306 *
307 * Initialize platform devices before machine init. This is a hack until full
308 * support for composition is added.
309 */
310 void qdev_machine_init(void);
311
312 /**
313 * @device_reset
314 *
315 * Reset a single device (by calling the reset method).
316 */
317 void device_reset(DeviceState *dev);
318
319 const struct VMStateDescription *qdev_get_vmsd(DeviceState *dev);
320
321 const char *qdev_fw_name(DeviceState *dev);
322
323 Object *qdev_get_machine(void);
324
325 /* FIXME: make this a link<> */
326 void qdev_set_parent_bus(DeviceState *dev, BusState *bus);
327
328 extern int qdev_hotplug;
329
330 char *qdev_get_dev_path(DeviceState *dev);
331
332 static inline void qbus_set_hotplug_handler(BusState *bus, DeviceState *handler,
333 Error **errp)
334 {
335 object_property_set_link(OBJECT(bus), OBJECT(handler),
336 QDEV_HOTPLUG_HANDLER_PROPERTY, errp);
337 bus->allow_hotplug = 1;
338 }
339 #endif