QEMU学习笔记——QOM(Qemu Object Model)

（转载）本文发自 http://www.binss.me/blog/qemu-note-of-qemu-object-model/，转载请注明出处。

QOM(Qemu Object Model)是QEMU最新的设备模型。QEMU一开始采用ad hoc，每种设备都有不同的表示方式，非常混乱。于是开发了qdev，将所有的模拟设备进行了整合，变成了一种单根结点(系统总线)的树状形式，并且增加了hotplug的功能。后来可能由于Device和Bus之间的复杂关系，又开发了QOM。

QOM是QEMU在C的基础上自己实现的一套面向对象机制，负责将device、bus等设备都抽象成为对象。对象的初始化分为四步：

1. 将 TypeInfo 注册 TypeImpl
2. 实例化 ObjectClass
3. 实例化 Object
4. 添加 Property

根据QEMU的 wiki ，QOM没有构造和析构的概念。但矛盾的是根据代码， TypeInfo 中定义的 class_init 和 instance_init 无论从名字还是实现上都做了对象的初始化工作，比如设置对象成员的值。但为什么说它们最多只能算是初始化函数呢？

Everything in QOM is a device

根据实现，经过 class_init 和 instance_init 产生设备对应Object后，这个Object是不能直接使用的。其真正初始化逻辑的大头都放在 realize 中做，比如创建对应的memory region，挂载到对应bus上等等。只有在 realize 后，设备才算真正构造完成，可以拿来用了。因此QEMU认为，类似构造和析构的是realize和unrealize。而在设备的生命周期中，可以被realize和unrealize多次。这也是最让我莫名其妙的地方。

为了保持习惯，本文会依然将 class_init 和 instance_init 当做构造函数，称前者为类构造函数，后者为类实例构造函数。

TypeInfo => ModuleEntry

TypeInfo 定义了一种类型。如 KVM在kvm-all.c中的定义：

	static const TypeInfo kvm_accel_type = {
	.name = TYPE_KVM_ACCEL,
	.parent = TYPE_ACCEL,
	.class_init = kvm_accel_class_init,
	.instance_size = sizeof(KVMState),
	};

包含 类型的名称(name)、父类名称(parent)、Object实例的大小(instance_size)、是否抽象类(abstract)、初始化函数(class_init)。

代码底部有 type_init ，由 C run-time(CRT)负责执行：

type_init(kvm_type_init) => module_init(function, MODULE_INIT_QOM) => register_module_init(function, type)

	void register_module_init(void (*fn)(void), module_init_type type)
	{
	ModuleEntry *e;
	ModuleTypeList *l;
	e = g_malloc0(sizeof(*e));
	e->init = fn;
	e->type = type;
	l = find_type(type);
	QTAILQ_INSERT_TAIL(l, e, node);
	}

创建了 type 为 MODULE_INIT_QOM ，init为 kvm_type_init 的 ModuleEntry ，并加入到 MODULE_INIT_QOM 的 ModuleTypeList 中。

ModuleEntry => TypeImpl

在 main.c(vl.c) 的一开始执行了 module_call_init(MODULE_INIT_QOM) ，它从 init_type_list 中取出对应的 ModuleTypeList ，然后对里面的 ModuleEntry 成员都调用 init 函数。

对于上文提到的 ModuleEntry ，调用的是 kvm_type_init => type_register_static(&kvm_accel_type) => type_register => type_register_internal

	static TypeImpl *type_register_internal(const TypeInfo *info)
	{
	TypeImpl *ti;
	ti = type_new(info);
	type_table_add(ti);
	return ti;
	}

它根据 kvm_accel_type(TypeInfo) 创建一个名为TYPE_KVM_ACCEL的 TypeImpl 类型的结构。

同时将该 TypeImpl 注册到全局 type_table 中，key为类型名称，即 TYPE_KVM_ACCEL

