qdev.h 22.3 KB
Newer Older
Paul Brook's avatar
Paul Brook committed
1 2 3 4
#ifndef QDEV_H
#define QDEV_H

#include "hw.h"
Blue Swirl's avatar
Blue Swirl committed
5
#include "qemu-queue.h"
6
#include "qemu-char.h"
Gerd Hoffmann's avatar
Gerd Hoffmann committed
7
#include "qemu-option.h"
8
#include "qapi/qapi-visit-core.h"
9
#include "qemu/object.h"
Paul Brook's avatar
Paul Brook committed
10

11 12 13
typedef struct Property Property;

typedef struct PropertyInfo PropertyInfo;
Paul Brook's avatar
Paul Brook committed
14

15 16
typedef struct CompatProperty CompatProperty;

17
typedef struct DeviceInfo DeviceInfo;
Paul Brook's avatar
Paul Brook committed
18

Paul Brook's avatar
Paul Brook committed
19
typedef struct BusState BusState;
Paul Brook's avatar
Paul Brook committed
20

21 22
typedef struct BusInfo BusInfo;

Gerd Hoffmann's avatar
Gerd Hoffmann committed
23 24 25 26 27
enum DevState {
    DEV_STATE_CREATED = 1,
    DEV_STATE_INITIALIZED,
};

28 29 30 31
enum {
    DEV_NVECTORS_UNSPECIFIED = -1,
};

32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
/**
 * @DevicePropertyAccessor - called when trying to get/set a property
 *
 * @dev the device that owns the property
 * @v the visitor that contains the property data
 * @opaque the device property opaque
 * @name the name of the property
 * @errp a pointer to an Error that is filled if getting/setting fails.
 */
typedef void (DevicePropertyAccessor)(DeviceState *dev,
                                      Visitor *v,
                                      void *opaque,
                                      const char *name,
                                      Error **errp);

/**
 * @DevicePropertyRelease - called when a property is removed from a device
 *
 * @dev the device that owns the property
 * @name the name of the property
 * @opaque the opaque registered with the property
 */
typedef void (DevicePropertyRelease)(DeviceState *dev,
                                     const char *name,
                                     void *opaque);

typedef struct DeviceProperty
{
    gchar *name;
    gchar *type;
    DevicePropertyAccessor *get;
    DevicePropertyAccessor *set;
    DevicePropertyRelease *release;
    void *opaque;

    QTAILQ_ENTRY(DeviceProperty) node;
} DeviceProperty;

70 71
#define TYPE_DEVICE "device"
#define DEVICE(obj) OBJECT_CHECK(DeviceState, (obj), TYPE_DEVICE)
72 73
#define DEVICE_CLASS(klass) OBJECT_CLASS_CHECK(DeviceClass, (klass), TYPE_DEVICE)
#define DEVICE_GET_CLASS(obj) OBJECT_GET_CLASS(DeviceClass, (obj), TYPE_DEVICE)
74 75 76

typedef struct DeviceClass {
    ObjectClass parent_class;
77
    DeviceInfo *info;
78
    void (*reset)(DeviceState *dev);
79 80
} DeviceClass;

Paul Brook's avatar
Paul Brook committed
81 82
/* This structure should not be accessed directly.  We declare it here
   so that it can be embedded in individual device state structures.  */
Paul Brook's avatar
Paul Brook committed
83
struct DeviceState {
84 85
    Object parent_obj;

Gerd Hoffmann's avatar
Gerd Hoffmann committed
86
    const char *id;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
87
    enum DevState state;
88
    QemuOpts *opts;
89
    int hotplugged;
Paul Brook's avatar
Paul Brook committed
90
    BusState *parent_bus;
Paul Brook's avatar
Paul Brook committed
91 92 93 94
    int num_gpio_out;
    qemu_irq *gpio_out;
    int num_gpio_in;
    qemu_irq *gpio_in;
Blue Swirl's avatar
Blue Swirl committed
95
    QLIST_HEAD(, BusState) child_bus;
96
    int num_child_bus;
97
    QTAILQ_ENTRY(DeviceState) sibling;
Jan Kiszka's avatar
Jan Kiszka committed
98 99
    int instance_id_alias;
    int alias_required_for_version;
100 101 102 103 104 105

    /**
     * This tracks the number of references between devices.  See @qdev_ref for
     * more information.
     */
    uint32_t ref;
106 107

