Commit Graph

94 Commits

Author SHA1 Message Date
Markus Armbruster
ab07e96c46 qga/qapi-schema: Fix guest-set-memory-blocks documentation
Documentation claims the command can "return NULL".  "NULL" doesn't
exist in JSON.  "null" does, but the command returns lists, and null
isn't.  Correct documentation to "return an empty list".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-13-armbru@redhat.com>
2024-03-04 07:12:40 +01:00
Markus Armbruster
e22955e7f6 qga/qapi-schema: Tweak documentation of fsfreeze commands
"Returns:" sections of guest-fsfreeze-freeze and
guest-fsfreeze-freeze-list describe both command behavior and success
response.  Move behavior out, so "Returns:" is only about success
response.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-12-armbru@redhat.com>
2024-03-04 07:12:40 +01:00
Markus Armbruster
6a90cc82b5 qga/qapi-schema: Clean up "Returns" sections
Drop "on success" where it is redundant with "Returns:".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-11-armbru@redhat.com>
2024-03-04 07:12:40 +01:00
Markus Armbruster
3630a47903 qga/qapi-schema: Delete useless "Returns" sections
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-10-armbru@redhat.com>
2024-03-04 07:12:40 +01:00
Markus Armbruster
3ef507fe10 qga/qapi-schema: Move error documentation to new "Errors" sections
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-9-armbru@redhat.com>
2024-03-04 07:12:40 +01:00
Markus Armbruster
ca86608f7b qga/qapi-schema: Plug trivial documentation holes
Add missing return member documentation of guest-get-disks,
guest-get-devices, guest-get-diskstats, and guest-get-cpustats.

The NVMe SMART information returned by guest-getdisks remains
undocumented.  Add a TODO there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-10-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12 10:04:31 +01:00
Markus Armbruster
0b34cf84e6 qga/qapi-schema: Clean up documentation of guest-set-vcpus
The command's doc comment describes the argument, but it's not marked
up as such.  Easy enough to fix.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-9-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12 10:04:31 +01:00
Markus Armbruster
ab27bb03d3 qga/qapi-schema: Clean up documentation of guest-set-memory-blocks
The command's doc comment describes the argument, but it's not marked
up as such.  Easy enough to fix.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-8-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2024-02-12 10:04:31 +01:00
Markus Armbruster
0cec50119f qapi: Require member documentation (with loophole)
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-12 10:04:31 +01:00
Markus Armbruster
3424ed6caf qga/qapi-schema: Move command description right after command name
Documentation of commands guest-ssh-get-authorized-keys,
guest-ssh-add-authorized-keys, and guest-ssh-remove-authorized-keys
describes the command's purpose after its arguments.  Everywhere else,
we do it the other way round.  Move it for consistency.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-6-armbru@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2024-02-03 09:20:33 +01:00
Daniel Xu
f897ef0d47 qapi: qga: Clarify when out-data and err-data are populated
If output is being captured for a guest-exec invocation, the out-data
and err-data fields of guest-exec-status are only populated after the
process is reaped. This is somewhat counter intuitive and too late to
change. Thus, it would be good to document the behavior.

Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2023-10-11 14:30:54 +03:00
Michael Tokarev
40b89515d0 spelling: information
3 trivial fixes: 2 .json comments which goes to
executables, and 1 .h file comment.

Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2023-06-09 23:38:16 +03:00
Markus Armbruster
059d341a67 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>
2023-05-10 10:01:01 +02:00
Daniel Xu
810f677ab8 qga: Add merged variant to GuestExecCaptureOutputMode
Currently, any captured output (via `capture-output`) is segregated into
separate GuestExecStatus fields (`out-data` and `err-data`). This means
that downstream consumers have no way to reassemble the captured data
back into the original stream.

This is relevant for chatty and semi-interactive (ie. read only) CLI
tools.  Such tools may deliberately interleave stdout and stderr for
visual effect. If segregated, the output becomes harder to visually
understand.

This commit adds a new enum variant to the GuestExecCaptureOutputMode
qapi to merge the output streams such that consumers can have a pristine
view of the original command output.

Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2023-05-04 09:12:48 +00:00
Daniel Xu
9c5ccc52ab qga: Refactor guest-exec capture-output to take enum
Previously capture-output was an optional boolean flag that either
captured all output or captured none. While this is OK in most cases, it
lacks flexibility for more advanced capture cases, such as wanting to
only capture stdout.

