diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/deprecated.rst | 12 | ||||
| -rw-r--r-- | docs/devel/ci-jobs.rst | 11 | ||||
| -rw-r--r-- | docs/devel/tcg-plugins.rst | 68 |
3 files changed, 66 insertions, 25 deletions
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index 1e1a5e96ad..6e88a84bba 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -139,6 +139,18 @@ The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which should be used instead. +Plugin argument passing through ``arg=<string>`` (since 6.1) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Passing TCG plugins arguments through ``arg=`` is redundant is makes the +command-line less readable, especially when the argument itself consist of a +name and a value, e.g. ``-plugin plugin_name,arg="arg_name=arg_value"``. +Therefore, the usage of ``arg`` is redundant. Single-word arguments are treated +as short-form boolean values, and passed to plugins as ``arg_name=on``. +However, short-form booleans are deprecated and full explicit ``arg_name=on`` +form is preferred. + + QEMU Machine Protocol (QMP) commands ------------------------------------ diff --git a/docs/devel/ci-jobs.rst b/docs/devel/ci-jobs.rst index 9cd9819786..277975e4ad 100644 --- a/docs/devel/ci-jobs.rst +++ b/docs/devel/ci-jobs.rst @@ -38,3 +38,14 @@ these artifacts are not already cached, downloading them make the jobs reach the timeout limit). Set this variable to have the tests using the Avocado framework run automatically. +AARCH64_RUNNER_AVAILABLE +~~~~~~~~~~~~~~~~~~~~~~~~ +If you've got access to an aarch64 host that can be used as a gitlab-CI +runner, you can set this variable to enable the tests that require this +kind of host. The runner should be tagged with "aarch64". + +S390X_RUNNER_AVAILABLE +~~~~~~~~~~~~~~~~~~~~~~ +If you've got access to an IBM Z host that can be used as a gitlab-CI +runner, you can set this variable to enable the tests that require this +kind of host. The runner should be tagged with "s390x". diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 047bf4ada7..dac5101a3c 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -80,7 +80,7 @@ Once built a program can be run with multiple plugins loaded each with their own arguments:: $QEMU $OTHER_QEMU_ARGS \ - -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ + -plugin tests/plugin/libhowvec.so,inline=on,count=hint \ -plugin tests/plugin/libhotblocks.so Arguments are plugin specific and can be used to modify their @@ -193,17 +193,32 @@ Similar to hotblocks but this time tracks memory accesses:: 0x0000000048b000, 0x0001, 130594, 0x0001, 355 0x0000000048a000, 0x0001, 1826, 0x0001, 11 +The hotpages plugin can be configured using the following arguments: + + * sortby=reads|writes|address + + Log the data sorted by either the number of reads, the number of writes, or + memory address. (Default: entries are sorted by the sum of reads and writes) + + * io=on + + Track IO addresses. Only relevant to full system emulation. (Default: off) + + * pagesize=N + + The page size used. (Default: N = 4096) + - contrib/plugins/howvec.c This is an instruction classifier so can be used to count different types of instructions. It has a number of options to refine which get -counted. You can give an argument for a class of instructions to break -it down fully, so for example to see all the system registers -accesses:: +counted. You can give a value to the `count` argument for a class of +instructions to break it down fully, so for example to see all the system +registers accesses:: ./aarch64-softmmu/qemu-system-aarch64 $(QEMU_ARGS) \ -append "root=/dev/sda2 systemd.unit=benchmark.service" \ - -smp 4 -plugin ./contrib/plugins/libhowvec.so,arg=sreg -d plugin + -smp 4 -plugin ./contrib/plugins/libhowvec.so,count=sreg -d plugin which will lead to a sorted list after the class breakdown:: @@ -271,7 +286,7 @@ communicate over:: ./sparc-softmmu/qemu-system-sparc -monitor none -parallel none \ -net none -M SS-20 -m 256 -kernel day11/zImage.elf \ - -plugin ./contrib/plugins/liblockstep.so,arg=lockstep-sparc.sock \ + -plugin ./contrib/plugins/liblockstep.so,sockpath=lockstep-sparc.sock \ -d plugin,nochain which will eventually report:: @@ -286,27 +301,27 @@ which will eventually report:: previously @ 0x000000ffd08098/5 (809900593 insns) previously @ 0x000000ffd080c0/1 (809900588 insns) -- contrib/plugins/hwprofile +- contrib/plugins/hwprofile.c The hwprofile tool can only be used with system emulation and allows the user to see what hardware is accessed how often. It has a number of options: - * arg=read or arg=write + * track=read or track=write By default the plugin tracks both reads and writes. You can use one of these options to limit the tracking to just one class of accesses. - * arg=source + * source Will include a detailed break down of what the guest PC that made the - access was. Not compatible with arg=pattern. Example output:: + access was. Not compatible with the pattern option. Example output:: cirrus-low-memory @ 0xfffffd00000a0000 pc:fffffc0000005cdc, 1, 256 pc:fffffc0000005ce8, 1, 256 pc:fffffc0000005cec, 1, 256 - * arg=pattern + * pattern Instead break down the accesses based on the offset into the HW region. This can be useful for seeing the most used registers of a @@ -345,7 +360,7 @@ which will output an execution trace following this structure:: 0, 0xd34, 0xf9c8f000, "bl #0x10c8" 0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM -- contrib/plugins/cache +- contrib/plugins/cache.c Cache modelling plugin that measures the performance of a given cache configuration when a given working set is run:: @@ -355,11 +370,8 @@ configuration when a given working set is run:: will report the following:: - Data accesses: 996479, Misses: 507 - Miss rate: 0.050879% - - Instruction accesses: 2641737, Misses: 18617 - Miss rate: 0.704726% + core #, data accesses, data misses, dmiss rate, insn accesses, insn misses, imiss rate + 0 996695 508 0.0510% 2642799 18617 0.7044% address, data misses, instruction 0x424f1e (_int_malloc), 109, movq %rax, 8(%rcx) @@ -377,29 +389,35 @@ will report the following:: The plugin has a number of arguments, all of them are optional: - * arg="limit=N" + * limit=N Print top N icache and dcache thrashing instructions along with their address, number of misses, and its disassembly. (default: 32) - * arg="icachesize=N" - * arg="iblksize=B" - * arg="iassoc=A" + * icachesize=N + * iblksize=B + * iassoc=A Instruction cache configuration arguments. They specify the cache size, block size, and associativity of the instruction cache, respectively. (default: N = 16384, B = 64, A = 8) - * arg="dcachesize=N" - * arg="dblksize=B" - * arg="dassoc=A" + * dcachesize=N + * dblksize=B + * dassoc=A Data cache configuration arguments. They specify the cache size, block size, and associativity of the data cache, respectively. (default: N = 16384, B = 64, A = 8) - * arg="evict=POLICY" + * evict=POLICY Sets the eviction policy to POLICY. Available policies are: :code:`lru`, :code:`fifo`, and :code:`rand`. The plugin will use the specified policy for both instruction and data caches. (default: POLICY = :code:`lru`) + + * cores=N + + Sets the number of cores for which we maintain separate icache and dcache. + (default: for linux-user, N = 1, for full system emulation: N = cores + available to guest) |