    QTAILQ_HEAD(, DeviceProperty) properties;
108 109 110 111

    /* Do not, under any circumstance, use this parent link below anywhere
     * outside of qdev.c.  You have been warned. */
    DeviceState *parent;
Paul Brook's avatar
Paul Brook committed
112 113
};

114
typedef void (*bus_dev_printfn)(Monitor *mon, DeviceState *dev, int indent);
115
typedef char *(*bus_get_dev_path)(DeviceState *dev);
116 117 118 119 120 121
/*
 * This callback is used to create Open Firmware device path in accordance with
 * OF spec http://forthworks.com/standards/of1275.pdf. Indicidual bus bindings
 * can be found here http://playground.sun.com/1275/bindings/.
 */
typedef char *(*bus_get_fw_dev_path)(DeviceState *dev);
122
typedef int (qbus_resetfn)(BusState *bus);
123

124 125 126 127
struct BusInfo {
    const char *name;
    size_t size;
    bus_dev_printfn print_dev;
128
    bus_get_dev_path get_dev_path;
129
    bus_get_fw_dev_path get_fw_dev_path;
130
    qbus_resetfn *reset;
131
    Property *props;
132
};
Paul Brook's avatar
Paul Brook committed
133 134 135

struct BusState {
    DeviceState *parent;
136
    BusInfo *info;
Paul Brook's avatar
Paul Brook committed
137
    const char *name;
138
    int allow_hotplug;
139
    int qdev_allocated;
140
    QTAILQ_HEAD(ChildrenHead, DeviceState) children;
Blue Swirl's avatar
Blue Swirl committed
141
    QLIST_ENTRY(BusState) sibling;
Paul Brook's avatar
Paul Brook committed
142 143
};

144 145 146 147
struct Property {
    const char   *name;
    PropertyInfo *info;
    int          offset;
148
    int          bitnr;
149 150 151 152 153
    void         *defval;
};

enum PropertyType {
    PROP_TYPE_UNSPEC = 0,
Juan Quintela's avatar
Juan Quintela committed
154
    PROP_TYPE_UINT8,
155 156
    PROP_TYPE_UINT16,
    PROP_TYPE_UINT32,
157
    PROP_TYPE_INT32,
Blue Swirl's avatar
Blue Swirl committed
158
    PROP_TYPE_UINT64,
159 160
    PROP_TYPE_TADDR,
    PROP_TYPE_MACADDR,
161
    PROP_TYPE_LOSTTICKPOLICY,
Gerd Hoffmann's avatar
Gerd Hoffmann committed
162
    PROP_TYPE_DRIVE,
163
    PROP_TYPE_CHR,
Gerd Hoffmann's avatar
Gerd Hoffmann committed
164
    PROP_TYPE_STRING,
Gerd Hoffmann's avatar
Gerd Hoffmann committed
165
    PROP_TYPE_NETDEV,
Gerd Hoffmann's avatar
Gerd Hoffmann committed
166
    PROP_TYPE_VLAN,
167
    PROP_TYPE_PTR,
168
    PROP_TYPE_BIT,
169 170 171 172
};

struct PropertyInfo {
    const char *name;
173
    const char *legacy_name;
174 175
    size_t size;
    enum PropertyType type;
176 177
    int64_t min;
    int64_t max;
178 179
    int (*parse)(DeviceState *dev, Property *prop, const char *str);
    int (*print)(DeviceState *dev, Property *prop, char *dest, size_t len);
180
    void (*free)(DeviceState *dev, Property *prop);
181 182
    DevicePropertyAccessor *get;
    DevicePropertyAccessor *set;
183 184
};

185
typedef struct GlobalProperty {
186 187 188
    const char *driver;
    const char *property;
    const char *value;
189 190
    QTAILQ_ENTRY(GlobalProperty) next;
} GlobalProperty;
191

Paul Brook's avatar
Paul Brook committed
192 193
/*** Board API.  This should go away once we have a machine config file.  ***/

