| 1 | #ifndef QDEV_CORE_H |
| 2 | #define QDEV_CORE_H |
| 3 | |
| 4 | #include "qemu/atomic.h" |
| 5 | #include "qemu/queue.h" |
| 6 | #include "qemu/bitmap.h" |
| 7 | #include "qemu/mem-reentrancy.h" |
| 8 | #include "qemu/rcu.h" |
| 9 | #include "qemu/rcu_queue.h" |
| 10 | #include "qom/object.h" |
| 11 | #include "hw/core/hotplug.h" |
| 12 | #include "hw/core/resettable.h" |
| 13 | #include "monitor/hmp.h" |
| 14 | |
| 15 | /** |
| 16 | * DOC: The QEMU Device API |
| 17 | * |
| 18 | * All modern devices should represented as a derived QOM class of |
| 19 | * TYPE_DEVICE. The device API introduces the additional methods of |
| 20 | * @realize and @unrealize to represent additional stages in a device |
| 21 | * objects life cycle. |
| 22 | * |
| 23 | * Realization |
| 24 | * ----------- |
| 25 | * |
| 26 | * Devices are constructed in two stages: |
| 27 | * |
| 28 | * 1) object instantiation via object_initialize() and |
| 29 | * 2) device realization via the #DeviceState.realized property |
| 30 | * |
| 31 | * The former may not fail (and must not abort or exit, since it is called |
| 32 | * during device introspection already), and the latter may return error |
| 33 | * information to the caller and must be re-entrant. |
| 34 | * Trivial field initializations should go into #TypeInfo.instance_init. |
| 35 | * Operations depending on @props static properties should go into @realize. |
| 36 | * After successful realization, setting static properties will fail. |
| 37 | * |
| 38 | * As an interim step, the #DeviceState.realized property can also be |
| 39 | * set with qdev_realize(). In the future, devices will propagate this |
| 40 | * state change to their children and along busses they expose. The |
| 41 | * point in time will be deferred to machine creation, so that values |
| 42 | * set in @realize will not be introspectable beforehand. Therefore |
| 43 | * devices must not create children during @realize; they should |
| 44 | * initialize them via object_initialize() in their own |
| 45 | * #TypeInfo.instance_init and forward the realization events |
| 46 | * appropriately. |
| 47 | * |
| 48 | * Any type may override the @realize and/or @unrealize callbacks but needs |
| 49 | * to call the parent type's implementation if keeping their functionality |
| 50 | * is desired. Refer to QOM documentation for further discussion and examples. |
| 51 | * |
| 52 | * .. note:: |
| 53 | * Since TYPE_DEVICE doesn't implement @realize and @unrealize, types |
| 54 | * derived directly from it need not call their parent's @realize and |
| 55 | * @unrealize. For other types consult the documentation and |
| 56 | * implementation of the respective parent types. |
| 57 | * |
| 58 | * Hiding a device |
| 59 | * --------------- |
| 60 | * |
| 61 | * To hide a device, a DeviceListener function hide_device() needs to |
| 62 | * be registered. It can be used to defer adding a device and |
| 63 | * therefore hide it from the guest. The handler registering to this |
| 64 | * DeviceListener can save the QOpts passed to it for re-using it |
| 65 | * later. It must return if it wants the device to be hidden or |
| 66 | * visible. When the handler function decides the device shall be |
| 67 | * visible it will be added with qdev_device_add() and realized as any |
| 68 | * other device. Otherwise qdev_device_add() will return early without |
| 69 | * adding the device. The guest will not see a "hidden" device until |
| 70 | * it was marked visible and qdev_device_add called again. |
| 71 | * |
| 72 | */ |
| 73 | |
| 74 | enum { |
| 75 | DEV_NVECTORS_UNSPECIFIED = -1, |
| 76 | }; |
| 77 | |
| 78 | #define TYPE_DEVICE "device" |
| 79 | OBJECT_DECLARE_TYPE(DeviceState, DeviceClass, DEVICE) |
| 80 | |
| 81 | typedef enum DeviceCategory { |
| 82 | DEVICE_CATEGORY_BRIDGE, |
| 83 | DEVICE_CATEGORY_USB, |
| 84 | DEVICE_CATEGORY_STORAGE, |
| 85 | DEVICE_CATEGORY_NETWORK, |
| 86 | DEVICE_CATEGORY_INPUT, |
| 87 | DEVICE_CATEGORY_DISPLAY, |
| 88 | DEVICE_CATEGORY_SOUND, |
| 89 | DEVICE_CATEGORY_MISC, |
| 90 | DEVICE_CATEGORY_CPU, |
| 91 | DEVICE_CATEGORY_WATCHDOG, |
| 92 | DEVICE_CATEGORY_MAX |
| 93 | } DeviceCategory; |
| 94 | |
| 95 | typedef void (*DeviceRealize)(DeviceState *dev, Error **errp); |
| 96 | typedef void (*DeviceUnrealize)(DeviceState *dev); |
| 97 | typedef void (*DeviceReset)(DeviceState *dev); |
| 98 | typedef void (*BusRealize)(BusState *bus, Error **errp); |
| 99 | typedef void (*BusUnrealize)(BusState *bus); |
| 100 | typedef int (*DeviceSyncConfig)(DeviceState *dev, Error **errp); |
| 101 | |
| 102 | /** |
| 103 | * struct DeviceClass - The base class for all devices. |
| 104 | * @props: Properties accessing state fields. |
| 105 | * @realize: Callback function invoked when the #DeviceState:realized |
| 106 | * property is changed to %true. |
| 107 | * @unrealize: Callback function invoked when the #DeviceState:realized |
| 108 | * property is changed to %false. |
| 109 | * @sync_config: Callback function invoked when QMP command device-sync-config |
| 110 | * is called. Should synchronize device configuration from host to guest part |
| 111 | * and notify the guest about the change. |
| 112 | * @hotpluggable: indicates if #DeviceClass is hotpluggable, available |
| 113 | * as readonly "hotpluggable" property of #DeviceState instance |
| 114 | * |
| 115 | */ |
| 116 | struct DeviceClass { |
| 117 | /* private: */ |
| 118 | ObjectClass parent_class; |
| 119 | |
| 120 | /* public: */ |
| 121 | |
| 122 | /** |
| 123 | * @categories: device categories device belongs to |
| 124 | */ |
| 125 | DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX); |
| 126 | /** |
| 127 | * @fw_name: name used to identify device to firmware interfaces |
| 128 | */ |
| 129 | const char *fw_name; |
| 130 | /** |
| 131 | * @desc: human readable description of device |
| 132 | */ |
| 133 | const char *desc; |
| 134 | |
| 135 | /** |
| 136 | * @props_: properties associated with device, should only be |
| 137 | * assigned by using device_class_set_props(). The underscore |
| 138 | * ensures a compile-time error if someone attempts to assign |
| 139 | * dc->props directly. |
| 140 | */ |
| 141 | const Property *props_; |
| 142 | |
| 143 | /** |
| 144 | * @props_count_: number of elements in @props_; should only be |
| 145 | * assigned by using device_class_set_props(). |
| 146 | */ |
| 147 | uint16_t props_count_; |
| 148 | |
| 149 | /** |
| 150 | * @user_creatable: Can user instantiate with -device / device_add? |
| 151 | * |
| 152 | * All devices should support instantiation with device_add, and |
| 153 | * this flag should not exist. But we're not there, yet. Some |
| 154 | * devices fail to instantiate with cryptic error messages. |
| 155 | * Others instantiate, but don't work. Exposing users to such |
| 156 | * behavior would be cruel; clearing this flag will protect them. |
| 157 | * It should never be cleared without a comment explaining why it |
| 158 | * is cleared. |
| 159 | * |
| 160 | * TODO remove once we're there |
| 161 | */ |
| 162 | bool user_creatable; |
| 163 | bool hotpluggable; |
| 164 | |
| 165 | /* callbacks */ |
| 166 | /** |
| 167 | * @legacy_reset: deprecated device reset method pointer |
| 168 | * |
| 169 | * Modern code should use the ResettableClass interface to |
| 170 | * implement a multi-phase reset. |
| 171 | * |
| 172 | * TODO: remove once every reset callback is unused |
| 173 | */ |
| 174 | DeviceReset legacy_reset; |
| 175 | DeviceRealize realize; |
| 176 | DeviceUnrealize unrealize; |
| 177 | DeviceSyncConfig sync_config; |
| 178 | |
| 179 | /** |
| 180 | * @vmsd: device state serialisation description for |
| 181 | * migration/save/restore |
| 182 | */ |
| 183 | const VMStateDescription *vmsd; |
| 184 | |
| 185 | /** |
| 186 | * @bus_type: bus type |
| 187 | * private: to qdev / bus. |
| 188 | */ |
| 189 | const char *bus_type; |
| 190 | }; |
| 191 | |
| 192 | typedef struct NamedGPIOList NamedGPIOList; |
| 193 | |
| 194 | struct NamedGPIOList { |
| 195 | char *name; |
| 196 | qemu_irq *in; |
| 197 | int num_in; |
| 198 | int num_out; |
| 199 | QLIST_ENTRY(NamedGPIOList) node; |
| 200 | }; |
| 201 | |
| 202 | typedef struct Clock Clock; |
| 203 | typedef struct NamedClockList NamedClockList; |
| 204 | |
| 205 | struct NamedClockList { |
| 206 | char *name; |
| 207 | Clock *clock; |
| 208 | bool output; |
| 209 | bool alias; |
| 210 | QLIST_ENTRY(NamedClockList) node; |
| 211 | }; |
| 212 | |
| 213 | typedef QLIST_HEAD(, NamedGPIOList) NamedGPIOListHead; |
| 214 | typedef QLIST_HEAD(, NamedClockList) NamedClockListHead; |
| 215 | typedef QLIST_HEAD(, BusState) BusStateHead; |
| 216 | |
| 217 | /** |
| 218 | * struct DeviceState - common device state, accessed with qdev helpers |
| 219 | * |
| 220 | * This structure should not be accessed directly. We declare it here |
| 221 | * so that it can be embedded in individual device state structures. |
| 222 | */ |
| 223 | struct DeviceState { |
| 224 | /* private: */ |
| 225 | Object parent_obj; |
| 226 | /* public: */ |
| 227 | |
| 228 | /** |
| 229 | * @id: global device id |
| 230 | */ |
| 231 | char *id; |
| 232 | /** |
| 233 | * @canonical_path: canonical path of realized device in the QOM tree |
| 234 | */ |
| 235 | char *canonical_path; |
| 236 | /** |
| 237 | * @realized: has device been realized? |
| 238 | */ |
| 239 | bool realized; |
| 240 | /** |
| 241 | * @pending_deleted_event: track pending deletion events during unplug |
| 242 | */ |
| 243 | bool pending_deleted_event; |
| 244 | /** |
| 245 | * @pending_deleted_expires_ms: optional timeout for deletion events |
| 246 | */ |
| 247 | int64_t pending_deleted_expires_ms; |
| 248 | /** |
| 249 | * @hotplugged: was device added after PHASE_MACHINE_READY? |
| 250 | */ |
| 251 | int hotplugged; |
| 252 | /** |
| 253 | * @allow_unplug_during_migration: can device be unplugged during migration |
| 254 | */ |
| 255 | bool allow_unplug_during_migration; |
| 256 | /** |
| 257 | * @parent_bus: bus this device belongs to |
| 258 | */ |
| 259 | BusState *parent_bus; |
| 260 | /** |
| 261 | * @gpios: QLIST of named GPIOs the device provides. |
| 262 | */ |
| 263 | NamedGPIOListHead gpios; |
| 264 | /** |
| 265 | * @clocks: QLIST of named clocks the device provides. |
| 266 | */ |
| 267 | NamedClockListHead clocks; |
| 268 | /** |
| 269 | * @child_bus: QLIST of child buses |
| 270 | */ |
| 271 | BusStateHead child_bus; |
| 272 | /** |
| 273 | * @num_child_bus: number of @child_bus entries |
| 274 | */ |
| 275 | int num_child_bus; |
| 276 | /** |
| 277 | * @instance_id_alias: device alias for handling legacy migration setups |
| 278 | */ |
| 279 | int instance_id_alias; |
| 280 | /** |
| 281 | * @alias_required_for_version: indicates @instance_id_alias is |
| 282 | * needed for migration |
| 283 | */ |
| 284 | int alias_required_for_version; |
| 285 | /** |
| 286 | * @reset: ResettableState for the device; handled by Resettable interface. |
| 287 | */ |
| 288 | ResettableState reset; |
| 289 | /** |
| 290 | * @unplug_blockers: list of reasons to block unplugging of device |
| 291 | */ |
| 292 | GSList *unplug_blockers; |
| 293 | /** |
| 294 | * @mem_reentrancy_guard: Is the device currently in mmio/pio/dma? |
| 295 | * |
| 296 | * Used to prevent re-entrancy confusing things. |
| 297 | */ |
| 298 | MemReentrancyGuard mem_reentrancy_guard; |
| 299 | }; |
| 300 | |
| 301 | typedef struct DeviceListener DeviceListener; |
| 302 | struct DeviceListener { |
| 303 | void (*realize)(DeviceListener *listener, DeviceState *dev); |
| 304 | void (*unrealize)(DeviceListener *listener, DeviceState *dev); |
| 305 | /* |
| 306 | * This callback is called upon init of the DeviceState and |
| 307 | * informs qdev if a device should be visible or hidden. We can |
| 308 | * hide a failover device depending for example on the device |
| 309 | * opts. |
| 310 | * |
| 311 | * On errors, it returns false and errp is set. Device creation |
| 312 | * should fail in this case. |
| 313 | */ |
| 314 | bool (*hide_device)(DeviceListener *listener, const QDict *device_opts, |
| 315 | bool from_json, Error **errp); |
| 316 | QTAILQ_ENTRY(DeviceListener) link; |
| 317 | }; |
| 318 | |
| 319 | #define TYPE_BUS "bus" |
| 320 | DECLARE_OBJ_CHECKERS(BusState, BusClass, |
| 321 | BUS, TYPE_BUS) |
| 322 | |
| 323 | struct BusClass { |
| 324 | ObjectClass parent_class; |
| 325 | |
| 326 | #ifdef CONFIG_HMP |
| 327 | /* FIXME first arg should be BusState */ |
| 328 | void (*print_dev)(MonitorHMP *mon, DeviceState *dev, int indent); |
| 329 | #endif |
| 330 | /* |
| 331 | * Return a newly allocated string containing the path of the |
| 332 | * device on this bus. |
| 333 | */ |
| 334 | char *(*get_dev_path)(DeviceState *dev); |
| 335 | |
| 336 | /* |
| 337 | * This callback is used to create Open Firmware device path in accordance |
| 338 | * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus |
| 339 | * bindings can be found at http://playground.sun.com/1275/bindings/. |
| 340 | */ |
| 341 | char *(*get_fw_dev_path)(DeviceState *dev); |
| 342 | |
| 343 | /* |
| 344 | * Return whether the device can be added to @bus, |
| 345 | * based on the address that was set (via device properties) |
| 346 | * before realize. If not, on return @errp contains the |
| 347 | * human-readable error message. |
| 348 | */ |
| 349 | bool (*check_address)(BusState *bus, DeviceState *dev, Error **errp); |
| 350 | |
| 351 | BusRealize realize; |
| 352 | BusUnrealize unrealize; |
| 353 | |
| 354 | /* maximum devices allowed on the bus, 0: no limit. */ |
| 355 | int max_dev; |
| 356 | /* number of automatically allocated bus ids (e.g. ide.0) */ |
| 357 | int automatic_ids; |
| 358 | }; |
| 359 | |
| 360 | typedef struct BusChild { |
| 361 | struct rcu_head rcu; |
| 362 | DeviceState *child; |
| 363 | int index; |
| 364 | QTAILQ_ENTRY(BusChild) sibling; |
| 365 | } BusChild; |
| 366 | |
| 367 | #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler" |
| 368 | |
| 369 | typedef QTAILQ_HEAD(, BusChild) BusChildHead; |
| 370 | typedef QLIST_ENTRY(BusState) BusStateEntry; |
| 371 | |
| 372 | /** |
| 373 | * struct BusState: |
| 374 | * @obj: parent object |
| 375 | * @parent: parent Device |
| 376 | * @name: name of bus |
| 377 | * @hotplug_handler: link to a hotplug handler associated with bus. |
| 378 | * @max_index: max number of child buses |
| 379 | * @realized: is the bus itself realized? |
| 380 | * @full: is the bus full? |
| 381 | * @num_children: current number of child buses |
| 382 | */ |
| 383 | struct BusState { |
| 384 | /* private: */ |
| 385 | Object obj; |
| 386 | /* public: */ |
| 387 | DeviceState *parent; |
| 388 | char *name; |
| 389 | HotplugHandler *hotplug_handler; |
| 390 | int max_index; |
| 391 | bool realized; |
| 392 | bool full; |
| 393 | int num_children; |
| 394 | |
| 395 | /** |
| 396 | * @children: an RCU protected QTAILQ, thus readers must use RCU |
| 397 | * to access it, and writers must hold the big qemu lock |
| 398 | */ |
| 399 | BusChildHead children; |
| 400 | /** |
| 401 | * @sibling: next bus |
| 402 | */ |
| 403 | BusStateEntry sibling; |
| 404 | /** |
| 405 | * @reset: ResettableState for the bus; handled by Resettable interface. |
| 406 | */ |
| 407 | ResettableState reset; |
| 408 | }; |
| 409 | |
| 410 | /*** Board API. This should go away once we have a machine config file. ***/ |
| 411 | |
| 412 | /** |
| 413 | * qdev_new: Create a device on the heap |
| 414 | * @name: device type to create (we assert() that this type exists) |
| 415 | * |
| 416 | * This only allocates the memory and initializes the device state |
| 417 | * structure, ready for the caller to set properties if they wish. |
| 418 | * The device still needs to be realized. |
| 419 | * |
| 420 | * Return: a derived DeviceState object with a reference count of 1. |
| 421 | */ |
| 422 | DeviceState *qdev_new(const char *name); |
| 423 | |
| 424 | /** |
| 425 | * qdev_try_new: Try to create a device on the heap |
| 426 | * @name: device type to create |
| 427 | * |
| 428 | * This is like qdev_new(), except it returns %NULL when type @name |
| 429 | * does not exist, rather than asserting. |
| 430 | * |
| 431 | * Return: a derived DeviceState object with a reference count of 1 or |
| 432 | * NULL if type @name does not exist. |
| 433 | */ |
| 434 | DeviceState *qdev_try_new(const char *name); |
| 435 | |
| 436 | /** |
| 437 | * qdev_is_realized() - check if device is realized |
| 438 | * @dev: The device to check. |
| 439 | * |
| 440 | * Context: May be called outside big qemu lock. |
| 441 | * Return: true if the device has been fully constructed, false otherwise. |
| 442 | */ |
| 443 | static inline bool qdev_is_realized(const DeviceState *dev) |
| 444 | { |
| 445 | return qatomic_load_acquire(&dev->realized); |
| 446 | } |
| 447 | |
| 448 | /** |
| 449 | * qdev_realize: Realize @dev. |
| 450 | * @dev: device to realize |
| 451 | * @bus: bus to plug it into (may be NULL) |
| 452 | * @errp: pointer to error object |
| 453 | * |
| 454 | * "Realize" the device, i.e. perform the second phase of device |
| 455 | * initialization. |
| 456 | * @dev must not be plugged into a bus already. |
| 457 | * If @bus, plug @dev into @bus. This takes a reference to @dev. |
| 458 | * If @dev has no QOM parent, make one up, taking another reference. |
| 459 | * |
| 460 | * If you created @dev using qdev_new(), you probably want to use |
| 461 | * qdev_realize_and_unref() instead. |
| 462 | * |
| 463 | * Return: true on success, else false setting @errp with error |
| 464 | */ |
| 465 | bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp); |
| 466 | |
| 467 | /** |
| 468 | * qdev_realize_and_unref: Realize @dev and drop a reference |
| 469 | * @dev: device to realize |
| 470 | * @bus: bus to plug it into (may be NULL) |
| 471 | * @errp: pointer to error object |
| 472 | * |
| 473 | * Realize @dev and drop a reference. |
| 474 | * This is like qdev_realize(), except the caller must hold a |
| 475 | * (private) reference, which is dropped on return regardless of |
| 476 | * success or failure. Intended use:: |
| 477 | * |
| 478 | * dev = qdev_new(); |
| 479 | * [...] |
| 480 | * qdev_realize_and_unref(dev, bus, errp); |
| 481 | * |
| 482 | * Now @dev can go away without further ado. |
| 483 | * |
| 484 | * If you are embedding the device into some other QOM device and |
| 485 | * initialized it via some variant on object_initialize_child() then |
| 486 | * do not use this function, because that family of functions arrange |
| 487 | * for the only reference to the child device to be held by the parent |
| 488 | * via the child<> property, and so the reference-count-drop done here |
| 489 | * would be incorrect. For that use case you want qdev_realize(). |
| 490 | * |
| 491 | * Return: true on success, else false setting @errp with error |
| 492 | */ |
| 493 | bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); |
| 494 | |
| 495 | /** |
| 496 | * qdev_unrealize: Unrealize a device |
| 497 | * @dev: device to unrealize |
| 498 | * |
| 499 | * This function will "unrealize" a device, which is the first phase |
| 500 | * of correctly destroying a device that has been realized. It will: |
| 501 | * |
| 502 | * - unrealize any child buses by calling qbus_unrealize() |
| 503 | * (this will recursively unrealize any devices on those buses) |
| 504 | * - call the unrealize method of @dev |
| 505 | * |
| 506 | * The device can then be freed by causing its reference count to go |
| 507 | * to zero. |
| 508 | * |
| 509 | * Warning: most devices in QEMU do not expect to be unrealized. Only |
| 510 | * devices which are hot-unpluggable should be unrealized (as part of |
| 511 | * the unplugging process); all other devices are expected to last for |
| 512 | * the life of the simulation and should not be unrealized and freed. |
| 513 | */ |
| 514 | void qdev_unrealize(DeviceState *dev); |
| 515 | void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id, |
| 516 | int required_for_version); |
| 517 | HotplugHandler *qdev_get_bus_hotplug_handler(DeviceState *dev); |
| 518 | HotplugHandler *qdev_get_machine_hotplug_handler(DeviceState *dev); |
| 519 | bool qdev_hotplug_allowed(DeviceState *dev, BusState *bus, Error **errp); |
| 520 | bool qdev_hotunplug_allowed(DeviceState *dev, Error **errp); |
| 521 | |
| 522 | /** |
| 523 | * qdev_get_hotplug_handler() - Get handler responsible for device wiring |
| 524 | * @dev: the device we want the HOTPLUG_HANDLER for. |
| 525 | * |
| 526 | * Note: in case @dev has a parent bus, it will be returned as handler unless |
| 527 | * machine handler overrides it. |
| 528 | * |
| 529 | * Return: pointer to object that implements TYPE_HOTPLUG_HANDLER interface |
| 530 | * or NULL if there aren't any. |
| 531 | */ |
| 532 | HotplugHandler *qdev_get_hotplug_handler(DeviceState *dev); |
| 533 | void qdev_unplug(DeviceState *dev, Error **errp); |
| 534 | int qdev_sync_config(DeviceState *dev, Error **errp); |
| 535 | void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev, |
| 536 | DeviceState *dev, Error **errp); |
| 537 | void qdev_machine_creation_done(void); |
| 538 | bool qdev_machine_modified(void); |
| 539 | |
| 540 | /** |
| 541 | * qdev_add_unplug_blocker: Add an unplug blocker to a device |
| 542 | * |
| 543 | * @dev: Device to be blocked from unplug |
| 544 | * @reason: Reason for blocking |
| 545 | */ |
| 546 | void qdev_add_unplug_blocker(DeviceState *dev, Error *reason); |
| 547 | |
| 548 | /** |
| 549 | * qdev_del_unplug_blocker: Remove an unplug blocker from a device |
| 550 | * |
| 551 | * @dev: Device to be unblocked |
| 552 | * @reason: Pointer to the Error used with qdev_add_unplug_blocker. |
| 553 | * Used as a handle to lookup the blocker for deletion. |
| 554 | */ |
| 555 | void qdev_del_unplug_blocker(DeviceState *dev, Error *reason); |
| 556 | |
| 557 | /** |
| 558 | * qdev_unplug_blocked: Confirm if a device is blocked from unplug |
| 559 | * |
| 560 | * @dev: Device to be tested |
| 561 | * @errp: The reasons why the device is blocked, if any |
| 562 | * |
| 563 | * Returns: true (also setting @errp) if device is blocked from unplug, |
| 564 | * false otherwise |
| 565 | */ |
| 566 | bool qdev_unplug_blocked(DeviceState *dev, Error **errp); |
| 567 | |
| 568 | /** |
| 569 | * typedef GpioPolarity - Polarity of a GPIO line |
| 570 | * |
| 571 | * GPIO lines use either positive (active-high) logic, |
| 572 | * or negative (active-low) logic. |
| 573 | * |
| 574 | * In active-high logic (%GPIO_POLARITY_ACTIVE_HIGH), a pin is |
| 575 | * active when the voltage on the pin is high (relative to ground); |
| 576 | * whereas in active-low logic (%GPIO_POLARITY_ACTIVE_LOW), a pin |
| 577 | * is active when the voltage on the pin is low (or grounded). |
| 578 | */ |
| 579 | typedef enum { |
| 580 | GPIO_POLARITY_ACTIVE_LOW, |
| 581 | GPIO_POLARITY_ACTIVE_HIGH |
| 582 | } GpioPolarity; |
| 583 | |
| 584 | /** |
| 585 | * qdev_get_gpio_in: Get one of a device's anonymous input GPIO lines |
| 586 | * @dev: Device whose GPIO we want |
| 587 | * @n: Number of the anonymous GPIO line (which must be in range) |
| 588 | * |
| 589 | * Returns the qemu_irq corresponding to an anonymous input GPIO line |
| 590 | * (which the device has set up with qdev_init_gpio_in()). The index |
| 591 | * @n of the GPIO line must be valid (i.e. be at least 0 and less than |
| 592 | * the total number of anonymous input GPIOs the device has); this |
| 593 | * function will assert() if passed an invalid index. |
| 594 | * |
| 595 | * This function is intended to be used by board code or SoC "container" |
| 596 | * device models to wire up the GPIO lines; usually the return value |
| 597 | * will be passed to qdev_connect_gpio_out() or a similar function to |
| 598 | * connect another device's output GPIO line to this input. |
| 599 | * |
| 600 | * For named input GPIO lines, use qdev_get_gpio_in_named(). |
| 601 | * |
| 602 | * Return: qemu_irq corresponding to anonymous input GPIO line |
| 603 | */ |
| 604 | qemu_irq qdev_get_gpio_in(DeviceState *dev, int n); |
| 605 | |
| 606 | /** |
| 607 | * qdev_get_gpio_in_named: Get one of a device's named input GPIO lines |
| 608 | * @dev: Device whose GPIO we want |
| 609 | * @name: Name of the input GPIO array |
| 610 | * @n: Number of the GPIO line in that array (which must be in range) |
| 611 | * |
| 612 | * Returns the qemu_irq corresponding to a single input GPIO line |
| 613 | * in a named array of input GPIO lines on a device (which the device |
| 614 | * has set up with qdev_init_gpio_in_named()). |
| 615 | * The @name string must correspond to an input GPIO array which exists on |
| 616 | * the device, and the index @n of the GPIO line must be valid (i.e. |
| 617 | * be at least 0 and less than the total number of input GPIOs in that |
| 618 | * array); this function will assert() if passed an invalid name or index. |
| 619 | * |
| 620 | * For anonymous input GPIO lines, use qdev_get_gpio_in(). |
| 621 | * |
| 622 | * Return: qemu_irq corresponding to named input GPIO line |
| 623 | */ |
| 624 | qemu_irq qdev_get_gpio_in_named(DeviceState *dev, const char *name, int n); |
| 625 | |
| 626 | /** |
| 627 | * qdev_connect_gpio_out: Connect one of a device's anonymous output GPIO lines |
| 628 | * @dev: Device whose GPIO to connect |
| 629 | * @n: Number of the anonymous output GPIO line (which must be in range) |
| 630 | * @pin: qemu_irq to connect the output line to |
| 631 | * |
| 632 | * This function connects an anonymous output GPIO line on a device |
| 633 | * up to an arbitrary qemu_irq, so that when the device asserts that |
| 634 | * output GPIO line, the qemu_irq's callback is invoked. |
| 635 | * The index @n of the GPIO line must be valid (i.e. be at least 0 and |
| 636 | * less than the total number of anonymous output GPIOs the device has |
| 637 | * created with qdev_init_gpio_out()); otherwise this function will assert(). |
| 638 | * |
| 639 | * Outbound GPIO lines can be connected to any qemu_irq, but the common |
| 640 | * case is connecting them to another device's inbound GPIO line, using |
| 641 | * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named(). |
| 642 | * |
| 643 | * It is not valid to try to connect one outbound GPIO to multiple |
| 644 | * qemu_irqs at once, or to connect multiple outbound GPIOs to the |
| 645 | * same qemu_irq. (Warning: there is no assertion or other guard to |
| 646 | * catch this error: the model will just not do the right thing.) |
| 647 | * Instead, for fan-out you can use the TYPE_SPLIT_IRQ device: connect |
| 648 | * a device's outbound GPIO to the splitter's input, and connect each |
| 649 | * of the splitter's outputs to a different device. For fan-in you |
| 650 | * can use the TYPE_OR_IRQ device, which is a model of a logical OR |
| 651 | * gate with multiple inputs and one output. |
| 652 | * |
| 653 | * For named output GPIO lines, use qdev_connect_gpio_out_named(). |
| 654 | */ |
| 655 | void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin); |
| 656 | |
| 657 | /** |
| 658 | * qdev_connect_gpio_out_named: Connect one of a device's named output |
| 659 | * GPIO lines |
| 660 | * @dev: Device whose GPIO to connect |
| 661 | * @name: Name of the output GPIO array |
| 662 | * @n: Number of the output GPIO line within that array (which must be in range) |
| 663 | * @input_pin: qemu_irq to connect the output line to |
| 664 | * |
| 665 | * This function connects a single GPIO output in a named array of output |
| 666 | * GPIO lines on a device up to an arbitrary qemu_irq, so that when the |
| 667 | * device asserts that output GPIO line, the qemu_irq's callback is invoked. |
| 668 | * The @name string must correspond to an output GPIO array which exists on |
| 669 | * the device, and the index @n of the GPIO line must be valid (i.e. |
| 670 | * be at least 0 and less than the total number of output GPIOs in that |
| 671 | * array); this function will assert() if passed an invalid name or index. |
| 672 | * |
| 673 | * Outbound GPIO lines can be connected to any qemu_irq, but the common |
| 674 | * case is connecting them to another device's inbound GPIO line, using |
| 675 | * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named(). |
| 676 | * |
| 677 | * It is not valid to try to connect one outbound GPIO to multiple |
| 678 | * qemu_irqs at once, or to connect multiple outbound GPIOs to the |
| 679 | * same qemu_irq; see qdev_connect_gpio_out() for details. |
| 680 | * |
| 681 | * For anonymous output GPIO lines, use qdev_connect_gpio_out(). |
| 682 | */ |
| 683 | void qdev_connect_gpio_out_named(DeviceState *dev, const char *name, int n, |
| 684 | qemu_irq input_pin); |
| 685 | |
| 686 | /** |
| 687 | * qdev_get_gpio_out_connector: Get the qemu_irq connected to an output GPIO |
| 688 | * @dev: Device whose output GPIO we are interested in |
| 689 | * @name: Name of the output GPIO array |
| 690 | * @n: Number of the output GPIO line within that array |
| 691 | * |
| 692 | * Returns whatever qemu_irq is currently connected to the specified |
| 693 | * output GPIO line of @dev. This will be NULL if the output GPIO line |
| 694 | * has never been wired up to the anything. Note that the qemu_irq |
| 695 | * returned does not belong to @dev -- it will be the input GPIO or |
| 696 | * IRQ of whichever device the board code has connected up to @dev's |
| 697 | * output GPIO. |
| 698 | * |
| 699 | * You probably don't need to use this function -- it is used only |
| 700 | * by the platform-bus subsystem. |
| 701 | * |
| 702 | * Return: qemu_irq associated with GPIO or NULL if un-wired. |
| 703 | */ |
| 704 | qemu_irq qdev_get_gpio_out_connector(const DeviceState *dev, |
| 705 | const char *name, int n); |
| 706 | |
| 707 | /** |
| 708 | * qdev_intercept_gpio_out: Intercept an existing GPIO connection |
| 709 | * @dev: Device to intercept the outbound GPIO line from |
| 710 | * @icpt: New qemu_irq to connect instead |
| 711 | * @name: Name of the output GPIO array |
| 712 | * @n: Number of the GPIO line in the array |
| 713 | * |
| 714 | * .. note:: |
| 715 | * This function is provided only for use by the qtest testing framework |
| 716 | * and is not suitable for use in non-testing parts of QEMU. |
| 717 | * |
| 718 | * This function breaks an existing connection of an outbound GPIO |
| 719 | * line from @dev, and replaces it with the new qemu_irq @icpt, as if |
| 720 | * ``qdev_connect_gpio_out_named(dev, icpt, name, n)`` had been called. |
| 721 | * The previously connected qemu_irq is returned, so it can be restored |
| 722 | * by a second call to qdev_intercept_gpio_out() if desired. |
| 723 | * |
| 724 | * Return: old disconnected qemu_irq if one existed |
| 725 | */ |
| 726 | qemu_irq qdev_intercept_gpio_out(DeviceState *dev, qemu_irq icpt, |
| 727 | const char *name, int n); |
| 728 | |
| 729 | BusState *qdev_get_child_bus(DeviceState *dev, const char *name); |
| 730 | |
| 731 | /*** Device API. ***/ |
| 732 | |
| 733 | /** |
| 734 | * qdev_init_gpio_in: create an array of anonymous input GPIO lines |
| 735 | * @dev: Device to create input GPIOs for |
| 736 | * @handler: Function to call when GPIO line value is set |
| 737 | * @n: Number of GPIO lines to create |
| 738 | * |
| 739 | * Devices should use functions in the qdev_init_gpio_in* family in |
| 740 | * their instance_init or realize methods to create any input GPIO |
| 741 | * lines they need. There is no functional difference between |
| 742 | * anonymous and named GPIO lines. Stylistically, named GPIOs are |
| 743 | * preferable (easier to understand at callsites) unless a device |
| 744 | * has exactly one uniform kind of GPIO input whose purpose is obvious. |
| 745 | * Note that input GPIO lines can serve as 'sinks' for IRQ lines. |
| 746 | * |
| 747 | * See qdev_get_gpio_in() for how code that uses such a device can get |
| 748 | * hold of an input GPIO line to manipulate it. |
| 749 | */ |
| 750 | void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n); |
| 751 | |
| 752 | /** |
| 753 | * qdev_init_gpio_out: create an array of anonymous output GPIO lines |
| 754 | * @dev: Device to create output GPIOs for |
| 755 | * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines |
| 756 | * @n: Number of GPIO lines to create |
| 757 | * |
| 758 | * Devices should use functions in the qdev_init_gpio_out* family |
| 759 | * in their instance_init or realize methods to create any output |
| 760 | * GPIO lines they need. There is no functional difference between |
| 761 | * anonymous and named GPIO lines. Stylistically, named GPIOs are |
| 762 | * preferable (easier to understand at callsites) unless a device |
| 763 | * has exactly one uniform kind of GPIO output whose purpose is obvious. |
| 764 | * |
| 765 | * The @pins argument should be a pointer to either a "qemu_irq" |
| 766 | * (if @n == 1) or a "qemu_irq []" array (if @n > 1) in the device's |
| 767 | * state structure. The device implementation can then raise and |
| 768 | * lower the GPIO line by calling qemu_set_irq(). (If anything is |
| 769 | * connected to the other end of the GPIO this will cause the handler |
| 770 | * function for that input GPIO to be called.) |
| 771 | * |
| 772 | * See qdev_connect_gpio_out() for how code that uses such a device |
| 773 | * can connect to one of its output GPIO lines. |
| 774 | * |
| 775 | * There is no need to release the @pins allocated array because it |
| 776 | * will be automatically released when @dev calls its instance_finalize() |
| 777 | * handler. |
| 778 | */ |
| 779 | void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n); |
| 780 | |
| 781 | /** |
| 782 | * qdev_init_gpio_out_named: create an array of named output GPIO lines |
| 783 | * @dev: Device to create output GPIOs for |
| 784 | * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines |
| 785 | * @name: Name to give this array of GPIO lines |
| 786 | * @n: Number of GPIO lines to create in this array |
| 787 | * |
| 788 | * Like qdev_init_gpio_out(), but creates an array of GPIO output lines |
| 789 | * with a name. Code using the device can then connect these GPIO lines |
| 790 | * using qdev_connect_gpio_out_named(). |
| 791 | */ |
| 792 | void qdev_init_gpio_out_named(DeviceState *dev, qemu_irq *pins, |
| 793 | const char *name, int n); |
| 794 | |
| 795 | /** |
| 796 | * qdev_init_gpio_in_named_with_opaque() - create an array of input GPIO lines |
| 797 | * @dev: Device to create input GPIOs for |
| 798 | * @handler: Function to call when GPIO line value is set |
| 799 | * @opaque: Opaque data pointer to pass to @handler |
| 800 | * @name: Name of the GPIO input (must be unique for this device) |
| 801 | * @n: Number of GPIO lines in this input set |
| 802 | */ |
| 803 | void qdev_init_gpio_in_named_with_opaque(DeviceState *dev, |
| 804 | qemu_irq_handler handler, |
| 805 | void *opaque, |
| 806 | const char *name, int n); |
| 807 | |
| 808 | /** |
| 809 | * qdev_init_gpio_in_named() - create an array of input GPIO lines |
| 810 | * @dev: device to add array to |
| 811 | * @handler: a &typedef qemu_irq_handler function to call when GPIO is set |
| 812 | * @name: Name of the GPIO input (must be unique for this device) |
| 813 | * @n: Number of GPIO lines in this input set |
| 814 | * |
| 815 | * Like qdev_init_gpio_in_named_with_opaque(), but the opaque pointer |
| 816 | * passed to the handler is @dev (which is the most commonly desired behaviour). |
| 817 | */ |
| 818 | static inline void qdev_init_gpio_in_named(DeviceState *dev, |
| 819 | qemu_irq_handler handler, |
| 820 | const char *name, int n) |
| 821 | { |
| 822 | qdev_init_gpio_in_named_with_opaque(dev, handler, dev, name, n); |
| 823 | } |
| 824 | |
| 825 | /** |
| 826 | * qdev_pass_gpios: create GPIO lines on container which pass through to device |
| 827 | * @dev: Device which has GPIO lines |
| 828 | * @container: Container device which needs to expose them |
| 829 | * @name: Name of GPIO array to pass through (NULL for the anonymous GPIO array) |
| 830 | * |
| 831 | * In QEMU, complicated devices like SoCs are often modelled with a |
| 832 | * "container" QOM device which itself contains other QOM devices and |
| 833 | * which wires them up appropriately. This function allows the container |
| 834 | * to create GPIO arrays on itself which simply pass through to a GPIO |
| 835 | * array of one of its internal devices. |
| 836 | * |
| 837 | * If @dev has both input and output GPIOs named @name then both will |
| 838 | * be passed through. It is not possible to pass a subset of the array |
| 839 | * with this function. |
| 840 | * |
| 841 | * To users of the container device, the GPIO array created on @container |
| 842 | * behaves exactly like any other. |
| 843 | */ |
| 844 | void qdev_pass_gpios(DeviceState *dev, DeviceState *container, |
| 845 | const char *name); |
| 846 | |
| 847 | BusState *qdev_get_parent_bus(const DeviceState *dev); |
| 848 | |
| 849 | /*** BUS API. ***/ |
| 850 | |
| 851 | DeviceState *qdev_find_recursive(BusState *bus, const char *id); |
| 852 | |
| 853 | /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */ |
| 854 | typedef int (qbus_walkerfn)(BusState *bus, void *opaque); |
| 855 | typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque); |
| 856 | |
| 857 | void qbus_init(void *bus, size_t size, const char *typename, |
| 858 | DeviceState *parent, const char *name); |
| 859 | BusState *qbus_new(const char *typename, DeviceState *parent, const char *name); |
| 860 | bool qbus_realize(BusState *bus, Error **errp); |
| 861 | void qbus_unrealize(BusState *bus); |
| 862 | |
| 863 | /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion, |
| 864 | * < 0 if either devfn or busfn terminate walk somewhere in cursion, |
| 865 | * 0 otherwise. */ |
| 866 | int qbus_walk_children(BusState *bus, |
| 867 | qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn, |
| 868 | qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn, |
| 869 | void *opaque); |
| 870 | int qdev_walk_children(DeviceState *dev, |
| 871 | qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn, |
| 872 | qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn, |
| 873 | void *opaque); |
| 874 | |
| 875 | /** |
| 876 | * device_cold_reset() - perform a recursive cold reset on a device |
| 877 | * @dev: device to reset. |
| 878 | * |
| 879 | * Reset device @dev and perform a recursive processing using the resettable |
| 880 | * interface. It triggers a RESET_TYPE_COLD. |
| 881 | */ |
| 882 | void device_cold_reset(DeviceState *dev); |
| 883 | |
| 884 | /** |
| 885 | * bus_cold_reset() - perform a recursive cold reset on a bus |
| 886 | * @bus: bus to reset |
| 887 | * |
| 888 | * Reset bus @bus and perform a recursive processing using the resettable |
| 889 | * interface. It triggers a RESET_TYPE_COLD. |
| 890 | */ |
| 891 | void bus_cold_reset(BusState *bus); |
| 892 | |
| 893 | /** |
| 894 | * device_is_in_reset() - check device reset state |
| 895 | * @dev: device to check |
| 896 | * |
| 897 | * Return: true if the device @dev is currently being reset. |
| 898 | */ |
| 899 | bool device_is_in_reset(DeviceState *dev); |
| 900 | |
| 901 | /** |
| 902 | * bus_is_in_reset() - check bus reset state |
| 903 | * @bus: bus to check |
| 904 | * |
| 905 | * Return: true if the bus @bus is currently being reset. |
| 906 | */ |
| 907 | bool bus_is_in_reset(BusState *bus); |
| 908 | |
| 909 | /* This should go away once we get rid of the NULL bus hack */ |
| 910 | BusState *sysbus_get_default(void); |
| 911 | |
| 912 | char *qdev_get_fw_dev_path(DeviceState *dev); |
| 913 | char *qdev_get_own_fw_dev_path_from_handler(BusState *bus, DeviceState *dev); |
| 914 | |
| 915 | /** |
| 916 | * device_class_set_props(): add a set of properties to an device |
| 917 | * @dc: the parent DeviceClass all devices inherit |
| 918 | * @props: an array of properties |
| 919 | * |
| 920 | * This will add a set of properties to the object. It will fault if |
| 921 | * you attempt to add an existing property defined by a parent class. |
| 922 | * To modify an inherited property you need to use???? |
| 923 | * |
| 924 | * Validate that @props has at least one Property. |
| 925 | * Validate that @props is an array, not a pointer, via ARRAY_SIZE. |
| 926 | * Validate that the array does not have a legacy terminator at compile-time; |
| 927 | * requires -O2 and the array to be const. |
| 928 | */ |
| 929 | #define device_class_set_props(dc, props) \ |
| 930 | do { \ |
| 931 | QEMU_BUILD_BUG_ON(sizeof(props) == 0); \ |
| 932 | size_t props_count_ = ARRAY_SIZE(props); \ |
| 933 | if ((props)[props_count_ - 1].name == NULL) { \ |
| 934 | qemu_build_not_reached(); \ |
| 935 | } \ |
| 936 | device_class_set_props_n((dc), (props), props_count_); \ |
| 937 | } while (0) |
| 938 | |
| 939 | /** |
| 940 | * device_class_set_props_n(): add a set of properties to an device |
| 941 | * @dc: the parent DeviceClass all devices inherit |
| 942 | * @props: an array of properties |
| 943 | * @n: ARRAY_SIZE(@props) |
| 944 | * |
| 945 | * This will add a set of properties to the object. It will fault if |
| 946 | * you attempt to add an existing property defined by a parent class. |
| 947 | * To modify an inherited property you need to use???? |
| 948 | */ |
| 949 | void device_class_set_props_n(DeviceClass *dc, const Property *props, size_t n); |
| 950 | |
| 951 | /** |
| 952 | * device_class_set_parent_realize() - set up for chaining realize fns |
| 953 | * @dc: The device class |
| 954 | * @dev_realize: the device realize function |
| 955 | * @parent_realize: somewhere to save the parents realize function |
| 956 | * |
| 957 | * This is intended to be used when the new realize function will |
| 958 | * eventually call its parent realization function during creation. |
| 959 | * This requires storing the function call somewhere (usually in the |
| 960 | * instance structure) so you can eventually call |
| 961 | * dc->parent_realize(dev, errp) |
| 962 | */ |
| 963 | void device_class_set_parent_realize(DeviceClass *dc, |
| 964 | DeviceRealize dev_realize, |
| 965 | DeviceRealize *parent_realize); |
| 966 | |
| 967 | /** |
| 968 | * device_class_set_legacy_reset(): set the DeviceClass::reset method |
| 969 | * @dc: The device class |
| 970 | * @dev_reset: the reset function |
| 971 | * |
| 972 | * This function sets the DeviceClass::reset method. This is widely |
| 973 | * used in existing code, but new code should prefer to use the |
| 974 | * Resettable API as documented in docs/devel/reset.rst. |
| 975 | * In addition, devices which need to chain to their parent class's |
| 976 | * reset methods or which need to be subclassed must use Resettable. |
| 977 | */ |
| 978 | void device_class_set_legacy_reset(DeviceClass *dc, |
| 979 | DeviceReset dev_reset); |
| 980 | |
| 981 | /** |
| 982 | * device_class_set_parent_unrealize() - set up for chaining unrealize fns |
| 983 | * @dc: The device class |
| 984 | * @dev_unrealize: the device realize function |
| 985 | * @parent_unrealize: somewhere to save the parents unrealize function |
| 986 | * |
| 987 | * This is intended to be used when the new unrealize function will |
| 988 | * eventually call its parent unrealization function during the |
| 989 | * unrealize phase. This requires storing the function call somewhere |
| 990 | * (usually in the instance structure) so you can eventually call |
| 991 | * dc->parent_unrealize(dev); |
| 992 | */ |
| 993 | void device_class_set_parent_unrealize(DeviceClass *dc, |
| 994 | DeviceUnrealize dev_unrealize, |
| 995 | DeviceUnrealize *parent_unrealize); |
| 996 | |
| 997 | const VMStateDescription *qdev_get_vmsd(DeviceState *dev); |
| 998 | |
| 999 | const char *qdev_fw_name(DeviceState *dev); |
| 1000 | |
| 1001 | void qdev_assert_realized_properly(void); |
| 1002 | Object *qdev_get_machine(void); |
| 1003 | |
| 1004 | /** |
| 1005 | * qdev_create_fake_machine(): Create a fake machine container. |
| 1006 | * |
| 1007 | * .. note:: |
| 1008 | * This function is a kludge for user emulation (USER_ONLY) |
| 1009 | * because when thread (TYPE_CPU) are realized, qdev_realize() |
| 1010 | * access a machine container. |
| 1011 | */ |
| 1012 | void qdev_create_fake_machine(void); |
| 1013 | |
| 1014 | /** |
| 1015 | * machine_get_container: |
| 1016 | * @name: The name of container to lookup |
| 1017 | * |
| 1018 | * Get a container of the machine (QOM path "/machine/NAME"). |
| 1019 | * |
| 1020 | * Returns: the machine container object. |
| 1021 | */ |
| 1022 | Object *machine_get_container(const char *name); |
| 1023 | |
| 1024 | /** |
| 1025 | * qdev_get_human_name() - Return a human-readable name for a device |
| 1026 | * @dev: The device. Must be a valid and non-NULL pointer. |
| 1027 | * |
| 1028 | * Returns: A newly allocated string suitable for user-facing error |
| 1029 | * messages. |
| 1030 | * |
| 1031 | * Return the device's ID if it has one. Else, return the path of a |
| 1032 | * device on its bus if it has one. Else return its canonical QOM |
| 1033 | * path. |
| 1034 | */ |
| 1035 | char *qdev_get_human_name(DeviceState *dev); |
| 1036 | |
| 1037 | /* FIXME: make this a link<> */ |
| 1038 | bool qdev_set_parent_bus(DeviceState *dev, BusState *bus, Error **errp); |
| 1039 | |
| 1040 | extern bool qdev_hot_removed; |
| 1041 | |
| 1042 | /** |
| 1043 | * qdev_get_dev_path(): Return the path of a device on its bus |
| 1044 | * @dev: device to get the path of |
| 1045 | * |
| 1046 | * Returns: A newly allocated string containing the dev path of |
| 1047 | * @dev. The caller must free this with g_free(). |
| 1048 | * The format of the string depends on the bus; for instance a |
| 1049 | * PCI device's path will be in the format:: |
| 1050 | * |
| 1051 | * Domain:00:Slot.Function:Slot.Function....:Slot.Function |
| 1052 | * |
| 1053 | * and a SCSI device's path will be:: |
| 1054 | * |
| 1055 | * channel:ID:LUN |
| 1056 | * |
| 1057 | * (possibly prefixed by the path of the SCSI controller). |
| 1058 | * |
| 1059 | * If @dev is NULL or not on a bus, returns NULL. |
| 1060 | */ |
| 1061 | char *qdev_get_dev_path(DeviceState *dev); |
| 1062 | |
| 1063 | void qbus_set_hotplug_handler(BusState *bus, Object *handler); |
| 1064 | void qbus_set_bus_hotplug_handler(BusState *bus); |
| 1065 | |
| 1066 | static inline bool qbus_is_hotpluggable(BusState *bus) |
| 1067 | { |
| 1068 | HotplugHandler *plug_handler = bus->hotplug_handler; |
| 1069 | bool ret = !!plug_handler; |
| 1070 | |
| 1071 | if (plug_handler) { |
| 1072 | HotplugHandlerClass *hdc; |
| 1073 | |
| 1074 | hdc = HOTPLUG_HANDLER_GET_CLASS(plug_handler); |
| 1075 | if (hdc->is_hotpluggable_bus) { |
| 1076 | ret = hdc->is_hotpluggable_bus(plug_handler, bus); |
| 1077 | } |
| 1078 | } |
| 1079 | return ret; |
| 1080 | } |
| 1081 | |
| 1082 | /** |
| 1083 | * qbus_mark_full: Mark this bus as full, so no more devices can be attached |
| 1084 | * @bus: Bus to mark as full |
| 1085 | * |
| 1086 | * By default, QEMU will allow devices to be plugged into a bus up |
| 1087 | * to the bus class's device count limit. Calling this function |
| 1088 | * marks a particular bus as full, so that no more devices can be |
| 1089 | * plugged into it. In particular this means that the bus will not |
| 1090 | * be considered as a candidate for plugging in devices created by |
| 1091 | * the user on the commandline or via the monitor. |
| 1092 | * If a machine has multiple buses of a given type, such as I2C, |
| 1093 | * where some of those buses in the real hardware are used only for |
| 1094 | * internal devices and some are exposed via expansion ports, you |
| 1095 | * can use this function to mark the internal-only buses as full |
| 1096 | * after you have created all their internal devices. Then user |
| 1097 | * created devices will appear on the expansion-port bus where |
| 1098 | * guest software expects them. |
| 1099 | */ |
| 1100 | static inline void qbus_mark_full(BusState *bus) |
| 1101 | { |
| 1102 | bus->full = true; |
| 1103 | } |
| 1104 | |
| 1105 | void device_listener_register(DeviceListener *listener); |
| 1106 | void device_listener_unregister(DeviceListener *listener); |
| 1107 | |
| 1108 | /** |
| 1109 | * qdev_should_hide_device() - check if device should be hidden |
| 1110 | * |
| 1111 | * @opts: options QDict |
| 1112 | * @from_json: true if @opts entries are typed, false for all strings |
| 1113 | * @errp: pointer to error object |
| 1114 | * |
| 1115 | * When a device is added via qdev_device_add() this will be called. |
| 1116 | * |
| 1117 | * Return: if the device should be added now or not. |
| 1118 | */ |
| 1119 | bool qdev_should_hide_device(const QDict *opts, bool from_json, Error **errp); |
| 1120 | |
| 1121 | typedef enum MachineInitPhase { |
| 1122 | /* current_machine is NULL. */ |
| 1123 | PHASE_NO_MACHINE, |
| 1124 | |
| 1125 | /* current_machine is not NULL, but current_machine->accel is NULL. */ |
| 1126 | PHASE_MACHINE_CREATED, |
| 1127 | |
| 1128 | /* |
| 1129 | * current_machine->accel is not NULL, but the machine properties have |
| 1130 | * not been validated and machine_class->init has not yet been called. |
| 1131 | */ |
| 1132 | PHASE_ACCEL_CREATED, |
| 1133 | |
| 1134 | /* |
| 1135 | * Late backend objects have been created and initialized. |
| 1136 | */ |
| 1137 | PHASE_LATE_BACKENDS_CREATED, |
| 1138 | |
| 1139 | /* |
| 1140 | * machine_class->init has been called, thus creating any embedded |
| 1141 | * devices and validating machine properties. Devices created at |
| 1142 | * this time are considered to be cold-plugged. |
| 1143 | */ |
| 1144 | PHASE_MACHINE_INITIALIZED, |
| 1145 | |
| 1146 | /* |
| 1147 | * QEMU is ready to start CPUs and devices created at this time |
| 1148 | * are considered to be hot-plugged. The monitor is not restricted |
| 1149 | * to "preconfig" commands. |
| 1150 | */ |
| 1151 | PHASE_MACHINE_READY, |
| 1152 | } MachineInitPhase; |
| 1153 | |
| 1154 | bool phase_check(MachineInitPhase phase); |
| 1155 | void phase_advance(MachineInitPhase phase); |
| 1156 | |
| 1157 | #endif |