Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: qemu/qemu
base: b2896c1b0987
Choose a base ref
...
head repository: qemu/qemu
compare: 568992e3440f
Choose a head ref
  • 18 commits
  • 48 files changed
  • 2 contributors

Commits on May 9, 2023

  1. docs/devel/qapi-code-gen: Clean up use of quotes a bit 

    Section "Definition documentation" uses both single and double quotes
around doc text snippets.  Stick to double quotes.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-2-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    0c7811a View commit details
    Browse the repository at this point in the history

  2. docs/devel/qapi-code-gen: Turn FIXME admonitions into comments 

    We have two FIXME notes.  These FIXMEs are for QAPI developers.  They
are not useful for QAPI schema developers.  They are marked up as
admonitions, which makes them look important in generated HTML.

Turn them into comments.  QAPI developers will still see them (they
read and write the .rst).  QAPI schema developers may still see
them (if they read the .rst instead of the generated .html), but "this
is just for QAPI developers" should be more obvious.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-3-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    a2836b3 View commit details
    Browse the repository at this point in the history

  3. qapi: Fix crash on stray double quote character 

    When the lexer chokes on a stray character, its shows the characters
until the next structural character in the error message.  It uses a
regular expression to match a non-empty string of non-structural
characters.  Bug: the regular expression treats '"' as structural.
When the lexer chokes on '"', the match fails, and trips
must_match()'s assertion.  Fix the regular expression.

Fixes: 14c3279 (qapi: Improve reporting of lexical errors)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-4-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    5b5fe0e View commit details
    Browse the repository at this point in the history

  4. meson: Fix to make QAPI generator output depend on main.py 

    @qapi_gen_depends is missing scripts/qapi/main.py.  Fix that, and drop
a duplicate scripts/qapi/common.py.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-5-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    88d357d View commit details
    Browse the repository at this point in the history

  5. Revert "qapi: BlockExportRemoveMode: move comments to TODO" 

    This reverts commit 97cd74f.

The next commit will hide TODO: sections.  See there for rationale.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-6-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    b71fd73 View commit details
    Browse the repository at this point in the history

  6. sphinx/qapidoc: Do not emit TODO sections into user manuals 

    QAPI doc comments are for QMP users: they go into the "QEMU QMP
Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".

The doc comment TODO sections are for somebody else, namely for the
people who can do: developers.  Do not emit them into the user
manuals.

This elides the following TODOs:

* SchemaInfoCommand

  # TODO: @Success-Response (currently irrelevant, because it's QGA, not QMP)

  This is a note to developers adding introspection to the guest
  agent.  It makes no sense to users.

* @query-hotpluggable-cpus

  # TODO: Better documentation; currently there is none.

  This is a reminder for developers.  It doesn't help users.

* @device_add

  # TODO: This command effectively bypasses QAPI completely due to its
  #       "additional arguments" business.  It shouldn't have been added to
  #       the schema in this form.  It should be qapified properly, or
  #       replaced by a properly qapified command.

  Likewise.

Eliding them is an improvement.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-7-armbru@redhat.com>
Reviewed-by: Ani Sinha <anisinha@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    f57e1d0 View commit details
    Browse the repository at this point in the history

  7. qapi: Tidy up a slightly awkward TODO comment 

    MigrateSetParameters has a TODO comment sitting right behind its doc
comment.  I wrote it this way to keep it out of the manual, but that
reason is not obvious.

The previous commit (sphinx/qapidoc: Do not emit TODO sections into
user manuals) lets me move it into the doc comment as a TODO section.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-8-armbru@redhat.com>
Reviewed-by: Ani Sinha <anisinha@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    56266c6 View commit details
    Browse the repository at this point in the history

  8. qapi/dump: Indent bulleted lists consistently 

    Documentation of dump-guest-memory contains two bulleted lists.  The
first one is indented, the second one isn't.  Delete the first one's
indentation for a more consistent look.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-9-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    22bd6e9 View commit details
    Browse the repository at this point in the history

  9. tests/qapi-schema/doc-good: Improve a comment 

    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>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    5962635 View commit details
    Browse the repository at this point in the history

  10. tests/qapi-schema/doc-good: Improve argument description tests 

    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>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    a87a9b4 View commit details
    Browse the repository at this point in the history

  11. qapi: Fix argument description indentation stripping 

    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>
    Markus Armbruster committed May 9, 2023
    Copy the full SHA
    9b2c674 View commit details
    Browse the repository at this point in the history