Paul Brook's avatar
Paul Brook committed
194
DeviceState *qdev_create(BusState *bus, const char *name);
195
DeviceState *qdev_try_create(BusState *bus, const char *name);
Blue Swirl's avatar
Blue Swirl committed
196
bool qdev_exists(const char *name);
197
int qdev_device_help(QemuOpts *opts);
Gerd Hoffmann's avatar
Gerd Hoffmann committed
198
DeviceState *qdev_device_add(QemuOpts *opts);
199
int qdev_init(DeviceState *dev) QEMU_WARN_UNUSED_RESULT;
Markus Armbruster's avatar
Markus Armbruster committed
200
void qdev_init_nofail(DeviceState *dev);
Jan Kiszka's avatar
Jan Kiszka committed
201 202
void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
                                 int required_for_version);
203
int qdev_unplug(DeviceState *dev);
Paul Brook's avatar
Paul Brook committed
204
void qdev_free(DeviceState *dev);
205 206
int qdev_simple_unplug_cb(DeviceState *dev);
void qdev_machine_creation_done(void);
207
bool qdev_machine_modified(void);
Paul Brook's avatar
Paul Brook committed
208 209 210 211

qemu_irq qdev_get_gpio_in(DeviceState *dev, int n);
void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin);

Paul Brook's avatar
Paul Brook committed
212
BusState *qdev_get_child_bus(DeviceState *dev, const char *name);
Paul Brook's avatar
Paul Brook committed
213

Paul Brook's avatar
Paul Brook committed
214 215
/*** Device API.  ***/

216
typedef int (*qdev_initfn)(DeviceState *dev, DeviceInfo *info);
217
typedef int (*qdev_event)(DeviceState *dev);
218
typedef void (*qdev_resetfn)(DeviceState *dev);
Paul Brook's avatar
Paul Brook committed
219

Paul Brook's avatar
Paul Brook committed
220
struct DeviceInfo {
221
    const char *name;
222
    const char *fw_name;
223 224
    const char *alias;
    const char *desc;
225
    size_t size;
226
    Property *props;
227
    int no_user;
228

Gerd Hoffmann's avatar
Gerd Hoffmann committed
229
    /* callbacks */
230
    qdev_resetfn reset;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
231

Gerd Hoffmann's avatar
Gerd Hoffmann committed
232 233 234
    /* device state */
    const VMStateDescription *vmsd;

235 236 237 238 239
    /**
     * See #TypeInfo::class_init()
     */
    void (*class_init)(ObjectClass *klass, void *data);

240
    /* Private to qdev / bus.  */
Paul Brook's avatar
Paul Brook committed
241
    qdev_initfn init;
242 243
    qdev_event unplug;
    qdev_event exit;
244
    BusInfo *bus_info;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
245
    struct DeviceInfo *next;
Paul Brook's avatar
Paul Brook committed
246
};
247
extern DeviceInfo *device_info_list;
Paul Brook's avatar
Paul Brook committed
248

249
void qdev_register(DeviceInfo *info);
250
void qdev_register_subclass(DeviceInfo *info, const char *parent);
Paul Brook's avatar
Paul Brook committed
251 252

/* Register device properties.  */
Paul Brook's avatar
Paul Brook committed
253
/* GPIO inputs also double as IRQ sinks.  */
Paul Brook's avatar
Paul Brook committed
254 255 256 257 258
void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n);
void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n);

CharDriverState *qdev_init_chardev(DeviceState *dev);

Paul Brook's avatar
Paul Brook committed
259
BusState *qdev_get_parent_bus(DeviceState *dev);
Paul Brook's avatar
Paul Brook committed
260

Paul Brook's avatar
Paul Brook committed
261 262
/*** BUS API. ***/

263 264
DeviceState *qdev_find_recursive(BusState *bus, const char *id);

265 266 267 268
/* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */
typedef int (qbus_walkerfn)(BusState *bus, void *opaque);
typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque);

269 270
void qbus_create_inplace(BusState *bus, BusInfo *info,
                         DeviceState *parent, const char *name);
271
BusState *qbus_create(BusInfo *info, DeviceState *parent, const char *name);
272 273 274 275 276 277 278
/* Returns > 0 if either devfn or busfn skip walk somewhere in cursion,
 *         < 0 if either devfn or busfn terminate walk somewhere in cursion,
 *           0 otherwise. */
int qbus_walk_children(BusState *bus, qdev_walkerfn *devfn,
                       qbus_walkerfn *busfn, void *opaque);
int qdev_walk_children(DeviceState *dev, qdev_walkerfn *devfn,
                       qbus_walkerfn *busfn, void *opaque);
