From 49e8565b3df3f43aae57a3850e1b4cd176ef6582 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 22 Feb 2021 10:14:50 +0000 Subject: meson.build: expose TCG cross compiler information in summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Blink and you miss the cross TCG compiler stuff so lets display it with the rest of the compiler information. Signed-off-by: Alex Bennée Tested-by: Philippe Mathieu-Daudé Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Richard Henderson Acked-by: Paolo Bonzini Message-Id: <20210222101455.12640-2-alex.bennee@linaro.org> --- meson.build | 18 ++++++++++++++++++ tests/tcg/configure.sh | 8 -------- 2 files changed, 18 insertions(+), 8 deletions(-) diff --git a/meson.build b/meson.build index 05a67c2..f3db83e 100644 --- a/meson.build +++ b/meson.build @@ -2509,6 +2509,24 @@ endif summary_info += {'strip binaries': get_option('strip')} summary_info += {'sparse': sparse.found() ? sparse.full_path() : false} summary_info += {'mingw32 support': targetos == 'windows'} + +# snarf the cross-compilation information for tests +foreach target: target_dirs + tcg_mak = meson.current_build_dir() / 'tests/tcg' / 'config-' + target + '.mak' + if fs.exists(tcg_mak) + config_cross_tcg = keyval.load(tcg_mak) + target = config_cross_tcg['TARGET_NAME'] + compiler = '' + if 'DOCKER_CROSS_CC_GUEST' in config_cross_tcg + summary_info += {target + ' tests': config_cross_tcg['DOCKER_CROSS_CC_GUEST'] + + ' via ' + config_cross_tcg['DOCKER_IMAGE']} + elif 'CROSS_CC_GUEST' in config_cross_tcg + summary_info += {target + ' tests' + : config_cross_tcg['CROSS_CC_GUEST'] } + endif + endif +endforeach + summary(summary_info, bool_yn: true, section: 'Compilation') # Targets and accelerators diff --git a/tests/tcg/configure.sh b/tests/tcg/configure.sh index 551c02f..36b8a73 100755 --- a/tests/tcg/configure.sh +++ b/tests/tcg/configure.sh @@ -263,11 +263,3 @@ for target in $target_list; do echo "DOCKER_CROSS_CC_GUEST=$container_cross_cc" >> $config_target_mak fi done - -# report container support state -echo "cross containers $container" - -if test -n "$enabled_cross_compilers"; then - echo - echo "NOTE: guest cross-compilers enabled:$enabled_cross_compilers" -fi -- cgit v1.1 From 9d66a0eada1cf558cc7fabe1e86131ea68ea7192 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Mon, 22 Feb 2021 10:14:51 +0000 Subject: docker: Bump Fedora images to release 33 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fedora 33 was released on October 27, 2020. Update all the Fedora 32 images to this new release. Suggested-by: Daniel Berrangé Signed-off-by: Philippe Mathieu-Daudé Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Message-Id: <20210118181255.314672-1-philmd@redhat.com> Message-Id: <20210222101455.12640-3-alex.bennee@linaro.org> --- tests/docker/dockerfiles/fedora-cris-cross.docker | 2 +- tests/docker/dockerfiles/fedora-i386-cross.docker | 2 +- tests/docker/dockerfiles/fedora-win32-cross.docker | 2 +- tests/docker/dockerfiles/fedora-win64-cross.docker | 2 +- tests/docker/dockerfiles/fedora.docker | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/docker/dockerfiles/fedora-cris-cross.docker b/tests/docker/dockerfiles/fedora-cris-cross.docker index 09e7e44..1dfff6e 100644 --- a/tests/docker/dockerfiles/fedora-cris-cross.docker +++ b/tests/docker/dockerfiles/fedora-cris-cross.docker @@ -2,7 +2,7 @@ # Cross compiler for cris system tests # -FROM fedora:30 +FROM fedora:33 ENV PACKAGES gcc-cris-linux-gnu RUN dnf install -y $PACKAGES RUN rpm -q $PACKAGES | sort > /packages.txt diff --git a/tests/docker/dockerfiles/fedora-i386-cross.docker b/tests/docker/dockerfiles/fedora-i386-cross.docker index a6e4112..966072c 100644 --- a/tests/docker/dockerfiles/fedora-i386-cross.docker +++ b/tests/docker/dockerfiles/fedora-i386-cross.docker @@ -1,4 +1,4 @@ -FROM fedora:31 +FROM fedora:33 ENV PACKAGES \ bzip2 \ diffutils \ diff --git a/tests/docker/dockerfiles/fedora-win32-cross.docker b/tests/docker/dockerfiles/fedora-win32-cross.docker index 087df59..81b5659 100644 --- a/tests/docker/dockerfiles/fedora-win32-cross.docker +++ b/tests/docker/dockerfiles/fedora-win32-cross.docker @@ -1,4 +1,4 @@ -FROM fedora:32 +FROM fedora:33 # Please keep this list sorted alphabetically ENV PACKAGES \ diff --git a/tests/docker/dockerfiles/fedora-win64-cross.docker b/tests/docker/dockerfiles/fedora-win64-cross.docker index d5d2f5f..bcb428e 100644 --- a/tests/docker/dockerfiles/fedora-win64-cross.docker +++ b/tests/docker/dockerfiles/fedora-win64-cross.docker @@ -1,4 +1,4 @@ -FROM fedora:32 +FROM fedora:33 # Please keep this list sorted alphabetically ENV PACKAGES \ diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfiles/fedora.docker index 0d7602a..915fdc1 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -1,4 +1,4 @@ -FROM fedora:32 +FROM fedora:33 # Please keep this list sorted alphabetically ENV PACKAGES \ -- cgit v1.1 From d98946450d82d2b46c3cc93e22cee2b189f019b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 22 Feb 2021 10:14:52 +0000 Subject: tests/acceptance: allow a "graceful" failing for virtio-gpu test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is a band-aid with a TODO for cases when QEMU doesn't start due to missing VirGL. Longer term we could do with some proper feature probing. Signed-off-by: Alex Bennée Reviewed-by: Marc-André Lureau Reviewed-by: Willian Rampazzo Reviewed-by: Richard Henderson Message-Id: <20210222101455.12640-4-alex.bennee@linaro.org> --- tests/acceptance/virtio-gpu.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tests/acceptance/virtio-gpu.py b/tests/acceptance/virtio-gpu.py index ab1a4c1..ab18cdd 100644 --- a/tests/acceptance/virtio-gpu.py +++ b/tests/acceptance/virtio-gpu.py @@ -85,7 +85,12 @@ class VirtioGPUx86(Test): "-append", kernel_command_line, ) - self.vm.launch() + try: + self.vm.launch() + except: + # TODO: probably fails because we are missing the VirGL features + self.cancel("VirGL not enabled?") + self.wait_for_console_pattern("as init process") exec_command_and_wait_for_pattern( self, "/usr/sbin/modprobe virtio_gpu", "" -- cgit v1.1 From 663a041e1dff50eaa66c8d2b01ade1ac8cd65619 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 22 Feb 2021 10:14:53 +0000 Subject: docs/devel: expand on use of containers to build tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expand on the usage of containers for building tests and why we have some that are not used to build QEMU itself. Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Reviewed-by: Thomas Huth Cc: Thomas Huth Message-Id: <20210222101455.12640-5-alex.bennee@linaro.org> --- docs/devel/testing.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 00ce16d..488d4e3 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -272,10 +272,10 @@ Note that the following group names have a special meaning: - disabled: Tests in this group are disabled and ignored by check. -.. _docker-ref: +.. _container-ref: -Docker based tests -================== +Container based tests +===================== Introduction ------------ @@ -1001,10 +1001,17 @@ for the architecture in question, for example:: There is also a ``--cross-cc-flags-ARCH`` flag in case additional compiler flags are needed to build for a given target. -If you have the ability to run containers as the user you can also -take advantage of the build systems "Docker" support. It will then use -containers to build any test case for an enabled guest where there is -no system compiler available. See :ref:`docker-ref` for details. +If you have the ability to run containers as the user the build system +will automatically use them where no system compiler is available. For +architectures where we also support building QEMU we will generally +use the same container to build tests. However there are a number of +additional containers defined that have a minimal cross-build +environment that is only suitable for building test cases. Sometimes +we may use a bleeding edge distribution for compiler features needed +for test cases that aren't yet in the LTS distros we support for QEMU +itself. + +See :ref:`container-ref` for more details. Running subset of tests ----------------------- -- cgit v1.1 From 9c1f491e02a64882201d20fa8324884baee91fd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 22 Feb 2021 10:14:54 +0000 Subject: docs/devel: update the container based tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This section has grown a little stale so clean-up the language and examples for current usage: - refer to containers at the top - mention podman can also be used - add podman prerequisites section - move to using "docker-help" for online help - mention the registry and it's purpose - don't refer to out-of-date min-glib image Signed-off-by: Alex Bennée Reviewed-by: Richard Henderson Reviewed-by: Thomas Huth Message-Id: <20210222101455.12640-6-alex.bennee@linaro.org> --- docs/devel/testing.rst | 61 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 488d4e3..e572604 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -280,13 +280,17 @@ Container based tests Introduction ------------ -The Docker testing framework in QEMU utilizes public Docker images to build and -test QEMU in predefined and widely accessible Linux environments. This makes -it possible to expand the test coverage across distros, toolchain flavors and -library versions. - -Prerequisites -------------- +The container testing framework in QEMU utilizes public images to +build and test QEMU in predefined and widely accessible Linux +environments. This makes it possible to expand the test coverage +across distros, toolchain flavors and library versions. The support +was originally written for Docker although we also support Podman as +an alternative container runtime. Although the many of the target +names and scripts are prefixed with "docker" the system will +automatically run on whichever is configured. + +Docker Prerequisites +-------------------- Install "docker" with the system package manager and start the Docker service on your development machine, then make sure you have the privilege to run @@ -316,26 +320,53 @@ Note that any one of above configurations makes it possible for the user to exploit the whole host with Docker bind mounting or other privileged operations. So only do it on development machines. +Podman Prerequisites +-------------------- + +Install "podman" with the system package manager. + +.. code:: + + $ sudo dnf install podman + $ podman ps + +The last command should print an empty table, to verify the system is ready. + Quickstart ---------- -From source tree, type ``make docker`` to see the help. Testing can be started -without configuring or building QEMU (``configure`` and ``make`` are done in -the container, with parameters defined by the make target): +From source tree, type ``make docker-help`` to see the help. Testing +can be started without configuring or building QEMU (``configure`` and +``make`` are done in the container, with parameters defined by the +make target): .. code:: - make docker-test-build@min-glib + make docker-test-build@centos8 -This will create a container instance using the ``min-glib`` image (the image +This will create a container instance using the ``centos8`` image (the image is downloaded and initialized automatically), in which the ``test-build`` job is executed. +Registry +-------- + +The QEMU project has a container registry hosted by GitLab at +``registry.gitlab.com/qemu-project/qemu`` which will automatically be +used to pull in pre-built layers. This avoids unnecessary strain on +the distro archives created by multiple developers running the same +container build steps over and over again. This can be overridden +locally by using the ``NOCACHE`` build option: + +.. code:: + + make docker-image-debian10 NOCACHE=1 + Images ------ -Along with many other images, the ``min-glib`` image is defined in a Dockerfile -in ``tests/docker/dockerfiles/``, called ``min-glib.docker``. ``make docker`` +Along with many other images, the ``centos8`` image is defined in a Dockerfile +in ``tests/docker/dockerfiles/``, called ``centos8.docker``. ``make docker-help`` command will list all the available images. To add a new image, simply create a new ``.docker`` file under the @@ -355,7 +386,7 @@ QEMU. Docker tests are the executables under ``tests/docker`` named library, ``tests/docker/common.rc``, which provides helpers to find the QEMU source and build it. -The full list of tests is printed in the ``make docker`` help. +The full list of tests is printed in the ``make docker-help`` help. Debugging a Docker test failure ------------------------------- -- cgit v1.1 From 4583cdadf807c272fe01501b414c570a527e6f41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 22 Feb 2021 10:14:55 +0000 Subject: docs/devel: add forward reference to check-tcg MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For completeness reference the check-tcg tests in the container preamble text. Signed-off-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Richard Henderson Reviewed-by: Thomas Huth Cc: Thomas Huth Message-Id: <20210222101455.12640-7-alex.bennee@linaro.org> --- docs/devel/testing.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index e572604..1434a50 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -289,6 +289,9 @@ an alternative container runtime. Although the many of the target names and scripts are prefixed with "docker" the system will automatically run on whichever is configured. +The container images are also used to augment the generation of tests +for testing TCG. See :ref:`checktcg-ref` for more details. + Docker Prerequisites -------------------- @@ -1011,6 +1014,8 @@ And remove any package you want with:: If you've used ``make check-acceptance``, the Python virtual environment where Avocado is installed will be cleaned up as part of ``make check-clean``. +.. _checktcg-ref: + Testing with "make check-tcg" ============================= -- cgit v1.1 From 93a11007681a8051c07834c52d785a2948ff9632 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Tue, 23 Feb 2021 09:59:31 +0000 Subject: docs: move CODING_STYLE into the developer documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There is no particular reason to keep this on it's own in the root of the tree. Move it into the rest of the fine developer manual and fixup any links to it. The only tweak I've made is to fix the code-block annotations to mention the language C. Signed-off-by: Alex Bennée Reviewed-by: Claudio Fontana Message-Id: <20210223095931.16908-1-alex.bennee@linaro.org> --- CODING_STYLE.rst | 679 -------------------------------------- README.rst | 4 +- docs/devel/index.rst | 1 + docs/devel/style.rst | 679 ++++++++++++++++++++++++++++++++++++++ scripts/fix-multiline-comments.sh | 2 +- 5 files changed, 684 insertions(+), 681 deletions(-) delete mode 100644 CODING_STYLE.rst create mode 100644 docs/devel/style.rst diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst deleted file mode 100644 index 7bf4e39..0000000 --- a/CODING_STYLE.rst +++ /dev/null @@ -1,679 +0,0 @@ -================= -QEMU Coding Style -================= - -.. contents:: Table of Contents - -Please use the script checkpatch.pl in the scripts directory to check -patches before submitting. - -Formatting and style -******************** - -Whitespace -========== - -Of course, the most important aspect in any coding style is whitespace. -Crusty old coders who have trouble spotting the glasses on their noses -can tell the difference between a tab and eight spaces from a distance -of approximately fifteen parsecs. Many a flamewar has been fought and -lost on this issue. - -QEMU indents are four spaces. Tabs are never used, except in Makefiles -where they have been irreversibly coded into the syntax. -Spaces of course are superior to tabs because: - -* You have just one way to specify whitespace, not two. Ambiguity breeds - mistakes. -* The confusion surrounding 'use tabs to indent, spaces to justify' is gone. -* Tab indents push your code to the right, making your screen seriously - unbalanced. -* Tabs will be rendered incorrectly on editors who are misconfigured not - to use tab stops of eight positions. -* Tabs are rendered badly in patches, causing off-by-one errors in almost - every line. -* It is the QEMU coding style. - -Do not leave whitespace dangling off the ends of lines. - -Multiline Indent ----------------- - -There are several places where indent is necessary: - -* if/else -* while/for -* function definition & call - -When breaking up a long line to fit within line width, we need a proper indent -for the following lines. - -In case of if/else, while/for, align the secondary lines just after the -opening parenthesis of the first. - -For example: - -.. code-block:: c - - if (a == 1 && - b == 2) { - - while (a == 1 && - b == 2) { - -In case of function, there are several variants: - -* 4 spaces indent from the beginning -* align the secondary lines just after the opening parenthesis of the first - -For example: - -.. code-block:: c - - do_something(x, y, - z); - - do_something(x, y, - z); - - do_something(x, do_another(y, - z)); - -Line width -========== - -Lines should be 80 characters; try not to make them longer. - -Sometimes it is hard to do, especially when dealing with QEMU subsystems -that use long function or symbol names. If wrapping the line at 80 columns -is obviously less readable and more awkward, prefer not to wrap it; better -to have an 85 character line than one which is awkwardly wrapped. - -Even in that case, try not to make lines much longer than 80 characters. -(The checkpatch script will warn at 100 characters, but this is intended -as a guard against obviously-overlength lines, not a target.) - -Rationale: - -* Some people like to tile their 24" screens with a 6x4 matrix of 80x24 - xterms and use vi in all of them. The best way to punish them is to - let them keep doing it. -* Code and especially patches is much more readable if limited to a sane - line length. Eighty is traditional. -* The four-space indentation makes the most common excuse ("But look - at all that white space on the left!") moot. -* It is the QEMU coding style. - -Naming -====== - -Variables are lower_case_with_underscores; easy to type and read. Structured -type names are in CamelCase; harder to type but standing out. Enum type -names and function type names should also be in CamelCase. Scalar type -names are lower_case_with_underscores_ending_with_a_t, like the POSIX -uint64_t and family. Note that this last convention contradicts POSIX -and is therefore likely to be changed. - -Variable Naming Conventions ---------------------------- - -A number of short naming conventions exist for variables that use -common QEMU types. For example, the architecture independent CPUState -is often held as a ``cs`` pointer variable, whereas the concrete -CPUArchState is usually held in a pointer called ``env``. - -Likewise, in device emulation code the common DeviceState is usually -called ``dev``. - -Function Naming Conventions ---------------------------- - -Wrapped version of standard library or GLib functions use a ``qemu_`` -prefix to alert readers that they are seeing a wrapped version, for -example ``qemu_strtol`` or ``qemu_mutex_lock``. Other utility functions -that are widely called from across the codebase should not have any -prefix, for example ``pstrcpy`` or bit manipulation functions such as -``find_first_bit``. - -The ``qemu_`` prefix is also used for functions that modify global -emulator state, for example ``qemu_add_vm_change_state_handler``. -However, if there is an obvious subsystem-specific prefix it should be -used instead. - -Public functions from a file or subsystem (declared in headers) tend -to have a consistent prefix to show where they came from. For example, -``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions -from cpus.c. - -If there are two versions of a function to be called with or without a -lock held, the function that expects the lock to be already held -usually uses the suffix ``_locked``. - - -Block structure -=============== - -Every indented statement is braced; even if the block contains just one -statement. The opening brace is on the line that contains the control -flow statement that introduces the new block; the closing brace is on the -same line as the else keyword, or on a line by itself if there is no else -keyword. Example: - -.. code-block:: c - - if (a == 5) { - printf("a was 5.\n"); - } else if (a == 6) { - printf("a was 6.\n"); - } else { - printf("a was something else entirely.\n"); - } - -Note that 'else if' is considered a single statement; otherwise a long if/ -else if/else if/.../else sequence would need an indent for every else -statement. - -An exception is the opening brace for a function; for reasons of tradition -and clarity it comes on a line by itself: - -.. code-block:: c - - void a_function(void) - { - do_something(); - } - -Rationale: a consistent (except for functions...) bracing style reduces -ambiguity and avoids needless churn when lines are added or removed. -Furthermore, it is the QEMU coding style. - -Declarations -============ - -Mixed declarations (interleaving statements and declarations within -blocks) are generally not allowed; declarations should be at the beginning -of blocks. - -Every now and then, an exception is made for declarations inside a -#ifdef or #ifndef block: if the code looks nicer, such declarations can -be placed at the top of the block even if there are statements above. -On the other hand, however, it's often best to move that #ifdef/#ifndef -block to a separate function altogether. - -Conditional statements -====================== - -When comparing a variable for (in)equality with a constant, list the -constant on the right, as in: - -.. code-block:: c - - if (a == 1) { - /* Reads like: "If a equals 1" */ - do_something(); - } - -Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read. -Besides, good compilers already warn users when '==' is mis-typed as '=', -even when the constant is on the right. - -Comment style -============= - -We use traditional C-style /``*`` ``*``/ comments and avoid // comments. - -Rationale: The // form is valid in C99, so this is purely a matter of -consistency of style. The checkpatch script will warn you about this. - -Multiline comment blocks should have a row of stars on the left, -and the initial /``*`` and terminating ``*``/ both on their own lines: - -.. code-block:: c - - /* - * like - * this - */ - -This is the same format required by the Linux kernel coding style. - -(Some of the existing comments in the codebase use the GNU Coding -Standards form which does not have stars on the left, or other -variations; avoid these when writing new comments, but don't worry -about converting to the preferred form unless you're editing that -comment anyway.) - -Rationale: Consistency, and ease of visually picking out a multiline -comment from the surrounding code. - -Language usage -************** - -Preprocessor -============ - -Variadic macros ---------------- - -For variadic macros, stick with this C99-like syntax: - -.. code-block:: c - - #define DPRINTF(fmt, ...) \ - do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) - -Include directives ------------------- - -Order include directives as follows: - -.. code-block:: c - - #include "qemu/osdep.h" /* Always first... */ - #include <...> /* then system headers... */ - #include "..." /* and finally QEMU headers. */ - -The "qemu/osdep.h" header contains preprocessor macros that affect the behavior -of core system headers like . It must be the first include so that -core system headers included by external libraries get the preprocessor macros -that QEMU depends on. - -Do not include "qemu/osdep.h" from header files since the .c file will have -already included it. - -C types -======= - -It should be common sense to use the right type, but we have collected -a few useful guidelines here. - -Scalars -------- - -If you're using "int" or "long", odds are good that there's a better type. -If a variable is counting something, it should be declared with an -unsigned type. - -If it's host memory-size related, size_t should be a good choice (use -ssize_t only if required). Guest RAM memory offsets must use ram_addr_t, -but only for RAM, it may not cover whole guest address space. - -If it's file-size related, use off_t. -If it's file-offset related (i.e., signed), use off_t. -If it's just counting small numbers use "unsigned int"; -(on all but oddball embedded systems, you can assume that that -type is at least four bytes wide). - -In the event that you require a specific width, use a standard type -like int32_t, uint32_t, uint64_t, etc. The specific types are -mandatory for VMState fields. - -Don't use Linux kernel internal types like u32, __u32 or __le32. - -Use hwaddr for guest physical addresses except pcibus_t -for PCI addresses. In addition, ram_addr_t is a QEMU internal address -space that maps guest RAM physical addresses into an intermediate -address space that can map to host virtual address spaces. Generally -speaking, the size of guest memory can always fit into ram_addr_t but -it would not be correct to store an actual guest physical address in a -ram_addr_t. - -For CPU virtual addresses there are several possible types. -vaddr is the best type to use to hold a CPU virtual address in -target-independent code. It is guaranteed to be large enough to hold a -virtual address for any target, and it does not change size from target -to target. It is always unsigned. -target_ulong is a type the size of a virtual address on the CPU; this means -it may be 32 or 64 bits depending on which target is being built. It should -therefore be used only in target-specific code, and in some -performance-critical built-per-target core code such as the TLB code. -There is also a signed version, target_long. -abi_ulong is for the ``*``-user targets, and represents a type the size of -'void ``*``' in that target's ABI. (This may not be the same as the size of a -full CPU virtual address in the case of target ABIs which use 32 bit pointers -on 64 bit CPUs, like sparc32plus.) Definitions of structures that must match -the target's ABI must use this type for anything that on the target is defined -to be an 'unsigned long' or a pointer type. -There is also a signed version, abi_long. - -Of course, take all of the above with a grain of salt. If you're about -to use some system interface that requires a type like size_t, pid_t or -off_t, use matching types for any corresponding variables. - -Also, if you try to use e.g., "unsigned int" as a type, and that -conflicts with the signedness of a related variable, sometimes -it's best just to use the *wrong* type, if "pulling the thread" -and fixing all related variables would be too invasive. - -Finally, while using descriptive types is important, be careful not to -go overboard. If whatever you're doing causes warnings, or requires -casts, then reconsider or ask for help. - -Pointers --------- - -Ensure that all of your pointers are "const-correct". -Unless a pointer is used to modify the pointed-to storage, -give it the "const" attribute. That way, the reader knows -up-front that this is a read-only pointer. Perhaps more -importantly, if we're diligent about this, when you see a non-const -pointer, you're guaranteed that it is used to modify the storage -it points to, or it is aliased to another pointer that is. - -Typedefs --------- - -Typedefs are used to eliminate the redundant 'struct' keyword, since type -names have a different style than other identifiers ("CamelCase" versus -"snake_case"). Each named struct type should have a CamelCase name and a -corresponding typedef. - -Since certain C compilers choke on duplicated typedefs, you should avoid -them and declare a typedef only in one header file. For common types, -you can use "include/qemu/typedefs.h" for example. However, as a matter -of convenience it is also perfectly fine to use forward struct -definitions instead of typedefs in headers and function prototypes; this -avoids problems with duplicated typedefs and reduces the need to include -headers from other headers. - -Reserved namespaces in C and POSIX ----------------------------------- - -Underscore capital, double underscore, and underscore 't' suffixes should be -avoided. - -Low level memory management -=========================== - -Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign -APIs is not allowed in the QEMU codebase. Instead of these routines, -use the GLib memory allocation routines g_malloc/g_malloc0/g_new/ -g_new0/g_realloc/g_free or QEMU's qemu_memalign/qemu_blockalign/qemu_vfree -APIs. - -Please note that g_malloc will exit on allocation failure, so there -is no need to test for failure (as you would have to with malloc). -Calling g_malloc with a zero size is valid and will return NULL. - -Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following -reasons: - -* It catches multiplication overflowing size_t; -* It returns T ``*`` instead of void ``*``, letting compiler catch more type errors. - -Declarations like - -.. code-block:: c - - T *v = g_malloc(sizeof(*v)) - -are acceptable, though. - -Memory allocated by qemu_memalign or qemu_blockalign must be freed with -qemu_vfree, since breaking this will cause problems on Win32. - -String manipulation -=================== - -Do not use the strncpy function. As mentioned in the man page, it does *not* -guarantee a NULL-terminated buffer, which makes it extremely dangerous to use. -It also zeros trailing destination bytes out to the specified length. Instead, -use this similar function when possible, but note its different signature: - -.. code-block:: c - - void pstrcpy(char *dest, int dest_buf_size, const char *src) - -Don't use strcat because it can't check for buffer overflows, but: - -.. code-block:: c - - char *pstrcat(char *buf, int buf_size, const char *s) - -The same limitation exists with sprintf and vsprintf, so use snprintf and -vsnprintf. - -QEMU provides other useful string functions: - -.. code-block:: c - - int strstart(const char *str, const char *val, const char **ptr) - int stristart(const char *str, const char *val, const char **ptr) - int qemu_strnlen(const char *s, int max_len) - -There are also replacement character processing macros for isxyz and toxyz, -so instead of e.g. isalnum you should use qemu_isalnum. - -Because of the memory management rules, you must use g_strdup/g_strndup -instead of plain strdup/strndup. - -Printf-style functions -====================== - -Whenever you add a new printf-style function, i.e., one with a format -string argument and following "..." in its prototype, be sure to use -gcc's printf attribute directive in the prototype. - -This makes it so gcc's -Wformat and -Wformat-security options can do -their jobs and cross-check format strings with the number and types -of arguments. - -C standard, implementation defined and undefined behaviors -========================================================== - -C code in QEMU should be written to the C99 language specification. A copy -of the final version of the C99 standard with corrigenda TC1, TC2, and TC3 -included, formatted as a draft, can be downloaded from: - - ``_ - -The C language specification defines regions of undefined behavior and -implementation defined behavior (to give compiler authors enough leeway to -produce better code). In general, code in QEMU should follow the language -specification and avoid both undefined and implementation defined -constructs. ("It works fine on the gcc I tested it with" is not a valid -argument...) However there are a few areas where we allow ourselves to -assume certain behaviors because in practice all the platforms we care about -behave in the same way and writing strictly conformant code would be -painful. These are: - -* you may assume that integers are 2s complement representation -* you may assume that right shift of a signed integer duplicates - the sign bit (ie it is an arithmetic shift, not a logical shift) - -In addition, QEMU assumes that the compiler does not use the latitude -given in C99 and C11 to treat aspects of signed '<<' as undefined, as -documented in the GNU Compiler Collection manual starting at version 4.0. - -Automatic memory deallocation -============================= - -QEMU has a mandatory dependency either the GCC or CLang compiler. As -such it has the freedom to make use of a C language extension for -automatically running a cleanup function when a stack variable goes -out of scope. This can be used to simplify function cleanup paths, -often allowing many goto jumps to be eliminated, through automatic -free'ing of memory. - -The GLib2 library provides a number of functions/macros for enabling -automatic cleanup: - - ``_ - -Most notably: - -* g_autofree - will invoke g_free() on the variable going out of scope - -* g_autoptr - for structs / objects, will invoke the cleanup func created - by a previous use of G_DEFINE_AUTOPTR_CLEANUP_FUNC. This is - supported for most GLib data types and GObjects - -For example, instead of - -.. code-block:: c - - int somefunc(void) { - int ret = -1; - char *foo = g_strdup_printf("foo%", "wibble"); - GList *bar = ..... - - if (eek) { - goto cleanup; - } - - ret = 0; - - cleanup: - g_free(foo); - g_list_free(bar); - return ret; - } - -Using g_autofree/g_autoptr enables the code to be written as: - -.. code-block:: c - - int somefunc(void) { - g_autofree char *foo = g_strdup_printf("foo%", "wibble"); - g_autoptr (GList) bar = ..... - - if (eek) { - return -1; - } - - return 0; - } - -While this generally results in simpler, less leak-prone code, there -are still some caveats to beware of - -* Variables declared with g_auto* MUST always be initialized, - otherwise the cleanup function will use uninitialized stack memory - -* If a variable declared with g_auto* holds a value which must - live beyond the life of the function, that value must be saved - and the original variable NULL'd out. This can be simpler using - g_steal_pointer - - -.. code-block:: c - - char *somefunc(void) { - g_autofree char *foo = g_strdup_printf("foo%", "wibble"); - g_autoptr (GList) bar = ..... - - if (eek) { - return NULL; - } - - return g_steal_pointer(&foo); - } - - -QEMU Specific Idioms -******************** - -Error handling and reporting -============================ - -Reporting errors to the human user ----------------------------------- - -Do not use printf(), fprintf() or monitor_printf(). Instead, use -error_report() or error_vreport() from error-report.h. This ensures the -error is reported in the right place (current monitor or stderr), and in -a uniform format. - -Use error_printf() & friends to print additional information. - -error_report() prints the current location. In certain common cases -like command line parsing, the current location is tracked -automatically. To manipulate it manually, use the loc_``*``() from -error-report.h. - -Propagating errors ------------------- - -An error can't always be reported to the user right where it's detected, -but often needs to be propagated up the call chain to a place that can -handle it. This can be done in various ways. - -The most flexible one is Error objects. See error.h for usage -information. - -Use the simplest suitable method to communicate success / failure to -callers. Stick to common methods: non-negative on success / -1 on -error, non-negative / -errno, non-null / null, or Error objects. - -Example: when a function returns a non-null pointer on success, and it -can fail only in one way (as far as the caller is concerned), returning -null on failure is just fine, and certainly simpler and a lot easier on -the eyes than propagating an Error object through an Error ``*````*`` parameter. - -Example: when a function's callers need to report details on failure -only the function really knows, use Error ``*````*``, and set suitable errors. - -Do not report an error to the user when you're also returning an error -for somebody else to handle. Leave the reporting to the place that -consumes the error returned. - -Handling errors ---------------- - -Calling exit() is fine when handling configuration errors during -startup. It's problematic during normal operation. In particular, -monitor commands should never exit(). - -Do not call exit() or abort() to handle an error that can be triggered -by the guest (e.g., some unimplemented corner case in guest code -translation or device emulation). Guests should not be able to -terminate QEMU. - -Note that &error_fatal is just another way to exit(1), and &error_abort -is just another way to abort(). - - -trace-events style -================== - -0x prefix ---------- - -In trace-events files, use a '0x' prefix to specify hex numbers, as in: - -.. code-block:: - - some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 - -An exception is made for groups of numbers that are hexadecimal by -convention and separated by the symbols '.', '/', ':', or ' ' (such as -PCI bus id): - -.. code-block:: - - another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" - -However, you can use '0x' for such groups if you want. Anyway, be sure that -it is obvious that numbers are in hex, ex.: - -.. code-block:: - - data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" - -Rationale: hex numbers are hard to read in logs when there is no 0x prefix, -especially when (occasionally) the representation doesn't contain any letters -and especially in one line with other decimal numbers. Number groups are allowed -to not use '0x' because for some things notations like %x.%x.%x are used not -only in Qemu. Also dumping raw data bytes with '0x' is less readable. - -'#' printf flag ---------------- - -Do not use printf flag '#', like '%#x'. - -Rationale: there are two ways to add a '0x' prefix to printed number: '0x%...' -and '%#...'. For consistency the only one way should be used. Arguments for -'0x%' are: - -* it is more popular -* '%#' omits the 0x for the value 0 which makes output inconsistent diff --git a/README.rst b/README.rst index ce39d89..91aa1e3 100644 --- a/README.rst +++ b/README.rst @@ -66,7 +66,9 @@ When submitting patches, one common approach is to use 'git format-patch' and/or 'git send-email' to format & send the mail to the qemu-devel@nongnu.org mailing list. All patches submitted must contain a 'Signed-off-by' line from the author. Patches should follow the -guidelines set out in the CODING_STYLE.rst file. +guidelines set out in the `style section +` of +the Developers Guide. Additional information on submitting patches can be found online via the QEMU website diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 22854e3..ae664da 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -14,6 +14,7 @@ Contents: :maxdepth: 2 build-system + style kconfig testing fuzzing diff --git a/docs/devel/style.rst b/docs/devel/style.rst new file mode 100644 index 0000000..8b0bdb3 --- /dev/null +++ b/docs/devel/style.rst @@ -0,0 +1,679 @@ +================= +QEMU Coding Style +================= + +.. contents:: Table of Contents + +Please use the script checkpatch.pl in the scripts directory to check +patches before submitting. + +Formatting and style +******************** + +Whitespace +========== + +Of course, the most important aspect in any coding style is whitespace. +Crusty old coders who have trouble spotting the glasses on their noses +can tell the difference between a tab and eight spaces from a distance +of approximately fifteen parsecs. Many a flamewar has been fought and +lost on this issue. + +QEMU indents are four spaces. Tabs are never used, except in Makefiles +where they have been irreversibly coded into the syntax. +Spaces of course are superior to tabs because: + +* You have just one way to specify whitespace, not two. Ambiguity breeds + mistakes. +* The confusion surrounding 'use tabs to indent, spaces to justify' is gone. +* Tab indents push your code to the right, making your screen seriously + unbalanced. +* Tabs will be rendered incorrectly on editors who are misconfigured not + to use tab stops of eight positions. +* Tabs are rendered badly in patches, causing off-by-one errors in almost + every line. +* It is the QEMU coding style. + +Do not leave whitespace dangling off the ends of lines. + +Multiline Indent +---------------- + +There are several places where indent is necessary: + +* if/else +* while/for +* function definition & call + +When breaking up a long line to fit within line width, we need a proper indent +for the following lines. + +In case of if/else, while/for, align the secondary lines just after the +opening parenthesis of the first. + +For example: + +.. code-block:: c + + if (a == 1 && + b == 2) { + + while (a == 1 && + b == 2) { + +In case of function, there are several variants: + +* 4 spaces indent from the beginning +* align the secondary lines just after the opening parenthesis of the first + +For example: + +.. code-block:: c + + do_something(x, y, + z); + + do_something(x, y, + z); + + do_something(x, do_another(y, + z)); + +Line width +========== + +Lines should be 80 characters; try not to make them longer. + +Sometimes it is hard to do, especially when dealing with QEMU subsystems +that use long function or symbol names. If wrapping the line at 80 columns +is obviously less readable and more awkward, prefer not to wrap it; better +to have an 85 character line than one which is awkwardly wrapped. + +Even in that case, try not to make lines much longer than 80 characters. +(The checkpatch script will warn at 100 characters, but this is intended +as a guard against obviously-overlength lines, not a target.) + +Rationale: + +* Some people like to tile their 24" screens with a 6x4 matrix of 80x24 + xterms and use vi in all of them. The best way to punish them is to + let them keep doing it. +* Code and especially patches is much more readable if limited to a sane + line length. Eighty is traditional. +* The four-space indentation makes the most common excuse ("But look + at all that white space on the left!") moot. +* It is the QEMU coding style. + +Naming +====== + +Variables are lower_case_with_underscores; easy to type and read. Structured +type names are in CamelCase; harder to type but standing out. Enum type +names and function type names should also be in CamelCase. Scalar type +names are lower_case_with_underscores_ending_with_a_t, like the POSIX +uint64_t and family. Note that this last convention contradicts POSIX +and is therefore likely to be changed. + +Variable Naming Conventions +--------------------------- + +A number of short naming conventions exist for variables that use +common QEMU types. For example, the architecture independent CPUState +is often held as a ``cs`` pointer variable, whereas the concrete +CPUArchState is usually held in a pointer called ``env``. + +Likewise, in device emulation code the common DeviceState is usually +called ``dev``. + +Function Naming Conventions +--------------------------- + +Wrapped version of standard library or GLib functions use a ``qemu_`` +prefix to alert readers that they are seeing a wrapped version, for +example ``qemu_strtol`` or ``qemu_mutex_lock``. Other utility functions +that are widely called from across the codebase should not have any +prefix, for example ``pstrcpy`` or bit manipulation functions such as +``find_first_bit``. + +The ``qemu_`` prefix is also used for functions that modify global +emulator state, for example ``qemu_add_vm_change_state_handler``. +However, if there is an obvious subsystem-specific prefix it should be +used instead. + +Public functions from a file or subsystem (declared in headers) tend +to have a consistent prefix to show where they came from. For example, +``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions +from cpus.c. + +If there are two versions of a function to be called with or without a +lock held, the function that expects the lock to be already held +usually uses the suffix ``_locked``. + + +Block structure +=============== + +Every indented statement is braced; even if the block contains just one +statement. The opening brace is on the line that contains the control +flow statement that introduces the new block; the closing brace is on the +same line as the else keyword, or on a line by itself if there is no else +keyword. Example: + +.. code-block:: c + + if (a == 5) { + printf("a was 5.\n"); + } else if (a == 6) { + printf("a was 6.\n"); + } else { + printf("a was something else entirely.\n"); + } + +Note that 'else if' is considered a single statement; otherwise a long if/ +else if/else if/.../else sequence would need an indent for every else +statement. + +An exception is the opening brace for a function; for reasons of tradition +and clarity it comes on a line by itself: + +.. code-block:: c + + void a_function(void) + { + do_something(); + } + +Rationale: a consistent (except for functions...) bracing style reduces +ambiguity and avoids needless churn when lines are added or removed. +Furthermore, it is the QEMU coding style. + +Declarations +============ + +Mixed declarations (interleaving statements and declarations within +blocks) are generally not allowed; declarations should be at the beginning +of blocks. + +Every now and then, an exception is made for declarations inside a +#ifdef or #ifndef block: if the code looks nicer, such declarations can +be placed at the top of the block even if there are statements above. +On the other hand, however, it's often best to move that #ifdef/#ifndef +block to a separate function altogether. + +Conditional statements +====================== + +When comparing a variable for (in)equality with a constant, list the +constant on the right, as in: + +.. code-block:: c + + if (a == 1) { + /* Reads like: "If a equals 1" */ + do_something(); + } + +Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read. +Besides, good compilers already warn users when '==' is mis-typed as '=', +even when the constant is on the right. + +Comment style +============= + +We use traditional C-style /``*`` ``*``/ comments and avoid // comments. + +Rationale: The // form is valid in C99, so this is purely a matter of +consistency of style. The checkpatch script will warn you about this. + +Multiline comment blocks should have a row of stars on the left, +and the initial /``*`` and terminating ``*``/ both on their own lines: + +.. code-block:: c + + /* + * like + * this + */ + +This is the same format required by the Linux kernel coding style. + +(Some of the existing comments in the codebase use the GNU Coding +Standards form which does not have stars on the left, or other +variations; avoid these when writing new comments, but don't worry +about converting to the preferred form unless you're editing that +comment anyway.) + +Rationale: Consistency, and ease of visually picking out a multiline +comment from the surrounding code. + +Language usage +************** + +Preprocessor +============ + +Variadic macros +--------------- + +For variadic macros, stick with this C99-like syntax: + +.. code-block:: c + + #define DPRINTF(fmt, ...) \ + do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) + +Include directives +------------------ + +Order include directives as follows: + +.. code-block:: c + + #include "qemu/osdep.h" /* Always first... */ + #include <...> /* then system headers... */ + #include "..." /* and finally QEMU headers. */ + +The "qemu/osdep.h" header contains preprocessor macros that affect the behavior +of core system headers like . It must be the first include so that +core system headers included by external libraries get the preprocessor macros +that QEMU depends on. + +Do not include "qemu/osdep.h" from header files since the .c file will have +already included it. + +C types +======= + +It should be common sense to use the right type, but we have collected +a few useful guidelines here. + +Scalars +------- + +If you're using "int" or "long", odds are good that there's a better type. +If a variable is counting something, it should be declared with an +unsigned type. + +If it's host memory-size related, size_t should be a good choice (use +ssize_t only if required). Guest RAM memory offsets must use ram_addr_t, +but only for RAM, it may not cover whole guest address space. + +If it's file-size related, use off_t. +If it's file-offset related (i.e., signed), use off_t. +If it's just counting small numbers use "unsigned int"; +(on all but oddball embedded systems, you can assume that that +type is at least four bytes wide). + +In the event that you require a specific width, use a standard type +like int32_t, uint32_t, uint64_t, etc. The specific types are +mandatory for VMState fields. + +Don't use Linux kernel internal types like u32, __u32 or __le32. + +Use hwaddr for guest physical addresses except pcibus_t +for PCI addresses. In addition, ram_addr_t is a QEMU internal address +space that maps guest RAM physical addresses into an intermediate +address space that can map to host virtual address spaces. Generally +speaking, the size of guest memory can always fit into ram_addr_t but +it would not be correct to store an actual guest physical address in a +ram_addr_t. + +For CPU virtual addresses there are several possible types. +vaddr is the best type to use to hold a CPU virtual address in +target-independent code. It is guaranteed to be large enough to hold a +virtual address for any target, and it does not change size from target +to target. It is always unsigned. +target_ulong is a type the size of a virtual address on the CPU; this means +it may be 32 or 64 bits depending on which target is being built. It should +therefore be used only in target-specific code, and in some +performance-critical built-per-target core code such as the TLB code. +There is also a signed version, target_long. +abi_ulong is for the ``*``-user targets, and represents a type the size of +'void ``*``' in that target's ABI. (This may not be the same as the size of a +full CPU virtual address in the case of target ABIs which use 32 bit pointers +on 64 bit CPUs, like sparc32plus.) Definitions of structures that must match +the target's ABI must use this type for anything that on the target is defined +to be an 'unsigned long' or a pointer type. +There is also a signed version, abi_long. + +Of course, take all of the above with a grain of salt. If you're about +to use some system interface that requires a type like size_t, pid_t or +off_t, use matching types for any corresponding variables. + +Also, if you try to use e.g., "unsigned int" as a type, and that +conflicts with the signedness of a related variable, sometimes +it's best just to use the *wrong* type, if "pulling the thread" +and fixing all related variables would be too invasive. + +Finally, while using descriptive types is important, be careful not to +go overboard. If whatever you're doing causes warnings, or requires +casts, then reconsider or ask for help. + +Pointers +-------- + +Ensure that all of your pointers are "const-correct". +Unless a pointer is used to modify the pointed-to storage, +give it the "const" attribute. That way, the reader knows +up-front that this is a read-only pointer. Perhaps more +importantly, if we're diligent about this, when you see a non-const +pointer, you're guaranteed that it is used to modify the storage +it points to, or it is aliased to another pointer that is. + +Typedefs +-------- + +Typedefs are used to eliminate the redundant 'struct' keyword, since type +names have a different style than other identifiers ("CamelCase" versus +"snake_case"). Each named struct type should have a CamelCase name and a +corresponding typedef. + +Since certain C compilers choke on duplicated typedefs, you should avoid +them and declare a typedef only in one header file. For common types, +you can use "include/qemu/typedefs.h" for example. However, as a matter +of convenience it is also perfectly fine to use forward struct +definitions instead of typedefs in headers and function prototypes; this +avoids problems with duplicated typedefs and reduces the need to include +headers from other headers. + +Reserved namespaces in C and POSIX +---------------------------------- + +Underscore capital, double underscore, and underscore 't' suffixes should be +avoided. + +Low level memory management +=========================== + +Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign +APIs is not allowed in the QEMU codebase. Instead of these routines, +use the GLib memory allocation routines g_malloc/g_malloc0/g_new/ +g_new0/g_realloc/g_free or QEMU's qemu_memalign/qemu_blockalign/qemu_vfree +APIs. + +Please note that g_malloc will exit on allocation failure, so there +is no need to test for failure (as you would have to with malloc). +Calling g_malloc with a zero size is valid and will return NULL. + +Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following +reasons: + +* It catches multiplication overflowing size_t; +* It returns T ``*`` instead of void ``*``, letting compiler catch more type errors. + +Declarations like + +.. code-block:: c + + T *v = g_malloc(sizeof(*v)) + +are acceptable, though. + +Memory allocated by qemu_memalign or qemu_blockalign must be freed with +qemu_vfree, since breaking this will cause problems on Win32. + +String manipulation +=================== + +Do not use the strncpy function. As mentioned in the man page, it does *not* +guarantee a NULL-terminated buffer, which makes it extremely dangerous to use. +It also zeros trailing destination bytes out to the specified length. Instead, +use this similar function when possible, but note its different signature: + +.. code-block:: c + + void pstrcpy(char *dest, int dest_buf_size, const char *src) + +Don't use strcat because it can't check for buffer overflows, but: + +.. code-block:: c + + char *pstrcat(char *buf, int buf_size, const char *s) + +The same limitation exists with sprintf and vsprintf, so use snprintf and +vsnprintf. + +QEMU provides other useful string functions: + +.. code-block:: c + + int strstart(const char *str, const char *val, const char **ptr) + int stristart(const char *str, const char *val, const char **ptr) + int qemu_strnlen(const char *s, int max_len) + +There are also replacement character processing macros for isxyz and toxyz, +so instead of e.g. isalnum you should use qemu_isalnum. + +Because of the memory management rules, you must use g_strdup/g_strndup +instead of plain strdup/strndup. + +Printf-style functions +====================== + +Whenever you add a new printf-style function, i.e., one with a format +string argument and following "..." in its prototype, be sure to use +gcc's printf attribute directive in the prototype. + +This makes it so gcc's -Wformat and -Wformat-security options can do +their jobs and cross-check format strings with the number and types +of arguments. + +C standard, implementation defined and undefined behaviors +========================================================== + +C code in QEMU should be written to the C99 language specification. A copy +of the final version of the C99 standard with corrigenda TC1, TC2, and TC3 +included, formatted as a draft, can be downloaded from: + + ``_ + +The C language specification defines regions of undefined behavior and +implementation defined behavior (to give compiler authors enough leeway to +produce better code). In general, code in QEMU should follow the language +specification and avoid both undefined and implementation defined +constructs. ("It works fine on the gcc I tested it with" is not a valid +argument...) However there are a few areas where we allow ourselves to +assume certain behaviors because in practice all the platforms we care about +behave in the same way and writing strictly conformant code would be +painful. These are: + +* you may assume that integers are 2s complement representation +* you may assume that right shift of a signed integer duplicates + the sign bit (ie it is an arithmetic shift, not a logical shift) + +In addition, QEMU assumes that the compiler does not use the latitude +given in C99 and C11 to treat aspects of signed '<<' as undefined, as +documented in the GNU Compiler Collection manual starting at version 4.0. + +Automatic memory deallocation +============================= + +QEMU has a mandatory dependency either the GCC or CLang compiler. As +such it has the freedom to make use of a C language extension for +automatically running a cleanup function when a stack variable goes +out of scope. This can be used to simplify function cleanup paths, +often allowing many goto jumps to be eliminated, through automatic +free'ing of memory. + +The GLib2 library provides a number of functions/macros for enabling +automatic cleanup: + + ``_ + +Most notably: + +* g_autofree - will invoke g_free() on the variable going out of scope + +* g_autoptr - for structs / objects, will invoke the cleanup func created + by a previous use of G_DEFINE_AUTOPTR_CLEANUP_FUNC. This is + supported for most GLib data types and GObjects + +For example, instead of + +.. code-block:: c + + int somefunc(void) { + int ret = -1; + char *foo = g_strdup_printf("foo%", "wibble"); + GList *bar = ..... + + if (eek) { + goto cleanup; + } + + ret = 0; + + cleanup: + g_free(foo); + g_list_free(bar); + return ret; + } + +Using g_autofree/g_autoptr enables the code to be written as: + +.. code-block:: c + + int somefunc(void) { + g_autofree char *foo = g_strdup_printf("foo%", "wibble"); + g_autoptr (GList) bar = ..... + + if (eek) { + return -1; + } + + return 0; + } + +While this generally results in simpler, less leak-prone code, there +are still some caveats to beware of + +* Variables declared with g_auto* MUST always be initialized, + otherwise the cleanup function will use uninitialized stack memory + +* If a variable declared with g_auto* holds a value which must + live beyond the life of the function, that value must be saved + and the original variable NULL'd out. This can be simpler using + g_steal_pointer + + +.. code-block:: c + + char *somefunc(void) { + g_autofree char *foo = g_strdup_printf("foo%", "wibble"); + g_autoptr (GList) bar = ..... + + if (eek) { + return NULL; + } + + return g_steal_pointer(&foo); + } + + +QEMU Specific Idioms +******************** + +Error handling and reporting +============================ + +Reporting errors to the human user +---------------------------------- + +Do not use printf(), fprintf() or monitor_printf(). Instead, use +error_report() or error_vreport() from error-report.h. This ensures the +error is reported in the right place (current monitor or stderr), and in +a uniform format. + +Use error_printf() & friends to print additional information. + +error_report() prints the current location. In certain common cases +like command line parsing, the current location is tracked +automatically. To manipulate it manually, use the loc_``*``() from +error-report.h. + +Propagating errors +------------------ + +An error can't always be reported to the user right where it's detected, +but often needs to be propagated up the call chain to a place that can +handle it. This can be done in various ways. + +The most flexible one is Error objects. See error.h for usage +information. + +Use the simplest suitable method to communicate success / failure to +callers. Stick to common methods: non-negative on success / -1 on +error, non-negative / -errno, non-null / null, or Error objects. + +Example: when a function returns a non-null pointer on success, and it +can fail only in one way (as far as the caller is concerned), returning +null on failure is just fine, and certainly simpler and a lot easier on +the eyes than propagating an Error object through an Error ``*````*`` parameter. + +Example: when a function's callers need to report details on failure +only the function really knows, use Error ``*````*``, and set suitable errors. + +Do not report an error to the user when you're also returning an error +for somebody else to handle. Leave the reporting to the place that +consumes the error returned. + +Handling errors +--------------- + +Calling exit() is fine when handling configuration errors during +startup. It's problematic during normal operation. In particular, +monitor commands should never exit(). + +Do not call exit() or abort() to handle an error that can be triggered +by the guest (e.g., some unimplemented corner case in guest code +translation or device emulation). Guests should not be able to +terminate QEMU. + +Note that &error_fatal is just another way to exit(1), and &error_abort +is just another way to abort(). + + +trace-events style +================== + +0x prefix +--------- + +In trace-events files, use a '0x' prefix to specify hex numbers, as in: + +.. code-block:: c + + some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 + +An exception is made for groups of numbers that are hexadecimal by +convention and separated by the symbols '.', '/', ':', or ' ' (such as +PCI bus id): + +.. code-block:: c + + another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" + +However, you can use '0x' for such groups if you want. Anyway, be sure that +it is obvious that numbers are in hex, ex.: + +.. code-block:: c + + data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" + +Rationale: hex numbers are hard to read in logs when there is no 0x prefix, +especially when (occasionally) the representation doesn't contain any letters +and especially in one line with other decimal numbers. Number groups are allowed +to not use '0x' because for some things notations like %x.%x.%x are used not +only in Qemu. Also dumping raw data bytes with '0x' is less readable. + +'#' printf flag +--------------- + +Do not use printf flag '#', like '%#x'. + +Rationale: there are two ways to add a '0x' prefix to printed number: '0x%...' +and '%#...'. For consistency the only one way should be used. Arguments for +'0x%' are: + +* it is more popular +* '%#' omits the 0x for the value 0 which makes output inconsistent diff --git a/scripts/fix-multiline-comments.sh b/scripts/fix-multiline-comments.sh index 93f9b10..c15a041 100755 --- a/scripts/fix-multiline-comments.sh +++ b/scripts/fix-multiline-comments.sh @@ -1,6 +1,6 @@ #! /bin/sh # -# Fix multiline comments to match CODING_STYLE +# Fix multiline comments to match docs/devel/style.rst # # Copyright (C) 2018 Red Hat, Inc. # -- cgit v1.1