aboutsummaryrefslogtreecommitdiff
path: root/docs/devel/tcg-plugins.rst
AgeCommit message (Collapse)AuthorFilesLines
2024-02-28docs/devel: document some plugin assumptionsAlex Bennée1-0/+49
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>
2024-02-28docs/devel: lift example and plugin API sections upAlex Bennée1-3/+3
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>
2024-02-28contrib/plugins: extend execlog to track register changesAlex Bennée1-1/+16
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>
2023-02-02docs: add a new section to outline emulation supportAlex Bennée1-0/+2
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>
2022-10-06docs/devel: document the test pluginsAlex Bennée1-4/+133
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>
2022-10-06docs/devel: move API to end of tcg-plugins.rstAlex Bennée1-5/+10
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>
2022-10-06docs/devel: clean-up qemu invocations in tcg-pluginsAlex Bennée1-9/+9
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>
2022-10-06plugins: extend execlog to filter matchesAlex Bennée1-1/+8
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>
2022-03-23docs/tcg-plugins: document QEMU_PLUGIN behaviourChristoph Muellner1-2/+7
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>
2021-11-08docs: remove non-reference uses of single backticksJohn Snow1-1/+1
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>
2021-11-04docs/tcg-plugins: add L2 arguments to cache docsMahmoud Mandour1-2/+18
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>
2021-10-01docs: reorganize tcg-plugins.rstPaolo Bonzini1-47/+46
Clean up the heading levels to use === --- ~~~, and create a new "writing plugins" section. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-09-02docs/devel: be consistent about example plugin namesMahmoud Mandour1-2/+2
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>
2021-09-02docs/tcg-plugins: new passing parameters scheme for cache docsMahmoud Mandour1-9/+9
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>
2021-09-02plugins/howvec: adapting to the new argument passing schemeMahmoud Mandour1-5/+5
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>
2021-09-02plugins/hwprofile: adapt to the new plugin arguments schemeMahmoud Mandour1-4/+4
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>
2021-09-02plugins/lockstep: make socket path not positional & parse bool argMahmoud Mandour1-1/+1
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>
2021-09-02plugins/hotpages: introduce sortby arg and parsed bool args correctlyMahmoud Mandour1-0/+15
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>
2021-09-02docs/devel/tcg-plugins: added cores arg to cache pluginMahmoud Mandour1-5/+8
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>
2021-08-02docs/devel: Format literals correctlyPeter Maydell1-7/+7
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
2021-07-14docs/devel: Added cache plugin to the plugins docsMahmoud Mandour1-0/+59
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>
2021-07-14docs/devel: tcg-plugins: add execlog plugin descriptionAlexandre Iooss1-0/+24
This adds description of the execlog TCG plugin with an example. Signed-off-by: Alexandre Iooss <erdnaxe@crans.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20210702081307.1653644-3-erdnaxe@crans.org> Message-Id: <20210709143005.1554-36-alex.bennee@linaro.org>
2021-07-14tcg/plugins: enable by default for most TCG buildsAlex Bennée1-1/+2
Aside from a minor bloat to file size the ability to have TCG plugins has no real impact on performance unless a plugin is actively loaded. Even then the libempty.so plugin shows only a minor degradation in performance caused by the extra book keeping the TCG has to do to keep track of instructions. As it's a useful feature lets just enable it by default and reduce our testing matrix a little. We need to move our linker testing earlier so we can be sure we can enable the loader module required. As we have ruled out static & plugins in an earlier patch we can also reduce the indent a little. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Cc: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20210709143005.1554-33-alex.bennee@linaro.org>
2021-03-24docs/devel: include the plugin API information from the headersAlex Bennée1-0/+5
We have kerneldoc tags for the headers so we might as well extract them into our developer documentation whilst we are at it. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Aaron Lindsay <aaron@os.amperecomputing.com> Message-Id: <20210323165308.15244-3-alex.bennee@linaro.org>
2021-02-18plugins: new hwprofile pluginAlex Bennée1-0/+34
This is a plugin intended to help with profiling access to various bits of system hardware. It only really makes sense for system emulation. It takes advantage of the recently exposed helper API that allows us to see the device name (memory region name) associated with a device. You can specify arg=read or arg=write to limit the tracking to just reads or writes (by default it does both). The pattern option: -plugin ./tests/plugin/libhwprofile.so,arg=pattern will allow you to see the access pattern to devices, eg: gic_cpu @ 0xffffffc010040000 off:00000000, 8, 1, 8, 1 off:00000000, 4, 1, 4, 1 off:00000000, 2, 1, 2, 1 off:00000000, 1, 1, 1, 1 The source option: -plugin ./tests/plugin/libhwprofile.so,arg=source will track the virtual source address of the instruction making the access: pl011 @ 0xffffffc010031000 pc:ffffffc0104c785c, 1, 4, 0, 0 pc:ffffffc0104c7898, 1, 4, 0, 0 pc:ffffffc010512bcc, 2, 1867, 0, 0 You cannot mix source and pattern. Finally the match option allow you to limit the tracking to just the devices you care about. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Robert Foley <robert.foley@linaro.org> Reviewed-by: Robert Foley <robert.foley@linaro.org> Message-Id: <20210213130325.14781-4-alex.bennee@linaro.org>
2020-09-10plugins: move the more involved plugins to contribAlex Bennée1-0/+146
We have an exploding complexity problem in the testing so lets just move the more involved plugins into contrib. tests/plugins still exist for the basic plugins that exercise the API. We restore the old pre-meson style Makefile for contrib as it also doubles as a guide for out-of-tree plugin builds. While we are at it add some examples to the documentation and a specific plugins build target. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20200909112742.25730-11-alex.bennee@linaro.org>
2020-02-25docs/devel: document query handle lifetimesAlex Bennée1-2/+11
I forgot to document the lifetime of handles in the developer documentation. Do so now. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Robert Foley <robert.foley@linaro.org> Reviewed-by: Robert Foley <robert.foley@linaro.org> Message-Id: <20200225124710.14152-11-alex.bennee@linaro.org>
2019-11-20docs/devel: update tcg-plugins.rst with API versioning detailsAlex Bennée1-6/+21
While we are at it fix up the quoted code sections with the inline :: approach. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Robert Foley <robert.foley@linaro.org>
2019-11-20docs/devel: rename plugins.rst to tcg-plugins.rstAlex Bennée1-0/+112
This makes it a bit clearer what this is about. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
generated by cgit v1.1 at 2024-11-06 02:25:16 +0000