From 84174436a6cd948c3bac22bc02df5d2404ff641d Mon Sep 17 00:00:00 2001 From: Blue Swirl Date: Fri, 10 Sep 2010 18:47:31 +0000 Subject: [PATCH] HACKING: add C type rules 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 | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 3 deletions(-) diff --git a/CODING_STYLE b/CODING_STYLE index 92036f34bc..2c8268ddc2 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 4211d15a06..0c8fad569c 100644 --- a/HACKING +++ b/HACKING @@ -4,3 +4,71 @@ For variadic macros, stick with this C99-like 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 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. + +Use target_ulong (or abi_ulong) for CPU virtual addresses, however +devices should not need to use target_ulong. + +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. + +2.4. Reserved namespaces in C and POSIX +Underscore capital, double underscore, and underscore 't' suffixes should be +avoided.