Hi, recently I've been working on overhauling our QMP documentation; see https://jsnow.gitlab.io/qemu/qapi/index.html for a recent work-in-progress page showcasing this.
As part of this project, Markus and I decided it'd be nice to be able to auto-generate "Since" information. The short reason for 'why' is because since info hard-coded into doc comments may not be accurate with regards to the wire protocol availability for a given field when a QAPI definition is shared or inherited by multiple sources. If we can generate it, it should always be accurate. So, I've prototyped three things: (1) An out-of-tree fork of the QAPI generator that is capable of parsing qemu-commands.hx, qmp-commands.hx, and all versions of our qapi-schema.json files going all the way back to v0.12.0. It accomplishes this with some fairly brutish hacks that I never expect to need to check in to qemu.git. (2) A schema "compiler", a QAPI generator module that takes a parsed Schema and produces a single-file JSON Schema document that describes every command and event as it exists on the wire without using type names or any information not considered to be "API". This part *would* need to be checked in to qemu.git (if we go in this direction.) The compiled historical schema would also get checked in, for the QAPI parser to reference against to generate the since information. (Or, some kind of meta-compiled document with just the since information. Either way; the idea is that we'll catalog the output without needing to commit the parser compatibility hacks.) (3) A script that can diff two compiled schema, showing a change report between two versions. (I sent an email earlier today/yesterday showing example output of this script.) This one was more for "fun", but it helped prove all the other parts were working correctly, and it might be useful in the future when auditing changes during the RC phase. We may well decide to commit this script upstream, or one like it. All of those things are here: https://gitlab.com/jsnow/externalized-qapi I'm sharing this in its out-of-tree form mostly for Markus's sake as we debate the pros/cons of various choices I've made in this prototype, but you're welcome to peep the early discussions if you'd like, too. Notes: 1. If you want to try "compiling" schema yourself, clone the git repo and install it with "pip install .". Navigate to your qemu.git root and check out a release tag (such as v0.12.0 or v1.0 or v9.0.0) and then run "qapi-compile". (If your git tags are "weird", this might break. Sorry about that, it's a prototype... the hacky code that uses "git describe" is in qapi/compat.py if you run into troubles and wanna mess around with it.) 2. The "qapi compiler" makes use of schema addendum files for some old versions to produce correct output. You can browse them on gitlab here: https://gitlab.com/jsnow/externalized-qapi/-/tree/main/qapi/schemata?ref_type=heads There are addendum files for v0.12.0 through v2.0.0. Other "errata" are handled in code; no errata of any kind are needed in v2.8.0 or later. 3. If you don't wanna run the compiler yourself (or it broke because it's a real hackjob), I compiled all of the historical QAPI schema myself and checked them into the repo here: https://gitlab.com/jsnow/externalized-qapi/-/tree/main/compiled?ref_type=heads 4. You can diff any two compiled schema with "qapi-schema-diff A.json B.json". Put the earlier version first. 5. qapi-compile and qapi-schema-diff don't yet support "if" and "features" everywhere they should, but everything else should work correctly. 6. The commit history for this repo is actually pretty well factored; each compatibility hack for the QAPI parser has its own commit, so it's easy to suss out what work was required to make this work. I'm about to head off on a long weekend, I'll be back Tuesday. Have fun, --js
