docs/devel/writing-monitor-commands: Minor improvements

Avoid "JSON" when talking about the QAPI schema syntax. Capitalize
QEMU. Don't claim all HMP commands live in monitor/hmp-cmds.c (this
was n

docs/devel/writing-monitor-commands: Minor improvements

Avoid "JSON" when talking about the QAPI schema syntax. Capitalize
QEMU. Don't claim all HMP commands live in monitor/hmp-cmds.c (this
was never true). Fix punctuation and drop inappropriate "the" here
and there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227115617.237875-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

docs/devel/writing-monitor-commands: Repair a decade of rot

The tutorial doesn't match reality since at least 2013. Repairing it
involves fixing the following issues:

* Update for commit 6d3271715

docs/devel/writing-monitor-commands: Repair a decade of rot

The tutorial doesn't match reality since at least 2013. Repairing it
involves fixing the following issues:

* Update for commit 6d327171551 (aio / timers: Remove alarm timers):
replace the broken examples. Instead of having one for returning a
struct and another for returning a list of structs, do just one for
the latter. This resolves the FIXME added in commit
e218052f928 (aio / timers: De-document -clock) back in 2014.

* Update for commit 895a2a80e0e (qapi: Use 'struct' instead of 'type'
in schema).

* Update for commit 3313b6124b5 (qapi: add qapi2texi script): add
required documentation to the schema snippets, and drop section
"Command Documentation".

* Update for commit a3c45b3e629 (qapi: New special feature flag
"unstable"): supply the required feature, deemphasize the x- prefix.

* Update for commit dd98234c059 (qapi: introduce x-query-roms QMP
command): rephrase from "add new command" to "examine existing
command".

* Update for commit 9492718b7c0 (qapi misc: Elide redundant has_FOO in
generated C): hello-world's message argument no longer comes with a
has_message, add a second argument that does.

* Update for moved and renamed files.

While there, update QMP version output to current output.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227115617.237875-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
[Whitespace tidied up, typo fixed]

show more ...

qapi: Fix dangling references to docs/devel/qapi-code-gen.txt

Conversion of docs/devel/qapi-code-gen.txt to ReST left several
dangling references behind. Fix them to point to
docs/devel/qapi-code-g

qapi: Fix dangling references to docs/devel/qapi-code-gen.txt

Conversion of docs/devel/qapi-code-gen.txt to ReST left several
dangling references behind. Fix them to point to
docs/devel/qapi-code-gen.rst.

Fixes: f7aa076dbdfc (docs: convert qapi-code-gen.txt to ReST)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240120095327.666239-4-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

docs: Replace dangling references to docs/interop/qmp-intro.txt

Deletion of docs/interop/qmp-intro.txt left two dangling references
behind. Replace them by references to docs/interop/qmp-spec.rst.

docs: Replace dangling references to docs/interop/qmp-intro.txt

Deletion of docs/interop/qmp-intro.txt left two dangling references
behind. Replace them by references to docs/interop/qmp-spec.rst.

Fixes: 0ec4468f233c (docs/interop: Delete qmp-intro.txt)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240120095327.666239-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

show more ...

qapi: Start to elide redundant has_FOO in generated C

In QAPI, absent optional members are distinct from any present value.
We thus represent an optional schema member FOO as two C members: a
FOO wi

qapi: Start to elide redundant has_FOO in generated C

In QAPI, absent optional members are distinct from any present value.
We thus represent an optional schema member FOO as two C members: a
FOO with the member's type, and a bool has_FOO. Likewise for function
arguments.

However, has_FOO is actually redundant for a pointer-valued FOO, which
can be null only when has_FOO is false, i.e. has_FOO == !!FOO. Except
for arrays, where we a null FOO can also be a present empty array.

The redundant has_FOO are a nuisance to work with. Improve the
generator to elide them. Uses of has_FOO need to be replaced as
follows.

Tests of has_FOO become the equivalent comparison of FOO with null.
For brevity, this is commonly done by implicit conversion to bool.

Assignments to has_FOO get dropped.

Likewise for arguments to has_FOO parameters.

