summary refs log tree commit diff stats
path: root/qapi/block.json (follow)
Commit message (Collapse)AuthorAgeFilesLines
* qapi: add cross-references to block layerJohn Snow2025-07-141-7/+7
| | | | | | | | Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250711054005.60969-4-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Two unwanted cross-references dropped] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: rephrase return docs to avoid type nameJohn Snow2025-07-141-1/+1
| | | | | | | | | | | | | | "Returns: <description>" is rendered like "Return: <Type> – <description>". Mentioning the type in the description again is commonly redundant. Rephrase such descriptions not to. Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250711051045.51110-5-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> [Commit message amended to explain why] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* docs/sphinx: remove special parsing for freeform sectionsJohn Snow2025-07-141-2/+5
| | | | | | | | | | | | | | | | | Remove the QAPI doc section heading syntax, use plain rST section headings instead. Tests and documentation are updated to match. Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250618165353.1980365-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Add more detail to commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Fix capitalization in doc commentsMarkus Armbruster2025-06-031-1/+1
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250527073916.1243024-8-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: use imperative style in documentationPierrick Bouvier2025-05-281-1/+1
| | | | | | | | | | As requested by Markus: > We prefer imperative mood "Return" over "Returns". Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Message-ID: <20250522190542.588267-14-pierrick.bouvier@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Change several more]
* qapi: Refill doc comments to conform to conventionsMarkus Armbruster2024-08-051-6/+6
| | | | | | | | | | | | | | | 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]
* qapi: convert "Example" sections with longer proseJohn Snow2024-07-171-11/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | These examples require longer explanations or have explanations that require markup to look reasonable when rendered and so use the longer form of the ".. qmp-example::" directive. By using the :annotated: option, the content in the example block is assumed *not* to be a code block literal and is instead parsed as normal rST - with the exception that any code literal blocks after `::` will assumed to be a QMP code literal block. Note: There's one title-less conversion in this patch that comes along for the ride because it's part of a larger "Examples" block that was better to convert all at once. See commit-5: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+1: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-9-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: convert "Example" sections with titlesJohn Snow2024-07-171-7/+6
| | | | | | | | | | | | | | | | | | | | | | | | When an Example section has a brief explanation, convert it to a qmp-example:: section using the :title: option. Rule of thumb: If the title can fit on a single line and requires no rST markup, it's a good candidate for using the :title: option of qmp-example. In this patch, trailing punctuation is removed from the title section for consistent headline aesthetics. In just one case, specifics of the example are removed to make the title read better. See commit-4: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+2: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-8-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: convert "Example" sections without titlesJohn Snow2024-07-171-8/+10
| | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: convert "Note" sections to plain rSTJohn Snow2024-07-061-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: Refill doc comments to conform to current conventionsMarkus Armbruster2024-03-261-2/+2
| | | | | | | | | | | | | For legibility, wrap text paragraphs so every line is at most 70 characters long. 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 refilled paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-11-armbru@redhat.com>
* qapi: Tidy up block-latency-histogram-set documentation some moreMarkus Armbruster2024-03-261-5/+5
| | | | | | | | | Commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions) reflowed some text that should have been left alone. Revert that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-4-armbru@redhat.com>
* qapi: Delete useless "Returns" sectionsMarkus Armbruster2024-03-041-6/+0
| | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-6-armbru@redhat.com>
* qapi: Move error documentation to new "Errors" sectionsMarkus Armbruster2024-03-041-2/+6
| | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-5-armbru@redhat.com>
* qapi: Require descriptions and tagged sections to be indentedMarkus Armbruster2024-02-261-138/+138
| | | | | | | | | | | | 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]
* qapi: Reformat recent doc comments to conform to current conventionsMarkus Armbruster2023-07-261-2/+2
| | | | | | | | | | | | | | | Since commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions), a number of comments not conforming to the current formatting conventions were added. No problem, just sweep the entire documentation once more. 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: <20230720071610.1096458-7-armbru@redhat.com>
* qapi/block: Tidy up block-latency-histogram-set documentationMarkus Armbruster2023-07-261-4/+4
| | | | | | | | | | | | | | | | Examples come out like Example set new histograms for all io types with intervals [0, 10), [10, 50), [50, 100), [100, +inf): The sentence "set new histograms ..." starts with a lower case letter. Capitalize it. Same for the other examples. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20230720071610.1096458-3-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
* block: add accounting for zone append operationSam Li2023-05-151-0/+4
| | | | | | | | | | Taking account of the new zone append write operation for zoned devices, BLOCK_ACCT_ZONE_APPEND enum is introduced as other I/O request type (read, write, flush). Signed-off-by: Sam Li <faithilikerun@gmail.com> Message-id: 20230508051916.178322-3-faithilikerun@gmail.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
* qapi: Reformat doc comments to conform to current conventionsMarkus Armbruster2023-05-101-100/+114
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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]
* qapi: Tidy up examplesMarkus Armbruster2023-04-281-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | A few examples neglect to prefix QMP input with '->'. Fix that. Two examples have extra space after '<-'. Delete it. A few examples neglect to show output. Provide some. The example output for query-vcpu-dirty-limit could use further improvement. Add a TODO comment. Use "Examples:" instead of "Example:" where multiple examples are given. One example section numbers its two examples. Not done elsewhere; drop. Another example section separates them with "or". Likewise. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230425064223.820979-8-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
* block: add more commands to preconfig modePaolo Bonzini2022-06-141-2/+4
| | | | | | | | | | | | Of the block device commands, those that are available outside system emulators do not require a fully constructed machine by definition. Allow running them before machine initialization has concluded. Of the ones that are available inside system emulation, allow querying the PR managers, and setting up accounting and throttling. Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* qapi: Stop using whitespace for alignment in commentsAndrea Bolognani2022-05-161-3/+3
| | | | | | | | | | | | | | | | Perfectly aligned things look pretty, but keeping them that way as the schema evolves requires churn, and in some cases newly-added lines are not aligned properly. Overall, trying to align things is just not worth the trouble. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20220503073737.84223-8-abologna@redhat.com> Message-Id: <20220503073737.84223-9-abologna@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Two patches squashed together] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Drop unnecessary whitespace in commentsAndrea Bolognani2022-05-161-1/+1
| | | | | | | | | | | The only instances that get changed are those in which the additional whitespace was not (or couldn't possibly be) used for alignment purposes. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20220503073737.84223-7-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Drop unnecessary empty lines outside of commentsAndrea Bolognani2022-05-161-3/+0
| | | | | | | | Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220503073737.84223-6-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Drop unnecessary empty lines in commentsAndrea Bolognani2022-05-161-1/+0
| | | | | | | | Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220503073737.84223-5-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Add missing separators between sectionsAndrea Bolognani2022-05-161-0/+1
| | | | | | | | | | | This only affects readability. The generated documentation doesn't change. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220503073737.84223-4-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* block: add 'force' parameter to 'blockdev-change-medium' commandDenis V. Lunev2022-04-251-0/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 'blockdev-change-medium' is a convinient wrapper for the following sequence of commands: * blockdev-open-tray * blockdev-remove-medium * blockdev-insert-medium * blockdev-close-tray and should be used f.e. to change ISO image inside the CD-ROM tray. Though the guest could lock the tray and some linux guests like CentOS 8.5 actually does that. In this case the execution if this command results in the error like the following: Device 'scsi0-0-1-0' is locked and force was not specified, wait for tray to open and try again. This situation is could be resolved 'blockdev-open-tray' by passing flag 'force' inside. Thus is seems reasonable to add the same capability for 'blockdev-change-medium' too. Signed-off-by: Denis V. Lunev <den@openvz.org> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@openvz.org> Acked-by: "Dr. David Alan Gilbert" <dgilbert@redhat.com> CC: Kevin Wolf <kwolf@redhat.com> CC: Hanna Reitz <hreitz@redhat.com> CC: Eric Blake <eblake@redhat.com> CC: Markus Armbruster <armbru@redhat.com> Message-Id: <20220412221846.280723-1-den@openvz.org> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Hanna Reitz <hreitz@redhat.com>
* qapi: Normalize version references x.y.0 to just x.yMarkus Armbruster2020-12-101-1/+1
| | | | | | | | | | We use x.y most of the time, and x.y.0 sometimes. Normalize for consistency. Reported-by: Eduardo Habkost <ehabkost@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201118064158.3359056-1-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi/block.json: Add newline after "Example:" for block-latency-histogram-setPeter Maydell2020-09-291-4/+8
| | | | | | | | | | | | | | | | | | | | | | | The block-latency-histogram-set command is the only one which uses the Example/Examples section with the first line of the documentation immediately following the ':'. Bring it into line with the rest. This will allow us to avoid special-casing the indentation handling for "Examples" sections; instead for Examples as for any other section header these two indentations will be equivalent: Examples: Line one Line two Examples: Line one Line two Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-3-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* schemas: Add vim modelineAndrea Bolognani2020-08-031-0/+1
| | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: Mark deprecated QMP parts with feature 'deprecated'Markus Armbruster2020-03-171-9/+21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add feature 'deprecated' to the deprecated QMP commands, so their deprecation becomes visible in output of query-qmp-schema. Looks like this: {"name": "query-cpus", "ret-type": "[164]", "meta-type": "command", "arg-type": "0", ---> "features": ["deprecated"]} Management applications could conceivably use this for static checking. The deprecated commands are change, cpu-add, migrate-set-cache-size, migrate_set_downtime, migrate_set_speed, query-cpus, query-events, query-migrate-cache-size. The deprecated command arguments are block-commit arguments @base and @top, and block_set_io_throttle, blockdev-change-medium, blockdev-close-tray, blockdev-open-tray, eject argument @device. The deprecated command results are query-cpus-fast result @arch, query-block result @dirty-bitmaps, query-named-block-nodes result @encryption_key_missing and result @dirty-bitmaps's member @status. Same for query-block result @inserted, which mirrors query-named-block-nodes. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200317115459.31821-27-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* block: Move sysemu QMP commands to QAPI block moduleKevin Wolf2020-03-061-0/+386
| | | | | | | | | | | | | | QMP commands that are related to the system emulator and don't make sense in the context of tools such as qemu-storage-daemon should live in qapi/block.json rather than qapi/block-core.json. Move them there. The associated data types are actually also used in code shared with the tools, so they stay in block-core.json. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20200224143008.13362-6-kwolf@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
* block: Move common QMP commands to block-core QAPI moduleKevin Wolf2020-03-061-284/+0
| | | | | | | | | | | block-core is for everything that isn't related to the system emulator. Internal snapshots, the NBD server and quorum events make sense in the tools, too, so move them to block-core. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20200224143008.13362-5-kwolf@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
* qapi: Use explicit bulleted listsPeter Maydell2020-02-151-19/+14
| | | | | | | | | | | | | | | | | | | | | | | | A JSON block comment like this: Returns: nothing on success If @node is not a valid block device, DeviceNotFound If @name is not found, GenericError with an explanation renders like this: Returns: nothing on success If node is not a valid block device, DeviceNotFound If name is not found, GenericError with an explanation because whitespace is not significant. Use an actual bulleted list, so that the formatting is correct. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200213175647.17628-14-peter.maydell@linaro.org> Message-Id: <20200213175647.17628-15-peter.maydell@linaro.org> Message-Id: <20200213175647.17628-16-peter.maydell@linaro.org> [Three commits squashed into one] Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Fix indent level on doc comments in json filesPeter Maydell2020-02-151-7/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* nbd: Allow description when creating NBD blockdevEric Blake2020-02-051-3/+6
| | | | | | | | | | Allow blockdevs to match the feature already present in qemu-nbd -D. Enhance iotest 223 to cover it. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Maxim Levitsky <mlevitsk@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20191114024635.11363-5-eblake@redhat.com>
* nbd: fix outdated qapi docs syntax for tls-credsDaniel P. Berrangé2019-03-061-1/+1
| | | | | | | Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20190227162035.18543-4-berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com>
* nbd: allow authorization with nbd-server-start QMP commandDaniel P. Berrange2019-03-061-1/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | As with the previous patch to qemu-nbd, the nbd-server-start QMP command also needs to be able to specify authorization when enabling TLS encryption. First the client must create a QAuthZ object instance using the 'object-add' command: { 'execute': 'object-add', 'arguments': { 'qom-type': 'authz-list', 'id': 'authz0', 'parameters': { 'policy': 'deny', 'rules': [ { 'match': '*CN=fred', 'policy': 'allow' } ] } } } They can then reference this in the new 'tls-authz' parameter when executing the 'nbd-server-start' command: { 'execute': 'nbd-server-start', 'arguments': { 'addr': { 'type': 'inet', 'host': '127.0.0.1', 'port': '9000' }, 'tls-creds': 'tls0', 'tls-authz': 'authz0' } } Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20190227162035.18543-3-berrange@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com>
* nbd: Remove x-nbd-server-add-bitmapEric Blake2019-01-141-23/+0
| | | | | | | | | | | | Now that nbd-server-add can do the same functionality (well, other than making the exported bitmap name different than the underlying bitamp - but we argued that was not essential, since it is just as easy to create a new non-persistent bitmap with the desired name), we no longer need the experimental separate command. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20190111194720.15671-7-eblake@redhat.com>
* nbd: Allow bitmap export during QMP nbd-server-addEric Blake2019-01-141-1/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | With the experimental x-nbd-server-add-bitmap command, there was a window of time where an NBD client could see the export but not the associated dirty bitmap, which can cause a client that planned on using the dirty bitmap to be forced to treat the entire image as dirty as a safety fallback. Furthermore, if the QMP client successfully exports a disk but then fails to add the bitmap, it has to take on the burden of removing the export. Since we don't allow changing the exposed dirty bitmap (whether to a different bitmap, or removing advertisement of the bitmap), it is nicer to make the bitmap tied to the export at the time the export is created, with automatic failure to export if the bitmap is not available. The experimental command included an optional 'bitmap-export-name' field for remapping the name exposed over NBD to be different from the bitmap name stored on disk. However, my libvirt demo code for implementing differential backups on top of persistent bitmaps did not need to take advantage of that feature (it is instead possible to create a new temporary bitmap with the desired name, use block-dirty-bitmap-merge to merge one or more persistent bitmaps into the temporary, then associate the temporary with the NBD export, if control is needed over the exported bitmap name). Hence, I'm not copying that part of the experiment over to the stable addition. For more details on the libvirt demo, see https://www.redhat.com/archives/libvir-list/2018-October/msg01254.html, https://kvmforum2018.sched.com/event/FzuB/facilitating-incremental-backup-eric-blake-red-hat This patch focuses on the user interface, and reduces (but does not completely eliminate) the window where an NBD client can see the export but not the dirty bitmap, with less work to clean up after errors. Later patches will add further cleanups now that this interface is declared stable via a single QMP command, including removing the race window. Update test 223 to use the new interface. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20190111194720.15671-6-eblake@redhat.com>
* pr-manager-helper: report event on connection/disconnectionPaolo Bonzini2018-06-281-0/+24
| | | | | | | | Let management know if there were any problems communicating with qemu-pr-helper. The event is edge-triggered, and is sent every time the connection status of the pr-manager-helper object changes. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* pr-manager: add query-pr-managers QMP commandPaolo Bonzini2018-06-281-0/+28
| | | | | | | This command lets you query the connection status of each pr-manager-helper object. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* qapi: new qmp command nbd-server-add-bitmapVladimir Sementsov-Ogievskiy2018-06-211-0/+23
| | | | | | | | | | | | | | For now, the actual command ix x-nbd-server-add-bitmap, reflecting the fact that we are still working on libvirt code that proves the command works as needed, and also the fact that we may remove bitmap-export-name (and just require that the exported name be the bitmap name). Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20180609151758.17343-6-vsementsov@virtuozzo.com> Reviewed-by: Eric Blake <eblake@redhat.com> [eblake: make the command experimental by adding x- prefix] Signed-off-by: Eric Blake <eblake@redhat.com>
* qapi: add nbd-server-removeVladimir Sementsov-Ogievskiy2018-01-261-0/+41
| | | | | | | | | | | | | Add command for removing an export. It is needed for cases when we don't want to keep the export after the operation on it was completed. The other example is a temporary node, created with blockdev-add. If we want to delete it we should firstly remove any corresponding NBD export. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20180119135719.24745-3-vsementsov@virtuozzo.com> [eblake: drop dead nb_clients code] Signed-off-by: Eric Blake <eblake@redhat.com>
* qapi: add name parameter to nbd-server-addVladimir Sementsov-Ogievskiy2018-01-261-2/+7
| | | | | | | | | | | | Allow user to specify name for new export, to not reuse internal node name and to not show it to clients. This also allows creating several exports per device. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180119135719.24745-2-vsementsov@virtuozzo.com> Signed-off-by: Eric Blake <eblake@redhat.com>
* qapi-schema: Improve section headingsMarkus Armbruster2017-09-041-3/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The generated QEMU QMP reference is now structured as follows: 1.1 Introduction 1.2 Stability Considerations 1.3 Common data types 1.4 Socket data types 1.5 VM run state 1.6 Cryptography 1.7 Block devices 1.7.1 Block core (VM unrelated) 1.7.2 QAPI block definitions (vm unrelated) 1.8 Character devices 1.9 Net devices 1.10 Rocker switch device 1.11 TPM (trusted platform module) devices 1.12 Remote desktop 1.12.1 Spice 1.12.2 VNC 1.13 Input 1.14 Migration 1.15 Transactions 1.16 Tracing 1.17 QMP introspection 1.18 Miscellanea Section "1.18 Miscellanea" is still too big: it documents 134 symbols. Section "1.7.1 Block core (VM unrelated)" is also rather big: 128 symbols. All the others are of reasonable size. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503602048-12268-17-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
* qapi-schema: Move block events from event.json to block.jsonMarkus Armbruster2017-09-041-0/+68
| | | | | | | | Cc: Alberto Garcia <berto@igalia.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503602048-12268-13-git-send-email-armbru@redhat.com> Reviewed-by: Alberto Garcia <berto@igalia.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
* qapi: Fix some QMP documentation regressionsEric Blake2017-06-041-1/+1
| | | | | | | | | | | | | | | | | | In the process of getting rid of docs/qmp-commands.txt, we managed to regress on some of the text that changed after the point where the move was first branched and when the move actually occurred. For example, commit 3282eca for blockdev-snapshot re-added the extra "options" layer which had been cleaned up in commit 0153d2f. This clears up all regressions identified over the range 02b351d..bd6092e: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg05127.html as well as a cleanup to x-blockdev-remove-medium to prefer 'id' over 'device' (matching the cleanup for 'eject'). Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
* sockets: Rename SocketAddress to SocketAddressLegacyMarkus Armbruster2017-05-091-1/+1
| | | | | | | | | | | | | | | The next commit will rename SocketAddressFlat to SocketAddress, and the commit after that will replace most uses of SocketAddressLegacy by SocketAddress, replacing most of this commit's renames right back. Note that checkpatch emits a few "line over 80 characters" warnings. The long lines are all temporary; the SocketAddressLegacy replacement will shorten them again. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1493192202-3184-5-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: The #optional tag is redundant, dropMarkus Armbruster2017-03-161-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | | We traditionally mark optional members #optional in the doc comment. Before commit 3313b61, this was entirely manual. Commit 3313b61 added some automation because its qapi2texi.py relied on #optional to determine whether a member is optional. This is no longer the case since the previous commit: the only thing qapi2texi.py still does with #optional is stripping it out. We still reject bogus qapi-schema.json and six places for qga/qapi-schema.json. Thus, you can't actually rely on #optional to see whether something is optional. Yet we still make people add it manually. That's just busy-work. Drop the code to check, fix up and strip out #optional, along with all instances of #optional. To keep it out, add code to reject it, to be dropped again once the dust settles. No change to generated documentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>