From patchwork Sun Aug 15 17:50:23 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Blue Swirl X-Patchwork-Id: 61773 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [199.232.76.165]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 4D45DB70A9 for ; Mon, 16 Aug 2010 07:11:11 +1000 (EST) Received: from localhost ([127.0.0.1]:56178 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OkkTz-0006Va-Oe for incoming@patchwork.ozlabs.org; Sun, 15 Aug 2010 17:11:07 -0400 Received: from [140.186.70.92] (port=57050 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Okjpu-00049e-NV for qemu-devel@nongnu.org; Sun, 15 Aug 2010 16:29:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OkhM3-0002RU-Pv for qemu-devel@nongnu.org; Sun, 15 Aug 2010 13:50:48 -0400 Received: from mail-qy0-f173.google.com ([209.85.216.173]:34105) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OkhM3-0002RO-LN for qemu-devel@nongnu.org; Sun, 15 Aug 2010 13:50:43 -0400 Received: by qyk5 with SMTP id 5so1863961qyk.4 for ; Sun, 15 Aug 2010 10:50:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:mime-version:received:from:date :message-id:subject:to:content-type; bh=gpAfYVdHM53alC0aPJhXxEqLGjZCmfXi53WUzpBTIaA=; b=tmH46Esj1pVZ0ll2DhOC9hfnGxM2N9ZKsxamp12pZboGwOA3xAcvAgg9QP7NNpzkLj h+iD6d0wSFwU+EynBrOTbHtavNVK3IQWqrn9E/wym8hK1+tFbTIqwBhQHPczcPnfT+Ck nDdJ9+CoEl2uSvYIXghGDp5CvgFxuPUp/uTx4= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:from:date:message-id:subject:to:content-type; b=s5lgePJ6D4KLjyWBQJ+ytyOMP2IeQXNOCPObIp7heJfJAm11SN7xDeMszBKL9vYpd4 q0CJSJ1KKU0cIVADE6ra6Ek5fka37PO3hOYtoCz4zTPAp9xaJ0VFCZDXZY20Id7Lp7lQ /yMDw5E0YdnubHoZ5yQdvyMvEkU9Fck4FsIYs= Received: by 10.229.71.71 with SMTP id g7mr17247qcj.177.1281894643175; Sun, 15 Aug 2010 10:50:43 -0700 (PDT) MIME-Version: 1.0 Received: by 10.229.183.135 with HTTP; Sun, 15 Aug 2010 10:50:23 -0700 (PDT) From: Blue Swirl Date: Sun, 15 Aug 2010 17:50:23 +0000 Message-ID: To: qemu-devel X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) Subject: [Qemu-devel] [PATCH 2/5] HACKING: add C type rules X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Add C type rules, adapted from libvirt HACKING. Also include a description of special QEMU scalar types. Move typedef rule from CODING_STYLE rule 3 to HACKING rule 6 where it belongs. Signed-off-by: Blue Swirl --- CODING_STYLE | 3 -- HACKING | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 3 deletions(-) diff --git a/CODING_STYLE b/CODING_STYLE index 92036f3..2c8268d 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -46,9 +46,6 @@ 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. -Typedefs are used to eliminate the redundant 'struct' keyword. It is the -QEMU coding style. - When wrapping standard library functions, use the prefix qemu_ to alert readers that they are seeing a wrapped version; otherwise avoid this prefix. diff --git a/HACKING b/HACKING index e60aa48..7c6b49e 100644 --- a/HACKING +++ b/HACKING @@ -4,3 +4,67 @@ For variadic macros, stick with C99 syntax: #define DPRINTF(fmt, ...) \ do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) + +2. C types + +It should be common sense to use the right type, but we have collected +a few useful guidelines here. + +2.1. 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 target_phys_addr_t for hardware physical addresses except pcibus_t +for PCI addresses. Use target_ulong (or abi_ulong) for CPU +virtual addresses, however devices should not need to use target_ulong. + +While using "bool" is good for readability, it comes with minor caveats: + - Don't use "bool" in places where the type size must be constant across + all systems, like public interfaces and on-the-wire protocols. + - Don't compare a bool variable against the literal, "true", + since a value with a logical non-false value need not be "1". + I.e., don't write "if (seen == true) ...". Rather, write "if (seen)...". + +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. + +2.2. 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. + +2.3. Typedefs +Typedefs are used to eliminate the redundant 'struct' keyword.