docs/devel: update tcg-plugins page

Reflect recent changes on API (inline ops) and new plugins.

Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Message-Id: <20240812231945.169310-1-pi

docs/devel: update tcg-plugins page

Reflect recent changes on API (inline ops) and new plugins.

Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Message-Id: <20240812231945.169310-1-pierrick.bouvier@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240813202329.1237572-21-alex.bennee@linaro.org>

show more ...

docs: split TCG plugin usage from devel section

The devel section is getting quite messy with the breakdown of the
example plugins which should be usable by users. As we mention plugins
in the emula

docs: split TCG plugin usage from devel section

The devel section is getting quite messy with the breakdown of the
example plugins which should be usable by users. As we mention plugins
in the emulation section along with semihosting move the overview
there leaving the development section about the details of writing
plugins.

While we are at make the headings nicer and convert the option lists
into nicely formatted tables.

Acked-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240729144414.830369-11-alex.bennee@linaro.org>

show more ...

plugins/stoptrigger: TCG plugin to stop execution under conditions

This new plugin allows to stop emulation using conditions on the
emulation state. By setting this plugin arguments, it is possible

plugins/stoptrigger: TCG plugin to stop execution under conditions

This new plugin allows to stop emulation using conditions on the
emulation state. By setting this plugin arguments, it is possible
to set an instruction count limit and/or trigger address(es) to stop at.
The code returned at emulation exit can be customized.

This plugin demonstrates how someone could stop QEMU execution.
It could be used for research purposes to launch some code and
deterministically stop it and understand where its execution flow went.

Co-authored-by: Alexandre Iooss <erdnaxe@crans.org>
Signed-off-by: Simon Hamelin <simon.hamelin@grenoble-inp.org>
Signed-off-by: Alexandre Iooss <erdnaxe@crans.org>
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Message-Id: <20240715081521.19122-2-simon.hamelin@grenoble-inp.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240718094523.1198645-5-alex.bennee@linaro.org>

show more ...

docs: add precision about capstone for execlog plugin

Some people are wondering why they get an empty string as disassembly.
Most of the time, they configured QEMU without Capstone support.
Let's do

docs: add precision about capstone for execlog plugin

Some people are wondering why they get an empty string as disassembly.
Most of the time, they configured QEMU without Capstone support.
Let's document this behaviour to help users.

Signed-off-by: Alexandre Iooss <erdnaxe@crans.org>
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Message-ID: <20240620135731.977377-1-erdnaxe@crans.org>
Signed-off-by: Thomas Huth <thuth@redhat.com>

show more ...

docs/devel: document some plugin assumptions

While we attempt to hide implementation details from the plugin we
shouldn't be totally obtuse. Let the user know what they can and can't
expect with the

docs/devel: document some plugin assumptions

While we attempt to hide implementation details from the plugin we
shouldn't be totally obtuse. Let the user know what they can and can't
expect with the various instrumentation options.

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240227144335.1196131-29-alex.bennee@linaro.org>

show more ...

docs/devel: lift example and plugin API sections up

This makes them a bit more visible in the TCG emulation menu rather
than hiding them away bellow the ToC limit.

Reviewed-by: Pierrick Bouvier <pi

docs/devel: lift example and plugin API sections up

This makes them a bit more visible in the TCG emulation menu rather
than hiding them away bellow the ToC limit.

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240227144335.1196131-28-alex.bennee@linaro.org>

show more ...

contrib/plugins: extend execlog to track register changes

With the new plugin register API we can now track changes to register
values. Currently the implementation is fairly dumb which will slow
do

contrib/plugins: extend execlog to track register changes

With the new plugin register API we can now track changes to register
values. Currently the implementation is fairly dumb which will slow
down if a large number of register values are being tracked. This
could be improved by only instrumenting instructions which mention
registers we are interested in tracking.

Example usage:

./qemu-aarch64 -D plugin.log -d plugin \
-cpu max,sve256=on \
-plugin contrib/plugins/libexeclog.so,reg=sp,reg=z\* \
./tests/tcg/aarch64-linux-user/sha512-sve

will display in the execlog any changes to the stack pointer (sp) and
the SVE Z registers.

As testing registers every instruction will be quite a heavy operation
there is an additional flag which attempts to optimise the register
tracking by only instrumenting instructions which are likely to change
its value. This relies on the QEMU disassembler showing up the register
names in disassembly so is an explicit opt-in.

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Cc: Akihiko Odaki <akihiko.odaki@daynix.com>
Based-On: <20231025093128.33116-19-akihiko.odaki@daynix.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20240227144335.1196131-27-alex.bennee@linaro.org>

