]>
Commit | Line | Data |
---|---|---|
45fad878 BS |
1 | 1. Preprocessor |
2 | ||
3 | For variadic macros, stick with this C99-like syntax: | |
4 | ||
5 | #define DPRINTF(fmt, ...) \ | |
6 | do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) | |
84174436 BS |
7 | |
8 | 2. C types | |
9 | ||
10 | It should be common sense to use the right type, but we have collected | |
11 | a few useful guidelines here. | |
12 | ||
13 | 2.1. Scalars | |
14 | ||
15 | If you're using "int" or "long", odds are good that there's a better type. | |
16 | If a variable is counting something, it should be declared with an | |
17 | unsigned type. | |
18 | ||
19 | If it's host memory-size related, size_t should be a good choice (use | |
20 | ssize_t only if required). Guest RAM memory offsets must use ram_addr_t, | |
21 | but only for RAM, it may not cover whole guest address space. | |
22 | ||
23 | If it's file-size related, use off_t. | |
24 | If it's file-offset related (i.e., signed), use off_t. | |
25 | If it's just counting small numbers use "unsigned int"; | |
26 | (on all but oddball embedded systems, you can assume that that | |
27 | type is at least four bytes wide). | |
28 | ||
29 | In the event that you require a specific width, use a standard type | |
30 | like int32_t, uint32_t, uint64_t, etc. The specific types are | |
31 | mandatory for VMState fields. | |
32 | ||
33 | Don't use Linux kernel internal types like u32, __u32 or __le32. | |
34 | ||
a8170e5e | 35 | Use hwaddr for guest physical addresses except pcibus_t |
84174436 BS |
36 | for PCI addresses. In addition, ram_addr_t is a QEMU internal address |
37 | space that maps guest RAM physical addresses into an intermediate | |
38 | address space that can map to host virtual address spaces. Generally | |
39 | speaking, the size of guest memory can always fit into ram_addr_t but | |
40 | it would not be correct to store an actual guest physical address in a | |
41 | ram_addr_t. | |
42 | ||
43 | Use target_ulong (or abi_ulong) for CPU virtual addresses, however | |
44 | devices should not need to use target_ulong. | |
45 | ||
46 | Of course, take all of the above with a grain of salt. If you're about | |
47 | to use some system interface that requires a type like size_t, pid_t or | |
48 | off_t, use matching types for any corresponding variables. | |
49 | ||
50 | Also, if you try to use e.g., "unsigned int" as a type, and that | |
51 | conflicts with the signedness of a related variable, sometimes | |
52 | it's best just to use the *wrong* type, if "pulling the thread" | |
53 | and fixing all related variables would be too invasive. | |
54 | ||
55 | Finally, while using descriptive types is important, be careful not to | |
56 | go overboard. If whatever you're doing causes warnings, or requires | |
57 | casts, then reconsider or ask for help. | |
58 | ||
59 | 2.2. Pointers | |
60 | ||
61 | Ensure that all of your pointers are "const-correct". | |
62 | Unless a pointer is used to modify the pointed-to storage, | |
63 | give it the "const" attribute. That way, the reader knows | |
64 | up-front that this is a read-only pointer. Perhaps more | |
65 | importantly, if we're diligent about this, when you see a non-const | |
66 | pointer, you're guaranteed that it is used to modify the storage | |
67 | it points to, or it is aliased to another pointer that is. | |
68 | ||
69 | 2.3. Typedefs | |
70 | Typedefs are used to eliminate the redundant 'struct' keyword. | |
71 | ||
72 | 2.4. Reserved namespaces in C and POSIX | |
73 | Underscore capital, double underscore, and underscore 't' suffixes should be | |
74 | avoided. | |
54b2cc50 BS |
75 | |
76 | 3. Low level memory management | |
77 | ||
78 | Use of the malloc/free/realloc/calloc/valloc/memalign/posix_memalign | |
79 | APIs is not allowed in the QEMU codebase. Instead of these routines, | |
f603a687 PM |
80 | use the GLib memory allocation routines g_malloc/g_malloc0/g_new/ |
81 | g_new0/g_realloc/g_free or QEMU's qemu_vmalloc/qemu_memalign/qemu_vfree | |
82 | APIs. | |
54b2cc50 | 83 | |
f603a687 PM |
84 | Please note that g_malloc will exit on allocation failure, so there |
85 | is no need to test for failure (as you would have to with malloc). | |
86 | Calling g_malloc with a zero size is valid and will return NULL. | |
54b2cc50 BS |
87 | |
88 | Memory allocated by qemu_vmalloc or qemu_memalign must be freed with | |
89 | qemu_vfree, since breaking this will cause problems on Win32 and user | |
90 | emulators. | |
d241f143 BS |
91 | |
92 | 4. String manipulation | |
93 | ||
9b9e3ec1 JM |
94 | Do not use the strncpy function. As mentioned in the man page, it does *not* |
95 | guarantee a NULL-terminated buffer, which makes it extremely dangerous to use. | |
96 | It also zeros trailing destination bytes out to the specified length. Instead, | |
97 | use this similar function when possible, but note its different signature: | |
98 | void pstrcpy(char *dest, int dest_buf_size, const char *src) | |
d241f143 BS |
99 | |
100 | Don't use strcat because it can't check for buffer overflows, but: | |
101 | char *pstrcat(char *buf, int buf_size, const char *s) | |
102 | ||
103 | The same limitation exists with sprintf and vsprintf, so use snprintf and | |
104 | vsnprintf. | |
105 | ||
106 | QEMU provides other useful string functions: | |
107 | int strstart(const char *str, const char *val, const char **ptr) | |
108 | int stristart(const char *str, const char *val, const char **ptr) | |
109 | int qemu_strnlen(const char *s, int max_len) | |
110 | ||
111 | There are also replacement character processing macros for isxyz and toxyz, | |
112 | so instead of e.g. isalnum you should use qemu_isalnum. | |
113 | ||
145e21db | 114 | Because of the memory management rules, you must use g_strdup/g_strndup |
d241f143 | 115 | instead of plain strdup/strndup. |
876f256b BS |
116 | |
117 | 5. Printf-style functions | |
118 | ||
119 | Whenever you add a new printf-style function, i.e., one with a format | |
120 | string argument and following "..." in its prototype, be sure to use | |
121 | gcc's printf attribute directive in the prototype. | |
122 | ||
123 | This makes it so gcc's -Wformat and -Wformat-security options can do | |
124 | their jobs and cross-check format strings with the number and types | |
125 | of arguments. | |
47536317 PM |
126 | |
127 | 6. C standard, implementation defined and undefined behaviors | |
128 | ||
129 | C code in QEMU should be written to the C99 language specification. A copy | |
130 | of the final version of the C99 standard with corrigenda TC1, TC2, and TC3 | |
131 | included, formatted as a draft, can be downloaded from: | |
132 | http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1256.pdf | |
133 | ||
134 | The C language specification defines regions of undefined behavior and | |
135 | implementation defined behavior (to give compiler authors enough leeway to | |
136 | produce better code). In general, code in QEMU should follow the language | |
137 | specification and avoid both undefined and implementation defined | |
138 | constructs. ("It works fine on the gcc I tested it with" is not a valid | |
139 | argument...) However there are a few areas where we allow ourselves to | |
140 | assume certain behaviors because in practice all the platforms we care about | |
141 | behave in the same way and writing strictly conformant code would be | |
142 | painful. These are: | |
143 | * you may assume that integers are 2s complement representation | |
144 | * you may assume that right shift of a signed integer duplicates | |
145 | the sign bit (ie it is an arithmetic shift, not a logical shift) |