279
void qdev_reset_all(DeviceState *dev);
280 281
void qbus_reset_all_fn(void *opaque);

Gerd Hoffmann's avatar
Gerd Hoffmann committed
282
void qbus_free(BusState *bus);
Paul Brook's avatar
Paul Brook committed
283 284 285

#define FROM_QBUS(type, dev) DO_UPCAST(type, qbus, dev)

286 287 288
/* This should go away once we get rid of the NULL bus hack */
BusState *sysbus_get_default(void);

289 290 291
/*** monitor commands ***/

void do_info_qtree(Monitor *mon);
292
void do_info_qdm(Monitor *mon);
293
int do_device_add(Monitor *mon, const QDict *qdict, QObject **ret_data);
294
int do_device_del(Monitor *mon, const QDict *qdict, QObject **ret_data);
295

296 297
/*** qdev-properties.c ***/

298
extern PropertyInfo qdev_prop_bit;
Juan Quintela's avatar
Juan Quintela committed
299
extern PropertyInfo qdev_prop_uint8;
300 301
extern PropertyInfo qdev_prop_uint16;
extern PropertyInfo qdev_prop_uint32;
302
extern PropertyInfo qdev_prop_int32;
Blue Swirl's avatar
Blue Swirl committed
303
extern PropertyInfo qdev_prop_uint64;
Jan Kiszka's avatar
Jan Kiszka committed
304
extern PropertyInfo qdev_prop_hex8;
305
extern PropertyInfo qdev_prop_hex32;
Blue Swirl's avatar
Blue Swirl committed
306
extern PropertyInfo qdev_prop_hex64;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
307
extern PropertyInfo qdev_prop_string;
308
extern PropertyInfo qdev_prop_chr;
309 310
extern PropertyInfo qdev_prop_ptr;
extern PropertyInfo qdev_prop_macaddr;
311
extern PropertyInfo qdev_prop_losttickpolicy;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
312
extern PropertyInfo qdev_prop_drive;
Gerd Hoffmann's avatar
Gerd Hoffmann committed
313 314
extern PropertyInfo qdev_prop_netdev;
extern PropertyInfo qdev_prop_vlan;
315
extern PropertyInfo qdev_prop_pci_devfn;
316

317 318 319 320 321 322 323 324 325 326 327 328 329
#define DEFINE_PROP(_name, _state, _field, _prop, _type) { \
        .name      = (_name),                                    \
        .info      = &(_prop),                                   \
        .offset    = offsetof(_state, _field)                    \
            + type_check(_type,typeof_field(_state, _field)),    \
        }
#define DEFINE_PROP_DEFAULT(_name, _state, _field, _defval, _prop, _type) { \
        .name      = (_name),                                           \
        .info      = &(_prop),                                          \
        .offset    = offsetof(_state, _field)                           \
            + type_check(_type,typeof_field(_state, _field)),           \
        .defval    = (_type[]) { _defval },                             \
        }
330 331 332 333 334 335 336 337
#define DEFINE_PROP_BIT(_name, _state, _field, _bit, _defval) {  \
        .name      = (_name),                                    \
        .info      = &(qdev_prop_bit),                           \
        .bitnr    = (_bit),                                      \
        .offset    = offsetof(_state, _field)                    \
            + type_check(uint32_t,typeof_field(_state, _field)), \
        .defval    = (bool[]) { (_defval) },                     \
        }
338

Juan Quintela's avatar
Juan Quintela committed
339 340
#define DEFINE_PROP_UINT8(_n, _s, _f, _d)                       \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_uint8, uint8_t)
341 342 343 344
#define DEFINE_PROP_UINT16(_n, _s, _f, _d)                      \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_uint16, uint16_t)
#define DEFINE_PROP_UINT32(_n, _s, _f, _d)                      \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_uint32, uint32_t)
345 346
#define DEFINE_PROP_INT32(_n, _s, _f, _d)                      \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_int32, int32_t)
347 348
#define DEFINE_PROP_UINT64(_n, _s, _f, _d)                      \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_uint64, uint64_t)
Jan Kiszka's avatar
Jan Kiszka committed
349 350
#define DEFINE_PROP_HEX8(_n, _s, _f, _d)                       \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_hex8, uint8_t)
351 352 353 354 355 356 357 358 359
#define DEFINE_PROP_HEX32(_n, _s, _f, _d)                       \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_hex32, uint32_t)
#define DEFINE_PROP_HEX64(_n, _s, _f, _d)                       \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_hex64, uint64_t)
#define DEFINE_PROP_PCI_DEVFN(_n, _s, _f, _d)                   \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_pci_devfn, uint32_t)

