From nobody Sun May 19 01:15:27 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=1566578832; cv=none; d=zoho.com; s=zohoarc; b=WPOgkqquOBozkGdInUX8i0x9NiL6DsBGAK7a47x9/wQgQoeVT7PO60B7TWjd82YSBZcDWWf94FjTFJBsyb/TsIZk4/QXzGLo3Hj3s/R34xluacPdPRSAC4M86kZy4mRChcqDqBCFvyVpZFmbeRDIBqosBHYH+FkKivtMkEJObcc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1566578832; 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=YmnMelMClU7h4875LlSzpiHL6uTwePfl40dksTdQf2A=; b=HIWlz5mKMhgaHHYTS/FYJmJVSBHATOIqizK1Myl8tMfYSfY8auVTrZOtZGjJWgQIkPQKLYDXj2bq+9iI70pbv34z6WXRc/+Oc7X4ZDbbbIxfZO10oxvhmp4kv+Ne2Ipgnop9//+YjyZgnBJh+sSL0K5iNUi6knJ27sD/xvSu6sY= 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 1566578832627389.5203109888621; Fri, 23 Aug 2019 09:47:12 -0700 (PDT) Received: from localhost ([::1]:59438 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CiT-0003yg-Bd for importer@patchew.org; Fri, 23 Aug 2019 12:47:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46827) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CbF-0006Zq-Ib for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:43 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i1CbC-0002so-JO for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:41 -0400 Received: from mx1.redhat.com ([209.132.183.28]:48706) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i1CbC-0002r1-Bf for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:38 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 0C02A30A7BAE; Fri, 23 Aug 2019 16:39:37 +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 894E0BA90; Fri, 23 Aug 2019 16:39:35 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Fri, 23 Aug 2019 17:39:28 +0100 Message-Id: <20190823163931.7442-2-berrange@redhat.com> In-Reply-To: <20190823163931.7442-1-berrange@redhat.com> References: <20190823163931.7442-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.47]); Fri, 23 Aug 2019 16:39:37 +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 1/4] docs: convert CODING_STYLE and HACKING to markdown 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?= , =?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.md | 37 +++++++++--------- HACKING =3D> HACKING.md | 68 ++++++++++++++++++--------------- README | 2 +- 3 files changed, 58 insertions(+), 49 deletions(-) rename CODING_STYLE =3D> CODING_STYLE.md (92%) rename HACKING =3D> HACKING.md (88%) diff --git a/CODING_STYLE b/CODING_STYLE.md similarity index 92% rename from CODING_STYLE rename to CODING_STYLE.md index cb8edcbb36..056eda7739 100644 --- a/CODING_STYLE +++ b/CODING_STYLE.md @@ -4,7 +4,7 @@ QEMU Coding Style Please use the script checkpatch.pl in the scripts directory to check patches before submitting. =20 -1. Whitespace +## Whitespace =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 @@ -29,7 +29,7 @@ Spaces of course are superior to tabs because: =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 @@ -53,9 +53,8 @@ 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 fir= st =20 For example: =20 @@ -68,7 +67,7 @@ For example: do_something(x, do_another(y, z)); =20 -2. Line width +## Line width =20 Lines should be 80 characters; try not to make them longer. =20 @@ -77,6 +76,7 @@ that use long function or symbol names. Even in that cas= e, 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. @@ -86,7 +86,7 @@ Rationale: at all that white space on the left!") moot. - It is the QEMU coding style. =20 -3. Naming +## Naming =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 @@ -98,7 +98,7 @@ and is therefore likely to be changed. 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 =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 @@ -130,7 +130,7 @@ 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 =20 Mixed declarations (interleaving statements and declarations within blocks) are generally not allowed; declarations should be at the beginning @@ -142,7 +142,7 @@ be placed at the top of the block even if there are sta= tements 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 =20 When comparing a variable for (in)equality with a constant, list the constant on the right, as in: @@ -156,7 +156,7 @@ Rationale: Yoda conditions (as in 'if (1 =3D=3D a)') ar= e 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 =20 We use traditional C-style /* */ comments and avoid // comments. =20 @@ -165,10 +165,12 @@ 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: + /* * 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 +182,24 @@ 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 =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 + 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" + 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" + 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 +207,13 @@ 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 diff --git a/HACKING b/HACKING.md similarity index 88% rename from HACKING rename to HACKING.md index 097d482603..f2f85be40f 100644 --- a/HACKING +++ b/HACKING.md @@ -1,19 +1,22 @@ -1. Preprocessor +QEMU Hacking +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -1.1. Variadic macros +## Preprocessor + +### Variadic macros =20 For variadic macros, stick with this C99-like syntax: =20 -#define DPRINTF(fmt, ...) \ - do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) + #define DPRINTF(fmt, ...) \ + do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) =20 -1.2. Include directives +### Include directives =20 Order include directives as follows: =20 -#include "qemu/osdep.h" /* Always first... */ -#include <...> /* then system headers... */ -#include "..." /* and finally QEMU headers. */ + #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 +26,12 @@ 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 =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 @@ -89,7 +92,7 @@ Finally, while using descriptive types is important, be c= areful 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 +102,7 @@ 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 +117,11 @@ 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 =20 Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign APIs is not allowed in the QEMU codebase. Instead of these routines, @@ -133,16 +136,15 @@ Calling g_malloc with a zero size is valid and will r= eturn NULL. 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 type erro= rs. =20 Declarations like T *v =3D g_malloc(sizeof(*v)) 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 =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. @@ -151,15 +153,17 @@ use this similar function when possible, but note its= different signature: 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) + + 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) + + 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 +171,7 @@ 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 =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 +181,13 @@ 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 =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 + + 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 +198,18 @@ 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 + + - 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 =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 @@ -217,7 +223,7 @@ like command line parsing, the current location is trac= ked 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 @@ -242,7 +248,7 @@ Do not report an error to the user when you're also ret= urning 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 index 441c33eb2f..374b8f1486 100644 --- a/README +++ b/README @@ -60,7 +60,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 and CODING_STYLE files. +guidelines set out in the HACKING.md and CODING_STYLE.md files. =20 Additional information on submitting patches can be found online via the QEMU website --=20 2.21.0 From nobody Sun May 19 01:15:27 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=1566578887; cv=none; d=zoho.com; s=zohoarc; b=i2IuMZj7cHKG6vfHXRgFeRZL7lnH/+BmjMrGXJR4pkMY5vcYW2Fb4dEfaJiOmspevazrtkTAdE6vzYqKXG9CEs1RNdcw5y9XiZe9NKUOzOeMNDYSOSd5L/UULtKvtNC/dlM9a4fJ9Jb6j/7T9vLHb6Lf5WpehoJXo6pbjfDxODw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1566578887; 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=y0kMGN5ZP7HL1KU8hV/pDDkE2wBX1+axOwvxFGI84E8=; b=HuNy6zD9ebieX2jAsM78ncfzIXdclfZKfLTch6IXQyKDkpLl+i45FeHmKq6iRaTpoznwvOgftrk5Mc0lBe1E5n/aIPa5HoHXAns3MX2zVXDKQqQXu0x6GMRvuVbupp0T3+p8pEVNkGqVRGc79rAMidZ7sW/qko9nBNF/Sq8ROmE= 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 1566578887293302.2378229432861; Fri, 23 Aug 2019 09:48:07 -0700 (PDT) Received: from localhost ([::1]:59442 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CjN-0004GQ-F9 for importer@patchew.org; Fri, 23 Aug 2019 12:48:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46840) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CbH-0006b2-5Y for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i1CbD-0002tY-MV for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:43 -0400 Received: from mx1.redhat.com ([209.132.183.28]:60799) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i1CbD-0002sz-Cz for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:39 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id AC0F618C4272; Fri, 23 Aug 2019 16:39:38 +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 59D43BA75; Fri, 23 Aug 2019 16:39:37 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Fri, 23 Aug 2019 17:39:29 +0100 Message-Id: <20190823163931.7442-3-berrange@redhat.com> In-Reply-To: <20190823163931.7442-1-berrange@redhat.com> References: <20190823163931.7442-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.62]); Fri, 23 Aug 2019 16:39:38 +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 2/4] docs: merge HACKING.md contents into CODING_STYLE.md 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?= , =?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 --- CODING_STYLE.md | 262 +++++++++++++++++++++++++++++++++++++++++++++++ HACKING.md | 263 ------------------------------------------------ README | 2 +- 3 files changed, 263 insertions(+), 264 deletions(-) delete mode 100644 HACKING.md diff --git a/CODING_STYLE.md b/CODING_STYLE.md index 056eda7739..9f4fc9dc77 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -217,3 +217,265 @@ and '%#...'. For consistency the only one way should = be used. Arguments for =20 - it is more popular - '%#' omits the 0x for the value 0 which makes output inconsistent + + +## Preprocessor + +### Variadic macros + +For variadic macros, stick with this C99-like syntax: + + #define DPRINTF(fmt, ...) \ + do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) + +### Include directives + +Order include directives as follows: + + #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 + +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 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 + +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 erro= rs. + +Declarations like 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 + +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) + +Don't use strcat because it can't check for buffer overflows, but: + + 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: + + 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: + + http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf + +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 + +### 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(). diff --git a/HACKING.md b/HACKING.md deleted file mode 100644 index f2f85be40f..0000000000 --- a/HACKING.md +++ /dev/null @@ -1,263 +0,0 @@ -QEMU Hacking -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -## Preprocessor - -### Variadic macros - -For variadic macros, stick with this C99-like syntax: - - #define DPRINTF(fmt, ...) \ - do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) - -### Include directives - -Order include directives as follows: - - #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 - -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 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 - -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 erro= rs. - -Declarations like 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 - -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) - -Don't use strcat because it can't check for buffer overflows, but: - - 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: - - 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: - - http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf - -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 - -### 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(). diff --git a/README b/README index 374b8f1486..9d2c2688ad 100644 --- a/README +++ b/README @@ -60,7 +60,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.md and CODING_STYLE.md files. +guidelines set out in the CODING_STYLE.md file. =20 Additional information on submitting patches can be found online via the QEMU website --=20 2.21.0 From nobody Sun May 19 01:15:27 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=1566578608; cv=none; d=zoho.com; s=zohoarc; b=hWS2/B7EcRQimqU7clM7t/iaU/aOnm4A+jCXxiTyiOADGttNwdHsyvnWbFy51FbAbTkQZPcMDoIH9CWOmJsIAEix3wT+g4hGAxB5DaRF+/npCdgnUSXySMtJsqXoyVYxmWFRxE555MXdg4GYylttKSloeNarp0mchY2htn/fbcM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1566578608; 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=kZ+Y/2zRJHPkgl5Wawiu+Q7gFJolMhpErPMHvtVCpAY=; b=Lidk3PHLTCmiRciYl5EhmID5+1qGuVq0dw5U1jmfkWC8iA8wOlEvW9fkQ3SIRv0/Nf5BZUM4RimxhZ7kPYv1mpCBt98FkS+XppfUj8+7m7d7cKpg06cPpdmE34lzC8mDyIlRFtb2epOklW+5pQUY8Buz+42zy3JjHuFIY9M41Z8= 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 1566578608666616.4407761320308; Fri, 23 Aug 2019 09:43:28 -0700 (PDT) Received: from localhost ([::1]:59406 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1Ceq-0008T7-Ql for importer@patchew.org; Fri, 23 Aug 2019 12:43:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46837) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CbG-0006aX-LT for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:43 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i1CbF-0002uU-Ce for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:42 -0400 Received: from mx1.redhat.com ([209.132.183.28]:41522) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i1CbF-0002u7-4x for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:41 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 7889A18DE76B; Fri, 23 Aug 2019 16:39:40 +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 2D418BA75; Fri, 23 Aug 2019 16:39:38 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Fri, 23 Aug 2019 17:39:30 +0100 Message-Id: <20190823163931.7442-4-berrange@redhat.com> In-Reply-To: <20190823163931.7442-1-berrange@redhat.com> References: <20190823163931.7442-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.63]); Fri, 23 Aug 2019 16:39:40 +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 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?= , =?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, or other resource cleanup (eg mutex unlocking). Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Alex Benn=C3=A9e Reviewed-by: Eric Blake Reviewed-by: Stefan Hajnoczi --- CODING_STYLE.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/CODING_STYLE.md b/CODING_STYLE.md index 9f4fc9dc77..f37b6c2d01 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -479,3 +479,104 @@ terminate QEMU. =20 Note that &error_fatal is just another way to exit(1), and &error_abort is just another way to abort(). + + +## 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: + + https://developer.gnome.org/glib/stable/glib-Miscellaneous-Macros.html + +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 + + 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: + + 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 + + + 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); + } + +The cleanup functions are not restricted to simply free'ing memory. The +GMutexLocker class is a variant of GMutex that has automatic locking and +unlocking at start and end of the enclosing scope + +In the following example, the `lock` in `MyObj` will be held for the +precise duration of the `somefunc` function + + typedef struct { + GMutex lock; + } MyObj; + + char *somefunc(MyObj *obj) { + g_autofree GMutexLocker *locker =3D g_mutex_locker_new(&obj->lock) + g_autofree char *foo =3D g_strdup_printf("foo%", "wibble"); + g_autoptr (GList) bar =3D ..... + + if (eek) { + return NULL; + } + + return g_steal_pointer(&foo); + } --=20 2.21.0 From nobody Sun May 19 01:15:27 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=1566578614; cv=none; d=zoho.com; s=zohoarc; b=lEp/6i6lby7IevK6sDbn8Kf6+BwDOzhCf9t/8Qt11Sco5LrmkodCvD7jGF9Wfp+cjbiRANj3fNFreKv9a34p4hgIO2vfcfJt4dXQC78FLiVhLvm/WdtQYvFcu9sKDZ96HmpIErmLunn2EM5o8T3GWKNI/q+PS1czbDeU9O017JI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1566578614; 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=0IoSoAfoeqsnM5bXu6clWOoEnJRERgx0VYH2HIQedHo=; b=PmkzeyztaauPhcALjYHjvojW5L3uuGw436pfRdOsLjC8dhL1EQ4LPrHN2XS08J/qX1rf5rgTOCjrn0/q4z5DEV8No1JBP8ceoibj+e8ieZCKcedeLUoYHImmor/jTiSIZAPrv3+wMafMVslh6HqIvu96/oY/2sJ0gb1L6RpE+6I= 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 1566578614295463.994617427015; Fri, 23 Aug 2019 09:43:34 -0700 (PDT) Received: from localhost ([::1]:59408 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1Ces-0008TW-2Q for importer@patchew.org; Fri, 23 Aug 2019 12:43:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:46856) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1CbI-0006c1-8x for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i1CbH-0002wP-8S for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:44 -0400 Received: from mx1.redhat.com ([209.132.183.28]:48350) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i1CbH-0002v7-2Z for qemu-devel@nongnu.org; Fri, 23 Aug 2019 12:39:43 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 55F26300BC7F; Fri, 23 Aug 2019 16:39:42 +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 C51326CE58; Fri, 23 Aug 2019 16:39:40 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Date: Fri, 23 Aug 2019 17:39:31 +0100 Message-Id: <20190823163931.7442-5-berrange@redhat.com> In-Reply-To: <20190823163931.7442-1-berrange@redhat.com> References: <20190823163931.7442-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.45]); Fri, 23 Aug 2019 16:39:42 +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 4/4] docs: add table of contents to CODING_STYLE.md 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?= , =?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.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CODING_STYLE.md b/CODING_STYLE.md index f37b6c2d01..0841edb2f7 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -1,6 +1,37 @@ QEMU Coding Style =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 +#### Table Of Contents + + * [Whitespace](#whitespace) + + [Multiline Indent](#multiline-indent) + * [Line width](#line-width) + * [Naming](#naming) + * [Block structure](#block-structure) + * [Declarations](#declarations) + * [Conditional statements](#conditional-statements) + * [Comment style](#comment-style) + * [trace-events style](#trace-events-style) + + [0x prefix](#0x-prefix) + + ['#' printf flag](#----printf-flag) + * [Preprocessor](#preprocessor) + + [Variadic macros](#variadic-macros) + + [Include directives](#include-directives) + * [C types](#c-types) + + [Scalars](#scalars) + + [Pointers](#pointers) + + [Typedefs](#typedefs) + + [Reserved namespaces in C and POSIX](#reserved-namespaces-in-c-and-p= osix) + * [Low level memory management](#low-level-memory-management) + * [String manipulation](#string-manipulation) + * [Printf-style functions](#printf-style-functions) + * [C standard, implementation defined and undefined behaviors](#c-standa= rd--implementation-defined-and-undefined-behaviors) + * [Error handling and reporting](#error-handling-and-reporting) + + [Reporting errors to the human user](#reporting-errors-to-the-human-= user) + + [Propagating errors](#propagating-errors) + + [Handling errors](#handling-errors) + * [Automatic memory deallocation](#automatic-memory-deallocation) + Please use the script checkpatch.pl in the scripts directory to check patches before submitting. =20 --=20 2.21.0