[RFC 00/10] qom: Support marking object properties as deprecated

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

Hi,

This RFC is the follow-up work of v2.6 & v2.7 machines' removal [*], and
tries to introduce a general way to provide deprecation hint for
external user.

Its core idea is to detect external property settings (as well as
specific internal property settings, such as the compat property).

I think deprecated properties and internal-only properties are quite
similar, as both require consideration of external property usage. But
the former only triggers a warning, while the latter stops all external
access attempts.

For simplicity, this RFC series only considers deprecated properties.


Brief Introduction
==================

Now the common (but a bit fragmented) way to mark a property deprecated
is to add the warning in its accssors, or just document the deprecation
in docs/about/deprecated.rst without any hint when someone touches that
property.

Ideally, it's better to provide some hints to external user when he
tries to set the property via command line or HMP.

But this is pretty inconvenient (even impossible) for such qdev
properties, which are defined via DEFINE_PROP_* macros in the Property
array. For qdev properties, their accessors are provided by pre-defined
PropertyInfo, so that it's possible to modify PropertyInfo for a single
"deprecated" property.

Then it's necessary to introduce property flags to mark some properties
as deprecated, and to check the property flags when set the property,
thereby to print a deprecation warning.

This not only benefits traditional qdev properties but also helps the
deprecation of generic objects.

Note, internal attempt (except the compat case) should not trigger the
deprecation warning but external user should see the deprecation
information.

I think the most complex part is identifying the paths for property
settings (both external command-line options and internal specific
configurations). This series currently covers the following scenarios
(which I consider to be particularly important):

External cases:

 1) External global properties:
    * -global command line option.
    * -cpu command line features.
    * suger properties from object_compat_props[2]

 2) External ("TYPE_USER_CREATABLE") object:
    * -object command line used for external ("TYPE_USER_CREATABLE")
      object.

 3) External device:
    * -device command line - parsed based on keyval or json.

 4) External machine options:
    * -machine command line - parsed based on keyval.

 5) External accelerator options:
    * -accel command line.

 6) HMP command:
    * "qom-set" command.


Internal cases:
 1) internal global properties:
    * compat properties from object_compat_props[0,1].

 2) Internal machine options:
    * Builtin default machine options string:
      MachineClass::default_machine_opts - parsed based on keyval, too.


In fact, there are still some special device command lines that haven't
been considered yet. But I believe the remaining cases can be gradually
expanded?

If this approach is feasible, it's possible to further introduce an
"internal" flag to prevent external access to compat property.


[*]: hw/i386/pc: Remove deprecated 2.6 and 2.7 PC machines
     https://lore.kernel.org/qemu-devel/20251202162835.3227894-1-zhao1.liu@intel.com/

Thanks and Best Regards,
Zhao
---
Zhao Liu (10):
  qom: Rename ObjectPropertyFlags to ObjectPropertyAccessorFlags
  qom: Add basic object property deprecation hint support
  qom: Check property deprecation flag for global property
  qom: Check property deprecation flag for properities from qdict
  system/vl: Check property deprecation flag for properities of
    accelerator
  qom/qom-hmp-cmd: Check property deprecation flag for "qom-set" command
  hw/core/qdev-properties: Allow to mark qdev property as deprecated
  target/i386: Deprecate fill-mtrr-mask property
  target/i386: Deprecate cpuid-0xb property
  hw/intc/ioapic: Deprecate version property

 docs/about/deprecated.rst    |  31 +++++++++
 hw/core/qdev-properties.c    |  24 +++----
 hw/intc/ioapic.c             |   3 +-
 include/hw/qdev-properties.h |  18 ++++++
 include/qom/object.h         | 120 +++++++++++++++++++++++++++++++----
 qom/object.c                 | 101 ++++++++++++++++++++++-------
 qom/object_interfaces.c      |   2 +-
 qom/qom-hmp-cmds.c           |   2 +-
 system/vl.c                  |   2 +-
 target/i386/cpu.c            |   4 +-
 10 files changed, 253 insertions(+), 54 deletions(-)

-- 
2.34.1