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