Hi Daniel,
On Mon, Oct 21, 2024 at 09:35:22AM +0100, Daniel P. Berrangé wrote:
> Date: Mon, 21 Oct 2024 09:35:22 +0100
> From: "Daniel P. Berrangé" <berra...@redhat.com>
> Subject: Re: [Question] What is the definition of “private” fields in
> QOM?
>
> On Sun, Oct 20, 2024 at 12:10:14AM +0800, Zhao Liu wrote:
> > Hi maintainers and list,
> >
> > In the QOM structure, the class and object structs have two members:
> > parent_class and parent_obj, which are often marked as "< private >" in
> > the comment.
> >
> > I couldn’t find information on why to define ‘private’ and ‘public’,
> > even in the earliest QOM commits and the patch emails I could find.
> >
> > Does ‘private’ refer to the internal implementation code of QOM, or does
> > it refer to the specific code that defines and implements this object
> > and its class?
> >
> > I understand the original idea of private field indicates it cannot be
> > accessed directly out of the "private" scope.
>
> I see two scenarios
>
> * Devices where the structs are in the include/..../<blah>.h
>
> The private/public comments are a message to other code in QEMU about
> which fields are OK to access directly, and which should not be accessed.
Does "other code" refer to the fact that no arbitrary code should
directly access parent_obj/parent_class, but rather should use an
explicit cast to convert to the parent class/object?
For example, are the following direct accesses to parent_obj all
considered illegal?
hw/usb/hcd-ohci-pci.c:58: pci_set_word(dev->parent_obj.config + PCI_STATUS,
hw/arm/smmuv3.c:1094:
trace_smmuv3_translate_success(mr->parent_obj.name, sid, addr,
hw/arm/smmuv3.c:1101:
trace_smmuv3_translate_disable(mr->parent_obj.name, sid, addr,
hw/arm/smmuv3.c:1107: trace_smmuv3_translate_bypass(mr->parent_obj.name,
sid, addr,
hw/arm/smmuv3.c:1112: trace_smmuv3_translate_abort(mr->parent_obj.name,
sid, addr,
hw/arm/smmuv3.c:1119: mr->parent_obj.name, addr,
smmu_event_string(event.type));
hw/arm/smmuv3.c:1212:
trace_smmuv3_inv_notifiers_iova(mr->parent_obj.name, asid, vmid,
hw/arm/smmuv3.c:2033:
trace_smmuv3_notify_flag_add(iommu->parent_obj.name);
hw/arm/smmuv3.c:2036:
trace_smmuv3_notify_flag_del(iommu->parent_obj.name);
hw/arm/smmu-common.c:888: trace_smmu_inv_notifiers_mr(mr->parent_obj.name);
block/throttle-groups.c:777: if (!tg->name && tg->parent_obj.parent) {
iothread.c:173:
iothread->parent_obj.aio_max_batch);
iothread.c:359: info->aio_max_batch = iothread->parent_obj.aio_max_batch;
target/i386/sev.c:1240: if (sev_snp->parent_obj.kernel_hashes) {
target/ppc/kvm.c:2354: const char *vcpu_str = (cs->parent_obj.hotplugged ==
true) ?
target/openrisc/sys_helper.c:289: return cpu->parent_obj.cpu_index;
accel/kvm/kvm-all.c:4285: cpu->parent_obj.canonical_path,
accel/kvm/kvm-all.c:4377: if
(!apply_str_list_filter(cpu->parent_obj.canonical_path, targets)) {
accel/tcg/translator.c:26: offsetof(ArchCPU,
parent_obj.neg.can_do_io) -
accel/tcg/translator.c:50: offsetof(ArchCPU,
parent_obj.neg.icount_decr.u32)
accel/tcg/translator.c:80: offsetof(ArchCPU,
parent_obj.neg.icount_decr.u16.low)
include/hw/pci-host/dino.h:113: * PCI_CONFIG_ADDR is parent_obj.config_reg,
via pci_host_conf_be_ops,
...
> * Devices where the structs are in the ../<blah>.c
>
> The private/public comments look entirely pointless, as everything
> is private to the .c file.
Yes!
> 99% of the time it seems the "parent" / "parent_obj" fields are the only
> one marked private. There are a handful of classes where other fields are
> under the private comment, but not many.
Yes. "parent" / "parent_obj" are the most common cases.
Thanks,
Zhao
