Daniel P. Berrangé <berrange@redhat.com> writes:
On Wed, Mar 11, 2026 at 02:05:24PM +0100, Markus Armbruster wrote:
I can't find a good spot in the existing discussion where the following would fit neatly as a reply, so I'm starting at the top again.
Fact: a huge part of our external interface is *accidental* and virtually undocumented.
The sane way to do an external interface is to layer it on top of more powerful internal interfaces. The external interface exposes just the functionality that's wanted there. The internal interfaces can evolve without affecting the external one.
QMP works that way. QEMU code uses internal C interfaces. QEMU doesn't send QMP commands to itself. If we need something internally, we add it to a suitable internal interface. There's no need to add it to the external interface just for that.
QOM does not work that way. The internal and the external object configuration interface is one and the same. So, if we add a property for internal use, we can't *not* add it to the external interface.
This has led to an external interface that is frickin' huge: I count ~1000 device types with ~16000 properties in qemu-system-aarch64 alone. The vast majority is undocumented.
Time and again we've found ourselves unsure whether certain properties have external uses, or are even meant for external use.
We have been unable / unwilling to isolate the external interface from internal detail. This is madness.
As long as we persist in this madness, a sane, properly documented external interface will remain impossible.
Do we care? If yes, we should discuss how to isolate external and internal interfaces.
This series attempts to create a bit of infrastructure for such isolation: means to mark properties as internal. Is it the right infrastructure? Is it enough to be a useful step? Maybe not, but then I'd like to hear better ideas.
For -object / object_add we introduced formal QAPI modelling of all Object subclasses which implement the UserCreatable interface. IIUC, that gives us the desired separation between internal and external views, as only properties declared in qapi/qom.json are publically settable.
Correct. Kevin Wolf's work.
This work did not apply to the Device classes because the historical baggage with qdev being grafted onto qom, means we don't have that working via the UserCreatable inteface or -object/object_add.
Can we bring Device into the same world though ?
Kevin Wolf took a stab at it. I had a hard time understanding it back then. Various pennies finally dropped when he patiently explained it to me in person. I disliked certain aspects of its design, and wanted to explore a bit more. Never found the time. Perhaps we should just take it despite my design misgivings.
Adding 1000 device types to QAPI is a huge job, so it would need to be a long incremental job, unless perhaps we auto-generate QAPI descriptions for everything that already exists ?
Interesting idea. QAPI is declarative: types and their properties are declared in a schema. QOM is imperative: we execute C code to create types and their properties. Extracting a QAPI schema from the C code is impossible in the completely general case (halting problem), and merely impractical (I believe) in the special cases we have. We could start with QOM introspection instead: qom-list-types and qom-list-properties. These are only mostly complete, but should be good enough. Mapping QOM types to QAPI types would involve guesswork, because QOM doesn't have a type system, it has strings and bailing wire. Schema documentation would be placeholders at best. We could try to extract documentation from -device T,help. Most properties have nothing there, and the remainder likely needs to be rewritten completely to be fit for purpose.
More generally anything we can do to bring qdev & qom closer together feels desirable. I dream of a future where -device/device_add are obsolete....
That would be lovely.