ObjectClass

	struct ObjectClass
	{
	/*< private >*/
	Type type; // 用typedef定义的 TypeImpl 指针
	GSList *interfaces;
	const char *object_cast_cache[OBJECT_CLASS_CAST_CACHE];
	const char *class_cast_cache[OBJECT_CLASS_CAST_CACHE];
	ObjectUnparent *unparent;
	GHashTable *properties;
	};

ObjectClass 属于类对象，它是所有类对象的基类。

TypeImpl => ObjectClass

有两种路径，一种是主动地调用： object_class_get_list => object_class_foreach => g_hash_table_foreach(object_class_foreach_tramp) => object_class_foreach_tramp => type_initialize

比如 object_class_get_list(TYPE_DEVICE, false) 创建 TYPE_DEVICE 类型的 ObjectClass

该过程用到glic的函数 g_hash_table_foreach ，见 https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-foreach

另一种是被动调用，如：

• object_class_by_name
• object_class_get_parent
• object_new_with_type
• object_initialize_with_type

在获取 class、class的parent、创建type的object、初始化TypeImpl的object时，调用 type_initialize

	type_initialize
	=> 如果 TypeImpl 已创建(class成员有值)，返回
	=> ti->class = g_malloc0(ti->class_size) 根据class_size分配内存空间
	=> type_get_parent(ti) 获取父类的TypeImpl
	=> memcpy(ti->class, parent->class, parent->class_size) 将parent的class拷贝到自己class的最前面
	=> ti->class->properties = g_hash_table_new_full 创建存放property的hash table
	=> type_initialize_interface 初始化class的接口，包括父类和自己的
	=> ti->class->type = ti 设置class的type为对应TypeImpl
	=> parent->class_base_init 如果parent定义了 class_base_init ，调用之
	=> ti->class_init(ti->class, ti->class_data) 调用class的 class_init

对于 kvm_accel_type 这个 TypeInfo 的 TypeImpl ，调用的class_init是 kvm_accel_class_init ，它将传入的 ObjectClass 强转为子类 AccelClass ，设置 init_machine 成员为 kvm_init

这里的class是该类型的类实例，它的基类是 ObjectClass 。

继承

从创建流程可以看出，在创建类对象时，会调用 type_initialize ，其会递归地对 TypeImpl 中的 parent 成员(TypeImpl)递归调用 type_initialize ，然后将创建出来的相应 ObjectClass 拷贝到自己class的最前面。

类对象的第一个成员是 parent_class ，由于父类对象会拷到子类对象的最前面，因此可以认为其指向父类的对象，如此构成链状的继承链，最终指向基类对象 ObjectClass

比如 kvm_accel_type 对应的类对象，该类对象作为叶子类型并没有定义，但其父类 AccelClass 在代码中有定义，其的第一个成员为 ObjectClass ，表示其继承自 ObjectClass 。为了能表示该叶子类型继承 AccelClass ，它修改了 AccelClass的一些对象成员，这样在某种程度上表示了继承关系。比如修改了函数指针成员的指向，相当于实现了虚函数。

又如： register_info 对应的类对象 => PCIDeviceClass => DeviceClass => ObjectClass 构成继承链，最前端的叶子类型通过修改 PCIDeviceClass 成员进行定义。

强制类型转换

将一个父类的指针转换为子类的指针是不安全的，为了实现这种转换，各类需要提供强制类型转换的宏，如：

	#define ACCEL_CLASS(klass) \
	OBJECT_CLASS_CHECK(AccelClass, (klass), TYPE_ACCEL)
	#define OBJECT_CLASS_CHECK(class_type, class, name) \
	((class_type *)object_class_dynamic_cast_assert(OBJECT_CLASS(class), (name), \
	__FILE__, __LINE__, __func__))

如果类对象指针的name和目标子类的name一致，或类对象指针是目标子类的祖先，则执行转换，否则 abort

反过来，从子类指针转换为父类指针是安全的，因为类的第一项就指向父类，访问时不会存在越界等问题。

Object

