aboutsummaryrefslogtreecommitdiff
path: root/tests/qapi-schema
AgeCommit message (Collapse)AuthorFilesLines
2025-03-11qapi: clean up encoding of section kindsJohn Snow2-6/+6
We have several kinds of sections, and to tell them apart, we use Section attribute @tag and also the section object's Python type: type @tag untagged Section None @foo: ArgSection 'foo' Returns: Section 'Returns' Errors: Section 'Errors' Since: Section 'Since' TODO: Section 'TODO' Note: * @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>
2025-03-06qapi: Eliminate OrderedDictMarkus Armbruster1-10/+1
We use OrderedDict to ensure dictionary order is insertion order. Plain dict does that since Python 3.6, but it wasn't guaranteed until 3.7. Since we have 3.7 now, replace OrderedDict by dict. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250227080757.3978333-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2025-03-04docs/qapidoc: support header-less freeform sectionsJohn Snow2-0/+7
The code as written crashes when a free-form documentation block doesn't start with a heading or subheading, for example: | ## | # Just text, no heading. | ## The code will attempt to use the `node` variable uninitialized. To fix, create a generic block to insert the doc text into. (This patch also removes a lingering pylint warning in the QAPIDoc implementation that prevents getting a clean baseline to use for forthcoming additions.) Fixes: 43e0d14ee09a (docs/sphinx: fix extra stuff in TOC after freeform QMP sections) Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250224033741.222749-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Test updated to cover this] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2025-02-10qapi: expose all schema features to codeDaniel P. Berrangé4-0/+16
This replaces use of the constants from the QapiSpecialFeatures enum, with constants from the auto-generate QapiFeatures enum in qapi-features.h The 'deprecated' and 'unstable' features still have a little bit of special handling, being force defined to be the 1st + 2nd features in the enum, regardless of whether they're used in the schema. This retains compatibility with common code that references the features via the QapiSpecialFeatures constants. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20250205123550.2754387-5-berrange@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Imports tidied up with isort] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-09-10tests/qapi-schema: Drop temporary 'prefix'Markus Armbruster2-2/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This changes TestUnionEnumA's generated enumeration constant prefix from TEST_UNION_ENUMA to TEST_UNION_ENUM_A. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-ID: <20240904111836.3273842-3-armbru@redhat.com>
2024-09-10qapi: Smarter camel_to_upper() to reduce need for 'prefix'Markus Armbruster9-8/+2
camel_to_upper() converts its argument from camel case to upper case with '_' between words. Used for generated enumeration constant prefixes. When some of the words are spelled all caps, where exactly to insert '_' is guesswork. camel_to_upper()'s guesses are bad enough in places to make people override them with a 'prefix' in the schema. Rewrite it to guess better: 1. Insert '_' after a non-upper case character followed by an upper case character: OneTwo -> ONE_TWO One2Three -> ONE2_THREE 2. Insert '_' before the last upper case character followed by a non-upper case character: ACRONYMWord -> ACRONYM_Word Except at the beginning (as in OneTwo above), or when there is already one: AbCd -> AB_CD This changes the default enumeration constant prefix for a number of enums. Generated enumeration constants change only where the default is not overridden with 'prefix'. The following enumerations without a 'prefix' change: enum old camel_to_upper() new camel_to_upper() ------------------------------------------------------------------ DisplayGLMode DISPLAYGL_MODE DISPLAY_GL_MODE EbpfProgramID EBPF_PROGRAMID EBPF_PROGRAM_ID HmatLBDataType HMATLB_DATA_TYPE HMAT_LB_DATA_TYPE HmatLBMemoryHierarchy HMATLB_MEMORY_HIERARCHY HMAT_LB_MEMORY_HIERARCHY MultiFDCompression MULTIFD_COMPRESSION MULTI_FD_COMPRESSION OffAutoPCIBAR OFF_AUTOPCIBAR OFF_AUTO_PCIBAR QCryptoBlockFormat Q_CRYPTO_BLOCK_FORMAT QCRYPTO_BLOCK_FORMAT QCryptoBlockLUKSKeyslotState Q_CRYPTO_BLOCKLUKS_KEYSLOT_STATE QCRYPTO_BLOCK_LUKS_KEYSLOT_STATE QKeyCode Q_KEY_CODE QKEY_CODE XDbgBlockGraphNodeType X_DBG_BLOCK_GRAPH_NODE_TYPE XDBG_BLOCK_GRAPH_NODE_TYPE TestUnionEnumA TEST_UNION_ENUMA TEST_UNION_ENUM_A Add a 'prefix' so generated code doesn't change now. Subsequent commits will remove most of them again. Two will remain: MULTIFD_COMPRESSION, because migration code generally spells "multifd" that way, and Q_KEY_CODE, because that one is baked into subprojects/keycodemapdb/tools/keymap-gen. The following enumerations with a 'prefix' change so that the prefix is now superfluous: enum old camel_to_upper() new camel_to_upper() [equal to prefix] ------------------------------------------------------------------ BlkdebugIOType BLKDEBUGIO_TYPE BLKDEBUG_IO_TYPE QCryptoTLSCredsEndpoint Q_CRYPTOTLS_CREDS_ENDPOINT QCRYPTO_TLS_CREDS_ENDPOINT QCryptoSecretFormat Q_CRYPTO_SECRET_FORMAT QCRYPTO_SECRET_FORMAT QCryptoCipherMode Q_CRYPTO_CIPHER_MODE QCRYPTO_CIPHER_MODE QCryptodevBackendType Q_CRYPTODEV_BACKEND_TYPE QCRYPTODEV_BACKEND_TYPE QType [builtin] Q_TYPE QTYPE Drop these prefixes. The following enumerations with a 'prefix' change without making the 'prefix' superfluous: enum old camel_to_upper() new camel_to_upper() [equal to prefix] prefix ------------------------------------------------------------------ CpuS390Entitlement CPUS390_ENTITLEMENT CPU_S390_ENTITLEMENT S390_CPU_ENTITLEMENT CpuS390Polarization CPUS390_POLARIZATION CPU_S390_POLARIZATION S390_CPU_POLARIZATION CpuS390State CPUS390_STATE CPU_S390_STATE S390_CPU_STATE QAuthZListFormat Q_AUTHZ_LIST_FORMAT QAUTH_Z_LIST_FORMAT QAUTHZ_LIST_FORMAT QAuthZListPolicy Q_AUTHZ_LIST_POLICY QAUTH_Z_LIST_POLICY QAUTHZ_LIST_POLICY QCryptoAkCipherAlgorithm Q_CRYPTO_AK_CIPHER_ALGORITHM QCRYPTO_AK_CIPHER_ALGORITHM QCRYPTO_AKCIPHER_ALG QCryptoAkCipherKeyType Q_CRYPTO_AK_CIPHER_KEY_TYPE QCRYPTO_AK_CIPHER_KEY_TYPE QCRYPTO_AKCIPHER_KEY_TYPE QCryptoCipherAlgorithm Q_CRYPTO_CIPHER_ALGORITHM QCRYPTO_CIPHER_ALGORITHM QCRYPTO_CIPHER_ALG QCryptoHashAlgorithm Q_CRYPTO_HASH_ALGORITHM QCRYPTO_HASH_ALGORITHM QCRYPTO_HASH_ALG QCryptoIVGenAlgorithm Q_CRYPTOIV_GEN_ALGORITHM QCRYPTO_IV_GEN_ALGORITHM QCRYPTO_IVGEN_ALG QCryptoRSAPaddingAlgorithm Q_CRYPTORSA_PADDING_ALGORITHM QCRYPTO_RSA_PADDING_ALGORITHM QCRYPTO_RSA_PADDING_ALG QCryptodevBackendAlgType Q_CRYPTODEV_BACKEND_ALG_TYPE QCRYPTODEV_BACKEND_ALG_TYPE QCRYPTODEV_BACKEND_ALG QCryptodevBackendServiceType Q_CRYPTODEV_BACKEND_SERVICE_TYPE QCRYPTODEV_BACKEND_SERVICE_TYPE QCRYPTODEV_BACKEND_SERVICE Subsequent commits will tweak things to remove most of these prefixes. Only QAUTHZ_LIST_FORMAT and QAUTHZ_LIST_POLICY will remain. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-2-armbru@redhat.com>
2024-07-17qapi: remove "Example" doc sectionJohn Snow3-28/+40
Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match. Migrating to the new syntax --------------------------- The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block. ('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.) Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired. Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive. Why? ---- This patch has several benefits: 1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired. 2. Example sections can now use fully arbitrary rST. 3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets. (To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.) 4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator. (i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.) NOTE: As with the "Notes" conversion (d461c279737), this patch (and the three preceding) may change the rendering order for Examples in the current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi/parser: don't parse rST markup as section headersJohn Snow3-0/+9
The double-colon synax is rST formatting that precedes a literal code block. We do not want to capture these as QAPI-specific sections. Coerce blocks that start with e.g. "Example::" to be parsed as untagged paragraphs instead of special tagged sections. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240626222128.406106-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Indentation tweaked for consistency] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: convert "Note" sections to plain rSTJohn Snow6-15/+13
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/parser: fix comment parsing immediately following a doc blockJohn Snow1-0/+2
If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that. e.g. > ## > # = Hello World! > ## > > # I'm a comment! will break the parser, because it does not properly ignore the comment token if it immediately follows a doc block. Fixes: 3d035cd2cca6 (qapi: Rewrite doc comment parser) Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-7-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi/parser: preserve indentation in QAPIDoc sectionsJohn Snow1-16/+16
Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py that removes indentation the same way get_doc_indented() did. This is being done for the benefit of a new qapidoc generator which requires that indentation in argument and features sections are preserved. Prior to this patch, a section like this: ``` @name: lorem ipsum dolor sit amet consectetur adipiscing elit ``` would have its body text be parsed into: ``` lorem ipsum dolor sit amet consectetur adipiscing elit ``` We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment into: ``` lorem ipsum dolor sit amet consectetur adipiscing elit ``` This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as: ``` :arg type name: lorem ipsum dolor sit amet consectetur apidiscing elit ``` ...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. This understandably breaks the existing qapidoc.py; so a new function is added there to dedent the text for compatibility. Once the new generator is merged, this function will not be needed any longer and can be dropped. I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-6-jsnow@redhat.com> [Lost commit message paragraph restored] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-05-06qapi: Rename visitor parameter @variants to @alternativesMarkus Armbruster1-2/+3
A previous commit narrowed the type of .visit_alternate_type() parameter @variants from QAPISchemaVariants to QAPISchemaAlternatives. Rename it to @alternatives. One of them passes @alternatives to helper function gen_visit_alternate(). Rename its @variants parameter to @alternatives as well. Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-05-06qapi: Rename visitor parameter @variants to @branchesMarkus Armbruster1-2/+2
The previous commit narrowed the type of .visit_object_type() parameter @variants from QAPISchemaVariants to QAPISchemaBranches. Rename it to @branches. Same for .visit_object_type_flat(). A few of these pass @branches to helper functions: QAPISchemaGenRSTVisitor.visit_object_type() to ._nodes_for_members() and ._nodes_for_variant_when(), and QAPISchemaGenVisitVisitor.visit_object_type() to gen_visit_object_members(). Rename the helpers' @variants parameters to @branches as well. Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-03-04qapi: Reject "Returns" section when command doesn't return anythingMarkus Armbruster4-0/+9
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-14-armbru@redhat.com>
2024-03-04qapi: New documentation section tag "Errors"Markus Armbruster3-0/+10
We use section "Returns" for documenting both success and error response of commands. I intend to generate better command success response documentation. Easier when "Returns" documents just he success response. Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-4-armbru@redhat.com>
2024-03-04qapi: Slightly clearer error message for invalid "Returns" sectionMarkus Armbruster1-1/+1
Change "'Returns:' is only valid for commands" to "'Returns' section is only valid for commands". Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-3-armbru@redhat.com>
2024-02-26qapi: Divorce QAPIDoc from QAPIParseErrorMarkus Armbruster4-4/+4
QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to be the current comment line. Servicable, but action at a distance. The commit before previous moved most uses of QAPIParseError from QAPIDoc to QAPIParser. There are just three left. Convert them to QAPISemError. This involves passing info to a few methods. Then drop the reference to QAPIParser. The three errors lose the column number. Not really interesting here: it's the comment line's indentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-17-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Reject multiple and empty feature descriptionsMarkus Armbruster4-39/+2
The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-features. Recognize "Features:" lines anywhere. A second one is an error. A 'Features:' line without any features is useless, but not an error. Make it an error. This makes detecting a second "Features:" line easier. qapi/run-state.json actually has an instance of this since commit fe17522d854 (qapi: Remove deprecated 'singlestep' member of StatusInfo). Clean it up. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Merge adjacent untagged sectionsMarkus Armbruster1-2/+0
The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral change in the next commit. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-14-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Recognize section tags and 'Features:' only after blank lineMarkus Armbruster7-3/+15
Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Require descriptions and tagged sections to be indentedMarkus Armbruster1-6/+6
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-26qapi: Reject section heading in the middle of a doc commentMarkus Armbruster4-1/+10
docs/devel/qapi-code-gen.txt claims "A heading line must be the first line of the documentation comment block" since commit 55ec69f8b16 (docs/devel/qapi-code-gen.txt: Update to new rST backend conventions). Not true, we have code to make it work anywhere in a free-form doc comment: commit dcdc07a97cb (qapi: Make section headings start a new doc comment block). Make it true, for simplicity's sake. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-10-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Rename QAPIDoc.Section.name to .tagMarkus Armbruster1-1/+1
Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-9-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Improve error message for empty doc sectionsMarkus Armbruster1-1/+1
Improve the message for an empty tagged section from empty doc section 'Note' to text required after 'Note:' and the message for an empty argument or feature description from empty doc section 'foo' to text required after '@foo:' Improve the error position to refer to the beginning of the empty section instead of its end. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Improve error position for bogus invalid "Returns" sectionMarkus Armbruster1-1/+1
When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Point to the "Returns" section instead. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26qapi: Improve error position for bogus argument descriptionsMarkus Armbruster7-7/+7
When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus argument description instead. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-6-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26tests/qapi-schema: Cover 'Features:' not followed by descriptionsMarkus Armbruster4-0/+30
A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that makes rejecting duplicate 'Features:' easier. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-4-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26tests/qapi-schema: Cover duplicate 'Features:' lineMarkus Armbruster4-0/+34
We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section. If it was followed by feature description, we'd reject that like "description of '@feat2:' follows a section". Less than clear. To be improved shortly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-26tests/qapi-schema: Fix test 'QAPI rST doc'Markus Armbruster2-16/+15
The test compares Sphinx plain-text output against a golden reference. To work on Windows hosts, it filters out carriage returns in both files. Unfortunately, the filter doesn't work: it creates an empty file. Comparing empty files always succeeds. Fix the filter, and update the golden reference to current Sphinx output. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-2-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12qapi: Require member documentation (with loophole)Markus Armbruster2-1/+5
The QAPI generator forces you to document your stuff. Except for command arguments, event data, and members of enum and object types: these the generator silently "documents" as "Not documented". We can't require proper documentation there without first fixing all the offenders. We've always had too many offenders to pull that off. Right now, we have more than 500. Worse, we seem to fix old ones no faster than we add new ones: in the past year, we fixed 22 ones, but added 26 new ones. To help arrest the backsliding, make missing documentation an error unless the command, type, or event is in listed in new pragma documentation-exceptions. List all the current offenders: 117 commands and types in qapi/, and 9 in qga/. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12qapi: Indent tagged doc comment sections properlyMarkus Armbruster2-6/+6
docs/devel/qapi-code-gen demands that the "second and subsequent lines of sections other than "Example"/"Examples" should be indented". Commit a937b6aa739q (qapi: Reformat doc comments to conform to current conventions) missed a few instances, and messed up a few others. Clean that up. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-5-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2023-11-13tests/qapi-schema: Tidy up pylint warnings and adviceMarkus Armbruster1-5/+4
Pylint warns: tests/qapi-schema/test-qapi.py:139:13: W1514: Using open without explicitly specifying an encoding (unspecified-encoding) tests/qapi-schema/test-qapi.py:143:13: W1514: Using open without explicitly specifying an encoding (unspecified-encoding) Add encoding='utf-8'. Pylint advises: tests/qapi-schema/test-qapi.py:143:13: R1732: Consider using 'with' for resource-allocating operations (consider-using-with) Silence this by returning the value directly. Pylint advises: tests/qapi-schema/test-qapi.py:221:4: R1722: Consider using sys.exit() (consider-using-sys-exit) tests/qapi-schema/test-qapi.py:226:4: R1722: Consider using sys.exit() (consider-using-sys-exit) Sure, why not. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20231025092925.1785934-1-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2023-09-08tests/: spelling fixesMichael Tokarev1-1/+1
with some rewording in tests/qemu-iotests/298 tests/qtest/fuzz/generic_fuzz.c tests/unit/test-throttle.c as suggested by Eric. Signed-off-by: Michael Tokarev <mjt@tls.msk.ru> Reviewed-by: Eric Blake <eblake@redhat.com>
2023-05-22qapi: Improve error message for description following sectionMarkus Armbruster1-1/+1
The error message is bad when the section is untagged. For instance, test case doc-interleaved-section produces "'@foobar:' can't follow 'Note' section", which is okay, but if we drop the "Note:" tag, we get "'@foobar:' can't follow 'None' section, which is bad. Change the error message to "description of '@foobar:' follows a section". Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230510141637.3685080-1-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> [Conflict with commit 3e32dca3f0d resolved]
2023-05-10qapi: Relax doc string @name: description indentation rulesMarkus Armbruster4-4/+7
The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:". By convention, we format them like this: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, # sed do eiusmod tempor incididunt ut labore et dolore # magna aliqua. Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this: # @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could # not avoid copying dirty pages. This is between # 0 and @dirty-sync-count * @multifd-channels. # (since 7.1) The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write. The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one: # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is # only present when the postcopy-blocktime migration capability # is enabled. (Since 3.0) We could instead format it like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) or, since the commit before previous, like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) However, I'd rather have # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. # This is only present when the postcopy-blocktime migration # capability is enabled. (Since 3.0) because this is how rST field and option lists work. To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation. This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-14-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> [Work around lack of walrus operator in Python 3.7 and older]
2023-05-09qapi: Fix argument description indentation strippingMarkus Armbruster1-1/+1
When an argument's description starts on the line after the "#arg: " line, indentation is stripped only from the description's first line, as demonstrated by the previous commit. Moreover, subsequent lines with less indentation are not rejected. Make the first line's indentation the expected indentation for the remainder of the description. This fixes indentation stripping, and also requires at least that much indentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-12-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
2023-05-09tests/qapi-schema/doc-good: Improve argument description testsMarkus Armbruster2-13/+18
Improve the comments to better describe what they test. Cover argument description starting on a new line indented. This style isn't documented in docs/devel/qapi-code-gen.rst. qapi-gen.py accepts it, but messes up indentation: it's stripped from the first line, not subsequent ones. The next commit will fix this. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-11-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
2023-05-09tests/qapi-schema/doc-good: Improve a commentMarkus Armbruster2-1/+5
The QAPI generator doesn't reject undocumented members and features (yet). doc-good.json covers this, with clear "is undocumented" notes to signal intent. Except for @Variant1 member @var1, where it's "(but no @var: line)". Less clear. Replace by "@var1 is undocumented". Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-10-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
2023-04-26qapi: allow unions to contain further unionsDaniel P. Berrangé9-0/+126
This extends the QAPI schema validation to permit unions inside unions, provided the checks for clashing fields pass. Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20230420102619.348173-4-berrange@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2023-04-25qapi: support updating expected test output via makeDaniel P. Berrangé1-0/+1
It is possible to pass --update to tests/qapi-schema/test-qapi.py to make it update the output files on error. This is inconvenient to achieve though when test-qapi.py is run indirectly by make/meson. Instead simply allow for an env variable to be set: $ QAPI_TEST_UPDATE= make check-qapi-schema Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20230420102619.348173-2-berrange@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2023-04-24qapi: Require boxed for conditional command and event argumentsMarkus Armbruster12-19/+30
The C code generator fails to honor 'if' conditions of command and event arguments. For instance, tests/qapi-schema/qapi-schema-test.json has { 'event': 'TEST_IF_EVENT', 'data': { 'foo': 'TestIfStruct', 'bar': { 'type': ['str'], 'if': 'TEST_IF_EVT_ARG' } }, 'if': { 'all': ['TEST_IF_EVT', 'TEST_IF_STRUCT'] } } Generated tests/test-qapi-events.h fails to honor the TEST_IF_EVT_ARG condition: #if defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) void qapi_event_send_test_if_event(TestIfStruct *foo, strList *bar); #endif /* defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) */ Only uses so far are in tests/. We could fix the generator to emit something like #if defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) void qapi_event_send_test_if_event(TestIfStruct *foo #if defined(TEST_IF_EVT_ARG) , strList *bar #endif ); #endif /* defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) */ Ugly. Calls become similarly ugly. Not worth fixing. Conditional arguments work fine with 'boxed': true, simply because complex types with conditional members work fine. Not worth breaking. Reject conditional arguments unless boxed. Move the tests cases covering unboxed conditional arguments out of tests/qapi-schema/qapi-schema-test.json. Cover boxed conditional arguments there instead. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-15-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2023-04-24tests/qapi-schema: Cover optional conditional struct memberMarkus Armbruster2-1/+4
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-13-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2023-04-24tests/qapi-schema: Clean up positive test for conditionalsMarkus Armbruster2-8/+6
Union TestIfUnion is conditional on macros TEST_IF_UNION and TEST_IF_STRUCT. It uses TestIfEnum, which is conditional on macro TEST_IF_ENUM. If TEST_IF_UNION and TEST_IF_STRUCT are defined, but TEST_IF_ENUM isn't, the generated code won't compile. Command test-if-cmd is conditional an macros TEST_IF_CMD and TEST_IF_STRUCT, and uses TestIfEnum. Similar issue. Event TEST_IF_EVENT is conditional an macros TEST_IF_EVT and TEST_IF_STRUCT, and uses TestIfEnum. Similar issue. Replace the uses of TestIfEnum in the latter two by str. TestIfUnion is now TestIfEnum's only user. Change TestIfEnum's condition to TEST_IF_UNION. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-12-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [Commit message corrected]
2023-04-24tests/qapi-schema: Rename a few conditionalsMarkus Armbruster2-12/+12
Positive test case { 'enum': 'TestIfEnum', 'data': [ 'foo', { 'name' : 'bar', 'if': 'TEST_IF_ENUM_BAR' } ], 'if': 'TEST_IF_ENUM' } generates #if defined(TEST_IF_ENUM) typedef enum TestIfEnum { TEST_IF_ENUM_FOO, #if defined(TEST_IF_ENUM_BAR) TEST_IF_ENUM_BAR, #endif /* defined(TEST_IF_ENUM_BAR) */ TEST_IF_ENUM__MAX, } TestIfEnum; Macro TEST_IF_ENUM_BAR clashes with the enumeration constant. Wouldn't compile with -DTEST_IF_BAR. Rename the macro to TEST_IF_ENUM_MEMBER. For consistency, rename similar macros elsewhere as well. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-11-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2023-04-24tests/qapi-schema: Improve union discriminator coverageMarkus Armbruster2-3/+3
A union's 'discriminator' must name one of the common members. QAPISchemaVariants.check() looks it up by its c_name(), then checks the name matches exactly (because c_name() is not injective). Tests union-base-empty and union-invalid-discriminator both cover the case where lookup fails. Repurpose the latter to cover the case where it succeeds and the name check fails. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-10-armbru@redhat.com Reviewed-by: Eric Blake <eblake@redhat.com> [Commit message typo fixed]
2023-04-24qapi: Fix to reject 'data': 'mumble' in structMarkus Armbruster4-0/+5
A struct's 'data' must be a JSON object defining the struct's members. The QAPI code generator incorrectly accepts a JSON string instead, and then crashes in QAPISchema._make_members() called from ._def_struct_type(). Fix to reject it: factor check_type_implicit() out of check_type_name_or_implicit(), and switch check_struct() to use it instead. Also add a test case. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-9-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [More detailed commit message]
2023-04-24qapi: Fix error message when type name or array is expectedMarkus Armbruster4-4/+4
We incorrectly report "FOO should be a type name" when it could also be an array. Fix that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-8-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2023-04-24qapi: Improve error message for unexpected array typesMarkus Armbruster2-2/+2
We reject array types in certain places with "cannot be an array". Deleting this check improves the error message to "should be a type name" or "should be an object or type name", depending on context, so do that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-6-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2023-02-02meson: replace Perl usage with PythonMarc-André Lureau1-3/+4
Let's try to remove Perl usage during build time. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20230110132700.833690-5-marcandre.lureau@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20230124180127.1881110-8-alex.bennee@linaro.org>
2023-01-06tests/qapi-schema: remove Meson workaroundPaolo Bonzini1-5/+1
The referenced issue has been fixed since version 0.61, so remove the workaround. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
generated by cgit v1.1 at 2025-04-05 09:06:01 +0000