Update version for v3.0.0 release
[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/bitmap.h"
6 #include "qom/object.h"
7 #include "hw/irq.h"
8 #include "hw/hotplug.h"
9
10 enum {
11 DEV_NVECTORS_UNSPECIFIED = -1,
12 };
13
14 #define TYPE_DEVICE "device"
15 #define DEVICE(obj) OBJECT_CHECK(DeviceState, (obj), TYPE_DEVICE)
16 #define DEVICE_CLASS(klass) OBJECT_CLASS_CHECK(DeviceClass, (klass), TYPE_DEVICE)
17 #define DEVICE_GET_CLASS(obj) OBJECT_GET_CLASS(DeviceClass, (obj), TYPE_DEVICE)
18
19 typedef enum DeviceCategory {
20 DEVICE_CATEGORY_BRIDGE,
21 DEVICE_CATEGORY_USB,
22 DEVICE_CATEGORY_STORAGE,
23 DEVICE_CATEGORY_NETWORK,
24 DEVICE_CATEGORY_INPUT,
25 DEVICE_CATEGORY_DISPLAY,
26 DEVICE_CATEGORY_SOUND,
27 DEVICE_CATEGORY_MISC,
28 DEVICE_CATEGORY_CPU,
29 DEVICE_CATEGORY_MAX
30 } DeviceCategory;
31
32 typedef void (*DeviceRealize)(DeviceState *dev, Error **errp);
33 typedef void (*DeviceUnrealize)(DeviceState *dev, Error **errp);
34 typedef void (*DeviceReset)(DeviceState *dev);
35 typedef void (*BusRealize)(BusState *bus, Error **errp);
36 typedef void (*BusUnrealize)(BusState *bus, Error **errp);
37
38 struct VMStateDescription;
39
40 /**
41 * DeviceClass:
42 * @props: Properties accessing state fields.
43 * @realize: Callback function invoked when the #DeviceState:realized
44 * property is changed to %true.
45 * @unrealize: Callback function invoked when the #DeviceState:realized
46 * property is changed to %false.
47 * @hotpluggable: indicates if #DeviceClass is hotpluggable, available
48 * as readonly "hotpluggable" property of #DeviceState instance
49 *
50 * # Realization #
51 * Devices are constructed in two stages,
52 * 1) object instantiation via object_initialize() and
53 * 2) device realization via #DeviceState:realized property.
54 * The former may not fail (it might assert or exit), the latter may return
55 * error information to the caller and must be re-entrant.
56 * Trivial field initializations should go into #TypeInfo.instance_init.
57 * Operations depending on @props static properties should go into @realize.
58 * After successful realization, setting static properties will fail.
59 *
60 * As an interim step, the #DeviceState:realized property can also be
61 * set with qdev_init_nofail().
62 * In the future, devices will propagate this state change to their children
63 * and along busses they expose.
64 * The point in time will be deferred to machine creation, so that values
65 * set in @realize will not be introspectable beforehand. Therefore devices
66 * must not create children during @realize; they should initialize them via
67 * object_initialize() in their own #TypeInfo.instance_init and forward the
68 * realization events appropriately.
69 *
70 * Any type may override the @realize and/or @unrealize callbacks but needs
71 * to call the parent type's implementation if keeping their functionality
72 * is desired. Refer to QOM documentation for further discussion and examples.
73 *
74 * <note>
75 * <para>
76 * Since TYPE_DEVICE doesn't implement @realize and @unrealize, types
77 * derived directly from it need not call their parent's @realize and
78 * @unrealize.
79 * For other types consult the documentation and implementation of the
80 * respective parent types.
81 * </para>
82 * </note>
83 */
84 typedef struct DeviceClass {
85 /*< private >*/
86 ObjectClass parent_class;
87 /*< public >*/
88
89 DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX);
90 const char *fw_name;
91 const char *desc;
92 Property *props;
93
94 /*
95 * Can this device be instantiated with -device / device_add?
96 * All devices should support instantiation with device_add, and
97 * this flag should not exist. But we're not there, yet. Some
98 * devices fail to instantiate with cryptic error messages.
99 * Others instantiate, but don't work. Exposing users to such
100 * behavior would be cruel; clearing this flag will protect them.
101 * It should never be cleared without a comment explaining why it
102 * is cleared.
103 * TODO remove once we're there
104 */
105 bool user_creatable;
106 bool hotpluggable;
107
108 /* callbacks */
109 DeviceReset reset;
110 DeviceRealize realize;
111 DeviceUnrealize unrealize;
112
113 /* device state */
114 const struct VMStateDescription *vmsd;
115
116 /* Private to qdev / bus. */
117 const char *bus_type;
118 } DeviceClass;
119
120 typedef struct NamedGPIOList NamedGPIOList;
121
122 struct NamedGPIOList {
123 char *name;
124 qemu_irq *in;
125 int num_in;
126 int num_out;
127 QLIST_ENTRY(NamedGPIOList) node;
128 };
129
130 /**
131 * DeviceState:
132 * @realized: Indicates whether the device has been fully constructed.
133 *
134 * This structure should not be accessed directly. We declare it here
135 * so that it can be embedded in individual device state structures.
136 */
137 struct DeviceState {
138 /*< private >*/
139 Object parent_obj;
140 /*< public >*/
141
142 const char *id;
143 char *canonical_path;
144 bool realized;
145 bool pending_deleted_event;
146 QemuOpts *opts;
147 int hotplugged;
148 BusState *parent_bus;
149 QLIST_HEAD(, NamedGPIOList) gpios;
150 QLIST_HEAD(, BusState) child_bus;
151 int num_child_bus;
152 int instance_id_alias;
153 int alias_required_for_version;
154 };
155
156 struct DeviceListener {
157 void (*realize)(DeviceListener *listener, DeviceState *dev);
158 void (*unrealize)(DeviceListener *listener, DeviceState *dev);
159 QTAILQ_ENTRY(DeviceListener) link;
160 };
161
162 #define TYPE_BUS "bus"
163 #define BUS(obj) OBJECT_CHECK(BusState, (obj), TYPE_BUS)
164 #define BUS_CLASS(klass) OBJECT_CLASS_CHECK(BusClass, (klass), TYPE_BUS)
165 #define BUS_GET_CLASS(obj) OBJECT_GET_CLASS(BusClass, (obj), TYPE_BUS)
166
167 struct BusClass {
168 ObjectClass parent_class;
169
170 /* FIXME first arg should be BusState */
171 void (*print_dev)(Monitor *mon, DeviceState *dev, int indent);
172 char *(*get_dev_path)(DeviceState *dev);
173 /*
174 * This callback is used to create Open Firmware device path in accordance
175 * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus
176 * bindings can be found at http://playground.sun.com/1275/bindings/.
177 */
178 char *(*get_fw_dev_path)(DeviceState *dev);
179 void (*reset)(BusState *bus);
180 BusRealize realize;
181 BusUnrealize unrealize;
182
183 /* maximum devices allowed on the bus, 0: no limit. */
184 int max_dev;
185 /* number of automatically allocated bus ids (e.g. ide.0) */
186 int automatic_ids;
187 };
188
189 typedef struct BusChild {
190 DeviceState *child;
191 int index;
192 QTAILQ_ENTRY(BusChild) sibling;
193 } BusChild;
194
195 #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler"
196
197 /**
198 * BusState:
199 * @hotplug_device: link to a hotplug device associated with bus.
200 */
201 struct BusState {
202 Object obj;
203 DeviceState *parent;
204 char *name;
205 HotplugHandler *hotplug_handler;
206 int max_index;
207 bool realized;
208 QTAILQ_HEAD(ChildrenHead, BusChild) children;
209 QLIST_ENTRY(BusState) sibling;
210 };
211
212 /**
213 * Property:
214 * @set_default: true if the default value should be set from @defval,
215 * in which case @info->set_default_value must not be NULL
216 * (if false then no default value is set by the property system
217 * and the field retains whatever value it was given by instance_init).
218 * @defval: default value for the property. This is used only if @set_default
219 * is true.
220 */
221 struct Property {
222 const char *name;
223 const PropertyInfo *info;
224 ptrdiff_t offset;
225 uint8_t bitnr;
226 bool set_default;
227 union {
228 int64_t i;
229 uint64_t u;
230 } defval;
231 int arrayoffset;
232 const PropertyInfo *arrayinfo;
233 int arrayfieldsize;
234 const char *link_type;
235 };
236
237 struct PropertyInfo {
238 const char *name;
239 const char *description;
240 const QEnumLookup *enum_table;
241 int (*print)(DeviceState *dev, Property *prop, char *dest, size_t len);
242 void (*set_default_value)(Object *obj, const Property *prop);
243 void (*create)(Object *obj, Property *prop, Error **errp);
244 ObjectPropertyAccessor *get;
245 ObjectPropertyAccessor *set;
246 ObjectPropertyRelease *release;
247 };
248
249 /**
250 * GlobalProperty:
251 * @user_provided: Set to true if property comes from user-provided config
252 * (command-line or config file).
253 * @used: Set to true if property was used when initializing a device.
254 * @errp: Error destination, used like first argument of error_setg()
255 * in case property setting fails later. If @errp is NULL, we
256 * print warnings instead of ignoring errors silently. For
257 * hotplugged devices, errp is always ignored and warnings are
258 * printed instead.
259 */
260 typedef struct GlobalProperty {
261 const char *driver;
262 const char *property;
263 const char *value;
264 bool user_provided;
265 bool used;
266 Error **errp;
267 } GlobalProperty;
268
269 /*** Board API. This should go away once we have a machine config file. ***/
270
271 DeviceState *qdev_create(BusState *bus, const char *name);
272 DeviceState *qdev_try_create(BusState *bus, const char *name);
273 void qdev_init_nofail(DeviceState *dev);
274 void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
275 int required_for_version);
276 HotplugHandler *qdev_get_machine_hotplug_handler(DeviceState *dev);
277 HotplugHandler *qdev_get_hotplug_handler(DeviceState *dev);
278 void qdev_unplug(DeviceState *dev, Error **errp);
279 void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev,
280 DeviceState *dev, Error **errp);
281 void qdev_machine_creation_done(void);
282 bool qdev_machine_modified(void);
283
284 qemu_irq qdev_get_gpio_in(DeviceState *dev, int n);
285 qemu_irq qdev_get_gpio_in_named(DeviceState *dev, const char *name, int n);
286
287 void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin);
288 void qdev_connect_gpio_out_named(DeviceState *dev, const char *name, int n,
289 qemu_irq pin);
290 qemu_irq qdev_get_gpio_out_connector(DeviceState *dev, const char *name, int n);
291 qemu_irq qdev_intercept_gpio_out(DeviceState *dev, qemu_irq icpt,
292 const char *name, int n);
293
294 BusState *qdev_get_child_bus(DeviceState *dev, const char *name);
295
296 /*** Device API. ***/
297
298 /* Register device properties. */
299 /* GPIO inputs also double as IRQ sinks. */
300 void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n);
301 void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n);
302 void qdev_init_gpio_out_named(DeviceState *dev, qemu_irq *pins,
303 const char *name, int n);
304 /**
305 * qdev_init_gpio_in_named_with_opaque: create an array of input GPIO lines
306 * for the specified device
307 *
308 * @dev: Device to create input GPIOs for
309 * @handler: Function to call when GPIO line value is set
310 * @opaque: Opaque data pointer to pass to @handler
311 * @name: Name of the GPIO input (must be unique for this device)
312 * @n: Number of GPIO lines in this input set
313 */
314 void qdev_init_gpio_in_named_with_opaque(DeviceState *dev,
315 qemu_irq_handler handler,
316 void *opaque,
317 const char *name, int n);
318
319 /**
320 * qdev_init_gpio_in_named: create an array of input GPIO lines
321 * for the specified device
322 *
323 * Like qdev_init_gpio_in_named_with_opaque(), but the opaque pointer
324 * passed to the handler is @dev (which is the most commonly desired behaviour).
325 */
326 static inline void qdev_init_gpio_in_named(DeviceState *dev,
327 qemu_irq_handler handler,
328 const char *name, int n)
329 {
330 qdev_init_gpio_in_named_with_opaque(dev, handler, dev, name, n);
331 }
332
333 void qdev_pass_gpios(DeviceState *dev, DeviceState *container,
334 const char *name);
335
336 BusState *qdev_get_parent_bus(DeviceState *dev);
337
338 /*** BUS API. ***/
339
340 DeviceState *qdev_find_recursive(BusState *bus, const char *id);
341
342 /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */
343 typedef int (qbus_walkerfn)(BusState *bus, void *opaque);
344 typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque);
345
346 void qbus_create_inplace(void *bus, size_t size, const char *typename,
347 DeviceState *parent, const char *name);
348 BusState *qbus_create(const char *typename, DeviceState *parent, const char *name);
349 /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion,
350 * < 0 if either devfn or busfn terminate walk somewhere in cursion,
351 * 0 otherwise. */
352 int qbus_walk_children(BusState *bus,
353 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
354 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
355 void *opaque);
356 int qdev_walk_children(DeviceState *dev,
357 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
358 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
359 void *opaque);
360
361 void qdev_reset_all(DeviceState *dev);
362 void qdev_reset_all_fn(void *opaque);
363
364 /**
365 * @qbus_reset_all:
366 * @bus: Bus to be reset.
367 *
368 * Reset @bus and perform a bus-level ("hard") reset of all devices connected
369 * to it, including recursive processing of all buses below @bus itself. A
370 * hard reset means that qbus_reset_all will reset all state of the device.
371 * For PCI devices, for example, this will include the base address registers
372 * or configuration space.
373 */
374 void qbus_reset_all(BusState *bus);
375 void qbus_reset_all_fn(void *opaque);
376
377 /* This should go away once we get rid of the NULL bus hack */
378 BusState *sysbus_get_default(void);
379
380 char *qdev_get_fw_dev_path(DeviceState *dev);
381 char *qdev_get_own_fw_dev_path_from_handler(BusState *bus, DeviceState *dev);
382
383 /**
384 * @qdev_machine_init
385 *
386 * Initialize platform devices before machine init. This is a hack until full
387 * support for composition is added.
388 */
389 void qdev_machine_init(void);
390
391 /**
392 * @device_reset
393 *
394 * Reset a single device (by calling the reset method).
395 */
396 void device_reset(DeviceState *dev);
397
398 void device_class_set_parent_reset(DeviceClass *dc,
399 DeviceReset dev_reset,
400 DeviceReset *parent_reset);
401 void device_class_set_parent_realize(DeviceClass *dc,
402 DeviceRealize dev_realize,
403 DeviceRealize *parent_realize);
404 void device_class_set_parent_unrealize(DeviceClass *dc,
405 DeviceUnrealize dev_unrealize,
406 DeviceUnrealize *parent_unrealize);
407
408 const struct VMStateDescription *qdev_get_vmsd(DeviceState *dev);
409
410 const char *qdev_fw_name(DeviceState *dev);
411
412 Object *qdev_get_machine(void);
413
414 /* FIXME: make this a link<> */
415 void qdev_set_parent_bus(DeviceState *dev, BusState *bus);
416
417 extern bool qdev_hotplug;
418 extern bool qdev_hot_removed;
419
420 char *qdev_get_dev_path(DeviceState *dev);
421
422 GSList *qdev_build_hotpluggable_device_list(Object *peripheral);
423
424 void qbus_set_hotplug_handler(BusState *bus, DeviceState *handler,
425 Error **errp);
426
427 void qbus_set_bus_hotplug_handler(BusState *bus, Error **errp);
428
429 static inline bool qbus_is_hotpluggable(BusState *bus)
430 {
431 return bus->hotplug_handler;
432 }
433
434 void device_listener_register(DeviceListener *listener);
435 void device_listener_unregister(DeviceListener *listener);
436
437 #endif