Object 属于类实例对象，它是所有类实例对象的基类。

	struct Object
	{
	/*< private >*/
	ObjectClass *class; // 指向类对象
	ObjectFree *free;
	GHashTable *properties; // 维护属性的哈希表
	uint32_t ref; // 引用计数
	Object *parent; // 指向父类实例对象，实现继承
	};

可以看到其第一个成员指向类对象，同时维护有区别于类属性的类实例属性。

创建流程

就流程而言，在C runtime 根据 TypeInfo 创建了 TypeImpl 后，此后主要根据 TypeImpl 创建 ObjectClass 和 Object

以 TypeInfo(kvm_accel_type) 为例，其创建的 TypeImpl 在以下流程发挥作用：

	main => configure_accelerator => accel_init_machine(acc, ms)
	=> ObjectClass *oc = OBJECT_CLASS(acc) 将AccelClass指针转换成父类(ObjectClass)指针
	=> object_class_get_name 获取 ObjectClass->TypeImpl 的类名，如 kvm-accel
	=> ACCEL(object_new(cname)) 利用名称创建 AccelState 对象
	=> acc->init_machine(ms) 初始化machine，实际上是调用 kvm_init
	object_new
	=> type_get_by_name(typename) 根据类名查type_table获取 TypeImpl
	=> object_new_with_type => type_initialize 创建 TypeImpl 对应的类对象，设置到对应 TypeImpl->class 中
	=> g_malloc(type->instance_size) 分配类实例对象的内存
	=> object_initialize_with_type 创建类实例对象
	=> type_initialize 会再次尝试实例化类对象
	=> obj->class = type->class 设置类实例对象的类对象为 TypeImpl->class
	=> obj->properties = g_hash_table_new_full 创建存放类实例对象property的hash table
	=> object_init_with_type => object_init_with_type 如果 TypeImpl 有父类，递归调用object_init_with_type
	=> ti->instance_init(obj) 如果定义了类实例的构造函数，调用之

继承

定义上的继承主要指类的继承，既然类对象已经通过包含的方式实现了继承，那么类实例对象就可以通过调用自己的class成员调用父类的函数，访问父类的class property。

但在QEMU实现的这套面向对象模型中，类实例对象也拥有自己的构造函数，因此根据继承关系，需要对父类实例对象的构造函数进行调用。

从创建流程可以看出，在创建类实例对象时，会调用 object_init_with_type ，其会递归地对 TypeImpl 中的 parent 成员递归调用 object_init_with_type ，从而让所有父类的 instance_init 都得到调用，在调用时传入的是当前对象的地址，相当于在当前对象上对父类实例对象进行构造。

同理，类实例对象的第一个成员是 parent_obj ，指向父类的实例对象，如此构成链状的继承链，最终指向基类实例对象 Object

如： kvm_accel_type的类实例Object => AccelState => Object

又如： register_info的类实例Object => PCIDevice => DeviceState => Object

强制类型转换

同理，将一个父类实例的指针转换为子类实例指针是不安全的。为了实现这种转换，各类需要提供强制类型转换的宏，如：

	#define ACCEL(obj) \
	OBJECT_CHECK(AccelState, (obj), TYPE_ACCEL)
	#define OBJECT_CHECK(type, obj, name) \
	((type *)object_dynamic_cast_assert(OBJECT(obj), (name), \
	__FILE__, __LINE__, __func__))

如果类实例对象指针的name和目标子类实例的name一致，或类实例对象指针是目标子类的祖先，则执行转换，否则 abort。

反过来，从子类实例指针转换为父类实例指针是安全的，因为类实例的第一项就指向父类实例，访问时不会存在越界等问题。

属性

属性分为类对象(ObjectClass)属性和类实例对象(Object)属性，存储于 properties 成员中。properties 是一个 GHashTable ，存储了 属性名 到 ObjectProperty 的映射。

属性模版