show more ...

docs: add a new section to outline emulation support

This affects both system and user mode emulation so we should probably
list it up front.

Acked-by: Richard Henderson <richard.henderson@linaro.o

docs: add a new section to outline emulation support

This affects both system and user mode emulation so we should probably
list it up front.

Acked-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20230124180127.1881110-21-alex.bennee@linaro.org>

show more ...

docs/devel: document the test plugins

Although the test plugins are fairly basic they are still useful for
some things so we should document their existence.

Signed-off-by: Alex Bennée <alex.bennee

docs/devel: document the test plugins

Although the test plugins are fairly basic they are still useful for
some things so we should document their existence.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20220929114231.583801-41-alex.bennee@linaro.org>

show more ...

docs/devel: move API to end of tcg-plugins.rst

The API documentation is quite dry and doesn't flow nicely with the
rest of the document. Move it to its own section at the bottom along
with a little

docs/devel: move API to end of tcg-plugins.rst

The API documentation is quite dry and doesn't flow nicely with the
rest of the document. Move it to its own section at the bottom along
with a little leader text to remind people to update it.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Message-Id: <20220929114231.583801-39-alex.bennee@linaro.org>

show more ...

docs/devel: clean-up qemu invocations in tcg-plugins

We currently have the final binaries in the root of the build dir so
the build prefix is superfluous. Additionally add a shell prompt to be
more

docs/devel: clean-up qemu invocations in tcg-plugins

We currently have the final binaries in the root of the build dir so
the build prefix is superfluous. Additionally add a shell prompt to be
more in line with the rest of the code.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Message-Id: <20220929114231.583801-38-alex.bennee@linaro.org>

show more ...

plugins: extend execlog to filter matches

Sometimes the whole execlog is just two much so add the ability to
filter by instruction opcode or address.