#define DEFINE_PROP_PTR(_n, _s, _f)             \
    DEFINE_PROP(_n, _s, _f, qdev_prop_ptr, void*)
360 361
#define DEFINE_PROP_CHR(_n, _s, _f)             \
    DEFINE_PROP(_n, _s, _f, qdev_prop_chr, CharDriverState*)
Gerd Hoffmann's avatar
Gerd Hoffmann committed
362 363
#define DEFINE_PROP_STRING(_n, _s, _f)             \
    DEFINE_PROP(_n, _s, _f, qdev_prop_string, char*)
Gerd Hoffmann's avatar
Gerd Hoffmann committed
364 365
#define DEFINE_PROP_NETDEV(_n, _s, _f)             \
    DEFINE_PROP(_n, _s, _f, qdev_prop_netdev, VLANClientState*)
Gerd Hoffmann's avatar
Gerd Hoffmann committed
366 367
#define DEFINE_PROP_VLAN(_n, _s, _f)             \
    DEFINE_PROP(_n, _s, _f, qdev_prop_vlan, VLANState*)
368 369
#define DEFINE_PROP_DRIVE(_n, _s, _f) \
    DEFINE_PROP(_n, _s, _f, qdev_prop_drive, BlockDriverState *)
370
#define DEFINE_PROP_MACADDR(_n, _s, _f)         \
Gerd Hoffmann's avatar
Gerd Hoffmann committed
371
    DEFINE_PROP(_n, _s, _f, qdev_prop_macaddr, MACAddr)
372 373 374
#define DEFINE_PROP_LOSTTICKPOLICY(_n, _s, _f, _d) \
    DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_losttickpolicy, \
                        LostTickPolicy)
375 376 377 378

#define DEFINE_PROP_END_OF_LIST()               \
    {}

379 380
/* Set properties between creation and init.  */
void *qdev_get_prop_ptr(DeviceState *dev, Property *prop);
Gerd Hoffmann's avatar
Gerd Hoffmann committed
381
int qdev_prop_exists(DeviceState *dev, const char *name);
382 383
int qdev_prop_parse(DeviceState *dev, const char *name, const char *value);
void qdev_prop_set(DeviceState *dev, const char *name, void *src, enum PropertyType type);
384
void qdev_prop_set_bit(DeviceState *dev, const char *name, bool value);
Juan Quintela's avatar
Juan Quintela committed
385
void qdev_prop_set_uint8(DeviceState *dev, const char *name, uint8_t value);
386 387
void qdev_prop_set_uint16(DeviceState *dev, const char *name, uint16_t value);
void qdev_prop_set_uint32(DeviceState *dev, const char *name, uint32_t value);
388
void qdev_prop_set_int32(DeviceState *dev, const char *name, int32_t value);
Blue Swirl's avatar
Blue Swirl committed
389
void qdev_prop_set_uint64(DeviceState *dev, const char *name, uint64_t value);
390
void qdev_prop_set_string(DeviceState *dev, const char *name, char *value);
391
void qdev_prop_set_chr(DeviceState *dev, const char *name, CharDriverState *value);
Gerd Hoffmann's avatar
Gerd Hoffmann committed
392
void qdev_prop_set_netdev(DeviceState *dev, const char *name, VLANClientState *value);
Gerd Hoffmann's avatar
Gerd Hoffmann committed
393
void qdev_prop_set_vlan(DeviceState *dev, const char *name, VLANState *value);
394 395
int qdev_prop_set_drive(DeviceState *dev, const char *name, BlockDriverState *value) QEMU_WARN_UNUSED_RESULT;
void qdev_prop_set_drive_nofail(DeviceState *dev, const char *name, BlockDriverState *value);
Gerd Hoffmann's avatar
Gerd Hoffmann committed
396
void qdev_prop_set_macaddr(DeviceState *dev, const char *name, uint8_t *value);
397 398
void qdev_prop_set_losttickpolicy(DeviceState *dev, const char *name,
                                  LostTickPolicy *value);
