Statistics
| Branch: | Revision:

root / HACKING @ a74cdab4

History | View | Annotate | Download (4.8 kB)

1 45fad878 Blue Swirl
1. Preprocessor
2 45fad878 Blue Swirl
3 45fad878 Blue Swirl
For variadic macros, stick with this C99-like syntax:
4 45fad878 Blue Swirl
5 45fad878 Blue Swirl
#define DPRINTF(fmt, ...)                                       \
6 45fad878 Blue Swirl
    do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0)
7 84174436 Blue Swirl
8 84174436 Blue Swirl
2. C types
9 84174436 Blue Swirl
10 84174436 Blue Swirl
It should be common sense to use the right type, but we have collected
11 84174436 Blue Swirl
a few useful guidelines here.
12 84174436 Blue Swirl
13 84174436 Blue Swirl
2.1. Scalars
14 84174436 Blue Swirl
15 84174436 Blue Swirl
If you're using "int" or "long", odds are good that there's a better type.
16 84174436 Blue Swirl
If a variable is counting something, it should be declared with an
17 84174436 Blue Swirl
unsigned type.
18 84174436 Blue Swirl
19 84174436 Blue Swirl
If it's host memory-size related, size_t should be a good choice (use
20 84174436 Blue Swirl
ssize_t only if required). Guest RAM memory offsets must use ram_addr_t,
21 84174436 Blue Swirl
but only for RAM, it may not cover whole guest address space.
22 84174436 Blue Swirl
23 84174436 Blue Swirl
If it's file-size related, use off_t.
24 84174436 Blue Swirl
If it's file-offset related (i.e., signed), use off_t.
25 84174436 Blue Swirl
If it's just counting small numbers use "unsigned int";
26 84174436 Blue Swirl
(on all but oddball embedded systems, you can assume that that
27 84174436 Blue Swirl
type is at least four bytes wide).
28 84174436 Blue Swirl
29 84174436 Blue Swirl
In the event that you require a specific width, use a standard type
30 84174436 Blue Swirl
like int32_t, uint32_t, uint64_t, etc.  The specific types are
31 84174436 Blue Swirl
mandatory for VMState fields.
32 84174436 Blue Swirl
33 84174436 Blue Swirl
Don't use Linux kernel internal types like u32, __u32 or __le32.
34 84174436 Blue Swirl
35 84174436 Blue Swirl
Use target_phys_addr_t for guest physical addresses except pcibus_t
36 84174436 Blue Swirl
for PCI addresses.  In addition, ram_addr_t is a QEMU internal address
37 84174436 Blue Swirl
space that maps guest RAM physical addresses into an intermediate
38 84174436 Blue Swirl
address space that can map to host virtual address spaces.  Generally
39 84174436 Blue Swirl
speaking, the size of guest memory can always fit into ram_addr_t but
40 84174436 Blue Swirl
it would not be correct to store an actual guest physical address in a
41 84174436 Blue Swirl
ram_addr_t.
42 84174436 Blue Swirl
43 84174436 Blue Swirl
Use target_ulong (or abi_ulong) for CPU virtual addresses, however
44 84174436 Blue Swirl
devices should not need to use target_ulong.
45 84174436 Blue Swirl
46 84174436 Blue Swirl
Of course, take all of the above with a grain of salt.  If you're about
47 84174436 Blue Swirl
to use some system interface that requires a type like size_t, pid_t or
48 84174436 Blue Swirl
off_t, use matching types for any corresponding variables.
49 84174436 Blue Swirl
50 84174436 Blue Swirl
Also, if you try to use e.g., "unsigned int" as a type, and that
51 84174436 Blue Swirl
conflicts with the signedness of a related variable, sometimes
52 84174436 Blue Swirl
it's best just to use the *wrong* type, if "pulling the thread"
53 84174436 Blue Swirl
and fixing all related variables would be too invasive.
54 84174436 Blue Swirl
55 84174436 Blue Swirl
Finally, while using descriptive types is important, be careful not to
56 84174436 Blue Swirl
go overboard.  If whatever you're doing causes warnings, or requires
57 84174436 Blue Swirl
casts, then reconsider or ask for help.
58 84174436 Blue Swirl
59 84174436 Blue Swirl
2.2. Pointers
60 84174436 Blue Swirl
61 84174436 Blue Swirl
Ensure that all of your pointers are "const-correct".
62 84174436 Blue Swirl
Unless a pointer is used to modify the pointed-to storage,
63 84174436 Blue Swirl
give it the "const" attribute.  That way, the reader knows
64 84174436 Blue Swirl
up-front that this is a read-only pointer.  Perhaps more
65 84174436 Blue Swirl
importantly, if we're diligent about this, when you see a non-const
66 84174436 Blue Swirl
pointer, you're guaranteed that it is used to modify the storage
67 84174436 Blue Swirl
it points to, or it is aliased to another pointer that is.
68 84174436 Blue Swirl
69 84174436 Blue Swirl
2.3. Typedefs
70 84174436 Blue Swirl
Typedefs are used to eliminate the redundant 'struct' keyword.
71 84174436 Blue Swirl
72 84174436 Blue Swirl
2.4. Reserved namespaces in C and POSIX
73 84174436 Blue Swirl
Underscore capital, double underscore, and underscore 't' suffixes should be
74 84174436 Blue Swirl
avoided.
75 54b2cc50 Blue Swirl
76 54b2cc50 Blue Swirl
3. Low level memory management
77 54b2cc50 Blue Swirl
78 54b2cc50 Blue Swirl
Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign
79 54b2cc50 Blue Swirl
APIs is not allowed in the QEMU codebase. Instead of these routines,
80 54b2cc50 Blue Swirl
use the replacement qemu_malloc/qemu_mallocz/qemu_realloc/qemu_free or
81 54b2cc50 Blue Swirl
qemu_vmalloc/qemu_memalign/qemu_vfree APIs.
82 54b2cc50 Blue Swirl
83 54b2cc50 Blue Swirl
Please note that NULL check for the qemu_malloc result is redundant and
84 54b2cc50 Blue Swirl
that qemu_malloc() call with zero size is not allowed.
85 54b2cc50 Blue Swirl
86 54b2cc50 Blue Swirl
Memory allocated by qemu_vmalloc or qemu_memalign must be freed with
87 54b2cc50 Blue Swirl
qemu_vfree, since breaking this will cause problems on Win32 and user
88 54b2cc50 Blue Swirl
emulators.
89 d241f143 Blue Swirl
90 d241f143 Blue Swirl
4. String manipulation
91 d241f143 Blue Swirl
92 d241f143 Blue Swirl
Do not use the strncpy function.  According to the man page, it does
93 d241f143 Blue Swirl
*not* guarantee a NULL-terminated buffer, which makes it extremely dangerous
94 d241f143 Blue Swirl
to use.  Instead, use functionally equivalent function:
95 d241f143 Blue Swirl
void pstrcpy(char *buf, int buf_size, const char *str)
96 d241f143 Blue Swirl
97 d241f143 Blue Swirl
Don't use strcat because it can't check for buffer overflows, but:
98 d241f143 Blue Swirl
char *pstrcat(char *buf, int buf_size, const char *s)
99 d241f143 Blue Swirl
100 d241f143 Blue Swirl
The same limitation exists with sprintf and vsprintf, so use snprintf and
101 d241f143 Blue Swirl
vsnprintf.
102 d241f143 Blue Swirl
103 d241f143 Blue Swirl
QEMU provides other useful string functions:
104 d241f143 Blue Swirl
int strstart(const char *str, const char *val, const char **ptr)
105 d241f143 Blue Swirl
int stristart(const char *str, const char *val, const char **ptr)
106 d241f143 Blue Swirl
int qemu_strnlen(const char *s, int max_len)
107 d241f143 Blue Swirl
108 d241f143 Blue Swirl
There are also replacement character processing macros for isxyz and toxyz,
109 d241f143 Blue Swirl
so instead of e.g. isalnum you should use qemu_isalnum.
110 d241f143 Blue Swirl
111 d241f143 Blue Swirl
Because of the memory management rules, you must use qemu_strdup/qemu_strndup
112 d241f143 Blue Swirl
instead of plain strdup/strndup.
113 876f256b Blue Swirl
114 876f256b Blue Swirl
5. Printf-style functions
115 876f256b Blue Swirl
116 876f256b Blue Swirl
Whenever you add a new printf-style function, i.e., one with a format
117 876f256b Blue Swirl
string argument and following "..." in its prototype, be sure to use
118 876f256b Blue Swirl
gcc's printf attribute directive in the prototype.
119 876f256b Blue Swirl
120 876f256b Blue Swirl
This makes it so gcc's -Wformat and -Wformat-security options can do
121 876f256b Blue Swirl
their jobs and cross-check format strings with the number and types
122 876f256b Blue Swirl
of arguments.