This commits refactors guest-exec qapi to take an enum for capture mode
instead while preserving backwards compatibility.

Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2023-05-04 09:12:48 +00:00
Markus Armbruster
c0af9e1fc7 qga/qapi-schema: Fix member documentation markup
GuestDiskStatsInfo's member documentation is parsed as ordinary text
due to missing colons.  The generated documentation shows these
members as "Not documented".

The fix is obvious: add the missing colons.

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-12-armbru@redhat.com>
2023-04-28 11:48:34 +02:00
Markus Armbruster
573a5fab3e qga/qapi-schema: Fix a misspelled reference
Code returns a list of GuestNetworkInterface, documentation claims
GuestNetworkInfo, which doesn't exist.  Fix the documentation.

Fixes: 3424fc9f16 (qemu-ga: add guest-network-get-interfaces command)
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-3-armbru@redhat.com>
2023-04-28 11:48:34 +02:00
Markus Armbruster
a36c865370 qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status
Delete "error state indicates", because it doesn't make sense.
I suspect it was an accident.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20230425064223.820979-2-armbru@redhat.com>
2023-04-28 11:48:34 +02:00
Stefan Weil
1e458f1127 Fix some typos in documentation and comments
Most of them were found and fixed using codespell.

Signed-off-by: Stefan Weil <sw@weilnetz.de>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20221030105944.311940-1-sw@weilnetz.de>
Signed-off-by: Laurent Vivier <laurent@vivier.eu>
2022-11-05 20:35:45 +01:00
Thomas Huth
0e4ef702e8 qga: Replace 'blacklist' and 'whitelist' in the guest agent sources
Let's use better, more inclusive wording here.

Message-Id: <20220727092135.302915-3-thuth@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2022-09-20 12:37:00 +02:00
zhenwei pi
1db8a0b0ea qga: add command 'guest-get-cpustats'
A vCPU thread always reaches 100% utilization when:
- guest uses idle=poll
- disable HLT vm-exit
- enable MWAIT

Add new guest agent command 'guest-get-cpustats' to get guest CPU
statistics, we can know the guest workload and how busy the CPU is.

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Message-Id: <20220707005602.696557-3-pizhenwei@bytedance.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2022-07-13 12:19:18 +03:00
luzhipeng
3569664ee9 qga: add guest-get-diskstats command for Linux guests
Add a new 'guest-get-diskstats' command for report disk io statistics
for Linux guests. This can be useful for getting io flow or handling
IO fault, no need to enter guests.

Signed-off-by: luzhipeng <luzhipeng@cestc.cn>
Message-Id: <20220520021935.676-1-luzhipeng@cestc.cn>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2022-05-25 12:12:01 +03:00
Markus Armbruster
433a4fdc42 qapi: Fix malformed "Since:" section tags
"Since X.Y" is not recognized as a tagged section, and therefore not
formatted as such in generated documentation.  Fix by adding the
required colon.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20220422132807.1704411-1-armbru@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
2022-05-16 07:22:28 +02:00
zhenwei pi
22668881f3 qga: Introduce disk smart
After assigning a NVMe/SCSI controller to guest by VFIO, we lose
everything on the host side. A guest uses these devices exclusively,
we usually don't care the actions on these devices. But there is a
low probability that hitting physical hardware warning, we need a
chance to get the basic smart log info.

Introduce disk smart, and implement NVMe smart on linux.

Thanks to Keith and Marc-André.

CC: Keith Busch <kbusch@kernel.org>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Message-Id: <20220420022610.418052-3-pizhenwei@bytedance.com>
2022-05-04 13:03:19 +04:00
zhenwei pi
d48f61c8ea qga: Introduce NVMe disk bus type
Assigning a NVMe disk by VFIO or emulating a NVMe controller by QEMU,
a NVMe disk get exposed in guest side. Support NVMe disk bus type and
implement posix version.