用于创建属性对象 ObjectProperty

	struct Property {
	const char *name;
	PropertyInfo *info;
	ptrdiff_t offset;
	uint8_t bitnr;
	QType qtype;
	int64_t defval;
	int arrayoffset;
	PropertyInfo *arrayinfo;
	int arrayfieldsize;
	};

属性对象

属性对象包含属性名称、类型、描述，类型对应的属性结构，以及相应访问函数。

	typedef struct ObjectProperty
	{
	gchar *name;
	gchar *type;
	gchar *description;
	ObjectPropertyAccessor *get;
	ObjectPropertyAccessor *set;
	ObjectPropertyResolve *resolve;
	ObjectPropertyRelease *release;
	void *opaque;
	} ObjectProperty;

如对于bool类型的属性，opaque为 BoolProperty ，set为 property_set_bool ，get为 property_get_bool 。

	typedef struct BoolProperty
	{
	bool (*get)(Object *, Error **);
	void (*set)(Object *, bool, Error **);
	} BoolProperty;

用于保存用户传入的 getter 和 setter 。

getter / setter (callback hook)

定义了在设置/读取属性时触发的函数。

比如 device 类型的 instance_init 即 device_initfn 中，定义了 realized 属性：

object_property_add_bool(obj, "realized", device_get_realized, device_set_realized, NULL)

则 getter 为 device_get_realized ， setter 为 device_set_realized

静态属性

凡是在代码中就已经定义好名称和类型的属性，都是静态属性。包括在初始化过程中添加 和 props 。

初始化过程中添加

比如对于 TypeInfo x86_cpu_type_info ，类实例初始化函数 x86_cpu_initfn 定义好了属性：

	object_property_add(obj, "family", "int",
	x86_cpuid_version_get_family,
	x86_cpuid_version_set_family, NULL, NULL, NULL);
	object_property_add_alias(obj, "kvm_steal_time", obj, "kvm-steal-time", &error_abort);

该属性会直接加到类实例对象的properties中。

props

一些类对象会在 class_init 中设置 props 成员，比如 TypeInfo host_x86_cpu_type_info 在 host_x86_cpu_class_init 设置为 host_x86_cpu_properties：

	static Property host_x86_cpu_properties[] = {
	DEFINE_PROP_BOOL("migratable", X86CPU, migratable, true),
	DEFINE_PROP_BOOL("host-cache-info", X86CPU, cache_info_passthrough, false),
	DEFINE_PROP_END_OF_LIST()
	};
	#define DEFINE_PROP_BOOL(_name, _state, _field, _defval) { \
	.name = (_name), \
	.info = &(qdev_prop_bool), \
	.offset = offsetof(_state, _field) \
	+ type_check(bool, typeof_field(_state, _field)), \
	.qtype = QTYPE_QBOOL, \
	.defval = (bool)_defval, \
	}
	// 闭包
	PropertyInfo qdev_prop_bool = {
	.name = "bool",
	.get = get_bool,
	.set = set_bool,
	};

而类实例 X86CPU 中定义了这些属性：

	struct X86CPU {
	bool migratable;
	...
	bool cache_info_passthrough;
	...
	};

于是 X86CPU.migratable 和 X86CPU.cache_info_passthrough 两个成员被定义成属性。

在父类 device_type_info 的类实例初始化函数 device_initfn 中，对所有的props，有：

	do {
	for (prop = DEVICE_CLASS(class)->props; prop && prop->name; prop++) {
	qdev_property_add_legacy(dev, prop, &error_abort);
	qdev_property_add_static(dev, prop, &error_abort);
	}
	class = object_class_get_parent(class);
	} while (class != object_class_by_name(TYPE_DEVICE));

而 qdev_property_add_static ：

	=> object_property_add(obj, prop->name, prop->info->name, prop->info->get, prop->info->set, prop->info->release, prop, &local_err)
	根据Property中的数据，创建ObjectProperty，并将其加到类实例对象的 properties 中
	关键是将闭包中的get和set取出，作为ObjectProperty的get和set
	=> object_property_set_description 设置属性的描述字符串
	=> 设置属性的默认值

