From nobody Wed Nov 5 16:45:32 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.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 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1535911127887822.7477109769726; Sun, 2 Sep 2018 10:58:47 -0700 (PDT) Received: from localhost ([::1]:41953 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWe1-00010I-KI for importer@patchew.org; Sun, 02 Sep 2018 13:58:41 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41170) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWZs-0005pg-Qs for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fwWZo-0002ic-RO for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:22 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:34416 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fwWZl-0002dH-0n for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:18 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 1C389804B9F1 for ; Sun, 2 Sep 2018 17:54:14 +0000 (UTC) Received: from localhost.localdomain (unknown [10.35.206.21]) by smtp.corp.redhat.com (Postfix) with ESMTP id 047722027EA5; Sun, 2 Sep 2018 17:54:12 +0000 (UTC) From: Yoni Bettan To: qemu-devel@nongnu.org Date: Sun, 2 Sep 2018 20:53:59 +0300 Message-Id: <20180902175401.8195-2-ybettan@redhat.com> In-Reply-To: <20180902175401.8195-1-ybettan@redhat.com> References: <20180902175401.8195-1-ybettan@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Sun, 02 Sep 2018 17:54:14 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.8]); Sun, 02 Sep 2018 17:54:14 +0000 (UTC) for IP:'10.11.54.4' DOMAIN:'int-mx04.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'ybettan@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH V2 1/3] README.md : Formatted to fit Markdown (.md) format. X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Yoni Bettan , ehabkost@redhat.com, stefanha@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RDMRC_1 RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Also updated scripts/checkpatch.pl and made it reference to README.md instead of README. Signed-off-by: Yoni Bettan --- README =3D> README.md | 89 ++++++++++++++++++++++--------------------- scripts/checkpatch.pl | 2 +- 2 files changed, 46 insertions(+), 45 deletions(-) rename README =3D> README.md (67%) diff --git a/README b/README.md similarity index 67% rename from README rename to README.md index 49a9fd09cd..5fc06dcf8a 100644 --- a/README +++ b/README.md @@ -1,5 +1,4 @@ - QEMU README - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +# Qemu =20 QEMU is a generic and open source machine & userspace emulator and virtualizer. @@ -27,89 +26,93 @@ It is commonly invoked indirectly via the libvirt libra= ry when using open source applications such as oVirt, OpenStack and virt-manager. =20 QEMU as a whole is released under the GNU General Public License, -version 2. For full licensing details, consult the LICENSE file. +version 2. For full licensing details, consult the [LICENSE](LICENSE) file. =20 =20 -Building -=3D=3D=3D=3D=3D=3D=3D=3D +## Building =20 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 - mkdir build - cd build - ../configure - make +``` +mkdir build +cd build +../configure +make +``` =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 +* https://qemu.org/Hosts/Linux +* https://qemu.org/Hosts/Mac +* https://qemu.org/Hosts/W32 =20 =20 -Submitting patches -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +## Submitting patches =20 The QEMU source code is maintained under the GIT version control system. =20 - git clone git://git.qemu.org/qemu.git +`git clone git://git.qemu.org/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. +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](https://lists.nongnu.org/mailman/listinfo/qemu-dev= el) +mailing list. All patches submitted must contain a 'Signed-off-by' line fr= om +the author. Patches should follow the guidelines set out in the +[HACKING.md](HACKING.md) and [CODING_STYLE.md](CODING_STYLE.md) 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 +* https://qemu.org/Contribute/SubmitAPatch +* https://qemu.org/Contribute/TrivialPatches =20 The QEMU website is also maintained under source control. =20 - git clone git://git.qemu.org/qemu-web.git - https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/ +`git clone git://git.qemu.org/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 +A `git-publish` utility was created to make above process less cumbersome, and is highly recommended for making regular contributions, or even just for sending consecutive patch series revisions. It also -requires a working 'git send-email' setup, and by default doesn't +requires a working `git send-email` setup, and by default doesn't automate everything, so you may want to go through the above steps manually for once. =20 For installation instructions, please go to =20 - https://github.com/stefanha/git-publish +* https://github.com/stefanha/git-publish =20 The workflow with 'git-publish' is: =20 - $ git checkout master -b my-feature - $ # work on new commits, add your 'Signed-off-by' lines to each - $ git publish +``` +git checkout master -b my-feature +# work on new commits, add your 'Signed-off-by' lines to each +git publish +``` =20 Your patch series will be sent and tagged as my-feature-v1 if you need to = refer back to it in the future. =20 Sending v2: =20 - $ git checkout my-feature # same topic branch - $ # making changes to the commits (using 'git rebase', for example) - $ git publish +``` +git checkout my-feature # same topic branch +# making changes to the commits (using 'git rebase', for example) +git publish +``` =20 Your patch series will be sent with 'v2' tag in the subject and the git tip will be tagged as my-feature-v2. =20 -Bug reporting -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +## Bug reporting =20 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/ +* 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,22 +121,20 @@ reported via launchpad. =20 For additional information on bug reporting consult: =20 - https://qemu.org/Contribute/ReportABug +* https://qemu.org/Contribute/ReportABug =20 =20 -Contact -=3D=3D=3D=3D=3D=3D=3D +## Contact =20 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-devel@nongnu.org](https://lists.nongnu.org/mailman/listinfo/qemu-d= evel) +* #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 +* https://qemu.org/Contribute/StartHere =20 --- End +## End diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 42e1c50dd8..55167e064e 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -407,7 +407,7 @@ sub top_of_kernel_tree { =20 my @tree_check =3D ( "COPYING", "MAINTAINERS", "Makefile", - "README", "docs", "VERSION", + "README.md", "docs", "VERSION", "vl.c" ); =20 --=20 2.17.1 From nobody Wed Nov 5 16:45:32 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.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 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1535911119783315.06922889276007; Sun, 2 Sep 2018 10:58:39 -0700 (PDT) Received: from localhost ([::1]:41952 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWdy-0000yW-NQ for importer@patchew.org; Sun, 02 Sep 2018 13:58:38 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41231) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWZv-0005pj-3w for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:30 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fwWZo-0002iy-Uk for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:24 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:40572 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fwWZm-0002eZ-Iw for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:18 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 92A5583221 for ; Sun, 2 Sep 2018 17:54:15 +0000 (UTC) Received: from localhost.localdomain (unknown [10.35.206.21]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7812D2027EA5; Sun, 2 Sep 2018 17:54:14 +0000 (UTC) From: Yoni Bettan To: qemu-devel@nongnu.org Date: Sun, 2 Sep 2018 20:54:00 +0300 Message-Id: <20180902175401.8195-3-ybettan@redhat.com> In-Reply-To: <20180902175401.8195-1-ybettan@redhat.com> References: <20180902175401.8195-1-ybettan@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.1]); Sun, 02 Sep 2018 17:54:15 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.1]); Sun, 02 Sep 2018 17:54:15 +0000 (UTC) for IP:'10.11.54.4' DOMAIN:'int-mx04.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'ybettan@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH V2 2/3] CODING_STYLE.md : Formatted to fit Markdown (.md) format. X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Yoni Bettan , ehabkost@redhat.com, stefanha@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RDMRC_1 RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Yoni Bettan --- CODING_STYLE =3D> CODING_STYLE.md | 151 +++++++++++++++++--------------- 1 file changed, 80 insertions(+), 71 deletions(-) rename CODING_STYLE =3D> CODING_STYLE.md (50%) diff --git a/CODING_STYLE b/CODING_STYLE.md similarity index 50% rename from CODING_STYLE rename to CODING_STYLE.md index ec075dedc4..776868458d 100644 --- a/CODING_STYLE +++ b/CODING_STYLE.md @@ -1,10 +1,9 @@ -QEMU Coding Style -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +# QEMU Coding Style =20 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 @@ -16,20 +15,20 @@ 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 +* 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 +* 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 +* 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 +* Tabs are rendered badly in patches, causing off-by-one errors in almost every line. - - It is the QEMU coding style. +* It is the QEMU coding style. =20 Do not leave whitespace dangling off the ends of lines. =20 -2. Line width +## Line width =20 Lines should be 80 characters; try not to make them longer. =20 @@ -38,28 +37,28 @@ 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. +* 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 +## 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 -names and function type names should also be in CamelCase. Scalar type -names are lower_case_with_underscores_ending_with_a_t, like the POSIX -uint64_t and family. Note that this last convention contradicts POSIX +Variables are `lower_case_with_underscores`; easy to type and read. Struc= tured +type names are in `CamelCase`; harder to type but standing out. Enum type +names and function type names should also be in `CamelCase`. Scalar type +names are `lower_case_with_underscores_ending_with_a_t`, like the POSIX +`uint64_t` and family. Note that this last convention contradicts POSIX and is therefore likely to be changed. =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 =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 @@ -67,69 +66,79 @@ 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 - if (a =3D=3D 5) { - printf("a was 5.\n"); - } else if (a =3D=3D 6) { - printf("a was 6.\n"); - } else { - printf("a was something else entirely.\n"); - } +``` +if (a =3D=3D 5) { + printf("a was 5.\n"); +} else if (a =3D=3D 6) { + printf("a was 6.\n"); +} else { + printf("a was something else entirely.\n"); +} +``` =20 -Note that 'else if' is considered a single statement; otherwise a long if/ -else if/else if/.../else sequence would need an indent for every else +Note that `else if` is considered a single statement; otherwise a long `if/ +else` `if/else` `if/.../else` sequence would need an indent for every else statement. =20 An exception is the opening brace for a function; for reasons of tradition and clarity it comes on a line by itself: =20 - void a_function(void) - { - do_something(); - } +``` +void a_function(void) +{ + do_something(); +} +``` =20 Rationale: a consistent (except for functions...) bracing style reduces ambiguity and avoids needless churn when lines are added or removed. Furthermore, it is the QEMU coding style. =20 -5. Declarations +## Declarations =20 Mixed declarations (interleaving statements and declarations within blocks) are generally not allowed; declarations should be at the beginning of blocks. =20 Every now and then, an exception is made for declarations inside a -#ifdef or #ifndef block: if the code looks nicer, such declarations can +`#ifdef` or `#ifndef` block: if the code looks nicer, such declarations can be placed at the top of the block even if there are statements above. -On the other hand, however, it's often best to move that #ifdef/#ifndef +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: =20 +``` if (a =3D=3D 1) { /* Reads like: "If a equals 1" */ do_something(); } +``` =20 -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', +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 =20 -We use traditional C-style /* */ comments and avoid // comments. +We use traditional C-style `/* comment */` and avoid `// comment`. =20 -Rationale: The // form is valid in C99, so this is purely a matter of +Rationale: The `// comment` form is valid in C99, so this is purely a matt= er 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: - /* - * like - * this - */ +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 @@ -141,37 +150,37 @@ 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: +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 +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 +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 %02x = %02x"` =20 -Rationale: hex numbers are hard to read in logs when there is no 0x prefix, +Rationale: hex numbers are hard to read in logs when there is no `0x` pref= ix, especially when (occasionally) the representation doesn't contain any lett= ers and especially in one line with other decimal numbers. Number groups are a= llowed -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. +to not use `0x` because for some things notations like `%x.%x.%x` are used= not +only in Qemu. Also dumping raw data bytes with `0x` is less readable. =20 -8.2 '#' printf flag +### '#' printf flag =20 -Do not use printf flag '#', like '%#x'. +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 +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 --=20 2.17.1 From nobody Wed Nov 5 16:45:32 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.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 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1535911247780216.5110724078129; Sun, 2 Sep 2018 11:00:47 -0700 (PDT) Received: from localhost ([::1]:41966 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWfv-0003Zq-Kq for importer@patchew.org; Sun, 02 Sep 2018 14:00:39 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:41232) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fwWZv-0005pk-3y for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:30 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fwWZp-0002jr-4f for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:24 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:59246 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fwWZn-0002fu-3P for qemu-devel@nongnu.org; Sun, 02 Sep 2018 13:54:20 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 4424E402332F for ; Sun, 2 Sep 2018 17:54:17 +0000 (UTC) Received: from localhost.localdomain (unknown [10.35.206.21]) by smtp.corp.redhat.com (Postfix) with ESMTP id EBD732027EA5; Sun, 2 Sep 2018 17:54:15 +0000 (UTC) From: Yoni Bettan To: qemu-devel@nongnu.org Date: Sun, 2 Sep 2018 20:54:01 +0300 Message-Id: <20180902175401.8195-4-ybettan@redhat.com> In-Reply-To: <20180902175401.8195-1-ybettan@redhat.com> References: <20180902175401.8195-1-ybettan@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Sun, 02 Sep 2018 17:54:17 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.6]); Sun, 02 Sep 2018 17:54:17 +0000 (UTC) for IP:'10.11.54.4' DOMAIN:'int-mx04.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'ybettan@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH V2 3/3] HACKING.md : Formatted to fit Markdown (.md) format. X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Yoni Bettan , ehabkost@redhat.com, stefanha@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RDMRC_1 RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Yoni Bettan --- HACKING =3D> HACKING.md | 186 ++++++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 89 deletions(-) rename HACKING =3D> HACKING.md (53%) diff --git a/HACKING b/HACKING.md similarity index 53% rename from HACKING rename to HACKING.md index 0fc3e0fc04..f9d7631e64 100644 --- a/HACKING +++ b/HACKING.md @@ -1,86 +1,90 @@ -1. Preprocessor +## Preprocessor =20 -1.1. Variadic macros +### Variadic macros =20 For variadic macros, stick with this C99-like syntax: =20 +``` #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. */ +``` =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 +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= that core system headers included by external libraries get the preprocessor ma= cros that QEMU depends on. =20 -Do not include "qemu/osdep.h" from header files since the .c file will have +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 -unsigned type. +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 +`unsigned `. =20 -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, +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. =20 -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"; +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). =20 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 +like `int32_t`, `uint32_t`, `uint64_t`, etc. The specific types are mandatory for VMState fields. =20 -Don't use Linux kernel internal types like u32, __u32 or __le32. +Don't use Linux kernel internal types like `u32`, `__u32` or `__le32`. =20 -Use hwaddr for guest physical addresses except pcibus_t -for PCI addresses. In addition, ram_addr_t is a QEMU internal address +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 +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. +`ram_addr_t`. =20 For CPU virtual addresses there are several possible types. -vaddr is the best type to use to hold a CPU virtual address in +`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 +`target_ulong` is a type the size of a virtual address on the CPU; this me= ans 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 +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 +on 64 bit CPUs, like `sparc32plus`.) Definitions of structures that must m= atch 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. +to be an `unsigned long` or a pointer type. +There is also a signed version, `abi_long`. =20 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. +to use some system interface that requires a type like `size_t`, `pid_t` or +`off_t`, use matching types for any corresponding variables. =20 -Also, if you try to use e.g., "unsigned int" as a type, and that +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. @@ -89,83 +93,86 @@ 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, -give it the "const" attribute. That way, the reader knows +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. =20 -2.3. Typedefs -Typedefs are used to eliminate the redundant 'struct' keyword. +### Typedefs +Typedefs are used to eliminate the redundant `struct` keyword. =20 -2.4. Reserved namespaces in C and POSIX -Underscore capital, double underscore, and underscore 't' suffixes should = be +### Reserved namespaces in C and POSIX +`_`, `__`, 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 +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 +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. =20 -Please note that g_malloc will exit on allocation failure, so there +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. +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 + a. It catches multiplication overflowing `size_t`; + b. It returns `T *` instead of `void *`, letting compiler catch more type errors. =20 -Declarations like T *v =3D g_malloc(sizeof(*v)) are acceptable, though. +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. +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* +Do not use the `strncpy` function. As mentioned in the man page, it does = *not* guarantee a NULL-terminated buffer, which makes it extremely dangerous to = use. It also zeros trailing destination bytes out to the specified length. Ins= tead, use this similar function when possible, but note its different signature: -void pstrcpy(char *dest, int dest_buf_size, const char *src) +`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) +Don't use `strcat` because it can't check for buffer overflows, but: +`char *pstrcat(char *buf, int buf_size, const char *s)` =20 -The same limitation exists with sprintf and vsprintf, so use snprintf and -vsnprintf. +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) +``` =20 -There are also replacement character processing macros for isxyz and toxyz, -so instead of e.g. isalnum you should use qemu_isalnum. +There are also replacement character processing macros for `isxyz` and `to= xyz`, +so instead of e.g. `isalnum` you should use `qemu_isalnum`. =20 -Because of the memory management rules, you must use g_strdup/g_strndup -instead of plain strdup/strndup. +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 +string argument and following `...` in its prototype, be sure to use gcc's printf attribute directive in the prototype. =20 -This makes it so gcc's -Wformat and -Wformat-security options can do +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 @@ -181,37 +188,38 @@ 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 +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 +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. =20 -Use error_printf() & friends to print additional information. +Use `error_printf()` & friends to print additional information. =20 -error_report() prints the current location. In certain common cases +`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. +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 handle it. This can be done in various ways. =20 -The most flexible one is Error objects. See error.h for usage +The most flexible one is Error objects. See `error.h` for usage information. =20 Use the simplest suitable method to communicate success / failure to @@ -220,26 +228,26 @@ error, non-negative / -errno, non-null / null, or Err= or objects. =20 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. +`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`. =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 errors. =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 +Calling `exit()` is fine when handling configuration errors during startup. It's problematic during normal operation. In particular, -monitor commands should never exit(). +monitor commands should never `exit()`. =20 -Do not call exit() or abort() to handle an error that can be triggered +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. =20 -Note that &error_fatal is just another way to exit(1), and &error_abort -is just another way to abort(). +Note that `&error_fatal` is just another way to `exit(1)`, and `&error_abo= rt` +is just another way to `abort()`. --=20 2.17.1