Test PCI passthrough case:
~#virsh qemu-agent-command buster '{"execute":"guest-get-disks"}' | jq
  ...
    {
      "name": "/dev/nvme0n1",
      "dependencies": [],
      "partition": false,
      "address": {
        "serial": "SAMSUNG MZQL23T8HCLS-00A07_S64HNE0N500076",
        "bus-type": "nvme",
        "bus": 0,
        "unit": 0,
        "pci-controller": {
          "bus": 0,
          "slot": 22,
          "domain": 0,
          "function": 0
        },
        "dev": "/dev/nvme0n1",
        "target": 0
      }
  ...

Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Message-Id: <20220420022610.418052-2-pizhenwei@bytedance.com>
2022-05-04 12:02:17 +04:00
John Snow
a9e2eb06ed qapi: Add spaces after symbol declaration for consistency
Several QGA definitions omit a blank line after the symbol
declaration. This works OK currently, but it's the only place where we
do this. Adjust it for consistency.

Future commits may wind up enforcing this formatting.

Signed-off-by: John Snow <jsnow@redhat.com>

Message-Id: <20210930205716.1148693-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2021-10-02 07:33:41 +02:00
Marc-André Lureau
8a9f1e1d9c qapi: make 'if' condition strings simple identifiers
Change the 'if' condition strings to be C-agnostic. It will accept
'[A-Z][A-Z0-9_]*' identifiers. This allows to express configuration
conditions in other languages (Rust or Python for ex) or other more
suitable forms.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Tested-by: John Snow <jsnow@redhat.com>
Message-Id: <20210804083105.97531-11-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Rebased with semantic conflict in redefined-event.json]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2021-08-26 13:53:56 +02:00
Markus Armbruster
5aceeac04d qapi: Enforce struct member naming rules
Struct members, including command arguments, event data, and union
inline base members, should use '-', not '_'.  Enforce this.  Fix the
fixable offenders (all in tests/), and add the remainder to pragma
member-name-exceptions.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210323094025.3569441-27-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2021-03-23 22:31:43 +01:00
Markus Armbruster
b86df37478 qapi: Rename pragma *-whitelist to *-exceptions
Rename pragma returns-whitelist to command-returns-exceptions, and
name-case-whitelist to member-name-case-exceptions.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210323094025.3569441-20-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2021-03-23 22:31:05 +01:00
Thomas Huth
5b723a5d8d qga/commands-posix: Send CCW address on s390x with the fsinfo data
We need the CCW address on the libvirt side to correctly identify
the disk, so add this information to the GuestDiskAddress on s390x.

Signed-off-by: Thomas Huth <thuth@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: Michael Roth <michael.roth@amd.com>
Message-Id: <20201127082353.448251-1-thuth@redhat.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
2020-12-21 18:11:33 +01:00
Michael Roth
a8aa94b5f8 qga: update schema for guest-get-disks 'dependents' field
The recently-added 'guest-get-disk' command returns a list of
GuestDiskInfo entries, which in turn have a 'dependents' field which
lists devices these entries are dependent upon. Thus, 'dependencies'
is a better name for this field. Address this by renaming the field
accordingly.

Additionally, 'dependents' is specified as non-optional, even though
it's not implemented for w32. This is misleading, since it gives users
the impression that a particular disk might not have dependencies,
when in reality that information is simply not known to the guest
agent. Address this by making 'dependents' an optional field, and only
marking it as in-use when the facilities to obtain this information are
available to the guest agent.

Cc: Eric Blake <eblake@redhat.com>
Cc: Tomáš Golembiovský <tgolembi@redhat.com>
Cc: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-16 10:48:11 -06:00
Marc-André Lureau
cad97c08a1 qga: add ssh-get-authorized-keys
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
*fix-up merge conflicts due to qga-ssh-test being disabled in earlier
 patch due to G_TEST_OPTION_ISOLATE_DIRS triggering build-oss-fuzz
 leak detector.
*fix up style and disallowed g_assert* usage reported by checkpatch
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 20:04:13 -06:00
Michael Roth
0e3c94758e qga: add *reset argument to ssh-add-authorized-keys
I prefer 'reset' over 'clear', since 'clear' and keys may have some
other relations or meaning.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
*fix disallowed g_assert* usage reported by checkpatch
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 20:01:44 -06:00
Marc-André Lureau
8d769ec777 qga: add ssh-{add,remove}-authorized-keys
Add new commands to add and remove SSH public keys from
~/.ssh/authorized_keys.

I took a different approach for testing, including the unit tests right
with the code. I wanted to overwrite the function to get the user
details, I couldn't easily do that over QMP. Furthermore, I prefer
having unit tests very close to the code, and unit files that are domain
specific (commands-posix is too crowded already). FWIW, that
coding/testing style is Rust-style (where tests can or should even be
part of the documentation!).

Fixes:
https://bugzilla.redhat.com/show_bug.cgi?id=1885332

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
*squashed in fix-ups for setting file ownership and use of QAPI
 conditionals for CONFIG_POSIX instead of stub definitions
*disable qga-ssh-test for now due to G_TEST_OPTION_ISOLATE_DIRS
 triggering leak detector in build-oss-fuzz
