Documentation/QOMConventions

QOM Coding Conventions

• DO use TYPE_FOO constants, defined in a header if used in other parts of code
• DO use verbose cast macro names
  • bad: PHB(obj)
  • bad: PCI_HOST(obj)
  • good: PCI_HOST_BRIDGE(obj)
  • excessive: PERIPHERAL_COMPONENT_INTERCONNECT_HOST_BRIDGE(obj)
• DO use names-separated-by-dashes
• DON'T duplicate literal string type names

#define TYPE_EXAMPLE "example"

.name = TYPE_EXAMPLE,

object_new(TYPE_EXAMPLE)
qdev_create(NULL, TYPE_EXAMPLE)

• DO place parent field first
• DON'T use busdev or similar qdev conventions

typedef struct MyState {
    /*< private >*/
    Object parent_obj; /* or PCIDevice parent_obj etc. */
    /*< public >*/

    uint32_t some_register_value;
} MyState;

• DO use QOM cast macros (based on struct layout)
• DON'T rely on qdev's DO_UPCAST() macro (field names)
• DO use per-type variable declarations
• Avoid using cast macros other than OBJECT() inline

void do_something_with(MyDeviceState *s) {
    PCIDevice *pci = PCI_DEVICE(s);

    pci->field = foo; /* not s->pci.field or PCI_DEVICE(s)->field */
    qdev_foo(DEVICE(s)); /* okay if cast is not repeated */

When to create class types and macros

If your class (a) will be subclassed or (b) has member fields it needs to put in its class struct then you should write all of:

• a FOO_CLASS macro
• a FOO_GET_CLASS macro
• a FooClass structure definition containing at least the parent class field:

typedef struct {
    /*< private >*/
    MyParentClass parent_class;
    /*< public >*/

    [any fields you need]
} FooClass;

• and your TypeInfo for this class should set the .class_size field to sizeof(FooClass).

These ensure that nothing in future should need changing if new fields are added to your class struct, and that any subclasses have the correct typenames available so they won't need to change either even if your implementation changes.

If your class meets neither of the above requirements (ie it is a simple leaf class) then:

• don't provide FOO_CLASS or FOO_GET_CLASS
• don't provide a FooClass structure
• leave the TypeInfo's .class_size field unset.

If a change means a class which didn't provide these macros/types now needs to provide them, then your change should add all of them (ie move the class from the latter category to the former).