Introduced in commit db789c6cd33 ("ppc: Provide basic
raise_exception_* functions"), raise_exception_ra() has
never been used. Remove as dead code.
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com>
Message-ID: <20250127102620.39159-9-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Expose powerpc_checkstop() prototype, and move it to
tcg-excp_helper.c, only built when TCG is available.
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com>
Message-ID: <20250127102620.39159-8-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
target/ppc: Ensure powerpc_mcheck_checkstop() is only called under TCG
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20250127102620.39159-7-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
target/ppc: Move ppc_ldl_code() to tcg-excp_helper.c
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com>
Message-ID: <20250127102620.39159-6-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com>
Message-ID: <20250127102620.39159-5-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
target/ppc: Make ppc_ldl_code() declaration public
We are going to move code calling ppc_ldl_code() out of
excp_helper.c where it is defined. Expose its declaration
for few commits, until eventually making it static again
once everything is moved.
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com>
Message-ID: <20250127102620.39159-4-philmd@linaro.org> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
TCG does not model SMT priority, timing, resource controls
and status so this register has no effect for now.
[npiggin: adjust changelog] Signed-off-by: dan tan <dantan@linux.ibm.com>
Message-ID: <20250116154226.13376-1-dantan@linux.vnet.ibm.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Chalapathi V [Mon, 3 Mar 2025 14:13:28 +0000 (08:13 -0600)]
hw/ssi/pnv_spi: Put a limit to RDR match failures
There is a possibility that SPI controller can get into loop due to indefinite
RDR match failures. Hence put a limit to failures and stop the sequencer.
Signed-off-by: Chalapathi V <chalapathi.v@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com>
Message-ID: <20250303141328.23991-5-chalapathi.v@linux.ibm.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Chalapathi V [Mon, 3 Mar 2025 14:13:27 +0000 (08:13 -0600)]
hw/ssi/pnv_spi: Make bus names distinct for each controllers of a socket
Create a spi buses with distinct names on each socket so that responders
are attached to correct SPI controllers.
Change the bus name to chipX.spi.<busnum> where X = 0..<num_sockets>
QOM tree on a 2 socket machine:
(qemu) info qom-tree
/machine (powernv10-machine)
/chip[0] (power10_v2.0-pnv-chip)
/pib_spic[0] (pnv-spi)
/chip0.spi.0 (SSI)
/xscom-spi[0] (memory-region)
/chip[1] (power10_v2.0-pnv-chip)
/pib_spic[0] (pnv-spi)
/chip1.spi.0 (SSI)
/xscom-spi[0] (memory-region)
Signed-off-by: Chalapathi V <chalapathi.v@linux.ibm.com>
Message-ID: <20250303141328.23991-4-chalapathi.v@linux.ibm.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Chalapathi V [Mon, 3 Mar 2025 14:13:26 +0000 (08:13 -0600)]
hw/ssi/pnv_spi: Use local var seq_index instead of get_seq_index().
Use a local variable seq_index instead of repeatedly calling
get_seq_index() method and open-code next_sequencer_fsm().
Signed-off-by: Chalapathi V <chalapathi.v@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com>
Message-ID: <20250303141328.23991-3-chalapathi.v@linux.ibm.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Chalapathi V [Mon, 3 Mar 2025 14:13:25 +0000 (08:13 -0600)]
hw/ssi/pnv_spi: Replace PnvXferBuffer with Fifo8 structure
In PnvXferBuffer dynamically allocating and freeing is a
process overhead. Hence used an existing Fifo8 buffer with
capacity of 16 bytes.
Signed-off-by: Chalapathi V <chalapathi.v@linux.ibm.com>
Message-ID: <20250303141328.23991-2-chalapathi.v@linux.ibm.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Glenn Miles [Tue, 11 Mar 2025 01:55:00 +0000 (11:55 +1000)]
qtest/xive: Add test of pool interrupts
Added new test for pool interrupts. Removed all printfs from pnv-xive2-* qtests.
Signed-off-by: Glenn Miles <milesg@linux.vnet.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Glenn Miles [Tue, 11 Mar 2025 03:36:14 +0000 (13:36 +1000)]
qtest/xive: Change printf to g_test_message
Change all printf() in pnv-xive2-* qtests to g_test_message()
[npiggin: split from pool qtest] Signed-off-by: Glenn Miles <milesg@linux.vnet.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Glenn Miles [Tue, 11 Mar 2025 02:26:33 +0000 (12:26 +1000)]
pnv/xive2: Rename nvp_ to nvx_ if they can refer to NVP or NVGC
The blk/index in some paths may refer to an NVP or an NVGC. When it
is not known ahead of time, use the nvx_ prefix to prevent confusion.
[npiggin: split out of larger fix patch and reworded] Signed-off-by: Glenn Miles <milesg@linux.vnet.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:53:52 +0000 (11:53 +1000)]
ppc/xive2: Support crowd-matching when looking for target
XIVE crowd sizes are encoded into a 2-bit field as follows:
0: 0b00
2: 0b01
4: 0b10
16: 0b11
A crowd size of 8 is not supported.
If an END is defined with the 'crowd' bit set, then a target can be
running on different blocks. It means that some bits from the block
VP are masked when looking for a match. It is similar to groups, but
on the block instead of the VP index.
Most of the changes are due to passing the extra argument 'crowd' all
the way to the function checking for matches.
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Glenn Miles <milesg@linux.vnet.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:51:22 +0000 (11:51 +1000)]
ppc/xive2: Process group backlog when updating the CPPR
When the hypervisor or OS pushes a new value to the CPPR, if the LSMFB
value is lower than the new CPPR value, there could be a pending group
interrupt in the backlog, so it needs to be scanned.
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:51:22 +0000 (11:51 +1000)]
ppc/xive2: Process group backlog when pushing an OS context
When pushing an OS context, we were already checking if there was a
pending interrupt in the IPB and sending a notification if needed. We
also need to check if there is a pending group interrupt stored in the
NVG table. To avoid useless backlog scans, we only scan if the NVP
belongs to a group.
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:51:21 +0000 (11:51 +1000)]
ppc/xive2: Add undelivered group interrupt to backlog
When a group interrupt cannot be delivered, we need to:
- increment the backlog counter for the group in the NVG table
(if the END is configured to keep a backlog).
- start a broadcast operation to set the LSMFB field on matching CPUs
which can't take the interrupt now because they're running at too
high a priority.
[npiggin: squash in fixes from milesg]
[milesg: only load the NVP if the END is !ignore]
[milesg: always broadcast backlog, not only when there are precluded VPs]
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:51:21 +0000 (11:51 +1000)]
ppc/xive2: Support group-matching when looking for target
If an END has the 'i' bit set (ignore), then it targets a group of
VPs. The size of the group depends on the VP index of the target
(first 0 found when looking at the least significant bits of the
index) so a mask is applied on the VP index of a running thread to
know if we have a match.
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Frederic Barrat [Tue, 11 Mar 2025 01:51:21 +0000 (11:51 +1000)]
ppc/xive2: Add grouping level to notification
The NSR has a (so far unused) grouping level field. When a interrupt
is presented, that field tells the hypervisor or OS if the interrupt
is for an individual VP or for a VP-group/crowd. This patch reworks
the presentation API to allow to set/unset the level when
raising/accepting an interrupt.
It also renames xive_tctx_ipb_update() to xive_tctx_pipr_update() as
the IPB is only used for VP-specific target, whereas the PIPR always
needs to be updated.
Signed-off-by: Frederic Barrat <fbarrat@linux.ibm.com> Signed-off-by: Michael Kowal <kowal@linux.ibm.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Fri, 28 Feb 2025 15:07:57 +0000 (01:07 +1000)]
ppc/pnv: Add a default formatted PNOR image
The default PNOR image is erased and not recognised by skiboot, so NVRAM
gets disabled. This change adds a tiny pnor file that is a proper FFS
image with a formatted NVRAM partition. This is recognised by skiboot and
will persist across machine reboots.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Fri, 28 Feb 2025 15:07:57 +0000 (01:07 +1000)]
ppc/pnv: Add a PNOR address and size sanity checks
The BMC HIOMAP PNOR access protocol has certain limits on PNOR addresses
and sizes. Add some sanity checks for these so we don't get strange
behaviour.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Mon, 3 Mar 2025 00:27:01 +0000 (10:27 +1000)]
ppc/pnv: Move PNOR to offset 0 in the ISA FW space
skiboot has a bug that does not handle ISA FW access correctly for IDSEL
devices > 0, and the current PNOR default address and size puts 64MB in
device 0 and 64MB in device 1, which causes skiboot to hit this bug and
breaks PNOR accesses.
Move the PNOR address down to 0 for now, so a 256MB PNOR can be accessed
via device 0.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Fri, 28 Feb 2025 14:36:37 +0000 (00:36 +1000)]
ppc/pnv: Implement LPC FW address space IDSEL
LPC FW address space is a 256MB (28-bit) region to one of 16-devices
that are selected with the IDSEL register. Implement this by making
the ISA FW address space 4GB, and move the 256MB OPB alias within
that space according to IDSEL.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Fri, 28 Feb 2025 17:06:43 +0000 (03:06 +1000)]
ppc/pnv: raise no-response errors if an LPC transaction fails
If nothing responds to an LPC access, the LPC host controller should
set an IRQSTAT error. Model this behaviour.
skiboot uses this error to "probe" LPC accesses, among other things to
determine if a SuperIO chip is present. After this change it recognizes
there is no SuperIO present and does not keep trying to access it.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Fri, 28 Feb 2025 17:16:29 +0000 (03:16 +1000)]
ppc/pnv: Support LPC host controller irqs other than serirqs
The LPC model has only supported serirqs (ISA device IRQs), however
there are internal sources that can raise other interrupts. Update the
device to handle these interrupt sources.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Wed, 18 Dec 2024 13:28:47 +0000 (23:28 +1000)]
target/ppc: Add Power9/10 power management SPRs
Linux power management code accesses these registers for pstate
management. Wire up a very simple implementation.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
---
After OCC fixes in QEMU pnv model and skiboot (since they have suffered
some bitrot), Linux will start performing PM SPR accesses. This is a
very simple implementation that makes it a bit happier.
Nicholas Piggin [Mon, 9 Dec 2024 10:00:45 +0000 (20:00 +1000)]
ppc/pnv/occ: Implement a basic dynamic OCC model
The OCC is an On Chip Controller that handles various thermal and power
management. It is a PPC405 microcontroller that runs its own firmware
which is out of scope of the powernv machine model. Some dynamic
behaviour and interfaces that are important for host CPU testing can be
implemented with a much simpler state machine.
This change adds a 100ms timer that ticks through a simple state machine
that looks for "OCC command requests" coming from host firmware, and
responds to them.
For now the powercap command is implemented because that is used by
OPAL and exported to Linux and is easy to test.
Nicholas Piggin [Sat, 16 Nov 2024 14:29:13 +0000 (00:29 +1000)]
ppc/pnv: Make HOMER memory a RAM region
The HOMER is a region of memory used by host and firmware and
microconrollers. It has very little logic by itself, just some BAR
registers. Users of this memory should operate on it rather than
have HOMER implement them with MMIO registers, which is not the
right model.
This change switches the implementation of HOMER from MMIO to RAM,
and moves the OCC register implementation to in-memory structure
accesses performed by the OCC model.
This has the downside that access to unimplemented regions of HOMER
are no longer flagged. Perhaps that could be done by adding a memory
region for HOMER, and ram subregions under that for each implemented
part. But for now this takes the simpler approach.
Note: This brings some data structure definitions from skiboot, which
does not match QEMU coding style but is not changed to make comparisons
and updates simpler.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Afterward, there is no error and the sensor_groups directory appears
under /sys/firmware/opal/.
The SLW_IMAGE_BASE address looks like a workaround to intercept firmware
memory accesses, but that does not seem to be required now (and would
have been broken by the OCC common area region mapping change anyway).
So it can be removed.
Fixes: 3a1b70b66b5cb4 ("ppc/pnv: Fix OCC common area region mapping") Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Tue, 10 Dec 2024 02:08:35 +0000 (12:08 +1000)]
ppc/pnv/homer: Make dummy reads return 0
HOMER memory implements some dummy registers that return a nonsense
value to satisfy skiboot accesses caused by "SLW" init and register
save/restore programming that has never worked under QEMU:
[ 0.265000943,3] SLW: Failed to set HRMOR for CPU 0,RC=0x1
[ 0.265356988,3] Disabling deep stop states
To simplify a later change to implement HOMER as a RAM area, make
these return zero, which has the same result.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Mon, 9 Dec 2024 13:16:35 +0000 (23:16 +1000)]
ppc/pnv/homer: Fix OCC registers
The HOMER OCC registers seem to have bitrotted and fail for various
reasons on powernv8, 9, and 10.
The major problems are that POWER8 has the wrong version value and its
pstate ordering is incorrect. POWER9/10 have not set the OCC state to
active. Non-zero chips are also set to OCC slaves for POWER9/10.
Unfortunately skiboot has also bitrotted and requires fixes that are
not yet in the bios files to run. With a patched skiboot, before this
change, powernv9/10 report:
[ 0.262050394,3] OCC: Chip: 0: OCC not active
[ 0.262128603,3] OCC: Initialization on all chips did not complete(timed out)
powernv8 reports:
[ 0.173572100,3] OCC: Unknown OCC-OPAL interface version.
[ 0.173812059,3] OCC: Initialization on all chips did not complete(timed out)
Nicholas Piggin [Sat, 16 Nov 2024 10:19:19 +0000 (20:19 +1000)]
ppc/pnv/phb4: Add pervasive chiplet support to PHB4/5
Each non-core chiplet on a chip has a "pervasive chiplet" unit and its
xscom register set. This adds support for PHB4/5.
skiboot reads the CPLT_CONF1 register in __phb4/5_get_max_link_width(),
which shows up as unimplemented xscom reads. Set a value in PCI CONF1
register's link-width field to demonstrate skiboot doing something
interesting with it.
In the bigger picture, it might be better to model the pervasive
chiplet type as parent that each non-core chiplet model derives from.
For now this is enough to get the PHB registers implemented and working
for skiboot, and provides a second example (after the N1 chiplet) that
will help if the design is reworked as such.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
Nicholas Piggin [Tue, 11 Mar 2025 04:54:49 +0000 (14:54 +1000)]
ppc/pnv: Update skiboot to 7.1-106
This skiboot firmware importantly contains updates for HOMER/OCC bugs.
These subsystems have bitrotted in QEMU and skiboot and this update
allows new QEMU models to be exercised.
Power11 support is also added. This model is not yet merged in QEMU,
but firmware support will make development and testing simpler.
Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
The ref405ep machine is scheduled for removal in QEMU 10.0. Keep the
405 CPU implementation for a while because it is theoretically
possible to model the power management (OCC) co-processor found on the
IBM POWER [8-11] processors.
Signed-off-by: Cédric Le Goater <clg@redhat.com> Reviewed-by: Nicholas Piggin <npiggin@gmail.com>
Message-ID: <20250204080649.836155-4-clg@redhat.com> Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
scripts/qapi/backend: Clean up create_backend()'s failure mode
create_backend()'s caller catches QAPIError, and returns non-zero exit
code on catch. The caller's caller passes the exit code to
sys.exit().
create_backend() doesn't care: it reports errors to stderr and
sys.exit()s.
Change it to raise QAPIError instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250311065352.992307-1-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
John Snow [Tue, 11 Mar 2025 03:43:01 +0000 (23:43 -0400)]
MAINTAINERS: Add jsnow as maintainer for Sphinx documentation
Since I've just about rewritten the entirety of the QAPI documentation
system, it's probably fair that I be the contact point for if it goes
awry.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-64-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:43:00 +0000 (23:43 -0400)]
docs: add qapi-domain syntax documentation
Who documents the documentation?
Me, I guess.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-63-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:59 +0000 (23:42 -0400)]
docs: enable qapidoc transmogrifier for QEMU QMP Reference
We are not enabling the transmogrifier for QSD or QGA yet because we
don't (yet) have a way to create separate indices, and all of the
definitions will bleed together, which isn't so nice.
For now, QMP is better than nothing at all!
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-62-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:58 +0000 (23:42 -0400)]
docs: disambiguate cross-references
The next patch will engage the qapidoc transmogrifier, which creates a
lot of cross-reference targets. Some of the existing targets
("migration", "qom", "replay") will become ambiguous as a result. Nail
them down more explicitly to prevent ambiguous cross-reference warnings.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-61-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:57 +0000 (23:42 -0400)]
qapi/parser: add undocumented stub members to all_sections
Parser and doc generator cooperate on generating stub documentation for
undocumented members. The parser makes up an ArgSection with an empty
description, and the doc generator makes up a description.
Right now, the made-up ArgSections go into doc.args. However, the new
doc generator uses .all_sections, not .args. So put them into
.all_sections, too.
Insert them right after existing 'member' sections. If there are none,
insert directly after the leading section.
Doesn't affect the old generator, because that one doesn't use
.all_sections.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-60-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message rewritten] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:56 +0000 (23:42 -0400)]
docs/qapidoc: generate entries for undocumented members
Presently, we never have any empty text entries for members. The next
patch will explicitly generate such sections, so enable support for it
in advance.
The parser will generate placeholder sections to indicate undocumented
members, but it's the qapidoc generator that's responsible for deciding
what to do with that stub section.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-59-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com>
[Tweak the stub section text] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:55 +0000 (23:42 -0400)]
docs/qapidoc: Add "the members of" pointers
Add "the members of ..." pointers to Members and Arguments lists where
appropriate, with clickable cross-references - so it's a slight
improvement over the old system :)
This patch is meant to be a temporary solution until we can review and
merge the inliner.
The implementation of this patch is a little bit of a hack: Sphinx is
not designed to allow you to mix fields of different "type"; i.e. mixing
member descriptions and free-form text under the same heading. To
accomplish this with a minimum of hackery, we technically document a
"dummy field" and then just strip off the documentation for that dummy
field in a post-processing step. We use the "q_dummy" variable for this
purpose, then strip it back out before final processing. If this
processing step should fail, you'll see warnings for a bad
cross-reference. (So if you don't see any, it must be working!)
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-58-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:54 +0000 (23:42 -0400)]
docs/qapidoc: add intermediate output debugger
Add debugging output for the qapidoc transmogrifier - setting DEBUG=1
will produce .ir files (one for each qapidoc directive) that write the
generated rst file to disk to allow for easy debugging and verification
of the generated document.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-57-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:53 +0000 (23:42 -0400)]
docs/qapidoc: process @foo into ``foo``
Add support for the special QAPI doc syntax to process @references as
``preformatted text``. At the moment, there are no actual
cross-references for individual members, so there is nothing to link
against. For now, process it identically to how we did in the old
qapidoc system.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-56-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:52 +0000 (23:42 -0400)]
docs/qapidoc: implement transmogrify() method
This is the true top-level processor for the new transmogrifier;
responsible both for generating the intermediate rST and then running
the nested parse on that generated document to produce the final
docutils tree that is then - very finally - postprocessed by sphinx for
final rendering to HTML &c.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-55-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com>
[Use the opportunity to move the __version__ assignment to where
PEP 8 wants it] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:51 +0000 (23:42 -0400)]
docs/qapidoc: add visit_entity()
Finally, the core entry method for a qapi entity.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-54-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:50 +0000 (23:42 -0400)]
docs/qapidoc: add visit_sections() method
Implement the actual main dispatch method that processes and handles the
list of doc sections for a given QAPI entity.
Process doc sections in strict source order. This is good; reordering
doc text is undesirable. Improvement over the old doc generator, which
can reorder doc comments that don't adhere to (largely unspoken)
conventions.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-53-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com>
[Commit message extended] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:49 +0000 (23:42 -0400)]
docs/qapidoc: add visit_member() method
This method is used for generating the "members" of a wide variety of
things, including structs, unions, enums, alternates, etc. The field
name it uses to do so is dependent on the type of entity the "member"
belongs to.
Currently, IF conditionals for individual members are not handled or
rendered, a small regression from the prior documentation
generator. This will be fixed in a future patch.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-52-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:48 +0000 (23:42 -0400)]
docs/qapidoc: add visit_returns() method
Generates :return: fields for explicit returns statements. Note that
this does not presently handle undocumented returns, which is handled in
a later commit.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-51-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:47 +0000 (23:42 -0400)]
docs/qapidoc: prepare to record entity being transmogrified
Prepare to keep a record of which entity we're working on documenting
for the purposes of being able to change certain generative features
conditionally and create stronger assertions.
If you find yourself asking: "Wait, but where does the current entity
actually get recorded?!", you're right! That part comes with the
visit_entity() implementation, which gets added later.
This patch is front-loaded for the sake of type checking in the
forthcoming commits before visit_entity() is ready to be added.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-50-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:46 +0000 (23:42 -0400)]
docs/qapidoc: add visit_feature() method
This adds a simple ":feat name: lorem ipsum ..." line to the generated
rST document, so at the moment it's only for "top level" features.
Features not attached directly to a QAPI definition are not currently
handled! This is a small regression over the prior documentation
generator that will be addressed in a future patch.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-49-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:45 +0000 (23:42 -0400)]
docs/qapidoc: add add_field() and generate_field() helper methods
These are simple rST generation methods that assist in getting the types
and formatting correct for a field list entry. add_field() is a more
raw, direct call while generate_field() is intended to be used for
generating the correct field from a member object.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-48-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:44 +0000 (23:42 -0400)]
docs/qapidoc: add format_type() method
This method is responsible for generating a type name for a given member
with the correct annotations for the QAPI domain. Features and enums do
not *have* types, so they return None. Everything else returns the type
name with a "?" suffix if that type is optional, and ensconced in
[brackets] if it's an array type.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-47-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:43 +0000 (23:42 -0400)]
docs/qapidoc: add visit_errors() method
Notably, this method does not currently address the formatting issues
present with the "errors" section in QAPIDoc and just vomits the text
verbatim into the rST doc, with somewhat inconsistent results.
To be addressed in a future patch.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-46-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:42 +0000 (23:42 -0400)]
docs/qapidoc: add visit_paragraph() method
This transforms "formerly known as untagged sections" into our pure
intermediate rST format. These sections are already pure rST, so this
method doesn't do a whole lot except ensure appropriate newlines.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-45-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:41 +0000 (23:42 -0400)]
docs/qapidoc: add preamble() method
This method adds the options/preamble to each definition block. Notably,
:since: and :ifcond: are added, as are any "special features" such as
:deprecated: and :unstable:.
If conditionals, if attached to special features, are currently
unhandled in this patch and will be addressed at a future date. We
currently do not have any if conditionals attached to special features.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-44-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:40 +0000 (23:42 -0400)]
docs/qapidoc: add visit_freeform() method
Add the transmogrifier implementation for converting freeform doc blocks
to rST.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-43-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
This is for the sake of the new rST generator (the "transmogrifier") so
we can advance multiple lines on occasion while keeping the
generated<-->source mappings accurate.
next_line now simply takes an optional n parameter which chooses the
number of lines to advance.
The next patch will use this when converting section syntax in free-form
documentation to more traditional rST section header syntax, which does
not always line up 1:1 for line counts.
For example:
```
##
# = Section <-- Info is pointing here, "L1"
#
# Lorem Ipsum
##
```
After consuming the single "Section" line from the source, we want to
advance the source pointer to the next non-empty line which requires
jumping by more than one line.
Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250311034303.75779-42-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:38 +0000 (23:42 -0400)]
docs/qapidoc: add visit_module() method
This method annotates the start of a new module, crediting the source
location to the first line of the module file.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-41-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:37 +0000 (23:42 -0400)]
docs/qapidoc: add transmogrifier class stub
Add the beginnings of the Transmogrifier class by adding the rST
conversion helpers that will be used to build the virtual rST document.
This version of the class does not actually "do anything" yet; each
individual feature is added one-at-a-time in the forthcoming commits.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-40-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:35 +0000 (23:42 -0400)]
docs/qapidoc: Fix static typing on qapidoc.py
Now that the legacy code is factored out, fix up the typing on the
remaining code in qapidoc.py. Add a type ignore to qapi_legacy.py to
prevent the errors there from bleeding out into qapidoc.py.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-38-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:34 +0000 (23:42 -0400)]
docs/qapidoc: split old implementation into qapidoc_legacy.py
This is being done primarily to be able to type check and delint the new
implementation without needing to worry about fixing up the old
implementation.
I'm adding the new implementation into the existing file instead of into
a new file so that when the dust settles, qapidoc.py will contain the
full history of development on this generative module.
This patch *should* be pure motion, give or take the import statements.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-37-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:33 +0000 (23:42 -0400)]
docs/qapidoc: add transmogrifier stub
This commit adds a stubbed option to the qapi-doc directive that opts-in
to the new rST generator; the implementation of which will follow in
subsequent commits.
Once all QAPI documents have been converted, this option and the old
qapidoc implementation can be dropped.
Note that moving code outside of the try...except block has no impact
because the code moved outside of that block does not ever raise a
QAPIError.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-36-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:32 +0000 (23:42 -0400)]
qapi/schema: add __repr__ to QAPIDoc.Section
Makes debugging far more pleasant when you can just print(section) and
get something reasonable to display.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-35-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* @foo can be a member or a feature description, depending on context.
* tag == 'Since' can be a Since: section or a member or feature
description. If it's a Section, it's the former, and if it's an
ArgSection, it's the latter.
Clean this up as follows. Move the member or feature name to new
ArgSection attribute @name, and replace @tag by enum @kind like this:
type kind name
untagged Section PLAIN
@foo: ArgSection MEMBER 'foo' if member or argument
ArgSection FEATURE 'foo' if feature
Returns: Section RETURNS
Errors: Section ERRORS
Since: Section SINCE
TODO: Section TODO
The qapi-schema tests are updated to account for the new section names;
"TODO" becomes "Todo" and `None` becomes "Plain" there.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-34-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:30 +0000 (23:42 -0400)]
qapi/parser: adjust info location for doc body section
Instead of using the info object for the doc block as a whole (which
always points to the very first line of the block), update the info
pointer for each call to ensure_untagged_section when the existing
section is otherwise empty. This way, Sphinx error information will
match precisely to where the text actually starts.
For example, this patch will move the info pointer for the "Hello!"
untagged section ...
> ## <-- from here ...
> # Hello! <-- ... to here.
> ##
This doesn't seem to improve error reporting now. It will with the
forthcoming QAPI doc transmogrifier.
If I stick bad rST into qapi/block-core.json like this:
> ##
> # @SnapshotInfo:
> #
> +# rST syntax error: *ahh!
> +#
> # @id: unique shapshot id
> #
> # @name: user chosen name
The existing code's error message will point to the beginning of the doc
comment, which is less than helpful. The transmogrifier's message will
point to the erroneous line, but to accomplish this, it needs this
patch.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-33-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:29 +0000 (23:42 -0400)]
docs/qapi-domain: Fix error context reporting in Sphinx 5.x and 6.x
Sphinx 5.3.0 to Sphinx 6.2.0 has a bug where nested content in an
ObjectDescription content block has its error position reported
incorrectly due to an oversight when they added nested section support
to this directive.
(This bug is present in Sphinx's own Python and C domains; test it
yourself by creating a py:func directive and creating a syntax error in
the directive's content block. The reporting will be incorrect.)
To avoid overriding and re-implementing the entirety of the run()
method, a workaround is employed where we parse the content block
ourselves in before_content(), then null the content block to make
Sphinx's own parsing a no-op. Then, in transform_content (which occurs
after Sphinx's nested parse), we simply swap our own parsed content tree
back in for Sphinx's.
It appears a little tricky, but it's the nicest solution I can find.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-32-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:28 +0000 (23:42 -0400)]
docs/qapi-domain: warn when QAPI domain xrefs fail to resolve
This patch adds a warning (which is a build failure under our current
build settings) whenever a QAPI cross-reference fails to resolve.
This applies to any cross-references of the form :qapi:{role}:`foo`,
which covers all of the automatically generated references by the qapi
domain, and any such references that are manually written into the
documentation rst files.
Cross-references of the form `foo` do not use this system, but are
already configured to issue a warning (Again, a build failure) if the
cross-reference isn't found anywhere.
Adds warnings that look like the following:
docs/qapi/index.rst:48: WARNING: qapi:type reference target not found: 'footype' [ref.qapi]
docs/qapi/index.rst:50: WARNING: qapi:mod reference target not found: 'foomod' [ref.qapi]
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-31-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:27 +0000 (23:42 -0400)]
docs/qapi-domain: add XREF compatibility goop for Sphinx < 4.1
Sphinx < 4.1 handles cross-references ... differently. Factor out and
isolate the compatibility goop we need to make cross references work
properly in old versions of Sphinx.
Yes, it's ugly. Yes, it works. No, I don't want to talk about
it.
Understand that this patch exists because of the overflowing love in my
heart.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-30-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:25 +0000 (23:42 -0400)]
docs/qapi-domain: add type cross-refs to field lists
This commit, finally, adds cross-referencing support to various field
lists; modeled tightly after Sphinx's own Python domain code.
Cross-referencing support is added to type names provided to :arg:,
:memb:, :returns: and :choice:.
:feat:, :error: and :value:, which do not take type names, do not
support this syntax.
The general syntax is simple:
:arg TypeName ArgName: Lorem Ipsum ...
The domain will transform TypeName into :qapi:type:`TypeName` in this
basic case, and also apply the ``literal`` decoration to indicate that
this is a type cross-reference.
For optional arguments, the special "?" suffix is used. Because "*" has
special meaning in rST that would cause parsing errors, we elect to use
"?" instead. The special syntax processing strips this character from
the end of any type name argument and will append ", optional" to the
rendered output, applying the cross-reference only to the actual type
name.
The intent here is that the actual syntax in doc-blocks need not change;
but e.g. qapidoc.py will need to process and transform "@arg foo lorem
ipsum" into ":arg type? foo: lorem ipsum" based on the schema
information. Therefore, nobody should ever actually witness this
intermediate syntax unless they are writing manual documentation or the
doc transmogrifier breaks.
For array arguments, type names can similarly be surrounded by "[]",
which are stripped off and then re-appended outside of the
cross-reference.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-28-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:24 +0000 (23:42 -0400)]
docs/qapi-domain: add warnings for malformed field lists
Normally, Sphinx will silently fall back to its standard field list
processing if it doesn't match one of your defined fields. A lot of the
time, that's not what we want - we want to be warned if we goof
something up.
For instance, the canonical argument field list form is:
:arg type name: descr
This form is captured by Sphinx and transformed so that the field label
will become "Arguments:". It's possible to omit the type name and descr
and still have it be processed correctly. However, if you omit the type
name, Sphinx no longer recognizes it:
:arg: this is not recognized.
This will turn into an arbitrary field list entry whose label is "Arg:",
and it otherwise silently fails. You may also see failures for doing
things like using :values: instead of :value:, or :errors: instead of
:error:, and so on. It's also case sensitive, and easy to trip up.
Add a validator that guarantees all field list entries that are the
direct child of an ObjectDescription use only recognized forms of field
lists, and emit a warning (treated as error by default in most build
configurations) whenever we detect one that is goofed up.
However, there's still benefit to allowing arbitrary fields -- they are
after all not a Sphinx invention, but perfectly normal docutils
syntax. Create an allow list for known spellings we don't mind letting
through, but warn against anything else.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-27-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:23 +0000 (23:42 -0400)]
docs/qapi-domain: add :ifcond: directive option
Add a special :ifcond: option that allows us to annotate the
definition-level conditionals.
The syntax of the argument is currently undefined, but it's possible we
can apply better formatting in the future. Currently, we just display
the ifcond string as preformatted text.
Signed-off-by: Harmonie Snow <harmonie@gmail.com> Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-26-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:22 +0000 (23:42 -0400)]
docs/qapi-domain: add :unstable: directive option
Although "unstable" is a feature (and *will* appear in the features
list), add a special :unstable: option to generate an eye-catch that
makes this information very hard to miss.
The forthcoming Transmogrifier in qapidoc.py will add this option
whenever it detects that the features list attached to a definition
contains the "unstable" entry.
Signed-off-by: Harmonie Snow <harmonie@gmail.com> Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-25-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
Although "deprecated" is a feature (and *will* appear in the features
list), add a special :deprecated: option to generate an eye-catch that
makes this information very hard to miss.
The forthcoming Transmogrifier in qapidoc.py will add this option
whenever it detects that the features list attached to a definition
contains the "deprecated" entry.
P.S., I outsourced the CSS ;)
Signed-off-by: Harmonie Snow <harmonie@gmail.com> Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-24-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:20 +0000 (23:42 -0400)]
docs/qapi-domain: add qapi:object directive
Adds the .. qapi:object:: directive, object, and :qapi:obj:`name`
cross-referencing role. This directive is meant to document both structs
and unions.
As per usual, QAPI cross-referencing for types in the member field list
will be added in a forthcoming commit.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-23-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:19 +0000 (23:42 -0400)]
docs/qapi-domain: add qapi:event directive
Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
cross-referencing role.
Adds the :memb type name: field list syntax for documenting event data
members. As this syntax and phrasing will be shared with Structs and
Unions as well, add the field list definition to a shared abstract
class.
As per usual, QAPI cross-referencing for types in the member field list
will be added in a forthcoming commit.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-22-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:18 +0000 (23:42 -0400)]
docs/qapi-domain: add qapi:alternate directive
Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
cross-reference role.
Add the "Alternatives:" field list for describing alternate choices. Like
other field lists that reference QAPI types, a forthcoming commit will
add cross-referencing support to this field.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-21-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:17 +0000 (23:42 -0400)]
docs/qapi-domain: add qapi:enum directive
Add the .. qapi:enum:: directive, object, and :qapi:enum:`name`
cross-reference role.
Add the :value name: field list for documenting Enum values.
Of note, also introduce a new "type" role that is intended to be used by
other QAPI object directives to cross-reference arbitrary QAPI type
names, but will exclude commands, events, and modules from
consideration.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-20-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:16 +0000 (23:42 -0400)]
docs/qapi-domain: add "Return:" field lists
Add "Return:" field list syntax to QAPI Commands.
Like "Arguments:" and "Errors:", the type name isn't currently processed
for cross-referencing, but this will be addressed in a forthcoming
commit.
The syntax of the new field is:
:return TypeName: description
description cont'd
This patch adds "Return" as a GroupedField, which means that multiple
return values can be annotated - this is only done because Sphinx does
not support mandatory type arguments to Ungrouped fields. Because we
want to cross-reference this type information later, we want to make the
type argument mandatory. As a result, you can technically add multiple
:return: fields, though I'm not aware of any circumstance in which you'd
need or want to. Recommendation: "Don't do that, then." The forthcoming
QAPIDoc transmogrifier does not, in fact, ever "do that".
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-19-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:15 +0000 (23:42 -0400)]
docs/qapi-domain: add "Errors:" field lists
``:error: descr`` can now be used to document error conditions. The
format of the description is not defined here; so the ability to name
specific types is left to the document writer.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-18-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:14 +0000 (23:42 -0400)]
docs/qapi-domain: add "Features:" field lists
Add support for Features field lists. There is no QAPI-specific
functionality here, but this could be changed if desired (if we wanted
the feature names to link somewhere, for instance.)
This feature list doesn't have any restrictions, so it can be used to
document object-wide features or per-member features as deemed
appropriate. It's essentially free-form text.
The syntax for this field is:
:feat name: description
description cont'd
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-17-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:13 +0000 (23:42 -0400)]
docs/qapi-domain: add "Arguments:" field lists
This adds special rendering for Sphinx's typed info field lists.
This patch does not add any QAPI-aware markup, rendering, or
cross-referencing for the type names, yet. That feature requires a
subclass to TypedField which will happen in its own commit quite a bit
later in this series; after all the basic fields and objects have been
established first.
The syntax for this field is:
:arg type name: description
description cont'd
You can omit the type or the description. You should not omit the name;
if you do so, it degenerates into a "normal field list" entry, and
probably isn't what you want.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-16-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:12 +0000 (23:42 -0400)]
docs/qapi-domain: add :since: directive option
Add a little special markup for registering "Since:" information. Adding
it as an option instead of generic content lets us hoist the information
into the Signature bar, optionally put it in the index, etc.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-15-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:11 +0000 (23:42 -0400)]
docs/qapi-domain: add qapi:command directive
This commit adds a stubbed version of QAPICommand that utilizes the
QAPIObject class, the qapi:command directive, the :qapi:cmd:
cross-reference role, and the "command" object type in the QAPI object
registry.
They don't do anything *particularly* interesting yet, but that will
come in forthcoming commits.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-14-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow [Tue, 11 Mar 2025 03:42:10 +0000 (23:42 -0400)]
docs/qapi-domain: add QAPIObject class
This patch adds another abstract class that describes "a QAPI
thingie". The main difference here is that this class will be generating
visible documentation, unlike the QAPIDescription class.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-13-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
projects / thirdparty / qemu.git / log