*fix disallowed g_assert* usage reported by checkpatch
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 19:58:15 -06:00
Tomáš Golembiovský
c27ea3f9ef qga: add command guest-get-disks
Add API and stubs for new guest-get-disks command.

The command guest-get-fsinfo can be used to list information about disks
and partitions but it is limited only to mounted disks with filesystem.
This new command should allow listing information about disks of the VM
regardles whether they are mounted or not. This can be usefull for
management applications for mapping virtualized devices or pass-through
devices to device names in the guest OS.

Signed-off-by: Tomáš Golembiovský <tgolembi@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 08:14:36 -06:00
Markus Armbruster
0083124b3a qga: Flatten simple union GuestDeviceId
Simple unions are simpler than flat unions in the schema, but more
complicated in C and on the QMP wire: there's extra indirection in C
and extra nesting on the wire, both pointless.  They should be avoided
in new code.

GuestDeviceId was recently added for guest-get-devices.  Convert it to
a flat union.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 08:14:36 -06:00
Markus Armbruster
a88bceef78 qga: Use common time encoding for guest-get-devices 'driver-date'
guest-get-devices returns 'driver-date' as string in the format
YYYY-MM-DD.  Goes back to recent commit 2e4211cee4 "qga: add command
guest-get-devices for reporting VirtIO devices".

We should avoid use of multiple encodings for the same kind of data.
Especially string encodings.  Change it to return nanoseconds since
the epoch, like guest-get-time does.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 08:14:35 -06:00
Markus Armbruster
b519e2e982 qga: Rename guest-get-devices return member 'address' to 'id'
Member 'address' is union GuestDeviceAddress with a single branch
GuestDeviceAddressPCI, containing PCI vendor ID and device ID.  This
is not a PCI address.  Type GuestPCIAddress is.  Messed up in recent
commit 2e4211cee4 "qga: add command guest-get-devices for reporting
VirtIO devices".

Rename type GuestDeviceAddressPCI to GuestDeviceIdPCI, type
GuestDeviceAddress to GuestDeviceId, and member 'address' to 'id'.

Document the member properly while there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Michael Roth <michael.roth@amd.com>
2020-11-02 08:14:35 -06:00
Peter Maydell
ac741a9e81 qga/qapi-schema.json: Add some headings
Add some section headings to the QGA json; this is purely so that we
have some H1 headings, as otherwise each command ends up being
visible in the interop/ manual's table of contents.  In an ideal
world there might be a proper 'Introduction' section the way there is
in qapi/qapi-schema.json.

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-12-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Tomáš Golembiovský
2e4211cee4 qga: add command guest-get-devices for reporting VirtIO devices
Add command for reporting devices on Windows guest. The intent is not so
much to report the devices but more importantly the driver (and its
version) that is assigned to the device. This gives caller the
information whether VirtIO drivers are installed and/or whether
inadequate driver is used on a device (e.g. QXL device with base VGA
driver).

Example:
[
    {
      "driver-date": "2019-08-12",
      "driver-name": "Red Hat VirtIO SCSI controller",
      "driver-version": "100.80.104.17300",
      "address": {
        "type": "pci",
        "data": {
          "device-id": 4162,
          "vendor-id": 6900
        }
      }
    },
    ...
]

Signed-off-by: Tomáš Golembiovský <tgolembi@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
*remove redundant glib autoptr declaration for GuestDeviceInfo
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2020-09-12 20:37:48 -05:00
Andrea Bolognani
f7160f3218 schemas: Add vim modeline
The various schemas included in QEMU use a JSON-based format which
is, however, strictly speaking not valid JSON.

As a consequence, when vim tries to apply syntax highlight rules
for JSON (as guessed from the file name), the result is an unreadable
mess which mostly consist of red markers pointing out supposed errors
in, well, pretty much everything.

Using Python syntax highlighting produces much better results, and
in fact these files already start with specially-formatted comments
that instruct Emacs to process them as if they were Python files.

This commit adds the equivalent special comments for vim.

Signed-off-by: Andrea Bolognani <abologna@redhat.com>
Message-Id: <20200729185024.121766-1-abologna@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-08-03 08:28:08 +02:00
Thomas Huth
ba620541d0 qga/qapi-schema: Document -1 for invalid PCI address fields
The "guest-get-fsinfo" could also be used for non-PCI devices in the
future. And the code in GuestPCIAddress() in qga/commands-win32.c seems
to be using "-1" for fields that it can not determine already. Thus
let's properly document "-1" as value for invalid PCI address fields.

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2020-07-27 18:03:55 -05:00
Philippe Mathieu-Daudé
1329651fb4 qga: Restrict guest-file-read count to 48 MB to avoid crashes
On [*] Daniel Berrangé commented:

  The QEMU guest agent protocol is not sensible way to access huge
  files inside the guest. It requires the inefficient process of
  reading the entire data into memory than duplicating it again in
  base64 format, and then copying it again in the JSON serializer /
  monitor code.

  For arbitrary general purpose file access, especially for large
  files, use a real file transfer program or use a network block
  device, not the QEMU guest agent.

