| Message ID | 20240812231945.169310-1-pierrick.bouvier@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] docs/devel: update tcg-plugins page | expand |
v2 -- rebased on top of master (plugins doc was split between several files) v3 -- fix bad commit message On 8/12/24 16:19, Pierrick Bouvier wrote: > Reflect recent changes on API (inline ops) and new plugins. > > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> > --- > docs/about/emulation.rst | 49 ++++++++++++++++++++++++++++++++------ > docs/devel/tcg-plugins.rst | 13 ++++++---- > 2 files changed, 50 insertions(+), 12 deletions(-) > > diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst > index c03033e4e95..eea1261baac 100644 > --- a/docs/about/emulation.rst > +++ b/docs/about/emulation.rst > @@ -207,8 +207,8 @@ Once built a program can be run with multiple plugins loaded each with > their own arguments:: > > $QEMU $OTHER_QEMU_ARGS \ > - -plugin contrib/plugin/libhowvec.so,inline=on,count=hint \ > - -plugin contrib/plugin/libhotblocks.so > + -plugin contrib/plugins/libhowvec.so,inline=on,count=hint \ > + -plugin contrib/plugins/libhotblocks.so > > Arguments are plugin specific and can be used to modify their > behaviour. In this case the howvec plugin is being asked to use inline > @@ -219,6 +219,14 @@ Linux user-mode emulation also evaluates the environment variable > > QEMU_PLUGIN="file=contrib/plugins/libhowvec.so,inline=on,count=hint" $QEMU > > +QEMU plugins avoid to write directly to stdin/stderr, and use the log provided > +by the API (see function ``qemu_plugin_outs``). > +To show output, you may use this additional parameter:: > + > + $QEMU $OTHER_QEMU_ARGS \ > + -d plugin \ > + -plugin contrib/plugins/libhowvec.so,inline=on,count=hint > + > Example Plugins > ~~~~~~~~~~~~~~~ > > @@ -260,8 +268,7 @@ Behaviour can be tweaked with the following arguments: > * - Option > - Description > * - inline=true|false > - - Use faster inline addition of a single counter. Not per-cpu and not > - thread safe. > + - Use faster inline addition of a single counter. > * - idle=true|false > - Dump the current execution stats whenever the guest vCPU idles > > @@ -381,6 +388,15 @@ run:: > 160 1 0 > 135 1 0 > > +Test inline operations > +...................... > + > +``tests/plugins/inline.c`` > + > +This plugin is used for testing all inline operations, conditional callbacks and > +scoreboard. It prints a per-cpu summary of all events. > + > + > Hot Blocks > .......... > > @@ -394,9 +410,6 @@ with linux-user execution as system emulation tends to generate > re-translations as blocks from different programs get swapped in and > out of system memory. > > -If your program is single-threaded you can use the ``inline`` option for > -slightly faster (but not thread safe) counters. > - > Example:: > > $ qemu-aarch64 \ > @@ -736,6 +749,28 @@ The plugin will log the reason of exit, for example:: > > 0xd4 reached, exiting > > +Limit instructions per second > +............................. > + > +This plugin can limit the number of Instructions Per Second that are executed:: > + > + # get number of instructions > + $ num_insn=$(./build/qemu-x86_64 -plugin ./build/tests/plugin/libinsn.so -d plugin /bin/true |& grep total | sed -e 's/.*: //') > + # limit speed to execute in 10 seconds > + $ time ./build/qemu-x86_64 -plugin ./build/contrib/plugins/libips.so,ips=$(($num_insn/10)) /bin/true > + real 10.000s > + > + > +.. list-table:: IPS arguments > + :widths: 20 80 > + :header-rows: 1 > + > + * - Option > + - Description > + * - ips=N > + - Maximum number of instructions per cpu that can be executed in one second. > + The plugin will sleep when the given number of instructions is reached. > + > Other emulation features > ------------------------ > > diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst > index d8725c2854a..9463692c411 100644 > --- a/docs/devel/tcg-plugins.rst > +++ b/docs/devel/tcg-plugins.rst > @@ -61,11 +61,14 @@ translation event the plugin has an option to enumerate the > instructions in a block of instructions and optionally register > callbacks to some or all instructions when they are executed. > > -There is also a facility to add an inline event where code to > -increment a counter can be directly inlined with the translation. > -Currently only a simple increment is supported. This is not atomic so > -can miss counts. If you want absolute precision you should use a > -callback which can then ensure atomicity itself. > +There is also a facility to add inline instructions doing various operations, > +like adding or storing an immediate value. It is also possible to execute a > +callback conditionally, with condition being evaluated inline. All those inline > +operations are associated to a ``scoreboard``, which is a thread-local storage > +automatically expanded when new cores/threads are created and that can be > +accessed/modified in a thread-safe way without any lock needed. Combining inline > +operations and conditional callbacks offer a more efficient way to instrument > +binaries, compared to classic callbacks. > > Finally when QEMU exits all the registered *atexit* callbacks are > invoked.
Pierrick Bouvier <pierrick.bouvier@linaro.org> writes: > Reflect recent changes on API (inline ops) and new plugins. > > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Queued to maintainer/for-9.1, thanks.
diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst index c03033e4e95..eea1261baac 100644 --- a/docs/about/emulation.rst +++ b/docs/about/emulation.rst @@ -207,8 +207,8 @@ Once built a program can be run with multiple plugins loaded each with their own arguments:: $QEMU $OTHER_QEMU_ARGS \ - -plugin contrib/plugin/libhowvec.so,inline=on,count=hint \ - -plugin contrib/plugin/libhotblocks.so + -plugin contrib/plugins/libhowvec.so,inline=on,count=hint \ + -plugin contrib/plugins/libhotblocks.so Arguments are plugin specific and can be used to modify their behaviour. In this case the howvec plugin is being asked to use inline @@ -219,6 +219,14 @@ Linux user-mode emulation also evaluates the environment variable QEMU_PLUGIN="file=contrib/plugins/libhowvec.so,inline=on,count=hint" $QEMU +QEMU plugins avoid to write directly to stdin/stderr, and use the log provided +by the API (see function ``qemu_plugin_outs``). +To show output, you may use this additional parameter:: + + $QEMU $OTHER_QEMU_ARGS \ + -d plugin \ + -plugin contrib/plugins/libhowvec.so,inline=on,count=hint + Example Plugins ~~~~~~~~~~~~~~~ @@ -260,8 +268,7 @@ Behaviour can be tweaked with the following arguments: * - Option - Description * - inline=true|false - - Use faster inline addition of a single counter. Not per-cpu and not - thread safe. + - Use faster inline addition of a single counter. * - idle=true|false - Dump the current execution stats whenever the guest vCPU idles @@ -381,6 +388,15 @@ run:: 160 1 0 135 1 0 +Test inline operations +...................... + +``tests/plugins/inline.c`` + +This plugin is used for testing all inline operations, conditional callbacks and +scoreboard. It prints a per-cpu summary of all events. + + Hot Blocks .......... @@ -394,9 +410,6 @@ with linux-user execution as system emulation tends to generate re-translations as blocks from different programs get swapped in and out of system memory. -If your program is single-threaded you can use the ``inline`` option for -slightly faster (but not thread safe) counters. - Example:: $ qemu-aarch64 \ @@ -736,6 +749,28 @@ The plugin will log the reason of exit, for example:: 0xd4 reached, exiting +Limit instructions per second +............................. + +This plugin can limit the number of Instructions Per Second that are executed:: + + # get number of instructions + $ num_insn=$(./build/qemu-x86_64 -plugin ./build/tests/plugin/libinsn.so -d plugin /bin/true |& grep total | sed -e 's/.*: //') + # limit speed to execute in 10 seconds + $ time ./build/qemu-x86_64 -plugin ./build/contrib/plugins/libips.so,ips=$(($num_insn/10)) /bin/true + real 10.000s + + +.. list-table:: IPS arguments + :widths: 20 80 + :header-rows: 1 + + * - Option + - Description + * - ips=N + - Maximum number of instructions per cpu that can be executed in one second. + The plugin will sleep when the given number of instructions is reached. + Other emulation features ------------------------ diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index d8725c2854a..9463692c411 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -61,11 +61,14 @@ translation event the plugin has an option to enumerate the instructions in a block of instructions and optionally register callbacks to some or all instructions when they are executed. -There is also a facility to add an inline event where code to -increment a counter can be directly inlined with the translation. -Currently only a simple increment is supported. This is not atomic so -can miss counts. If you want absolute precision you should use a -callback which can then ensure atomicity itself. +There is also a facility to add inline instructions doing various operations, +like adding or storing an immediate value. It is also possible to execute a +callback conditionally, with condition being evaluated inline. All those inline +operations are associated to a ``scoreboard``, which is a thread-local storage +automatically expanded when new cores/threads are created and that can be +accessed/modified in a thread-safe way without any lock needed. Combining inline +operations and conditional callbacks offer a more efficient way to instrument +binaries, compared to classic callbacks. Finally when QEMU exits all the registered *atexit* callbacks are invoked.
Reflect recent changes on API (inline ops) and new plugins. Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> --- docs/about/emulation.rst | 49 ++++++++++++++++++++++++++++++++------ docs/devel/tcg-plugins.rst | 13 ++++++---- 2 files changed, 50 insertions(+), 12 deletions(-)