@@ -1,3 +1,5 @@
+.. _qom:
+
===========================
The QEMU Object Model (QOM)
===========================
@@ -628,6 +628,43 @@ are still some caveats to beware of
QEMU Specific Idioms
********************
+QEMU Object Model Declarations
+==============================
+
+The QEMU Object Model (QOM) provides a framework for handling objects
+in the base C language. The first declaration of a storage or class
+structure should always be the parent and leave a visual space between
+that declaration and the new code. It is also useful to separate
+backing for properties (options driven by the user) and internal state
+to make navigation easier.
+
+For a storage structure the first declaration should always be called
+"parent_obj" and for a class structure the first member should always
+be called "parent_class" as below:
+
+.. code-block:: c
+
+ struct MyDeviceState {
+ DeviceState parent_obj;
+
+ /* Properties */
+ int prop_a;
+ char *prop_b;
+ /* Other stuff */
+ int internal_state;
+ };
+
+ struct MyDeviceClass {
+ DeviceClass parent_class;
+
+ void (*new_fn1)(void);
+ bool (*new_fn2)(CPUState *);
+ };
+
+Note that there is no need to provide typedefs for QOM structures
+since these are generated automatically by the QOM declaration macros.
+See :ref:`qom` for more details.
+
Error handling and reporting
============================