To avoid bug reports as BZ#1594054 (CVE-2018-12617), follow his
suggestion to put a low, hard limit on "count" in the guest agent
QAPI schema, and don't allow count to be larger than 48 MB.

[*] https://www.mail-archive.com/qemu-devel@nongnu.org/msg693176.html

Fixes: CVE-2018-12617
Buglink: https://bugzilla.redhat.com/show_bug.cgi?id=1594054
Reported-by: Fakhri Zulkifli <mohdfakhrizulkifli@gmail.com>
Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
*update schema documentation to indicate 48MB limit instead of 10MB
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2020-04-15 09:18:48 -05:00
Peter Maydell
a7b6e89641 qga/qapi-schema.json: minor format fixups for rST
We would like to switch the doc comments to rST format, and rST
requires a blank line before the start of a bulleted or enumerated
list. Two places in qapi-schema.json were missing this blank line.

Some places were using an indented line as a sort of single-item
bulleted list, which in the Texinfo output comes out all run
onto a single line; use a real bulleted list instead.

Some places unnecessarily indented lists, which confuses rST.

guest-fstrim:minimum's documentation was indented the
right amount to share a line with @minimum, but wasn't
actually doing so.

The indent on the bulleted list in the guest-set-vcpus
Returns section meant rST misindented it.

Changes to the generated Texinfo are very minor (the new
bulleted lists, and a few extra blank lines).

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-7-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-02-15 11:41:49 +01:00
Peter Maydell
883aff68a7 qga/qapi-schema.json: Fix indent level on doc comments
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>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-6-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-02-15 11:41:49 +01:00
Peter Maydell
72ec8bf362 qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment
The doc comment for GuestDiskBusType doesn't match up with the
enumeration because of a missing hyphen in 'file-backed-virtual'.
This means the docs are rendered wrongly:
       "virtual"
           Win virtual bus type "file-backed" virtual: Win file-backed bus type

       "file-backed-virtual"
           Not documented

Add the missing hyphen.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-5-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-02-15 11:41:49 +01:00
Daniel Henrique Barboza
bb6c8d407e qga: update docs with systemd suspend support info
Commit 067927d62e ("qga: systemd hibernate/suspend/hybrid-sleep
support") failed to update qapi-schema.json after adding systemd
hibernate/suspend/hybrid-sleep capabilities to guest-suspend-* QGA
commands.

Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2019-03-18 10:24:20 -05:00
Daniel Henrique Barboza
f8a5777738 qga: update guest-suspend-ram and guest-suspend-hybrid descriptions
This patch updates the descriptions of 'guest-suspend-ram' and
'guest-suspend-hybrid' to mention that both commands relies now
on the proper support for wake up from suspend, retrieved by the
'wakeup-suspend-support' attribute of the 'query-current-machine'
QMP command.

Reported-by: Balamuruhan S <bala24@linux.vnet.ibm.com>
Signed-off-by: Daniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Message-Id: <20181205194701.17836-3-danielhb413@gmail.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Acked-by: Eduardo Habkost <ehabkost@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2018-12-18 07:55:47 +01:00
Tomáš Golembiovský
6589ce3573 qga: linux: return disk device in guest-get-fsinfo
Report device node of the disk on Linux (e.g. "/dev/sda2").
Requirs libudev.

Signed-off-by: Tomáš Golembiovský <tgolembi@redhat.com>
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2018-10-31 09:04:20 -05:00
Tomáš Golembiovský
b616105a90 qga: linux: report disk serial number
Add reporting of disk serial number on Linux guests. The feature depends
on libudev.

Example:

    {
      "name": "dm-2",
      "mountpoint": "/",
      ...
      "disk": [
        {
          "serial": "SAMSUNG_MZ7LN512HCHP-000L1_S1ZKNXAG822493",
          ...
        }
      ],
    }

Signed-off-by: Tomáš Golembiovský <tgolembi@redhat.com>
Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
2018-10-31 09:04:20 -05:00