查看

可通过命令查看设备的静态属性，参数为设备 TypeInfo 的 name：

/home/binss/work/qemu/qemu-2.8.1.1/x86_64-softmmu/qemu-system-x86_64 -device Broadwell-x86_64-cpu,?

但是， x86_64-cpu 抽象设备无法打。 host-x86_64-cpu 无法列出。

动态属性

指在运行时动态进行添加的属性。比如用户通过参数传入了一个设备，需要作为属性和其它设备关联起来。

典型的动态属性就是 child<> 和 link<> (因为其类型就是这样构造的，后文简称child和link) 。

child

child实现了composition关系，表示一个设备(parent)创建了另外一个设备(child)，parent掌控child的生命周期，负责向其发送事件。一个device只能有一个parent，但能有多个child。这样就构成一棵组合树。

通过 object_property_add_child 添加child：

	=> object_property_add 将 child 作为 obj 的属性，属性名name，类型为 "child<child的类名>"，同时getter为object_get_child_property，没有setter
	=> child->parent = obj

例如 x86_cpu_realizefn => x86_cpu_apic_create => object_property_add_child(OBJECT(cpu), "lapic", OBJECT(cpu->apic_state), &error_abort) 将创建 APICCommonState ，并设置为 X86CPU 的child。

可以在qemu hmp查询到：

	(qemu) info qom-tree
	/machine (pc-q35-2.8-machine)
	/unattached (container)
	/device[0] (host-x86_64-cpu)
	...

link

link实现了backlink关系，表示一个设备引用了另外一个设备，是一种松散的联系。两个设备之间能有多个link关系，可以进行修改。它完善了组合树，使其构成构成了一幅有向图。

通过 object_property_add_link 添加link：

	=> 创建 LinkProperty ，填充目标(child)的信息
	=> object_property_add 将 LinkProperty 作为 obj 的属性，属性名name，类型为 "link<child的类名>"，同时getter为 object_get_link_property 。如果传入了check函数，则需要回调，设置setter为 object_set_link_property

例如 q35 有以下link：

	static void q35_host_initfn(Object *obj)
	{
	object_property_add_link(obj, MCH_HOST_PROP_RAM_MEM, TYPE_MEMORY_REGION,
	(Object **) &s->mch.ram_memory,
	qdev_prop_allow_set_link_before_realize, 0, NULL);
	object_property_add_link(obj, MCH_HOST_PROP_PCI_MEM, TYPE_MEMORY_REGION,
	(Object **) &s->mch.pci_address_space,
	qdev_prop_allow_set_link_before_realize, 0, NULL);
	object_property_add_link(obj, MCH_HOST_PROP_SYSTEM_MEM, TYPE_MEMORY_REGION,
	(Object **) &s->mch.system_memory,
	qdev_prop_allow_set_link_before_realize, 0, NULL);
	object_property_add_link(obj, MCH_HOST_PROP_IO_MEM, TYPE_MEMORY_REGION,
	(Object **) &s->mch.address_space_io,
	qdev_prop_allow_set_link_before_realize, 0, NULL);
	}

将 Q35PCIHost 和 ram_memory / pci_address_space / system_memory / address_space_io 链接起来。

API

根据前面所述，属性有两种定义方式，一种是通过 DEFINE_PROP_* 定义，另一种是通过 object_property_add_<type> 进行定义。根据不同的定义方式，set会不同，设置值的方式也有所不同。

object_property_set_<type>

用于设置某个属性的值。比如 object_property_set_bool ：

	=> qbool_from_bool 将要设置的值包装成相应的 QObject ，这里是QBool
	=> object_property_set_qobject
	=> qobject_input_visitor_new 将传入的QObject包装成Visitor，其中含各类型的处理函数
	=> object_property_set => object_property_find 从props的hash table中找到对应的 ObjectProperty
	=> prop->set

