From nobody Wed May 1 19:31:14 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567094932; cv=none; d=zoho.com; s=zohoarc; b=BwQNPFk5L/dq2KyXjzU5EZF+ciL2oCjfwa9fSFQLJBiu8ww4d8chsCnRm9r+O/KXW++bawSg41sysV4CxOrtHRxK430hvtqnj4xq5qpzLr6/5NY/mOXsyA4QSMumRPF6vfwzwQHBbs6oq77BuW8Jas/n+9rZe1vUhQJFPtDdku0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567094932; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=zA9eKof5MbLhwoNo/diFt3a8gUjeirGI03MOKYaZzvs=; b=O1+ZQbmYPlHYhXcsubb3qpBZ9itlRSkLVp+ooP0xX48VOp4ShP2ZIo+OEChAuzxXV2fOwsHWAJhUUmOw+OAS/HzLQ562YhhPBIp1VV2WsbfD3zoqcqTxW6IGY8JrB099iDmrZhEcKq9Pq48A/0RvBjqGgHAlUNdEIOp4dtSziiY= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1567094932441443.8598106084427; Thu, 29 Aug 2019 09:08:52 -0700 (PDT) Received: from localhost ([::1]:51738 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3Myh-0003Uv-3a for importer@patchew.org; Thu, 29 Aug 2019 12:08:51 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36523) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3MxJ-00026Q-CX for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:28 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i3MxG-0003nk-03 for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:25 -0400 Received: from mx1.redhat.com ([209.132.183.28]:44106) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i3MxF-0003mz-Nf for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:21 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 09BAC30833A3; Thu, 29 Aug 2019 16:07:21 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-60.ams2.redhat.com [10.36.112.60]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0DD711001DC2; Thu, 29 Aug 2019 16:07:16 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Thu, 29 Aug 2019 17:07:07 +0100 Message-Id: <20190829160710.8792-2-berrange@redhat.com> In-Reply-To: <20190829160710.8792-1-berrange@redhat.com> References: <20190829160710.8792-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.44]); Thu, 29 Aug 2019 16:07:21 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 1/4] docs: convert README, CODING_STYLE and HACKING to RST syntax X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Alex Benn=C3=A9e --- CODING_STYLE =3D> CODING_STYLE.rst | 121 +++++++++++++++++++----------- HACKING =3D> HACKING.rst | 123 +++++++++++++++++++++---------- README =3D> README.rst | 47 +++++++----- 3 files changed, 190 insertions(+), 101 deletions(-) rename CODING_STYLE =3D> CODING_STYLE.rst (72%) rename HACKING =3D> HACKING.rst (79%) rename README =3D> README.rst (84%) diff --git a/CODING_STYLE b/CODING_STYLE.rst similarity index 72% rename from CODING_STYLE rename to CODING_STYLE.rst index cb8edcbb36..713357cb80 100644 --- a/CODING_STYLE +++ b/CODING_STYLE.rst @@ -1,10 +1,14 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D QEMU Coding Style =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +.. contents:: Table of Contents + Please use the script checkpatch.pl in the scripts directory to check patches before submitting. =20 -1. Whitespace +Whitespace +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Of course, the most important aspect in any coding style is whitespace. Crusty old coders who have trouble spotting the glasses on their noses @@ -16,26 +20,27 @@ QEMU indents are four spaces. Tabs are never used, exc= ept in Makefiles where they have been irreversibly coded into the syntax. Spaces of course are superior to tabs because: =20 - - You have just one way to specify whitespace, not two. Ambiguity breeds - mistakes. - - The confusion surrounding 'use tabs to indent, spaces to justify' is go= ne. - - 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. +* You have just one way to specify whitespace, not two. Ambiguity breeds + mistakes. +* The confusion surrounding 'use tabs to indent, spaces to justify' is gon= e. +* 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. =20 Do not leave whitespace dangling off the ends of lines. =20 -1.1 Multiline Indent +Multiline Indent +---------------- =20 There are several places where indent is necessary: =20 - - if/else - - while/for - - function definition & call +* if/else +* while/for +* function definition & call =20 When breaking up a long line to fit within line width, we need a proper in= dent for the following lines. @@ -45,6 +50,8 @@ opening parenthesis of the first. =20 For example: =20 +.. code-block:: c + if (a =3D=3D 1 && b =3D=3D 2) { =20 @@ -53,12 +60,13 @@ For example: =20 In case of function, there are several variants: =20 - * 4 spaces indent from the beginning - * align the secondary lines just after the opening parenthesis of the - first +* 4 spaces indent from the beginning +* align the secondary lines just after the opening parenthesis of the first =20 For example: =20 +.. code-block:: c + do_something(x, y, z); =20 @@ -68,7 +76,8 @@ For example: do_something(x, do_another(y, z)); =20 -2. Line width +Line width +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Lines should be 80 characters; try not to make them longer. =20 @@ -77,16 +86,18 @@ that use long function or symbol names. Even in that c= ase, do not make lines much longer than 80 characters. =20 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. =20 -3. Naming +* 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 +=3D=3D=3D=3D=3D=3D =20 Variables are lower_case_with_underscores; easy to type and read. Structu= red type names are in CamelCase; harder to type but standing out. Enum type @@ -95,10 +106,11 @@ 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. =20 -When wrapping standard library functions, use the prefix qemu_ to alert +When wrapping standard library functions, use the prefix ``qemu_`` to alert readers that they are seeing a wrapped version; otherwise avoid this prefi= x. =20 -4. Block structure +Block structure +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Every indented statement is braced; even if the block contains just one statement. The opening brace is on the line that contains the control @@ -106,6 +118,8 @@ flow statement that introduces the new block; the closi= ng brace is on the same line as the else keyword, or on a line by itself if there is no else keyword. Example: =20 +.. code-block:: c + if (a =3D=3D 5) { printf("a was 5.\n"); } else if (a =3D=3D 6) { @@ -121,6 +135,8 @@ statement. An exception is the opening brace for a function; for reasons of tradition and clarity it comes on a line by itself: =20 +.. code-block:: c + void a_function(void) { do_something(); @@ -130,7 +146,8 @@ Rationale: a consistent (except for functions...) braci= ng style reduces ambiguity and avoids needless churn when lines are added or removed. Furthermore, it is the QEMU coding style. =20 -5. Declarations +Declarations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Mixed declarations (interleaving statements and declarations within blocks) are generally not allowed; declarations should be at the beginning @@ -142,11 +159,14 @@ be placed at the top of the block even if there are s= tatements above. On the other hand, however, it's often best to move that #ifdef/#ifndef block to a separate function altogether. =20 -6. Conditional statements +Conditional statements +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 When comparing a variable for (in)equality with a constant, list the constant on the right, as in: =20 +.. code-block:: c + if (a =3D=3D 1) { /* Reads like: "If a equals 1" */ do_something(); @@ -156,19 +176,24 @@ Rationale: Yoda conditions (as in 'if (1 =3D=3D a)') = are awkward to read. Besides, good compilers already warn users when '=3D=3D' is mis-typed as '= =3D', even when the constant is on the right. =20 -7. Comment style +Comment style +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -We use traditional C-style /* */ comments and avoid // comments. +We use traditional C-style /``*`` ``*``/ comments and avoid // comments. =20 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. =20 Multiline comment blocks should have a row of stars on the left, -and the initial /* and terminating */ both on their own lines: +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. =20 (Some of the existing comments in the codebase use the GNU Coding @@ -180,24 +205,32 @@ comment anyway.) Rationale: Consistency, and ease of visually picking out a multiline comment from the surrounding code. =20 -8. trace-events style +trace-events style +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -8.1 0x prefix +0x prefix +--------- =20 In trace-events files, use a '0x' prefix to specify hex numbers, as in: =20 -some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 +.. code-block:: + + some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 =20 An exception is made for groups of numbers that are hexadecimal by convention and separated by the symbols '.', '/', ':', or ' ' (such as PCI bus id): =20 -another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" +.. code-block:: + + another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" =20 However, you can use '0x' for such groups if you want. Anyway, be sure that it is obvious that numbers are in hex, ex.: =20 -data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %= 02x" +.. code-block:: + + data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %0= 2x %02x" =20 Rationale: hex numbers are hard to read in logs when there is no 0x prefix, especially when (occasionally) the representation doesn't contain any lett= ers @@ -205,12 +238,14 @@ 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 n= ot only in Qemu. Also dumping raw data bytes with '0x' is less readable. =20 -8.2 '#' printf flag +'#' printf flag +--------------- =20 Do not use printf flag '#', like '%#x'. =20 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 + +* it is more popular +* '%#' omits the 0x for the value 0 which makes output inconsistent diff --git a/HACKING b/HACKING.rst similarity index 79% rename from HACKING rename to HACKING.rst index 097d482603..668fc420c3 100644 --- a/HACKING +++ b/HACKING.rst @@ -1,19 +1,32 @@ -1. Preprocessor +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU Hacking +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -1.1. Variadic macros +.. contents:: Table of Contents + +Preprocessor +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Variadic macros +--------------- =20 For variadic macros, stick with this C99-like syntax: =20 -#define DPRINTF(fmt, ...) \ - do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) +.. code-block:: c =20 -1.2. Include directives + #define DPRINTF(fmt, ...) \ + do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) + +Include directives +------------------ =20 Order include directives as follows: =20 -#include "qemu/osdep.h" /* Always first... */ -#include <...> /* then system headers... */ -#include "..." /* and finally QEMU headers. */ +.. code-block:: c + + #include "qemu/osdep.h" /* Always first... */ + #include <...> /* then system headers... */ + #include "..." /* and finally QEMU headers. */ =20 The "qemu/osdep.h" header contains preprocessor macros that affect the beh= avior of core system headers like . It must be the first include so t= hat @@ -23,12 +36,14 @@ that QEMU depends on. Do not include "qemu/osdep.h" from header files since the .c file will have already included it. =20 -2. C types +C types +=3D=3D=3D=3D=3D=3D=3D =20 It should be common sense to use the right type, but we have collected a few useful guidelines here. =20 -2.1. Scalars +Scalars +------- =20 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 @@ -68,8 +83,8 @@ it may be 32 or 64 bits depending on which target is bein= g 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 +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 o= f a full CPU virtual address in the case of target ABIs which use 32 bit point= ers on 64 bit CPUs, like sparc32plus.) Definitions of structures that must mat= ch the target's ABI must use this type for anything that on the target is def= ined @@ -89,7 +104,8 @@ 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. =20 -2.2. Pointers +Pointers +-------- =20 Ensure that all of your pointers are "const-correct". Unless a pointer is used to modify the pointed-to storage, @@ -99,7 +115,8 @@ 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. =20 -2.3. Typedefs +Typedefs +-------- =20 Typedefs are used to eliminate the redundant 'struct' keyword, since type names have a different style than other identifiers ("CamelCase" versus @@ -114,11 +131,14 @@ definitions instead of typedefs in headers and functi= on prototypes; this avoids problems with duplicated typedefs and reduces the need to include headers from other headers. =20 -2.4. Reserved namespaces in C and POSIX +Reserved namespaces in C and POSIX +---------------------------------- + Underscore capital, double underscore, and underscore 't' suffixes should = be avoided. =20 -3. Low level memory management +Low level memory management +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign APIs is not allowed in the QEMU codebase. Instead of these routines, @@ -130,36 +150,51 @@ Please note that g_malloc will exit on allocation fai= lure, 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. =20 -Prefer g_new(T, n) instead of g_malloc(sizeof(T) * n) for the following +Prefer g_new(T, n) instead of g_malloc(sizeof(T) ``*`` n) for the following reasons: =20 - a. It catches multiplication overflowing size_t; - b. It returns T * instead of void *, letting compiler catch more type - errors. +* It catches multiplication overflowing size_t; +* It returns T ``*`` instead of void ``*``, letting compiler catch more ty= pe errors. + +Declarations like + +.. code-block:: c + + T *v =3D g_malloc(sizeof(*v)) =20 -Declarations like T *v =3D g_malloc(sizeof(*v)) are acceptable, though. +are acceptable, though. =20 Memory allocated by qemu_memalign or qemu_blockalign must be freed with qemu_vfree, since breaking this will cause problems on Win32. =20 -4. String manipulation +String manipulation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Do not use the strncpy function. As mentioned in the man page, it does *n= ot* guarantee a NULL-terminated buffer, which makes it extremely dangerous to = use. It also zeros trailing destination bytes out to the specified length. Ins= tead, use this similar function when possible, but note its different signature: -void pstrcpy(char *dest, int dest_buf_size, const char *src) + +.. code-block:: c + + void pstrcpy(char *dest, int dest_buf_size, const char *src) =20 Don't use strcat because it can't check for buffer overflows, but: -char *pstrcat(char *buf, int buf_size, const char *s) + +.. code-block:: c + + char *pstrcat(char *buf, int buf_size, const char *s) =20 The same limitation exists with sprintf and vsprintf, so use snprintf and vsnprintf. =20 QEMU provides other useful string functions: -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) + +.. 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) =20 There are also replacement character processing macros for isxyz and toxyz, so instead of e.g. isalnum you should use qemu_isalnum. @@ -167,7 +202,8 @@ 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. =20 -5. Printf-style functions +Printf-style functions +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 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 @@ -177,12 +213,14 @@ 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. =20 -6. C standard, implementation defined and undefined behaviors +C standard, implementation defined and undefined behaviors +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D =20 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: - http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf + + ``_ =20 The C language specification defines regions of undefined behavior and implementation defined behavior (to give compiler authors enough leeway to @@ -193,17 +231,20 @@ argument...) However there are a few areas where we a= llow ourselves to assume certain behaviors because in practice all the platforms we care abo= ut 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) + +* 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) =20 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. =20 -7. Error handling and reporting +Error handling and reporting +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 -7.1 Reporting errors to the human user +Reporting errors to the human user +---------------------------------- =20 Do not use printf(), fprintf() or monitor_printf(). Instead, use error_report() or error_vreport() from error-report.h. This ensures the @@ -214,10 +255,11 @@ Use error_printf() & friends to print additional info= rmation. =20 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 +automatically. To manipulate it manually, use the loc_``*``() from error-report.h. =20 -7.2 Propagating errors +Propagating errors +------------------ =20 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 @@ -233,16 +275,17 @@ error, non-negative / -errno, non-null / null, or Err= or 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. +the eyes than propagating an Error object through an Error ``*````*`` para= meter. =20 Example: when a function's callers need to report details on failure -only the function really knows, use Error **, and set suitable errors. +only the function really knows, use Error ``*````*``, and set suitable err= ors. =20 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. =20 -7.3 Handling errors +Handling errors +--------------- =20 Calling exit() is fine when handling configuration errors during startup. It's problematic during normal operation. In particular, diff --git a/README b/README.rst similarity index 84% rename from README rename to README.rst index 441c33eb2f..9ff2877416 100644 --- a/README +++ b/README.rst @@ -1,5 +1,6 @@ - QEMU README - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QEMU README +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 QEMU is a generic and open source machine & userspace emulator and virtualizer. @@ -37,6 +38,9 @@ QEMU is multi-platform software intended to be buildable = on all modern Linux platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other UNIX targets. The simple steps to build QEMU are: =20 + +.. code-block:: shell + mkdir build cd build ../configure @@ -44,9 +48,9 @@ of other UNIX targets. The simple steps to build QEMU are: =20 Additional information can also be found online via the QEMU website: =20 - https://qemu.org/Hosts/Linux - https://qemu.org/Hosts/Mac - https://qemu.org/Hosts/W32 +* ``_ +* ``_ +* ``_ =20 =20 Submitting patches @@ -54,24 +58,29 @@ Submitting patches =20 The QEMU source code is maintained under the GIT version control system. =20 +.. code-block:: shell + git clone https://git.qemu.org/git/qemu.git =20 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 HACKING and CODING_STYLE files. +guidelines set out in the HACKING.rst and CODING_STYLE.rst files. =20 Additional information on submitting patches can be found online via the QEMU website =20 - https://qemu.org/Contribute/SubmitAPatch - https://qemu.org/Contribute/TrivialPatches +* ``_ +* ``_ =20 The QEMU website is also maintained under source control. =20 +.. code-block:: shell + git clone https://git.qemu.org/git/qemu-web.git - https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/ + +* ``_ =20 A 'git-publish' utility was created to make above process less cumbersome, and is highly recommended for making regular contributions, @@ -82,10 +91,12 @@ manually for once. =20 For installation instructions, please go to =20 - https://github.com/stefanha/git-publish +* ``_ =20 The workflow with 'git-publish' is: =20 +.. code-block:: shell + $ git checkout master -b my-feature $ # work on new commits, add your 'Signed-off-by' lines to each $ git publish @@ -95,6 +106,8 @@ back to it in the future. =20 Sending v2: =20 +.. code-block:: shell + $ git checkout my-feature # same topic branch $ # making changes to the commits (using 'git rebase', for example) $ git publish @@ -109,7 +122,7 @@ The QEMU project uses Launchpad as its primary upstream= bug tracker. Bugs found when running code built from QEMU git or upstream released sources should be reported via: =20 - https://bugs.launchpad.net/qemu/ +* ``_ =20 If using QEMU via an operating system vendor pre-built binary package, it is preferable to report bugs to the vendor's own bug tracker first. If @@ -118,7 +131,7 @@ reported via launchpad. =20 For additional information on bug reporting consult: =20 - https://qemu.org/Contribute/ReportABug +* ``_ =20 =20 Contact @@ -127,13 +140,11 @@ Contact The QEMU community can be contacted in a number of ways, with the two main methods being email and IRC =20 - - qemu-devel@nongnu.org - https://lists.nongnu.org/mailman/listinfo/qemu-devel - - #qemu on irc.oftc.net +* ``_ +* ``_ +* #qemu on irc.oftc.net =20 Information on additional methods of contacting the community can be found online via the QEMU website: =20 - https://qemu.org/Contribute/StartHere - --- End +* ``_ --=20 2.21.0 From nobody Wed May 1 19:31:14 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567095017; cv=none; d=zoho.com; s=zohoarc; b=MDwqtqfzLe2pTxncYcL7F/zdCZOpHvNWTRnC9N8LVxAWfFy3ZhGH79/Tx+MNk8NhMPdkmtKOKEw9pP0Od8bcKPcQj2lnRW72Bm7ZI0zWJB70/UW0oeONgUW+rRXlbtzZ9roFLytUVED+tsXUAElz1ZQyKyyYwMXC7ilhNXAQhSE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567095017; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=I+m0HOjCZggTk8xNPsXnIb3I9zl7U7sTUDh0Phb7V1w=; b=YV0UhXFNB6rqAEVcQ4J9SS4RE2UepcIaYS0/Q/GPuYJOnHMUFlDGqRMJ16tmINgDLLOZwEzoOhPwNGRHlq4ZlL6vIH8hr4iBHiqj/ewcoBdgouEmOpRvalgcWLveiSs6o/jAULeZJ89w5C26+ILo7rfDknB1IIaEdLTU7t+XCnU= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1567095017193316.13005519721423; Thu, 29 Aug 2019 09:10:17 -0700 (PDT) Received: from localhost ([::1]:51750 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3N04-0005hc-3V for importer@patchew.org; Thu, 29 Aug 2019 12:10:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36573) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3MxP-0002FZ-8t for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i3MxL-0003uF-Nb for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:31 -0400 Received: from mx1.redhat.com ([209.132.183.28]:44440) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i3MxL-0003tJ-DU for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:27 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id A1D46935D0; Thu, 29 Aug 2019 16:07:26 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-60.ams2.redhat.com [10.36.112.60]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6F0531001B2B; Thu, 29 Aug 2019 16:07:21 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Thu, 29 Aug 2019 17:07:08 +0100 Message-Id: <20190829160710.8792-3-berrange@redhat.com> In-Reply-To: <20190829160710.8792-1-berrange@redhat.com> References: <20190829160710.8792-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Thu, 29 Aug 2019 16:07:26 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 2/4] docs: merge HACKING.rst contents into CODING_STYLE.rst X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" The split of information between the two docs is rather arbitary and unclear. It is simpler for contributors if all the information is in one file. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Alex Benn=C3=A9e --- CODING_STYLE.rst | 296 ++++++++++++++++++++++++++++++++++++++++++++++ HACKING.rst | 300 ----------------------------------------------- README.rst | 2 +- 3 files changed, 297 insertions(+), 301 deletions(-) delete mode 100644 HACKING.rst diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 713357cb80..4501d87352 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -205,6 +205,302 @@ comment anyway.) Rationale: Consistency, and ease of visually picking out a multiline comment from the surrounding code. =20 +Preprocessor +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 beh= avior +of core system headers like . It must be the first include so t= hat +core system headers included by external libraries get the preprocessor ma= cros +that QEMU depends on. + +Do not include "qemu/osdep.h" from header files since the .c file will have +already included it. + +C types +=3D=3D=3D=3D=3D=3D=3D + +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 o= f a +full CPU virtual address in the case of target ABIs which use 32 bit point= ers +on 64 bit CPUs, like sparc32plus.) Definitions of structures that must mat= ch +the target's ABI must use this type for anything that on the target is def= ined +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +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 ty= pe errors. + +Declarations like + +.. code-block:: c + + T *v =3D 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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Do not use the strncpy function. As mentioned in the man page, it does *n= ot* +guarantee a NULL-terminated buffer, which makes it extremely dangerous to = use. +It also zeros trailing destination bytes out to the specified length. Ins= tead, +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 abo= ut +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. + +Error handling and reporting +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +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 ``*````*`` para= meter. + +Example: when a function's callers need to report details on failure +only the function really knows, use Error ``*````*``, and set suitable err= ors. + +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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/HACKING.rst b/HACKING.rst deleted file mode 100644 index 668fc420c3..0000000000 --- a/HACKING.rst +++ /dev/null @@ -1,300 +0,0 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -QEMU Hacking -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -.. contents:: Table of Contents - -Preprocessor -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -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 beh= avior -of core system headers like . It must be the first include so t= hat -core system headers included by external libraries get the preprocessor ma= cros -that QEMU depends on. - -Do not include "qemu/osdep.h" from header files since the .c file will have -already included it. - -C types -=3D=3D=3D=3D=3D=3D=3D - -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 o= f a -full CPU virtual address in the case of target ABIs which use 32 bit point= ers -on 64 bit CPUs, like sparc32plus.) Definitions of structures that must mat= ch -the target's ABI must use this type for anything that on the target is def= ined -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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D - -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 ty= pe errors. - -Declarations like - -.. code-block:: c - - T *v =3D 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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Do not use the strncpy function. As mentioned in the man page, it does *n= ot* -guarantee a NULL-terminated buffer, which makes it extremely dangerous to = use. -It also zeros trailing destination bytes out to the specified length. Ins= tead, -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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D - -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 abo= ut -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. - -Error handling and reporting -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D - -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 ``*````*`` para= meter. - -Example: when a function's callers need to report details on failure -only the function really knows, use Error ``*````*``, and set suitable err= ors. - -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(). diff --git a/README.rst b/README.rst index 9ff2877416..7497709291 100644 --- a/README.rst +++ b/README.rst @@ -66,7 +66,7 @@ When submitting patches, one common approach is to use 'g= it 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 HACKING.rst and CODING_STYLE.rst files. +guidelines set out in the CODING_STYLE.rst file. =20 Additional information on submitting patches can be found online via the QEMU website --=20 2.21.0 From nobody Wed May 1 19:31:14 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567095102; cv=none; d=zoho.com; s=zohoarc; b=PCwiEKPPAGiwY6GSp7hcVkZdpQWuSeOouvzx9+YGuujLOP8xUeAxhNIREhk8/1+pKE7pNp7GLv49Oc1njKFD2SJLg4NKnzflXo3dznIuOH8QyorFSsLE25tqM53yONqztKZXf9LEMshbETtSjl0wkTTFyqteO8JFIp0dEUAa0BY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567095102; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=sI5EZ/y9A9OV/euvcfCTmdZ+gkCMSeP6hEsbFkhw4mo=; b=l/zjAXosswoTwf/OYlGWucwNZzB+Q5iFv9f6X9523CpuoSepcwFqoF4Pf+2CFKNHROvdONXPY6RkycaLbHtszsRq/7+kJuBY+AxxigqQVB6SuCzjSaW+THvSy2nPOgXz4XpM66gu44dm1bPBO7Q5TjXIIcU5hnOsp1kapg0O58I= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1567095102699688.7006576783959; Thu, 29 Aug 2019 09:11:42 -0700 (PDT) Received: from localhost ([::1]:51756 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3N1M-0006iE-22 for importer@patchew.org; Thu, 29 Aug 2019 12:11:36 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36597) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3MxS-0002Lp-60 for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i3MxQ-0003zC-VG for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:34 -0400 Received: from mx1.redhat.com ([209.132.183.28]:52234) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i3MxQ-0003yS-NT for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:32 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 093A710C696D; Thu, 29 Aug 2019 16:07:32 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-60.ams2.redhat.com [10.36.112.60]) by smtp.corp.redhat.com (Postfix) with ESMTP id 01049100EBD9; Thu, 29 Aug 2019 16:07:26 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Thu, 29 Aug 2019 17:07:09 +0100 Message-Id: <20190829160710.8792-4-berrange@redhat.com> In-Reply-To: <20190829160710.8792-1-berrange@redhat.com> References: <20190829160710.8792-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.65]); Thu, 29 Aug 2019 16:07:32 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 3/4] docs: document use of automatic cleanup functions in glib X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" Document the use of g_autofree and g_autoptr in glib for automatic freeing of memory. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Alex Benn=C3=A9e --- CODING_STYLE.rst | 85 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 4501d87352..39397f0f6f 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -441,6 +441,91 @@ In addition, QEMU assumes that the compiler does not u= se 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. =20 +Automatic memory deallocation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + +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 =3D -1; + char *foo =3D g_strdup_printf("foo%", "wibble"); + GList *bar =3D ..... + + if (eek) { + goto cleanup; + } + + ret =3D 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 =3D g_strdup_printf("foo%", "wibble"); + g_autoptr (GList) bar =3D ..... + + 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 =3D g_strdup_printf("foo%", "wibble"); + g_autoptr (GList) bar =3D ..... + + if (eek) { + return NULL; + } + + return g_steal_pointer(&foo); + } + + Error handling and reporting =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 --=20 2.21.0 From nobody Wed May 1 19:31:14 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1567095174; cv=none; d=zoho.com; s=zohoarc; b=ki+EJ5kkxajNqAO2MhutB+mi3ZCJYrnawioIz50T/M1qb3DPpNfcCVcxsc2o8/8DwCbYQkJxGUMIxiDY8CN6VRCGfC0c9VCIQcI/37XdENkamrIBvS/h7dIZ+EdkJXwCKfCptJzzW+flCeBYIRqyX47LDXAPHUSNimX6K/OGgko= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1567095174; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=dUL6Bgpi3gWQxZFw28nmy3yA+EQuU1UcVl6LRIy4FTc=; b=jI7BoaeqU05YKY2rcvPKyIhRDGVki+7ULKHfGtvcEMmNCrr4uAkZNZ6UJ1fuqVw+n9WuVMkUl5Kc334D71PcXAwTchaw8Xi51FyAjSiaKG8oUl5w3JaeG/8WW8TFfFzNUD/Dr3s+fjWI8ZoZFKT4k6S6zh27NwnH6G3plEtZuZM= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (209.51.188.17 [209.51.188.17]) by mx.zohomail.com with SMTPS id 1567095174724538.5566918841198; Thu, 29 Aug 2019 09:12:54 -0700 (PDT) Received: from localhost ([::1]:51770 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3N2W-0007d0-Jy for importer@patchew.org; Thu, 29 Aug 2019 12:12:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36697) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i3Mxe-0002eP-UO for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i3Mxd-0004Bb-TX for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:46 -0400 Received: from mx1.redhat.com ([209.132.183.28]:53758) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i3Mxd-0004Ax-O4 for qemu-devel@nongnu.org; Thu, 29 Aug 2019 12:07:45 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 0CB862A09DC; Thu, 29 Aug 2019 16:07:45 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-60.ams2.redhat.com [10.36.112.60]) by smtp.corp.redhat.com (Postfix) with ESMTP id 53FCC101E678; Thu, 29 Aug 2019 16:07:32 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Thu, 29 Aug 2019 17:07:10 +0100 Message-Id: <20190829160710.8792-5-berrange@redhat.com> In-Reply-To: <20190829160710.8792-1-berrange@redhat.com> References: <20190829160710.8792-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.38]); Thu, 29 Aug 2019 16:07:45 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 4/4] docs: split the CODING_STYLE doc into distinct groups X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" Signed-off-by: Daniel P. Berrang=C3=A9 --- CODING_STYLE.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 39397f0f6f..427699e0e4 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -7,6 +7,9 @@ QEMU Coding Style Please use the script checkpatch.pl in the scripts directory to check patches before submitting. =20 +Formatting and style +******************** + Whitespace =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -205,6 +208,9 @@ comment anyway.) Rationale: Consistency, and ease of visually picking out a multiline comment from the surrounding code. =20 +Language usage +************** + Preprocessor =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -526,6 +532,9 @@ are still some caveats to beware of } =20 =20 +QEMU Specific Idioms +******************** + Error handling and reporting =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 --=20 2.21.0