399 400 401 402
/* FIXME: Remove opaque pointer properties.  */
void qdev_prop_set_ptr(DeviceState *dev, const char *name, void *value);
void qdev_prop_set_defaults(DeviceState *dev, Property *props);

403 404
void qdev_prop_register_global_list(GlobalProperty *props);
void qdev_prop_set_globals(DeviceState *dev);
405 406
void error_set_from_qdev_prop_error(Error **errp, int ret, DeviceState *dev,
                                    Property *prop, const char *value);
407

408
char *qdev_get_fw_dev_path(DeviceState *dev);
409

Blue Swirl's avatar
Blue Swirl committed
410 411 412
/* This is a nasty hack to allow passing a NULL bus to qdev_create.  */
extern struct BusInfo system_bus_info;

413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
/**
 * @qdev_ref
 *
 * Increase the reference count of a device.  A device cannot be freed as long
 * as its reference count is greater than zero.
 *
 * @dev - the device
 */
void qdev_ref(DeviceState *dev);

/**
 * @qdef_unref
 *
 * Decrease the reference count of a device.  A device cannot be freed as long
 * as its reference count is greater than zero.
 *
 * @dev - the device
 */
void qdev_unref(DeviceState *dev);

433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511
/**
 * @qdev_property_add - add a new property to a device
 *
 * @dev - the device to add a property to
 *
 * @name - the name of the property.  This can contain any character except for
 *         a forward slash.  In general, you should use hyphens '-' instead of
 *         underscores '_' when naming properties.
 *
 * @type - the type name of the property.  This namespace is pretty loosely
 *         defined.  Sub namespaces are constructed by using a prefix and then
 *         to angle brackets.  For instance, the type 'virtio-net-pci' in the
 *         'link' namespace would be 'link<virtio-net-pci>'.
 *
 * @get - the getter to be called to read a property.  If this is NULL, then
 *        the property cannot be read.
 *
 * @set - the setter to be called to write a property.  If this is NULL,
 *        then the property cannot be written.
 *
 * @release - called when the property is removed from the device.  This is
 *            meant to allow a property to free its opaque upon device
 *            destruction.  This may be NULL.
 *
 * @opaque - an opaque pointer to pass to the callbacks for the property
 *
 * @errp - returns an error if this function fails
 */
void qdev_property_add(DeviceState *dev, const char *name, const char *type,
                       DevicePropertyAccessor *get, DevicePropertyAccessor *set,
                       DevicePropertyRelease *release,
                       void *opaque, Error **errp);

/**
 * @qdev_property_get - reads a property from a device
 *
 * @dev - the device
 *
 * @v - the visitor that will receive the property value.  This should be an
 *      Output visitor and the data will be written with @name as the name.
 *
 * @name - the name of the property
 *
 * @errp - returns an error if this function fails
 */
void qdev_property_get(DeviceState *dev, Visitor *v, const char *name,
                       Error **errp);

/**
 * @qdev_property_set - writes a property to a device
 *
 * @dev - the device
 *
 * @v - the visitor that will be used to write the property value.  This should
 *      be an Input visitor and the data will be first read with @name as the
 *      name and then written as the property value.
 *
 * @name - the name of the property
 *
 * @errp - returns an error if this function fails
 */
void qdev_property_set(DeviceState *dev, Visitor *v, const char *name,
                       Error **errp);

/**
 * @qdev_property_get_type - returns the type of a property
 *
 * @dev - the device
 *
 * @name - the name of the property
 *
 * @errp - returns an error if this function fails
 *
 * Returns:
 *   The type name of the property.
 */
const char *qdev_property_get_type(DeviceState *dev, const char *name,
                                   Error **errp);

512
/**
513 514
 * @qdev_property_add_static - add a @Property to a device referencing a
 * field in a struct.
515
 */
516
void qdev_property_add_static(DeviceState *dev, Property *prop, Error **errp);
517

Anthony Liguori's avatar
Anthony Liguori committed
518 519 520 521 522 523 524 525
/**
 * @qdev_get_root - returns the root device of the composition tree
 *
 * Returns:
 *   The root of the composition tree.
 */
DeviceState *qdev_get_root(void);

526 527 528 529 530 531 532 533 534
/**
 * @qdev_get_canonical_path - returns the canonical path for a device.  This
 * is the path within the composition tree starting from the root.
 *
 * Returns:
 *   The canonical path in the composition tree.
 */
