From b38a04f71f5bef5cb17c29eada99364b6a017e42 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 9 Jul 2021 15:29:26 +0100 Subject: Jobs based on custom runners: documentation and configuration placeholder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As described in the included documentation, the "custom runner" jobs extend the GitLab CI jobs already in place. One of their primary goals of catching and preventing regressions on a wider number of host systems than the ones provided by GitLab's shared runners. This sets the stage in which other community members can add their own machine configuration documentation/scripts, and accompanying job definitions. As a general rule, those newly added contributed jobs should run as "non-gating", until their reliability is verified (AKA "allow_failure: true"). Signed-off-by: Cleber Rosa Signed-off-by: Alex Bennée Reviewed-by: Alex Bennée Reviewed-by: Thomas Huth Reviewed-by: Willian Rampazzo Reviewed-by: Wainer dos Santos Moschetta Message-Id: <20210630012619.115262-2-crosa@redhat.com> Message-Id: <20210709143005.1554-2-alex.bennee@linaro.org> --- docs/devel/ci.rst | 32 ++++++++++++++++++++++++++++++++ docs/devel/index.rst | 1 + 2 files changed, 33 insertions(+) create mode 100644 docs/devel/ci.rst (limited to 'docs') diff --git a/docs/devel/ci.rst b/docs/devel/ci.rst new file mode 100644 index 0000000..064ffa9 --- /dev/null +++ b/docs/devel/ci.rst @@ -0,0 +1,32 @@ +== +CI +== + +QEMU has configurations enabled for a number of different CI services. +The most up to date information about them and their status can be +found at:: + + https://wiki.qemu.org/Testing/CI + +Jobs on Custom Runners +====================== + +Besides the jobs run under the various CI systems listed before, there +are a number additional jobs that will run before an actual merge. +These use the same GitLab CI's service/framework already used for all +other GitLab based CI jobs, but rely on additional systems, not the +ones provided by GitLab as "shared runners". + +The architecture of GitLab's CI service allows different machines to +be set up with GitLab's "agent", called gitlab-runner, which will take +care of running jobs created by events such as a push to a branch. +Here, the combination of a machine, properly configured with GitLab's +gitlab-runner, is called a "custom runner". + +The GitLab CI jobs definition for the custom runners are located under:: + + .gitlab-ci.d/custom-runners.yml + +Custom runners entail custom machines. To see a list of the machines +currently deployed in the QEMU GitLab CI and their maintainers, please +refer to the QEMU `wiki `__. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index ba90bad..40a7e2e 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -27,6 +27,7 @@ Contents: migration atomics stable-process + ci qtest decodetree secure-coding-practices -- cgit v1.1 From 159c5d177bf6f0caf1efb85b850b200ac7043c49 Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 9 Jul 2021 15:29:27 +0100 Subject: Jobs based on custom runners: build environment docs and playbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit To run basic jobs on custom runners, the environment needs to be properly set up. The most common requirement is having the right packages installed. The playbook introduced here covers the QEMU's project s390x and aarch64 machines. At the time this is being proposed, those machines have already had this playbook applied to them. Signed-off-by: Cleber Rosa Signed-off-by: Alex Bennée Tested-by: Alex Bennée Tested-by: Willian Rampazzo Reviewed-by: Wainer dos Santos Moschetta Reviewed-by: Willian Rampazzo Reviewed-by: Alex Bennée Message-Id: <20210630012619.115262-3-crosa@redhat.com> Message-Id: <20210709143005.1554-3-alex.bennee@linaro.org> --- docs/devel/ci.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'docs') diff --git a/docs/devel/ci.rst b/docs/devel/ci.rst index 064ffa9..bfedbb1 100644 --- a/docs/devel/ci.rst +++ b/docs/devel/ci.rst @@ -30,3 +30,43 @@ The GitLab CI jobs definition for the custom runners are located under:: Custom runners entail custom machines. To see a list of the machines currently deployed in the QEMU GitLab CI and their maintainers, please refer to the QEMU `wiki `__. + +Machine Setup Howto +------------------- + +For all Linux based systems, the setup can be mostly automated by the +execution of two Ansible playbooks. Create an ``inventory`` file +under ``scripts/ci/setup``, such as this:: + + fully.qualified.domain + other.machine.hostname + +You may need to set some variables in the inventory file itself. One +very common need is to tell Ansible to use a Python 3 interpreter on +those hosts. This would look like:: + + fully.qualified.domain ansible_python_interpreter=/usr/bin/python3 + other.machine.hostname ansible_python_interpreter=/usr/bin/python3 + +Build environment +~~~~~~~~~~~~~~~~~ + +The ``scripts/ci/setup/build-environment.yml`` Ansible playbook will +set up machines with the environment needed to perform builds and run +QEMU tests. This playbook consists on the installation of various +required packages (and a general package update while at it). It +currently covers a number of different Linux distributions, but it can +be expanded to cover other systems. + +The minimum required version of Ansible successfully tested in this +playbook is 2.8.0 (a version check is embedded within the playbook +itself). To run the playbook, execute:: + + cd scripts/ci/setup + ansible-playbook -i inventory build-environment.yml + +Please note that most of the tasks in the playbook require superuser +privileges, such as those from the ``root`` account or those obtained +by ``sudo``. If necessary, please refer to ``ansible-playbook`` +options such as ``--become``, ``--become-method``, ``--become-user`` +and ``--ask-become-pass``. -- cgit v1.1 From 40de78c284b14a54fbdde78d588ddb6d766f2a5f Mon Sep 17 00:00:00 2001 From: Cleber Rosa Date: Fri, 9 Jul 2021 15:29:28 +0100 Subject: Jobs based on custom runners: docs and gitlab-runner setup playbook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit To have the jobs dispatched to custom runners, gitlab-runner must be installed, active as a service and properly configured. The variables file and playbook introduced here should help with those steps. The playbook introduced here covers the Linux distributions and has been primarily tested on OS/machines that the QEMU project has available to act as runners, namely: * Ubuntu 20.04 on aarch64 * Ubuntu 18.04 on s390x But, it should work on all other Linux distributions. Earlier versions were tested on FreeBSD too, so chances of success are high. Signed-off-by: Cleber Rosa Signed-off-by: Alex Bennée Tested-by: Willian Rampazzo Tested-by: Alex Bennée Reviewed-by: Willian Rampazzo Reviewed-by: Wainer dos Santos Moschetta Reviewed-by: Alex Bennée Message-Id: <20210630012619.115262-4-crosa@redhat.com> Message-Id: <20210709143005.1554-4-alex.bennee@linaro.org> --- docs/devel/ci.rst | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'docs') diff --git a/docs/devel/ci.rst b/docs/devel/ci.rst index bfedbb1..b3bf3ef 100644 --- a/docs/devel/ci.rst +++ b/docs/devel/ci.rst @@ -70,3 +70,58 @@ privileges, such as those from the ``root`` account or those obtained by ``sudo``. If necessary, please refer to ``ansible-playbook`` options such as ``--become``, ``--become-method``, ``--become-user`` and ``--ask-become-pass``. + +gitlab-runner setup and registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The gitlab-runner agent needs to be installed on each machine that +will run jobs. The association between a machine and a GitLab project +happens with a registration token. To find the registration token for +your repository/project, navigate on GitLab's web UI to: + + * Settings (the gears-like icon at the bottom of the left hand side + vertical toolbar), then + * CI/CD, then + * Runners, and click on the "Expand" button, then + * Under "Set up a specific Runner manually", look for the value under + "And this registration token:" + +Copy the ``scripts/ci/setup/vars.yml.template`` file to +``scripts/ci/setup/vars.yml``. Then, set the +``gitlab_runner_registration_token`` variable to the value obtained +earlier. + +To run the playbook, execute:: + + cd scripts/ci/setup + ansible-playbook -i inventory gitlab-runner.yml + +Following the registration, it's necessary to configure the runner tags, +and optionally other configurations on the GitLab UI. Navigate to: + + * Settings (the gears like icon), then + * CI/CD, then + * Runners, and click on the "Expand" button, then + * "Runners activated for this project", then + * Click on the "Edit" icon (next to the "Lock" Icon) + +Tags are very important as they are used to route specific jobs to +specific types of runners, so it's a good idea to double check that +the automatically created tags are consistent with the OS and +architecture. For instance, an Ubuntu 20.04 aarch64 system should +have tags set as:: + + ubuntu_20.04,aarch64 + +Because the job definition at ``.gitlab-ci.d/custom-runners.yml`` +would contain:: + + ubuntu-20.04-aarch64-all: + tags: + - ubuntu_20.04 + - aarch64 + +It's also recommended to: + + * increase the "Maximum job timeout" to something like ``2h`` + * give it a better Description -- cgit v1.1 From 51f5c849c1036203f5979ea40f61c08f3897908e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Date: Fri, 9 Jul 2021 15:29:34 +0100 Subject: hw/usb/ccid: remove references to NSS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The NSS package was previously pre-requisite for building CCID related features, however, this became obsolete when the libcacard library was spun off to a separate project: commit 7b02f5447c64d1854468f758398c9f6fe9e5721f Author: Marc-André Lureau Date: Sun Aug 30 11:48:40 2015 +0200 libcacard: use the standalone project Signed-off-by: Daniel P. Berrangé Signed-off-by: Alex Bennée Reviewed-by: Wainer dos Santos Moschetta Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Willian Rampazzo Reviewed-by: Alex Bennée Message-Id: <20210623142245.307776-2-berrange@redhat.com> Message-Id: <20210709143005.1554-10-alex.bennee@linaro.org> --- docs/ccid.txt | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/ccid.txt b/docs/ccid.txt index c97fbd2..2b85b1b 100644 --- a/docs/ccid.txt +++ b/docs/ccid.txt @@ -34,15 +34,14 @@ reader and smart card (i.e. not backed by a physical device) using this device. 2. Building -The cryptographic functions and access to the physical card is done via NSS. - -Installing NSS: +The cryptographic functions and access to the physical card is done via the +libcacard library, whose development package must be installed prior to +building QEMU: In redhat/fedora: - yum install nss-devel -In ubuntu/debian: - apt-get install libnss3-dev - (not tested on ubuntu) + yum install libcacard-devel +In ubuntu: + apt-get install libcacard-dev Configuring and building: ./configure --enable-smartcard && make @@ -51,7 +50,7 @@ Configuring and building: 3. Using ccid-card-emulated with hardware Assuming you have a working smartcard on the host with the current -user, using NSS, qemu acts as another NSS client using ccid-card-emulated: +user, using libcacard, QEMU acts as another client using ccid-card-emulated: qemu -usb -device usb-ccid -device ccid-card-emulated -- cgit v1.1 From ba4dd2aabc35bc5385739e13f14e3a10a223ede0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 9 Jul 2021 15:29:57 +0100 Subject: tcg/plugins: enable by default for most TCG builds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Thomas Huth Reviewed-by: Richard Henderson Cc: Paolo Bonzini Message-Id: <20210709143005.1554-33-alex.bennee@linaro.org> --- docs/devel/tcg-plugins.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 18c6581..0cd77c7 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -71,7 +71,8 @@ API Usage ===== -The QEMU binary needs to be compiled for plugin support:: +Any QEMU binary with TCG support has plugins enabled by default. +Earlier releases needed to be explicitly enabled with:: configure --enable-plugins -- cgit v1.1 From 307ce0aaeb5799d05f63b76a91135466f6b15302 Mon Sep 17 00:00:00 2001 From: Alexandre Iooss Date: Fri, 9 Jul 2021 15:30:00 +0100 Subject: docs/devel: tcg-plugins: add execlog plugin description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This adds description of the execlog TCG plugin with an example. Signed-off-by: Alexandre Iooss Signed-off-by: Alex Bennée Message-Id: <20210702081307.1653644-3-erdnaxe@crans.org> Message-Id: <20210709143005.1554-36-alex.bennee@linaro.org> --- docs/devel/tcg-plugins.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs') diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 0cd77c7..179867e 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -320,3 +320,27 @@ the user to see what hardware is accessed how often. It has a number of options: off:0000001c, 1, 2 off:00000020, 1, 2 ... + +- contrib/plugins/execlog.c + +The execlog tool traces executed instructions with memory access. It can be used +for debugging and security analysis purposes. +Please be aware that this will generate a lot of output. + +The plugin takes no argument:: + + qemu-system-arm $(QEMU_ARGS) \ + -plugin ./contrib/plugins/libexeclog.so -d plugin + +which will output an execution trace following this structure:: + + # vCPU, vAddr, opcode, disassembly[, load/store, memory addr, device]... + 0, 0xa12, 0xf8012400, "movs r4, #0" + 0, 0xa14, 0xf87f42b4, "cmp r4, r6" + 0, 0xa16, 0xd206, "bhs #0xa26" + 0, 0xa18, 0xfff94803, "ldr r0, [pc, #0xc]", load, 0x00010a28, RAM + 0, 0xa1a, 0xf989f000, "bl #0xd30" + 0, 0xd30, 0xfff9b510, "push {r4, lr}", store, 0x20003ee0, RAM, store, 0x20003ee4, RAM + 0, 0xd32, 0xf9893014, "adds r0, #0x14" + 0, 0xd34, 0xf9c8f000, "bl #0x10c8" + 0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM -- cgit v1.1 From 4c125f3b7591758ebd96c3ac3ff469480b7aaea2 Mon Sep 17 00:00:00 2001 From: Mahmoud Mandour Date: Fri, 9 Jul 2021 15:30:04 +0100 Subject: docs/devel: Added cache plugin to the plugins docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mahmoud Mandour Signed-off-by: Alex Bennée Message-Id: <20210628053808.17422-1-ma.mandourr@gmail.com> Message-Id: <20210709143005.1554-40-alex.bennee@linaro.org> --- docs/devel/tcg-plugins.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'docs') diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst index 179867e..7e54f12 100644 --- a/docs/devel/tcg-plugins.rst +++ b/docs/devel/tcg-plugins.rst @@ -344,3 +344,62 @@ which will output an execution trace following this structure:: 0, 0xd32, 0xf9893014, "adds r0, #0x14" 0, 0xd34, 0xf9c8f000, "bl #0x10c8" 0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM + +- contrib/plugins/cache + +Cache modelling plugin that measures the performance of a given cache +configuration when a given working set is run:: + + qemu-x86_64 -plugin ./contrib/plugins/libcache.so \ + -d plugin -D cache.log ./tests/tcg/x86_64-linux-user/float_convs + +will report the following:: + + Data accesses: 996479, Misses: 507 + Miss rate: 0.050879% + + Instruction accesses: 2641737, Misses: 18617 + Miss rate: 0.704726% + + address, data misses, instruction + 0x424f1e (_int_malloc), 109, movq %rax, 8(%rcx) + 0x41f395 (_IO_default_xsputn), 49, movb %dl, (%rdi, %rax) + 0x42584d (ptmalloc_init.part.0), 33, movaps %xmm0, (%rax) + 0x454d48 (__tunables_init), 20, cmpb $0, (%r8) + ... + + address, fetch misses, instruction + 0x4160a0 (__vfprintf_internal), 744, movl $1, %ebx + 0x41f0a0 (_IO_setb), 744, endbr64 + 0x415882 (__vfprintf_internal), 744, movq %r12, %rdi + 0x4268a0 (__malloc), 696, andq $0xfffffffffffffff0, %rax + ... + +The plugin has a number of arguments, all of them are optional: + + * arg="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" + + 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" + + 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" + + 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`) -- cgit v1.1