[AJB: this shows for example

qemu-system-aarc

plugins: extend execlog to filter matches

Sometimes the whole execlog is just two much so add the ability to
filter by instruction opcode or address.

[AJB: this shows for example

qemu-system-aarch64 -display none -serial mon:stdio \
-M virt -cpu max \
-semihosting-config enable=on \
-kernel ./tests/tcg/aarch64-softmmu/memory-sve \
-plugin ./contrib/plugins/libexeclog.so,ifilter=st1w,afilter=0x40001808 -d plugin -D plugin.out

the st1w SVE instruction is not instrumenting its stores.]

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Alexandre Iooss <erdnaxe@crans.org>
Cc: Robert Henry <robhenry@microsoft.com>
Cc: Aaron Lindsay <aaron@os.amperecomputing.com>
Message-Id: <20220929114231.583801-36-alex.bennee@linaro.org>

show more ...

docs/tcg-plugins: document QEMU_PLUGIN behaviour

QEMU plugins can be loaded via command line arguments or via
the QEMU_PLUGIN environment variable. Currently, only the first method
is documented. Le

docs/tcg-plugins: document QEMU_PLUGIN behaviour

QEMU plugins can be loaded via command line arguments or via
the QEMU_PLUGIN environment variable. Currently, only the first method
is documented. Let's document QEMU_PLUGIN.

As drive-by cleanup, this patch fixes the path to the plugins
in the same section of the documentation.

Signed-off-by: Christoph Muellner <cmuellner@linux.com>
Message-Id: <20220316181412.1550044-1-cmuellner@linux.com>
[AJB: fixed some minor typos]
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

show more ...

docs: remove non-reference uses of single backticks

The single backtick markup in ReST is the "default role". Currently,
Sphinx's default role is called "content". Sphinx suggests you can use
the "A

docs: remove non-reference uses of single backticks

The single backtick markup in ReST is the "default role". Currently,
Sphinx's default role is called "content". Sphinx suggests you can use
the "Any" role instead to turn any single-backtick enclosed item into a
cross-reference.

This is useful for things like autodoc for Python docstrings, where it's
often nicer to reference other types with `foo` instead of the more
laborious :py:meth:`foo`. It's also useful in multi-domain cases to
easily reference definitions from other Sphinx domains, such as
referencing C code definitions from outside of kerneldoc comments.

Before we do that, though, we'll need to turn all existing usages of the
"content" role to inline verbatim markup wherever it does not correctly
resolve into a cross-refernece by using double backticks instead.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20211004215238.1523082-2-jsnow@redhat.com>

show more ...

docs/tcg-plugins: add L2 arguments to cache docs

cache plugin now allows optional L2 per-core cache emulation that can be
configured through plugin arguments, this commit adds this functionality
to

docs/tcg-plugins: add L2 arguments to cache docs

cache plugin now allows optional L2 per-core cache emulation that can be
configured through plugin arguments, this commit adds this functionality
to the docs.

While I'm at it, I editted the bullet point for cache plugin to say:
contrib/plugins/cache.c
instead of
contrib/plugins/cache
to match other plugins.

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210810134844.166490-6-ma.mandourr@gmail.com>
Message-Id: <20211026102234.3961636-18-alex.bennee@linaro.org>

show more ...

docs: reorganize tcg-plugins.rst

Clean up the heading levels to use === --- ~~~, and create a new "writing
plugins" section.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

docs/devel: be consistent about example plugin names

Some plugins were prefixed with `.c`, some were not. Since the name is
essentially the full-name of the plugin file, it's logical to include
the

docs/devel: be consistent about example plugin names

Some plugins were prefixed with `.c`, some were not. Since the name is
essentially the full-name of the plugin file, it's logical to include
the extension.

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Message-Id: <20210830121534.656559-1-ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

show more ...

docs/tcg-plugins: new passing parameters scheme for cache docs

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <al

docs/tcg-plugins: new passing parameters scheme for cache docs

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210730135817.17816-9-ma.mandourr@gmail.com>

show more ...

plugins/howvec: adapting to the new argument passing scheme

Correctly parsing plugin argument since they now must be provided as
full-form boolean parameters, e.g.:
-plugin ./contrib/plugins/lib

plugins/howvec: adapting to the new argument passing scheme

Correctly parsing plugin argument since they now must be provided as
full-form boolean parameters, e.g.:
-plugin ./contrib/plugins/libhowvec.so,verbose=on,inline=on

Also, introduced the argument "count" that accepts one opt to count
individually at a time.

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210730135817.17816-8-ma.mandourr@gmail.com>

show more ...

plugins/hwprofile: adapt to the new plugin arguments scheme

Parsing boolean arguments correctly (e.g. pattern=on or source=false).
Introduced a new "track" argument that takes a [read|write] value.

plugins/hwprofile: adapt to the new plugin arguments scheme

Parsing boolean arguments correctly (e.g. pattern=on or source=false).
Introduced a new "track" argument that takes a [read|write] value. This
substitutes passing read or write to "arg=" that is deprecated.

Also, matches are now taken one by one through the "match" argument.

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210730135817.17816-7-ma.mandourr@gmail.com>

show more ...

plugins/lockstep: make socket path not positional & parse bool arg

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée

plugins/lockstep: make socket path not positional & parse bool arg

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210730135817.17816-6-ma.mandourr@gmail.com>

show more ...

plugins/hotpages: introduce sortby arg and parsed bool args correctly

Since plugin arguments now expect boolean arguments, a plugin argument
name "sortby" now expects a value of "read", "write", or

plugins/hotpages: introduce sortby arg and parsed bool args correctly

Since plugin arguments now expect boolean arguments, a plugin argument
name "sortby" now expects a value of "read", "write", or "address".

"io" arg is now expected to be passed as a full-form boolean parameter,
i.e. "io=on|true|yes|off|false|no"

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210730135817.17816-4-ma.mandourr@gmail.com>

show more ...

docs/devel/tcg-plugins: added cores arg to cache plugin

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Message-Id: <20210803151301.123581-3-ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée

docs/devel/tcg-plugins: added cores arg to cache plugin

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Message-Id: <20210803151301.123581-3-ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

show more ...

docs/devel: Format literals correctly

In rST markup, single backticks `like this` represent "interpreted
text", which can be handled as a bunch of different things if tagged
with a specific "role":

docs/devel: Format literals correctly

In rST markup, single backticks `like this` represent "interpreted
text", which can be handled as a bunch of different things if tagged
with a specific "role":
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text
(the most common one for us is "reference to a URL, which gets
hyperlinked").

The default "role" if none is specified is "title_reference",
intended for references to book or article titles, and it renders
into the HTML as <cite>...</cite> (usually comes out as italics).

Fix various places in the devel section of the manual which were
using single backticks when double backticks (for literal text)
were intended.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-id: 20210726142338.31872-6-peter.maydell@linaro.org

show more ...

docs/devel: Added cache plugin to the plugins docs

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210628053808.17422-1-ma.m

docs/devel: Added cache plugin to the plugins docs

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210628053808.17422-1-ma.mandourr@gmail.com>
Message-Id: <20210709143005.1554-40-alex.bennee@linaro.org>

show more ...