对于 DEFINE_PROP_BOOL 创建的属性来说，其闭包为qdev_prop_bool，因此在初始化时 set 被设置为 set_bool

	set_bool
	=> qdev_get_prop_ptr 将设备指针加上属性值在其中的偏移量，得到属性值的地址
	=> visit_type_bool => v->type_bool (qobject_input_type_bool) => qobject_input_get_object 从Visitor中取出QObject
	=> qbool_get_bool 从QObject中取出值，设置到属性值的地址

对于 object_property_add_bool 创建的属性来说，它在 object_property_add 时设置 set 为 property_set_bool

	property_set_bool
	=> visit_type_bool => v->type_bool (qobject_input_type_bool) => qobject_input_get_object 找到QObject
	=> (BoolProperty)prop->set 调用setter

比如 device 类型的 instance_init 即 device_initfn 中，定义了 realized 属性：

object_property_add_bool(obj, "realized", device_get_realized, device_set_realized, NULL)

于是 setter 为 device_set_realized

	=> dc->realize 调用realize函数，其在 class_init 中定义
	=> dev->realized = value 设置类实例对象的成员

一句话总结，前者的属性值的设置由 type_bool 负责设置，而后者由 setter 负责设置。

object_property_get_<type>

用于读取某个属性的值。比如 object_property_get_bool ：

	=> object_property_get_qobject
	=> 创建空的QObject指针
	=> qobject_output_visitor_new 将传入的QObject包装成Visitor，其中含各类型的处理函数
	=> object_property_get => object_property_find 从props的hash table中找到对应的 ObjectProperty
	=> prop->get 调用get函数，设置QObject
	=> qobject_to_qbool 将QObject转成QBool
	=> qbool_get_bool 从QBool中取出值，返回

对于 DEFINE_PROP_BOOL 创建的属性来说，其闭包为qdev_prop_bool，因此在初始化时 get 被设置为 get_bool

	get_bool
	=> qdev_get_prop_ptr(dev, prop) 将设备指针加上属性值在其中的偏移量，得到属性值的地址
	=> visit_type_bool => v->type_bool (qobject_output_type_bool) => qobject_input_get_object 将属性值包装成QObject

对于 object_property_add_bool 创建的属性来说，它在 object_property_add 时设置 get 为 property_get_bool ：

	property_get_bool
	=> prop->get 调用getter，得到属性值
	=> visit_type_bool => v->type_bool (qobject_output_type_bool) => qobject_input_get_object 将属性值包装成QObject

个人的理解是，set 和 get 都需要通过 QObject 和 Visitor 两层包装。前者把要设置属性值包装成QObject再到Visitor，然后再取出设置到相应地址。后者根据属性值地址将属性值包装成QObject，设置为Visitor中QObject指针指向，然后再从QObject中取出值。

object_property_parse

在用一个string设置不知道类型的属性的值时，使用 object_property_parse：

	void object_property_parse(Object *obj, const char *string,
	const char *name, Error **errp)
	{
	Visitor *v = string_input_visitor_new(string);
	object_property_set(obj, v, name, errp);
	visit_free(v);
	}

它会创建一个 Visitor 并将值设置到里面，这里定义了string转其他类型属性的函数：

	v->visitor.type = VISITOR_INPUT;
	v->visitor.type_int64 = parse_type_int64;
	v->visitor.type_uint64 = parse_type_uint64;
	v->visitor.type_size = parse_type_size;
	v->visitor.type_bool = parse_type_bool;
	v->visitor.type_str = parse_type_str;
	v->visitor.type_number = parse_type_number;

总结

如此一来，根据 TypeInfo 创建了 TypeImpl ，然后根据 TypeImpl 创建了对应的 ObjectClass ，再根据 TypeImpl 创建了对应的 Object ， ObjectClass 和 Object 都有自己的 Property，关系如下：

	TypeImpl
	class -> ObjectClass(AccelClass) Object(AccelState)
	<- type <- class
	TypeImpl <- parent_type properties(GHashTable) properties(GHashTable)