Re: [Question] What is the definition of “private” fields in QOM?

[Zhao Liu <zhao1.liu@intel.com>]

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é" <berrange@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