gchar *qdev_get_canonical_path(DeviceState *dev);

535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562
/**
 * @qdev_resolve_path - resolves a path returning a device
 *
 * There are two types of supported paths--absolute paths and partial paths.
 * 
 * Absolute paths are derived from the root device and can follow child<> or
 * link<> properties.  Since they can follow link<> properties, they can be
 * arbitrarily long.  Absolute paths look like absolute filenames and are
 * prefixed with a leading slash.
 * 
 * Partial paths look like relative filenames.  They do not begin with a
 * prefix.  The matching rules for partial paths are subtle but designed to make
 * specifying devices easy.  At each level of the composition tree, the partial
 * path is matched as an absolute path.  The first match is not returned.  At
 * least two matches are searched for.  A successful result is only returned if
 * only one match is founded.  If more than one match is found, a flag is
 * return to indicate that the match was ambiguous.
 *
 * @path - the path to resolve
 *
 * @ambiguous - returns true if the path resolution failed because of an
 *              ambiguous match
 *
 * Returns:
 *   The matched device or NULL on path lookup failure.
 */
DeviceState *qdev_resolve_path(const char *path, bool *ambiguous);

563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
/**
 * @qdev_property_add_child - Add a child property to a device
 *
 * Child properties form the composition tree.  All devices need to be a child
 * of another device.  Devices can only be a child of one device.
 *
 * There is no way for a child to determine what its parent is.  It is not
 * a bidirectional relationship.  This is by design.
 *
 * @dev - the device to add a property to
 *
 * @name - the name of the property
 *
 * @child - the child device
 *
 * @errp - if an error occurs, a pointer to an area to store the area
 */
void qdev_property_add_child(DeviceState *dev, const char *name,
                             DeviceState *child, Error **errp);

583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605
/**
 * @qdev_property_add_link - Add a link property to a device
 *
 * Links establish relationships between devices.  Links are unidirectional
 * although two links can be combined to form a bidirectional relationship
 * between devices.
 *
 * Links form the graph in the device model.
 *
 * @dev - the device to add a property to
 *
 * @name - the name of the property
 *
 * @type - the qdev type of the link
 *
 * @child - a pointer to where the link device reference is stored
 *
 * @errp - if an error occurs, a pointer to an area to store the area
 */
void qdev_property_add_link(DeviceState *dev, const char *name,
                            const char *type, DeviceState **child,
                            Error **errp);

606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
/**
 * @qdev_property_add_str
 *
 * Add a string property using getters/setters.  This function will add a
 * property of type 'string'.
 *
 * @dev - the device to add a property to
 *
 * @name - the name of the property
 *
 * @get - the getter or NULL if the property is write-only.  This function must
 *        return a string to be freed by @g_free().
 *
 * @set - the setter or NULL if the property is read-only
 *
 * @errp - if an error occurs, a pointer to an area to store the error
 */
void qdev_property_add_str(DeviceState *dev, const char *name,
                           char *(*get)(DeviceState *, Error **),
                           void (*set)(DeviceState *, const char *, Error **),
                           Error **errp);

628 629 630 631 632 633 634 635 636 637 638 639 640 641
/**
 * @qdev_get_type
 *
 * Returns the string representation of the type of this object.
 *
 * @dev - the device
 *
 * @errp - if an error occurs, a pointer to an area to store the error
 *
 * Returns: a string representing the type.  This must be freed by the caller
 *          with g_free().
 */
char *qdev_get_type(DeviceState *dev, Error **errp);

642 643 644 645 646 647 648 649
/**
 * @qdev_machine_init
 *
 * Initialize platform devices before machine init.  This is a hack until full
 * support for composition is added.
 */
void qdev_machine_init(void);

650 651 652 653 654 655 656
/**
 * @device_reset
 *
 * Reset a single device (by calling the reset method).
 */
void device_reset(DeviceState *dev);

657 658 659 660 661 662 663 664
const VMStateDescription *qdev_get_vmsd(DeviceState *dev);

const char *qdev_fw_name(DeviceState *dev);

BusInfo *qdev_get_bus_info(DeviceState *dev);

Property *qdev_get_props(DeviceState *dev);

Paul Brook's avatar
Paul Brook committed
665
#endif