Commits on May 10, 2023

  1. qapi: Rewrite parsing of doc comment section symbols and tags 

    To recognize a line starting with a section symbol and or tag, we
first split it at the first space, then examine the part left of the
space.  We can just as well examine the unsplit line, so do that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-13-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
[Work around lack of walrus operator in Python 3.7 and older]
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    3e32dca View commit details
    Browse the repository at this point in the history

  2. qapi: Relax doc string @name: description indentation rules 

    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]
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    0834978 View commit details
    Browse the repository at this point in the history

  3. qapi: Section parameter @indent is no longer used, drop 

    Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-15-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    eb59cf7 View commit details
    Browse the repository at this point in the history

  4. docs/devel/qapi-code-gen: Update doc comment conventions 

    The commit before previous relaxed the indentation rules to let us
improve the doc comment conventions.  This commit changes the written
conventions.  The next commits will update QAPI schemas to conform to
them.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-16-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    9d16749 View commit details
    Browse the repository at this point in the history

  5. qga/qapi-schema: Reformat doc comments to conform to current conventions 

    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-17-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    059d341 View commit details
    Browse the repository at this point in the history

  6. qapi: Reformat doc comments to conform to current conventions 

    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]
    Markus Armbruster committed May 10, 2023
    Copy the full SHA
    a937b6a View commit details
    Browse the repository at this point in the history

  7. Merge tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru … 

    …into staging

QAPI patches patches for 2023-05-09

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmRbUEYSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTmzEP/3pDpVxpP7xXLevl2vFqkFyHEjc0L3N4
# x//ljgQojAdM6WU3e0qqOfp/NE2ktUg5D3z+QNiVP1/xXv/dtMGATdG+X9AZs0US
# XnhdicYdBng8bGuhlNuNY8QJ/I4ALwUR44LVOYibVohv2RVYWBapGiHowpyTyABq
# sFSHrj/cgvTMUn53yp7veZTo6rWG6RU/D5uUTOMsvKeAoHoOXMyBxV01SCt84t/J
# pcelINcriP6cQVzgfm1B39UNa0IxinGxEx/IIaxz5Ju66G05HTs4CsBFAF6/0QI/
# 3YerGWPt9fF6+qYNn21Gg9CL1fHHppNqTXkcuTeGn/Ohg53bosktti5Ysn73vtpR
# GWsJr6M4KQ1SwEbZIiFZCS3A4VTbRcr7WkXets39pcpxGDlNisi+zfV95kNo09xR
# hxi8SuWgb2OfQpVs/71eunp+PM1ZQsODurcy4x0/rlYJfhk53kQSMRtlfy5Cn6uY
# +weWUgygBSWG/w0qanWWK5TF1DNlRKzbix6cmMuGGKcpyF7EMWE1kqmjmmu7CQvM
# a3aPTqGtUt0LeqBQIhmeq/jEwd3vxQa1R85gd0/0sWxEMHkPXVfVoaryiaWAykye
# 7r+c8o/41c44zs8YxdZrz72su9fqKC/TeVf5soU46ZucmH8D6f7QHy+s1ec2PEjY
# l6cRIXTXHeQe
# =j6cJ
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 10 May 2023 09:05:26 AM BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [undefined]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [undefined]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2023-05-09-v2' of https://repo.or.cz/qemu/armbru:
  qapi: Reformat doc comments to conform to current conventions
  qga/qapi-schema: Reformat doc comments to conform to current conventions
  docs/devel/qapi-code-gen: Update doc comment conventions
  qapi: Section parameter @indent is no longer used, drop
  qapi: Relax doc string @name: description indentation rules
  qapi: Rewrite parsing of doc comment section symbols and tags
  qapi: Fix argument description indentation stripping
  tests/qapi-schema/doc-good: Improve argument description tests
  tests/qapi-schema/doc-good: Improve a comment
  qapi/dump: Indent bulleted lists consistently
  qapi: Tidy up a slightly awkward TODO comment
  sphinx/qapidoc: Do not emit TODO sections into user manuals
  Revert "qapi: BlockExportRemoveMode: move comments to TODO"
  meson: Fix to make QAPI generator output depend on main.py
  qapi: Fix crash on stray double quote character
  docs/devel/qapi-code-gen: Turn FIXME admonitions into comments
  docs/devel/qapi-code-gen: Clean up use of quotes a bit

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
    @rth7680
    rth7680 committed May 10, 2023
    Copy the full SHA
    568992e View commit details
    Browse the repository at this point in the history