Beware: code may violate the invariant has_FOO == !!FOO before the
transformation, and get away with it. The above transformation can
then break things. Two cases:

* Absent: if code ignores FOO entirely when !has_FOO (except for
freeing it if necessary), even non-null / uninitialized FOO works.
Such code is known to exist.

* Present: if code ignores FOO entirely when has_FOO, even null FOO
works. Such code should not exist.

In both cases, replacing tests of has_FOO by FOO reverts their sense.
We have to fix the value of FOO then.

To facilitate review of the necessary updates to handwritten code, add
means to opt out of this change, and opt out for all QAPI schema
modules where the change requires updates to handwritten code. The
next few commits will remove these opt-outs in reviewable chunks, then
drop the means to opt out.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20221104160712.3005652-5-armbru@redhat.com>

show more ...

monitor: expose monitor_puts to rest of code

This helps us construct strings elsewhere before echoing to the
monitor. It avoids having to jump through hoops like:

monitor_printf(mon, "%s", s->str

monitor: expose monitor_puts to rest of code

This helps us construct strings elsewhere before echoing to the
monitor. It avoids having to jump through hoops like:

monitor_printf(mon, "%s", s->str);

It will be useful in following patches but for now convert all
existing plain "%s" printfs to use the _puts api.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Message-Id: <20220929114231.583801-33-alex.bennee@linaro.org>

show more ...

docs/devel/writing-monitor-commands: Replace obsolete STEXI/ETEXI tags

STEXI and ETEXI is not used anymore since we switched to Sphinx.
Replace them in the example with SRST and ERST, too.

Message-

docs/devel/writing-monitor-commands: Replace obsolete STEXI/ETEXI tags

STEXI and ETEXI is not used anymore since we switched to Sphinx.
Replace them in the example with SRST and ERST, too.

Message-Id: <20220506150146.564244-1-thuth@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>

show more ...

Fix some typos in documentation (found by codespell)

Signed-off-by: Stefan Weil <sw@weilnetz.de>
Message-Id: <20211117210702.1393570-1-sw@weilnetz.de>
Reviewed-by: Philippe Mathieu-Daudé <philmd@red

Fix some typos in documentation (found by codespell)

Signed-off-by: Stefan Weil <sw@weilnetz.de>
Message-Id: <20211117210702.1393570-1-sw@weilnetz.de>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
[thuth: "what's" --> "what is" as suggested by philmd]
Signed-off-by: Thomas Huth <thuth@redhat.com>

show more ...

docs/devel: document expectations for HMP commands in the future

We no longer wish to have commands implemented in HMP only. All commands
should start with a QMP implementation and the HMP merely be

docs/devel: document expectations for HMP commands in the future

We no longer wish to have commands implemented in HMP only. All commands
should start with a QMP implementation and the HMP merely be a shim
around this. To reduce the burden of implementing QMP commands where
there is low expectation of machine usage, requirements for QAPI
modelling are relaxed provided the command is under the "x-" name
prefix.

Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: add example of command returning unstructured text

This illustrates how to add a QMP command returning unstructured text,
following the guidelines added in the previous patch. The exampl

docs/devel: add example of command returning unstructured text

This illustrates how to add a QMP command returning unstructured text,
following the guidelines added in the previous patch. The example uses
a simplified version of 'info roms'.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: document expectations for QAPI data modelling for QMP

Traditionally we have required that newly added QMP commands will model
any returned data using fine grained QAPI types. This is goo

docs/devel: document expectations for QAPI data modelling for QMP

Traditionally we have required that newly added QMP commands will model
any returned data using fine grained QAPI types. This is good for
commands that are intended to be consumed by machines, where clear data
representation is very important. Commands that don't satisfy this have
generally been added to HMP only.

In effect the decision of whether to add a new command to QMP vs HMP has
been used as a proxy for the decision of whether the cost of designing a
fine grained QAPI type is justified by the potential benefits.

As a result the commands present in QMP and HMP are non-overlapping
sets, although HMP comamnds can be accessed indirectly via the QMP
command 'human-monitor-command'.

One of the downsides of 'human-monitor-command' is that the QEMU monitor
APIs remain tied into various internal parts of the QEMU code. For
example any exclusively HMP command will need to use 'monitor_printf'
to get data out. It would be desirable to be able to fully isolate the
monitor implementation from QEMU internals, however, this is only
possible if all commands are exclusively based on QAPI with direct
QMP exposure.

The way to achieve this desired end goal is to finese the requirements
for QMP command design. For cases where the output of a command is only
intended for human consumption, it is reasonable to want to simplify
the implementation by returning a plain string containing formatted
data instead of designing a fine grained QAPI data type. This can be
permitted if-and-only-if the command is exposed under the 'x-' name
prefix. This indicates that the command data format is liable to
future change and that it is not following QAPI design best practice.

The poster child example for this would be the 'info registers' HMP
command which returns printf formatted data representing CPU state.
This information varies enourmously across target architectures and
changes relatively frequently as new CPU features are implemented.
It is there as debugging data for human operators, and any machine
usage would treat it as an opaque blob. It is thus reasonable to
expose this in QMP as 'x-query-registers' returning a 'str' field.

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: update error handling guidance for HMP commands

Best practice is to use the 'hmp_handle_error' function, not
'monitor_printf' or 'error_report_err'. This ensures that the
message always

docs/devel: update error handling guidance for HMP commands

Best practice is to use the 'hmp_handle_error' function, not
'monitor_printf' or 'error_report_err'. This ensures that the
message always gets an 'Error: ' prefix, distinguishing it
from normal command output.

Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: tweak headings in monitor command docs

The new headings reflect the intended structure of the document and will
better suit additions that follow.

Reviewed-by: Markus Armbruster <armbru

docs/devel: tweak headings in monitor command docs

The new headings reflect the intended structure of the document and will
better suit additions that follow.

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: rename file for writing monitor commands

The file already covers writing HMP commands, in addition to
the QMP commands, so it deserves a more general name.

Reviewed-by: Eric Blake <ebla

docs/devel: rename file for writing monitor commands

The file already covers writing HMP commands, in addition to
the QMP commands, so it deserves a more general name.

Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst

This does about the bare minimum, converting section headers to ReST
ones and adding an indent for code blocks.

Signed-off-by: Joh

docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst

This does about the bare minimum, converting section headers to ReST
ones and adding an indent for code blocks.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20210721165015.2180311-1-jsnow@redhat.com>
Reviewed-by: Connor Kuehl <ckuehl@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs: update to show preferred boolean syntax for -chardev

The preferred syntax is to use "foo=on|off", rather than a bare
"foo" or "nofoo".

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

docs: update to show preferred boolean syntax for -chardev

The preferred syntax is to use "foo=on|off", rather than a bare
"foo" or "nofoo".

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20210216191027.595031-8-berrange@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

qapi: Use QAPI_LIST_PREPEND() where possible

Anywhere we create a list of just one item or by prepending items
(typically because order doesn't matter), we can use
QAPI_LIST_PREPEND(). But places w

qapi: Use QAPI_LIST_PREPEND() where possible

Anywhere we create a list of just one item or by prepending items
(typically because order doesn't matter), we can use
QAPI_LIST_PREPEND(). But places where we must keep the list in order
by appending remain open-coded until later patches.

Note that as a side effect, this also performs a cleanup of two minor
issues in qga/commands-posix.c: the old code was performing
new = g_malloc0(sizeof(*ret));
which 1) is confusing because you have to verify whether 'new' and
'ret' are variables with the same type, and 2) would conflict with C++
compilation (not an actual problem for this file, but makes
copy-and-paste harder).

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <20201113011340.463563-5-eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
[Straightforward conflicts due to commit a8aa94b5f8 "qga: update
schema for guest-get-disks 'dependents' field" and commit a10b453a52
"target/mips: Move mips_cpu_add_definition() from helper.c to cpu.c"
resolved. Commit message tweaked.]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs/devel/writing-qmp-commands.txt: Fix docs

Fix the example of add qmp hello-world example.
Without ":", make will report error:
../qapi/misc.json:573:2: line should end with ':'

Signed-off-by: Z

docs/devel/writing-qmp-commands.txt: Fix docs

Fix the example of add qmp hello-world example.
Without ":", make will report error:
../qapi/misc.json:573:2: line should end with ':'

Signed-off-by: Zihao Chang <changzihao1@huawei.com>
Message-Id: <20201201143308.1626-1-changzihao1@huawei.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

monitor: Move {hmp, qmp}.c to monitor/{hmp, qmp}-cmds.c

Now that we have a monitor/ subdirectory, let's move hmp.c and qmp.c
from the root directory there. As they contain implementations of
monitor

monitor: Move {hmp, qmp}.c to monitor/{hmp, qmp}-cmds.c

Now that we have a monitor/ subdirectory, let's move hmp.c and qmp.c
from the root directory there. As they contain implementations of
monitor commands, rename them to {hmp,qmp}-cmds.c, so that {hmp,qmp}.c
are free for the HMP and QMP infrastructure.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20190613153405.24769-9-kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Move monitor.c to monitor/misc.c

Create a new monitor/ subdirectory and move monitor.c there. As the plan
is to move the monitor core into separate files, use the chance to
rename it to misc.c.

Sig

Move monitor.c to monitor/misc.c

Create a new monitor/ subdirectory and move monitor.c there. As the plan
is to move the monitor core into separate files, use the chance to
rename it to misc.c.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20190613153405.24769-8-kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: Move qapi-schema.json to qapi/, rename generated files

Move qapi-schema.json to qapi/, so it's next to its modules, and all
files get generated to qapi/, not just the ones generated for module

qapi: Move qapi-schema.json to qapi/, rename generated files

Move qapi-schema.json to qapi/, so it's next to its modules, and all
files get generated to qapi/, not just the ones generated for modules.

Consistently name the generated files qapi-MODULE.EXT:
qmp-commands.[ch] become qapi-commands.[ch], qapi-event.[ch] become
qapi-events.[ch], and qmp-introspect.[ch] become qapi-introspect.[ch].
This gets rid of the temporary hacks in scripts/qapi/commands.py,
scripts/qapi/events.py, and scripts/qapi/common.py.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20180211093607.27351-28-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
[eblake: Fix trailing dot in tpm.c, undo temporary hack for OSX toolchain]
Signed-off-by: Eric Blake <eblake@redhat.com>

show more ...

docs: Correct outdated information on QAPI

* Fix guidance on error classes

* Point to generated documentation

* Drop plea for documentation, because the QAPI code generator
enforces it since com

docs: Correct outdated information on QAPI

* Fix guidance on error classes

* Point to generated documentation

* Drop plea for documentation, because the QAPI code generator
enforces it since commit 3313b6124b

* Minor tweaks here and there

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20180211093607.27351-27-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Signed-off-by: Eric Blake <eblake@redhat.com>

show more ...

docs/devel/writing-qmp-commands: Update for modular QAPI

With modular code generation, putting stuff right into
qapi-schema.json is a bad idea. Update writing-qmp-commands.txt
accordingly.

Signed-

docs/devel/writing-qmp-commands: Update for modular QAPI

With modular code generation, putting stuff right into
qapi-schema.json is a bad idea. Update writing-qmp-commands.txt
accordingly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20180211093607.27351-26-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Signed-off-by: Eric Blake <eblake@redhat.com>

show more ...

docs: fix broken paths to docs/devel/qapi-code-gen.txt

With the move of some docs to docs/interop on ac06724a71,
a couple of references were not updated.

Signed-off-by: Philippe Mathieu-Daudé <f4bu

docs: fix broken paths to docs/devel/qapi-code-gen.txt

With the move of some docs to docs/interop on ac06724a71,
a couple of references were not updated.

Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>

show more ...

docs: fix broken paths to docs/interop dir

With the move of some docs to docs/interop on d59157e, a couple of
references were not updated.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
[PMD: fixed

docs: fix broken paths to docs/interop dir

With the move of some docs to docs/interop on d59157e, a couple of
references were not updated.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
[PMD: fixed a typo and another reference of docs/interop/qmp-spec.txt]
Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>

show more ...