[2/5] 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 <blauwirbel@gmail.com>
---
 CODING_STYLE |    3 --
 HACKING      |   68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 3 deletions(-)

On Thu, 26 Aug 2010, Blue Swirl wrote:

> 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 <blauwirbel@gmail.com>
> ---
>  CODING_STYLE |    3 --
>  HACKING      |   68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 68 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 4211d15..19fc874 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

... in C and POSIX (_t suffix is not special in C)

> +Underscore capital, double underscore, and underscore 't' suffixes should be
> +avoided.
>