]>
Commit | Line | Data |
---|---|---|
cd6b1674 KC |
1 | .. _coding-style: |
2 | ||
336a7451 | 3 | ================= |
6576b74b | 4 | QEMU Coding Style |
e68b98dc AL |
5 | ================= |
6 | ||
336a7451 DB |
7 | .. contents:: Table of Contents |
8 | ||
b6469683 BS |
9 | Please use the script checkpatch.pl in the scripts directory to check |
10 | patches before submitting. | |
11 | ||
9f8efa74 DB |
12 | Formatting and style |
13 | ******************** | |
14 | ||
bda8beba AB |
15 | The repository includes a ``.editorconfig`` file which can help with |
16 | getting the right settings for your preferred $EDITOR. See | |
17 | `<https://editorconfig.org/>`_ for details. | |
18 | ||
336a7451 DB |
19 | Whitespace |
20 | ========== | |
e68b98dc AL |
21 | |
22 | Of course, the most important aspect in any coding style is whitespace. | |
23 | Crusty old coders who have trouble spotting the glasses on their noses | |
24 | can tell the difference between a tab and eight spaces from a distance | |
56bef851 | 25 | of approximately fifteen parsecs. Many a flamewar has been fought and |
e68b98dc AL |
26 | lost on this issue. |
27 | ||
28 | QEMU indents are four spaces. Tabs are never used, except in Makefiles | |
1cb499fa | 29 | where they have been irreversibly coded into the syntax. |
e68b98dc AL |
30 | Spaces of course are superior to tabs because: |
31 | ||
336a7451 DB |
32 | * You have just one way to specify whitespace, not two. Ambiguity breeds |
33 | mistakes. | |
34 | * The confusion surrounding 'use tabs to indent, spaces to justify' is gone. | |
35 | * Tab indents push your code to the right, making your screen seriously | |
36 | unbalanced. | |
37 | * Tabs will be rendered incorrectly on editors who are misconfigured not | |
38 | to use tab stops of eight positions. | |
39 | * Tabs are rendered badly in patches, causing off-by-one errors in almost | |
40 | every line. | |
41 | * It is the QEMU coding style. | |
e68b98dc AL |
42 | |
43 | Do not leave whitespace dangling off the ends of lines. | |
44 | ||
336a7451 DB |
45 | Multiline Indent |
46 | ---------------- | |
6ac1fca4 WY |
47 | |
48 | There are several places where indent is necessary: | |
49 | ||
336a7451 DB |
50 | * if/else |
51 | * while/for | |
52 | * function definition & call | |
6ac1fca4 WY |
53 | |
54 | When breaking up a long line to fit within line width, we need a proper indent | |
55 | for the following lines. | |
56 | ||
57 | In case of if/else, while/for, align the secondary lines just after the | |
58 | opening parenthesis of the first. | |
59 | ||
60 | For example: | |
61 | ||
336a7451 DB |
62 | .. code-block:: c |
63 | ||
6ac1fca4 WY |
64 | if (a == 1 && |
65 | b == 2) { | |
66 | ||
67 | while (a == 1 && | |
68 | b == 2) { | |
69 | ||
70 | In case of function, there are several variants: | |
71 | ||
336a7451 DB |
72 | * 4 spaces indent from the beginning |
73 | * align the secondary lines just after the opening parenthesis of the first | |
6ac1fca4 WY |
74 | |
75 | For example: | |
76 | ||
336a7451 DB |
77 | .. code-block:: c |
78 | ||
6ac1fca4 WY |
79 | do_something(x, y, |
80 | z); | |
81 | ||
82 | do_something(x, y, | |
83 | z); | |
84 | ||
85 | do_something(x, do_another(y, | |
86 | z)); | |
87 | ||
336a7451 DB |
88 | Line width |
89 | ========== | |
e68b98dc | 90 | |
8fbe3d1f PB |
91 | Lines should be 80 characters; try not to make them longer. |
92 | ||
93 | Sometimes it is hard to do, especially when dealing with QEMU subsystems | |
a998de0d PM |
94 | that use long function or symbol names. If wrapping the line at 80 columns |
95 | is obviously less readable and more awkward, prefer not to wrap it; better | |
96 | to have an 85 character line than one which is awkwardly wrapped. | |
97 | ||
98 | Even in that case, try not to make lines much longer than 80 characters. | |
99 | (The checkpatch script will warn at 100 characters, but this is intended | |
100 | as a guard against obviously-overlength lines, not a target.) | |
e68b98dc AL |
101 | |
102 | Rationale: | |
e68b98dc | 103 | |
336a7451 DB |
104 | * Some people like to tile their 24" screens with a 6x4 matrix of 80x24 |
105 | xterms and use vi in all of them. The best way to punish them is to | |
106 | let them keep doing it. | |
107 | * Code and especially patches is much more readable if limited to a sane | |
108 | line length. Eighty is traditional. | |
109 | * The four-space indentation makes the most common excuse ("But look | |
110 | at all that white space on the left!") moot. | |
111 | * It is the QEMU coding style. | |
112 | ||
113 | Naming | |
114 | ====== | |
e68b98dc | 115 | |
c227f099 | 116 | Variables are lower_case_with_underscores; easy to type and read. Structured |
e3c52bf2 PM |
117 | type names are in CamelCase; harder to type but standing out. Enum type |
118 | names and function type names should also be in CamelCase. Scalar type | |
c227f099 AL |
119 | names are lower_case_with_underscores_ending_with_a_t, like the POSIX |
120 | uint64_t and family. Note that this last convention contradicts POSIX | |
121 | and is therefore likely to be changed. | |
122 | ||
bc3bde84 AB |
123 | Variable Naming Conventions |
124 | --------------------------- | |
125 | ||
126 | A number of short naming conventions exist for variables that use | |
127 | common QEMU types. For example, the architecture independent CPUState | |
128 | is often held as a ``cs`` pointer variable, whereas the concrete | |
129 | CPUArchState is usually held in a pointer called ``env``. | |
130 | ||
131 | Likewise, in device emulation code the common DeviceState is usually | |
132 | called ``dev``. | |
133 | ||
134 | Function Naming Conventions | |
135 | --------------------------- | |
136 | ||
137 | Wrapped version of standard library or GLib functions use a ``qemu_`` | |
138 | prefix to alert readers that they are seeing a wrapped version, for | |
139 | example ``qemu_strtol`` or ``qemu_mutex_lock``. Other utility functions | |
140 | that are widely called from across the codebase should not have any | |
141 | prefix, for example ``pstrcpy`` or bit manipulation functions such as | |
142 | ``find_first_bit``. | |
143 | ||
144 | The ``qemu_`` prefix is also used for functions that modify global | |
145 | emulator state, for example ``qemu_add_vm_change_state_handler``. | |
146 | However, if there is an obvious subsystem-specific prefix it should be | |
147 | used instead. | |
148 | ||
149 | Public functions from a file or subsystem (declared in headers) tend | |
150 | to have a consistent prefix to show where they came from. For example, | |
151 | ``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions | |
152 | from cpus.c. | |
153 | ||
154 | If there are two versions of a function to be called with or without a | |
155 | lock held, the function that expects the lock to be already held | |
156 | usually uses the suffix ``_locked``. | |
157 | ||
3918fe16 AB |
158 | If a function is a shim designed to deal with compatibility |
159 | workarounds we use the suffix ``_compat``. These are generally not | |
160 | called directly and aliased to the plain function name via the | |
161 | pre-processor. Another common suffix is ``_impl``; it is used for the | |
162 | concrete implementation of a function that will not be called | |
163 | directly, but rather through a macro or an inline function. | |
77ac4862 | 164 | |
336a7451 DB |
165 | Block structure |
166 | =============== | |
e68b98dc AL |
167 | |
168 | Every indented statement is braced; even if the block contains just one | |
169 | statement. The opening brace is on the line that contains the control | |
170 | flow statement that introduces the new block; the closing brace is on the | |
171 | same line as the else keyword, or on a line by itself if there is no else | |
172 | keyword. Example: | |
173 | ||
336a7451 DB |
174 | .. code-block:: c |
175 | ||
e68b98dc AL |
176 | if (a == 5) { |
177 | printf("a was 5.\n"); | |
178 | } else if (a == 6) { | |
179 | printf("a was 6.\n"); | |
180 | } else { | |
181 | printf("a was something else entirely.\n"); | |
182 | } | |
183 | ||
5f070c5f AK |
184 | Note that 'else if' is considered a single statement; otherwise a long if/ |
185 | else if/else if/.../else sequence would need an indent for every else | |
186 | statement. | |
187 | ||
e68b98dc AL |
188 | An exception is the opening brace for a function; for reasons of tradition |
189 | and clarity it comes on a line by itself: | |
190 | ||
336a7451 DB |
191 | .. code-block:: c |
192 | ||
e68b98dc AL |
193 | void a_function(void) |
194 | { | |
195 | do_something(); | |
196 | } | |
197 | ||
198 | Rationale: a consistent (except for functions...) bracing style reduces | |
199 | ambiguity and avoids needless churn when lines are added or removed. | |
200 | Furthermore, it is the QEMU coding style. | |
e939c6ed | 201 | |
336a7451 DB |
202 | Declarations |
203 | ============ | |
e939c6ed | 204 | |
690a35e1 PB |
205 | Mixed declarations (interleaving statements and declarations within |
206 | blocks) are generally not allowed; declarations should be at the beginning | |
207 | of blocks. | |
208 | ||
209 | Every now and then, an exception is made for declarations inside a | |
210 | #ifdef or #ifndef block: if the code looks nicer, such declarations can | |
211 | be placed at the top of the block even if there are statements above. | |
212 | On the other hand, however, it's often best to move that #ifdef/#ifndef | |
213 | block to a separate function altogether. | |
2bb0020c | 214 | |
336a7451 DB |
215 | Conditional statements |
216 | ====================== | |
2bb0020c GA |
217 | |
218 | When comparing a variable for (in)equality with a constant, list the | |
219 | constant on the right, as in: | |
220 | ||
336a7451 DB |
221 | .. code-block:: c |
222 | ||
25d68ffb WY |
223 | if (a == 1) { |
224 | /* Reads like: "If a equals 1" */ | |
225 | do_something(); | |
226 | } | |
2bb0020c GA |
227 | |
228 | Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read. | |
229 | Besides, good compilers already warn users when '==' is mis-typed as '=', | |
230 | even when the constant is on the right. | |
25ac5bbe | 231 | |
336a7451 DB |
232 | Comment style |
233 | ============= | |
25ac5bbe | 234 | |
336a7451 | 235 | We use traditional C-style /``*`` ``*``/ comments and avoid // comments. |
25ac5bbe PM |
236 | |
237 | Rationale: The // form is valid in C99, so this is purely a matter of | |
238 | consistency of style. The checkpatch script will warn you about this. | |
44c6d638 | 239 | |
2948f0cd | 240 | Multiline comment blocks should have a row of stars on the left, |
336a7451 DB |
241 | and the initial /``*`` and terminating ``*``/ both on their own lines: |
242 | ||
243 | .. code-block:: c | |
244 | ||
2948f0cd PM |
245 | /* |
246 | * like | |
247 | * this | |
248 | */ | |
336a7451 | 249 | |
2948f0cd PM |
250 | This is the same format required by the Linux kernel coding style. |
251 | ||
252 | (Some of the existing comments in the codebase use the GNU Coding | |
253 | Standards form which does not have stars on the left, or other | |
254 | variations; avoid these when writing new comments, but don't worry | |
255 | about converting to the preferred form unless you're editing that | |
256 | comment anyway.) | |
257 | ||
258 | Rationale: Consistency, and ease of visually picking out a multiline | |
259 | comment from the surrounding code. | |
260 | ||
9f8efa74 DB |
261 | Language usage |
262 | ************** | |
263 | ||
637f3956 DB |
264 | Preprocessor |
265 | ============ | |
266 | ||
267 | Variadic macros | |
268 | --------------- | |
269 | ||
270 | For variadic macros, stick with this C99-like syntax: | |
271 | ||
272 | .. code-block:: c | |
273 | ||
274 | #define DPRINTF(fmt, ...) \ | |
275 | do { printf("IRQ: " fmt, ## __VA_ARGS__); } while (0) | |
276 | ||
277 | Include directives | |
278 | ------------------ | |
279 | ||
280 | Order include directives as follows: | |
281 | ||
282 | .. code-block:: c | |
283 | ||
284 | #include "qemu/osdep.h" /* Always first... */ | |
285 | #include <...> /* then system headers... */ | |
286 | #include "..." /* and finally QEMU headers. */ | |
287 | ||
288 | The "qemu/osdep.h" header contains preprocessor macros that affect the behavior | |
289 | of core system headers like <stdint.h>. It must be the first include so that | |
290 | core system headers included by external libraries get the preprocessor macros | |
291 | that QEMU depends on. | |
292 | ||
293 | Do not include "qemu/osdep.h" from header files since the .c file will have | |
294 | already included it. | |
295 | ||
296 | C types | |
297 | ======= | |
298 | ||
299 | It should be common sense to use the right type, but we have collected | |
300 | a few useful guidelines here. | |
301 | ||
302 | Scalars | |
303 | ------- | |
304 | ||
305 | If you're using "int" or "long", odds are good that there's a better type. | |
306 | If a variable is counting something, it should be declared with an | |
307 | unsigned type. | |
308 | ||
309 | If it's host memory-size related, size_t should be a good choice (use | |
310 | ssize_t only if required). Guest RAM memory offsets must use ram_addr_t, | |
311 | but only for RAM, it may not cover whole guest address space. | |
312 | ||
313 | If it's file-size related, use off_t. | |
314 | If it's file-offset related (i.e., signed), use off_t. | |
315 | If it's just counting small numbers use "unsigned int"; | |
316 | (on all but oddball embedded systems, you can assume that that | |
317 | type is at least four bytes wide). | |
318 | ||
319 | In the event that you require a specific width, use a standard type | |
320 | like int32_t, uint32_t, uint64_t, etc. The specific types are | |
321 | mandatory for VMState fields. | |
322 | ||
323 | Don't use Linux kernel internal types like u32, __u32 or __le32. | |
324 | ||
325 | Use hwaddr for guest physical addresses except pcibus_t | |
326 | for PCI addresses. In addition, ram_addr_t is a QEMU internal address | |
327 | space that maps guest RAM physical addresses into an intermediate | |
328 | address space that can map to host virtual address spaces. Generally | |
329 | speaking, the size of guest memory can always fit into ram_addr_t but | |
330 | it would not be correct to store an actual guest physical address in a | |
331 | ram_addr_t. | |
332 | ||
333 | For CPU virtual addresses there are several possible types. | |
334 | vaddr is the best type to use to hold a CPU virtual address in | |
335 | target-independent code. It is guaranteed to be large enough to hold a | |
336 | virtual address for any target, and it does not change size from target | |
337 | to target. It is always unsigned. | |
338 | target_ulong is a type the size of a virtual address on the CPU; this means | |
339 | it may be 32 or 64 bits depending on which target is being built. It should | |
340 | therefore be used only in target-specific code, and in some | |
341 | performance-critical built-per-target core code such as the TLB code. | |
342 | There is also a signed version, target_long. | |
343 | abi_ulong is for the ``*``-user targets, and represents a type the size of | |
344 | 'void ``*``' in that target's ABI. (This may not be the same as the size of a | |
345 | full CPU virtual address in the case of target ABIs which use 32 bit pointers | |
346 | on 64 bit CPUs, like sparc32plus.) Definitions of structures that must match | |
347 | the target's ABI must use this type for anything that on the target is defined | |
348 | to be an 'unsigned long' or a pointer type. | |
349 | There is also a signed version, abi_long. | |
350 | ||
351 | Of course, take all of the above with a grain of salt. If you're about | |
352 | to use some system interface that requires a type like size_t, pid_t or | |
353 | off_t, use matching types for any corresponding variables. | |
354 | ||
355 | Also, if you try to use e.g., "unsigned int" as a type, and that | |
356 | conflicts with the signedness of a related variable, sometimes | |
357 | it's best just to use the *wrong* type, if "pulling the thread" | |
358 | and fixing all related variables would be too invasive. | |
359 | ||
360 | Finally, while using descriptive types is important, be careful not to | |
361 | go overboard. If whatever you're doing causes warnings, or requires | |
362 | casts, then reconsider or ask for help. | |
363 | ||
364 | Pointers | |
365 | -------- | |
366 | ||
367 | Ensure that all of your pointers are "const-correct". | |
368 | Unless a pointer is used to modify the pointed-to storage, | |
369 | give it the "const" attribute. That way, the reader knows | |
370 | up-front that this is a read-only pointer. Perhaps more | |
371 | importantly, if we're diligent about this, when you see a non-const | |
372 | pointer, you're guaranteed that it is used to modify the storage | |
373 | it points to, or it is aliased to another pointer that is. | |
374 | ||
375 | Typedefs | |
376 | -------- | |
377 | ||
378 | Typedefs are used to eliminate the redundant 'struct' keyword, since type | |
379 | names have a different style than other identifiers ("CamelCase" versus | |
380 | "snake_case"). Each named struct type should have a CamelCase name and a | |
381 | corresponding typedef. | |
382 | ||
383 | Since certain C compilers choke on duplicated typedefs, you should avoid | |
384 | them and declare a typedef only in one header file. For common types, | |
385 | you can use "include/qemu/typedefs.h" for example. However, as a matter | |
386 | of convenience it is also perfectly fine to use forward struct | |
387 | definitions instead of typedefs in headers and function prototypes; this | |
388 | avoids problems with duplicated typedefs and reduces the need to include | |
389 | headers from other headers. | |
390 | ||
391 | Reserved namespaces in C and POSIX | |
392 | ---------------------------------- | |
393 | ||
394 | Underscore capital, double underscore, and underscore 't' suffixes should be | |
395 | avoided. | |
396 | ||
397 | Low level memory management | |
398 | =========================== | |
399 | ||
9fed69e1 | 400 | Use of the ``malloc/free/realloc/calloc/valloc/memalign/posix_memalign`` |
637f3956 | 401 | APIs is not allowed in the QEMU codebase. Instead of these routines, |
9fed69e1 AB |
402 | use the GLib memory allocation routines |
403 | ``g_malloc/g_malloc0/g_new/g_new0/g_realloc/g_free`` | |
404 | or QEMU's ``qemu_memalign/qemu_blockalign/qemu_vfree`` APIs. | |
405 | ||
406 | Please note that ``g_malloc`` will exit on allocation failure, so | |
407 | there is no need to test for failure (as you would have to with | |
408 | ``malloc``). Generally using ``g_malloc`` on start-up is fine as the | |
409 | result of a failure to allocate memory is going to be a fatal exit | |
410 | anyway. There may be some start-up cases where failing is unreasonable | |
411 | (for example speculatively loading a large debug symbol table). | |
412 | ||
413 | Care should be taken to avoid introducing places where the guest could | |
414 | trigger an exit by causing a large allocation. For small allocations, | |
415 | of the order of 4k, a failure to allocate is likely indicative of an | |
416 | overloaded host and allowing ``g_malloc`` to ``exit`` is a reasonable | |
417 | approach. However for larger allocations where we could realistically | |
418 | fall-back to a smaller one if need be we should use functions like | |
419 | ``g_try_new`` and check the result. For example this is valid approach | |
420 | for a time/space trade-off like ``tlb_mmu_resize_locked`` in the | |
421 | SoftMMU TLB code. | |
422 | ||
423 | If the lifetime of the allocation is within the function and there are | |
424 | multiple exist paths you can also improve the readability of the code | |
425 | by using ``g_autofree`` and related annotations. See :ref:`autofree-ref` | |
426 | for more details. | |
427 | ||
428 | Calling ``g_malloc`` with a zero size is valid and will return NULL. | |
429 | ||
430 | Prefer ``g_new(T, n)`` instead of ``g_malloc(sizeof(T) * n)`` for the following | |
637f3956 DB |
431 | reasons: |
432 | ||
433 | * It catches multiplication overflowing size_t; | |
434 | * It returns T ``*`` instead of void ``*``, letting compiler catch more type errors. | |
435 | ||
436 | Declarations like | |
437 | ||
438 | .. code-block:: c | |
439 | ||
440 | T *v = g_malloc(sizeof(*v)) | |
441 | ||
442 | are acceptable, though. | |
443 | ||
9fed69e1 AB |
444 | Memory allocated by ``qemu_memalign`` or ``qemu_blockalign`` must be freed with |
445 | ``qemu_vfree``, since breaking this will cause problems on Win32. | |
637f3956 DB |
446 | |
447 | String manipulation | |
448 | =================== | |
449 | ||
450 | Do not use the strncpy function. As mentioned in the man page, it does *not* | |
451 | guarantee a NULL-terminated buffer, which makes it extremely dangerous to use. | |
452 | It also zeros trailing destination bytes out to the specified length. Instead, | |
453 | use this similar function when possible, but note its different signature: | |
454 | ||
455 | .. code-block:: c | |
456 | ||
457 | void pstrcpy(char *dest, int dest_buf_size, const char *src) | |
458 | ||
459 | Don't use strcat because it can't check for buffer overflows, but: | |
460 | ||
461 | .. code-block:: c | |
462 | ||
463 | char *pstrcat(char *buf, int buf_size, const char *s) | |
464 | ||
465 | The same limitation exists with sprintf and vsprintf, so use snprintf and | |
466 | vsnprintf. | |
467 | ||
468 | QEMU provides other useful string functions: | |
469 | ||
470 | .. code-block:: c | |
471 | ||
472 | int strstart(const char *str, const char *val, const char **ptr) | |
473 | int stristart(const char *str, const char *val, const char **ptr) | |
474 | int qemu_strnlen(const char *s, int max_len) | |
475 | ||
476 | There are also replacement character processing macros for isxyz and toxyz, | |
477 | so instead of e.g. isalnum you should use qemu_isalnum. | |
478 | ||
479 | Because of the memory management rules, you must use g_strdup/g_strndup | |
480 | instead of plain strdup/strndup. | |
481 | ||
482 | Printf-style functions | |
483 | ====================== | |
484 | ||
485 | Whenever you add a new printf-style function, i.e., one with a format | |
486 | string argument and following "..." in its prototype, be sure to use | |
487 | gcc's printf attribute directive in the prototype. | |
488 | ||
489 | This makes it so gcc's -Wformat and -Wformat-security options can do | |
490 | their jobs and cross-check format strings with the number and types | |
491 | of arguments. | |
492 | ||
493 | C standard, implementation defined and undefined behaviors | |
494 | ========================================================== | |
495 | ||
a68e025b AB |
496 | C code in QEMU should be written to the C11 language specification. A |
497 | copy of the final version of the C11 standard formatted as a draft, | |
498 | can be downloaded from: | |
637f3956 | 499 | |
a68e025b | 500 | `<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1548.pdf>`_ |
637f3956 DB |
501 | |
502 | The C language specification defines regions of undefined behavior and | |
503 | implementation defined behavior (to give compiler authors enough leeway to | |
504 | produce better code). In general, code in QEMU should follow the language | |
505 | specification and avoid both undefined and implementation defined | |
506 | constructs. ("It works fine on the gcc I tested it with" is not a valid | |
507 | argument...) However there are a few areas where we allow ourselves to | |
508 | assume certain behaviors because in practice all the platforms we care about | |
509 | behave in the same way and writing strictly conformant code would be | |
510 | painful. These are: | |
511 | ||
512 | * you may assume that integers are 2s complement representation | |
513 | * you may assume that right shift of a signed integer duplicates | |
514 | the sign bit (ie it is an arithmetic shift, not a logical shift) | |
515 | ||
516 | In addition, QEMU assumes that the compiler does not use the latitude | |
517 | given in C99 and C11 to treat aspects of signed '<<' as undefined, as | |
518 | documented in the GNU Compiler Collection manual starting at version 4.0. | |
519 | ||
9fed69e1 AB |
520 | .. _autofree-ref: |
521 | ||
821f2967 DB |
522 | Automatic memory deallocation |
523 | ============================= | |
524 | ||
525 | QEMU has a mandatory dependency either the GCC or CLang compiler. As | |
526 | such it has the freedom to make use of a C language extension for | |
527 | automatically running a cleanup function when a stack variable goes | |
528 | out of scope. This can be used to simplify function cleanup paths, | |
529 | often allowing many goto jumps to be eliminated, through automatic | |
530 | free'ing of memory. | |
531 | ||
532 | The GLib2 library provides a number of functions/macros for enabling | |
533 | automatic cleanup: | |
534 | ||
535 | `<https://developer.gnome.org/glib/stable/glib-Miscellaneous-Macros.html>`_ | |
536 | ||
537 | Most notably: | |
538 | ||
539 | * g_autofree - will invoke g_free() on the variable going out of scope | |
540 | ||
541 | * g_autoptr - for structs / objects, will invoke the cleanup func created | |
542 | by a previous use of G_DEFINE_AUTOPTR_CLEANUP_FUNC. This is | |
543 | supported for most GLib data types and GObjects | |
544 | ||
545 | For example, instead of | |
546 | ||
547 | .. code-block:: c | |
548 | ||
549 | int somefunc(void) { | |
550 | int ret = -1; | |
551 | char *foo = g_strdup_printf("foo%", "wibble"); | |
552 | GList *bar = ..... | |
553 | ||
554 | if (eek) { | |
555 | goto cleanup; | |
556 | } | |
557 | ||
558 | ret = 0; | |
559 | ||
560 | cleanup: | |
561 | g_free(foo); | |
562 | g_list_free(bar); | |
563 | return ret; | |
564 | } | |
565 | ||
566 | Using g_autofree/g_autoptr enables the code to be written as: | |
567 | ||
568 | .. code-block:: c | |
569 | ||
570 | int somefunc(void) { | |
571 | g_autofree char *foo = g_strdup_printf("foo%", "wibble"); | |
572 | g_autoptr (GList) bar = ..... | |
573 | ||
574 | if (eek) { | |
575 | return -1; | |
576 | } | |
577 | ||
578 | return 0; | |
579 | } | |
580 | ||
581 | While this generally results in simpler, less leak-prone code, there | |
582 | are still some caveats to beware of | |
583 | ||
584 | * Variables declared with g_auto* MUST always be initialized, | |
585 | otherwise the cleanup function will use uninitialized stack memory | |
586 | ||
587 | * If a variable declared with g_auto* holds a value which must | |
588 | live beyond the life of the function, that value must be saved | |
589 | and the original variable NULL'd out. This can be simpler using | |
590 | g_steal_pointer | |
591 | ||
592 | ||
593 | .. code-block:: c | |
594 | ||
595 | char *somefunc(void) { | |
596 | g_autofree char *foo = g_strdup_printf("foo%", "wibble"); | |
597 | g_autoptr (GList) bar = ..... | |
598 | ||
599 | if (eek) { | |
600 | return NULL; | |
601 | } | |
602 | ||
603 | return g_steal_pointer(&foo); | |
604 | } | |
605 | ||
606 | ||
9f8efa74 DB |
607 | QEMU Specific Idioms |
608 | ******************** | |
609 | ||
637f3956 DB |
610 | Error handling and reporting |
611 | ============================ | |
612 | ||
613 | Reporting errors to the human user | |
614 | ---------------------------------- | |
615 | ||
616 | Do not use printf(), fprintf() or monitor_printf(). Instead, use | |
617 | error_report() or error_vreport() from error-report.h. This ensures the | |
618 | error is reported in the right place (current monitor or stderr), and in | |
619 | a uniform format. | |
620 | ||
621 | Use error_printf() & friends to print additional information. | |
622 | ||
623 | error_report() prints the current location. In certain common cases | |
624 | like command line parsing, the current location is tracked | |
625 | automatically. To manipulate it manually, use the loc_``*``() from | |
626 | error-report.h. | |
627 | ||
628 | Propagating errors | |
629 | ------------------ | |
630 | ||
631 | An error can't always be reported to the user right where it's detected, | |
632 | but often needs to be propagated up the call chain to a place that can | |
633 | handle it. This can be done in various ways. | |
634 | ||
635 | The most flexible one is Error objects. See error.h for usage | |
636 | information. | |
637 | ||
638 | Use the simplest suitable method to communicate success / failure to | |
639 | callers. Stick to common methods: non-negative on success / -1 on | |
640 | error, non-negative / -errno, non-null / null, or Error objects. | |
641 | ||
642 | Example: when a function returns a non-null pointer on success, and it | |
643 | can fail only in one way (as far as the caller is concerned), returning | |
644 | null on failure is just fine, and certainly simpler and a lot easier on | |
645 | the eyes than propagating an Error object through an Error ``*````*`` parameter. | |
646 | ||
647 | Example: when a function's callers need to report details on failure | |
648 | only the function really knows, use Error ``*````*``, and set suitable errors. | |
649 | ||
650 | Do not report an error to the user when you're also returning an error | |
651 | for somebody else to handle. Leave the reporting to the place that | |
652 | consumes the error returned. | |
653 | ||
654 | Handling errors | |
655 | --------------- | |
656 | ||
657 | Calling exit() is fine when handling configuration errors during | |
658 | startup. It's problematic during normal operation. In particular, | |
659 | monitor commands should never exit(). | |
660 | ||
661 | Do not call exit() or abort() to handle an error that can be triggered | |
662 | by the guest (e.g., some unimplemented corner case in guest code | |
663 | translation or device emulation). Guests should not be able to | |
664 | terminate QEMU. | |
665 | ||
666 | Note that &error_fatal is just another way to exit(1), and &error_abort | |
667 | is just another way to abort(). | |
668 | ||
669 | ||
336a7451 DB |
670 | trace-events style |
671 | ================== | |
44c6d638 | 672 | |
336a7451 DB |
673 | 0x prefix |
674 | --------- | |
44c6d638 VSO |
675 | |
676 | In trace-events files, use a '0x' prefix to specify hex numbers, as in: | |
677 | ||
93a11007 | 678 | .. code-block:: c |
336a7451 DB |
679 | |
680 | some_trace(unsigned x, uint64_t y) "x 0x%x y 0x" PRIx64 | |
44c6d638 VSO |
681 | |
682 | An exception is made for groups of numbers that are hexadecimal by | |
683 | convention and separated by the symbols '.', '/', ':', or ' ' (such as | |
684 | PCI bus id): | |
685 | ||
93a11007 | 686 | .. code-block:: c |
336a7451 DB |
687 | |
688 | another_trace(int cssid, int ssid, int dev_num) "bus id: %x.%x.%04x" | |
44c6d638 VSO |
689 | |
690 | However, you can use '0x' for such groups if you want. Anyway, be sure that | |
691 | it is obvious that numbers are in hex, ex.: | |
692 | ||
93a11007 | 693 | .. code-block:: c |
336a7451 DB |
694 | |
695 | data_dump(uint8_t c1, uint8_t c2, uint8_t c3) "bytes (in hex): %02x %02x %02x" | |
44c6d638 VSO |
696 | |
697 | Rationale: hex numbers are hard to read in logs when there is no 0x prefix, | |
698 | especially when (occasionally) the representation doesn't contain any letters | |
699 | and especially in one line with other decimal numbers. Number groups are allowed | |
700 | to not use '0x' because for some things notations like %x.%x.%x are used not | |
5135fe71 | 701 | only in QEMU. Also dumping raw data bytes with '0x' is less readable. |
44c6d638 | 702 | |
336a7451 DB |
703 | '#' printf flag |
704 | --------------- | |
44c6d638 VSO |
705 | |
706 | Do not use printf flag '#', like '%#x'. | |
707 | ||
708 | Rationale: there are two ways to add a '0x' prefix to printed number: '0x%...' | |
709 | and '%#...'. For consistency the only one way should be used. Arguments for | |
710 | '0x%' are: | |
336a7451 DB |
711 | |
712 | * it is more popular | |
713 | * '%#' omits the 0x for the value 0 which makes output inconsistent |