aboutsummaryrefslogtreecommitdiff
path: root/qapi/transaction.json
AgeCommit message (Collapse)Author
2024-08-05qapi: Refill doc comments to conform to conventionsMarkus Armbruster
Sweep the entire documentation again. Last done in commit 209e64d9edf (qapi: Refill doc comments to conform to current conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240729065220.860163-1-armbru@redhat.com> [Straightforward conflict with commit 442110bc6f3 resolved]
2024-07-17qapi: convert "Example" sections without titlesJohn Snow
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples. See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why. Note: an empty "TODO" line was added to announce-self to keep the example from floating up into the body; this will be addressed more rigorously in the new qapidoc generator. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Markup fixed in one place] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: convert "Note" sections to plain rSTJohn Snow
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly. Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives. Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply: .. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ... ... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs. See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use. These are rendered in orange: .. Attention:: ... .. Caution:: ... .. WARNING:: ... These are rendered in red: .. DANGER:: ... .. Error:: ... These are rendered in green: .. Hint:: ... .. Important:: ... .. Tip:: ... These are rendered in blue: .. Note:: ... .. admonition:: custom title admonition body text This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example. NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes *may change* as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: nail down convention that Errors sections are listsJohn Snow
By unstated convention, Errors sections are rST lists. Document the convention, and make the one exception conform. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-10-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-03-04qapi: Delete useless "Returns" sectionsMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-6-armbru@redhat.com>
2024-03-04qapi: Move error documentation to new "Errors" sectionsMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-5-armbru@redhat.com>
2024-02-26qapi: Require descriptions and tagged sections to be indentedMarkus Armbruster
By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples. Turn this into a hard rule, and apply it to examples, too. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [Straightforward conflicts in qapi/migration.json resolved]
2024-02-12qapi: Add missing union tag documentationMarkus Armbruster
Low-hanging fruit, and except for StatsFilter, the only members of these unions lacking documentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2023-05-10qapi: Reformat doc comments to conform to current conventionsMarkus Armbruster
Change # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. to # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale. Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-18-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Acked-by: Lukas Straub <lukasstraub2@web.de> [Straightforward conflicts in qapi/audio.json qapi/misc-target.json qapi/run-state.json resolved]
2021-11-09qapi: deprecate drive-backupVladimir Sementsov-Ogievskiy
Modern way is using blockdev-add + blockdev-backup, which provides a lot more control on how target is opened. As example of drive-backup problems consider the following: User of drive-backup expects that target will be opened in the same cache and aio mode as source. Corresponding logic is in drive_backup_prepare(), where we take bs->open_flags of source. It works rather bad if source was added by blockdev-add. Assume source is qcow2 image. On blockdev-add we should specify aio and cache options for file child of qcow2 node. What happens next: drive_backup_prepare() looks at bs->open_flags of qcow2 source node. But there no BDRV_O_NOCAHE neither BDRV_O_NATIVE_AIO: BDRV_O_NOCAHE is places in bs->file->bs->open_flags, and BDRV_O_NATIVE_AIO is nowhere, as file-posix parse options and simply set s->use_linux_aio. The documentation is updated in a minimal way, so that drive-backup is noted only as a deprecated command, and blockdev-backup used in most of places. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2021-09-27qapi: Convert simple union TransactionAction to flat oneMarkus Armbruster
Simple unions predate flat unions. Having both complicates the QAPI schema language and the QAPI generator. We haven't been using simple unions in new code for a long time, because they are less flexible and somewhat awkward on the wire. To prepare for their removal, convert simple union TransactionAction to an equivalent flat one. Adds some boilerplate to the schema, which is a bit ugly, but a lot easier to maintain than the simple union feature. Cc: Kevin Wolf <kwolf@redhat.com> Cc: Hanna Reitz <hreitz@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Acked-by: Hanna Reitz <hreitz@redhat.com> Message-Id: <20210917143134.412106-11-armbru@redhat.com>
2021-05-12block: Drop the sheepdog block driverMarkus Armbruster
It was deprecated in commit e1c4269763, v5.2.0. See that commit message for rationale. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20210501075747.3293186-1-armbru@redhat.com> ACKed-by: Peter Krempa <pkrempa@redhat.com>
2020-08-03schemas: Add vim modelineAndrea Bolognani
The various schemas included in QEMU use a JSON-based format which is, however, strictly speaking not valid JSON. As a consequence, when vim tries to apply syntax highlight rules for JSON (as guessed from the file name), the result is an unreadable mess which mostly consist of red markers pointing out supposed errors in, well, pretty much everything. Using Python syntax highlighting produces much better results, and in fact these files already start with specially-formatted comments that instruct Emacs to process them as if they were Python files. This commit adds the equivalent special comments for vim. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20200729185024.121766-1-abologna@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-03-06qemu-storage-daemon: Add --monitor optionKevin Wolf
This adds and parses the --monitor option, so that a QMP monitor can be used in the storage daemon. The monitor offers commands defined in the QAPI schema at storage-daemon/qapi/qapi-schema.json. The --monitor options currently allows to create multiple monitors with the same ID. This part of the interface is considered unstable. We will reject such configurations as soon as we have a design for the monitor subsystem to perform these checks. (In the system emulator, we depend on QemuOpts rejecting duplicate IDs.) Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20200224143008.13362-21-kwolf@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2020-02-15qapi: Fix indent level on doc comments in json filesPeter Maydell
The current doc generation doesn't care much about indentation levels, but we would like to switch to an rST format, and rST does care about indentation. Make the doc comments more strongly consistent about indentation for multiline constructs like: @arg: description line 1 description line 2 Returns: line one line 2 so that there is always exactly one space after the colon, and subsequent lines align with the first. This commit is a purely whitespace change, and it does not alter the generated .texi files (because the texi generation code strips away all the extra whitespace). This does mean that we end up with some over-length lines. Note that when the documentation for an argument fits on a single line like this: @arg: one line only then stray extra spaces after the ':' don't affect the rST output, so I have not attempted to methodically fix them, though the preference is a single space here too. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2019-08-16qapi: implement block-dirty-bitmap-remove transaction actionJohn Snow
It is used to do transactional movement of the bitmap (which is possible in conjunction with merge command). Transactional bitmap movement is needed in scenarios with external snapshot, when we don't want to leave copy of the bitmap in the base image. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Max Reitz <mreitz@redhat.com> Message-id: 20190708220502.12977-3-jsnow@redhat.com [Edited "since" version to 4.2 --js] Signed-off-by: John Snow <jsnow@redhat.com>
2019-01-14block: remove 'x' prefix from experimental bitmap APIsJohn Snow
The 'x' prefix was added because I was uncertain of the direction we'd take for the libvirt API. With the general approach solidified, I feel comfortable committing to this API for 4.0. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20181221093529.23855-5-jsnow@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2018-10-29qapi: add transaction support for x-block-dirty-bitmap-mergeVladimir Sementsov-Ogievskiy
New action is like clean action: do the whole thing in .prepare and undo in .abort. This behavior for bitmap-changing actions is needed because backup job actions use bitmap in .prepare. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Reviewed-by: John Snow <jsnow@redhat.com>
2018-06-11qmp: transaction support for x-block-dirty-bitmap-enable/disableVladimir Sementsov-Ogievskiy
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Jeff Cody <jcody@redhat.com> Message-id: 20180606182449.1607-4-jsnow@redhat.com [Added x- prefix. --js] Signed-off-by: John Snow <jsnow@redhat.com>
2017-09-04qapi-schema: Collect transaction stuff in qapi/transaction.jsonMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503602048-12268-11-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>