From patchwork Thu Aug 12 17:50:06 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Blue Swirl X-Patchwork-Id: 61635 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 3D21CB70CB for ; Fri, 13 Aug 2010 03:51:59 +1000 (EST) Received: from localhost ([127.0.0.1]:36752 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Ojbwa-0005cx-De for incoming@patchwork.ozlabs.org; Thu, 12 Aug 2010 13:51:56 -0400 Received: from [140.186.70.92] (port=43138 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OjbvA-0005bw-4V for qemu-devel@nongnu.org; Thu, 12 Aug 2010 13:50:29 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1Ojbv8-0002aL-QK for qemu-devel@nongnu.org; Thu, 12 Aug 2010 13:50:28 -0400 Received: from mail-vw0-f45.google.com ([209.85.212.45]:33091) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Ojbv8-0002aC-Ny for qemu-devel@nongnu.org; Thu, 12 Aug 2010 13:50:26 -0400 Received: by vws19 with SMTP id 19so838974vws.4 for ; Thu, 12 Aug 2010 10:50:26 -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=DrtqYo6witmeIp18dglfGv0wHGzpx4UcuAhjMrDG/0A=; b=ZNGYf5wi+qs5k+wJyoBUphIPhKn4YniWu75d6Bo0f9huAmlY9GhWYfUEz2/Stv1aEE RLqa3YEiNihWkDNmtA4IvR0Vpaspa66Yof/z02eZdE79L53Fj8aS17fgtf2DpcuX5Azz yyftRR4V1mhWAUbJbaeOrGHE+Umwla5I0nNxY= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:from:date:message-id:subject:to:content-type; b=xXdbmR/HCWpu/HSndxw/URVm7PYinMu9vuj2cmuq6wj7asng956bOni407zWmNuRYP Ab2JW39E89osYwHfT317rkoeW5zy6KuMTrzm15CYE1WJ5exedjOv5AH1bIiT8npcnO7J HWkxxQBF5iiWNV3JzmIqhEz1bc3u33fTu1ffw= Received: by 10.229.52.5 with SMTP id f5mr329916qcg.254.1281635426152; Thu, 12 Aug 2010 10:50:26 -0700 (PDT) MIME-Version: 1.0 Received: by 10.229.241.15 with HTTP; Thu, 12 Aug 2010 10:50:06 -0700 (PDT) From: Blue Swirl Date: Thu, 12 Aug 2010 17:50:06 +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] CODING_STYLE: 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 from libvirt HACKING. Also include a description of special QEMU scalar types. Signed-off-by: Blue Swirl --- CODING_STYLE | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 56 insertions(+), 0 deletions(-) diff --git a/CODING_STYLE b/CODING_STYLE index c4c09ab..3f10d72 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -92,3 +92,59 @@ indentation to track nesting: #if defined(HAVE_POSIX_FALLOCATE) && !defined(HAVE_FALLOCATE) # define fallocate(a,ignored,b,c) posix_fallocate(a,b,c) #endif + +6. C types + +Use the right type. + +6.1. Scalars + +If you're using "int" or "long", odds are good that there's a better type. +If a variable is counting something, be sure to declare it with an +unsigned type. +If it's memory-size-related, use size_t (use ssize_t only if required). +If it's file-size related, use uintmax_t, or maybe 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. + +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. + +6.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.