]>
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 | ||
35 | Use target_phys_addr_t for guest physical addresses except pcibus_t | |
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. |