docs/devel/style.rst

9 Please use the script checkpatch.pl in the scripts directory to check
30 Spaces of course are superior to tabs because:
32 * You have just one way to specify whitespace, not two.  Ambiguity breeds
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
38   to use tab stops of eight positions.
54 When breaking up a long line to fit within line width, we need a proper indent
91 Lines should be 80 characters; try not to make them longer.
93 Sometimes it is hard to do, especially when dealing with QEMU subsystems
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.
98 Even in that case, try not to make lines much longer than 80 characters.
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
107 * Code and especially patches is much more readable if limited to a sane
116 Variables are lower_case_with_underscores; easy to type and read.  Structured
117 type names are in CamelCase; harder to type but standing out.  Enum type
121 and is therefore likely to be changed.
138 prefix to alert readers that they are seeing a wrapped version, for
150 to have a consistent prefix to show where they came from. For example,
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
158 If a function is a shim designed to deal with compatibility
160 called directly and aliased to the plain function name via the
207 of blocks. To avoid accidental re-use it is permissible to declare
219 On the other hand, however, it's often best to move that #ifdef/#ifndef
220 block to a separate function altogether.
235 Rationale: Yoda conditions (as in 'if (1 == a)') are awkward to read.
262 about converting to the preferred form unless you're editing that
313 QEMU makes fairly extensive use of the macro pre-processor to
317 achieved by making it easy for the compiler to constant fold or using
318 python scripting to generate grep friendly code.
321 ``.c.inc`` or ``.h.inc`` suffix to make it clear they are being
327 It should be common sense to use the right type, but we have collected
356 address space that can map to host virtual address spaces.  Generally
358 it would not be correct to store an actual guest physical address in a
362 vaddr is the best type to use to hold a CPU virtual address in
363 target-independent code. It is guaranteed to be large enough to hold a
365 to target. It is always unsigned.
376 to be an 'unsigned long' or a pointer type.
380 to use some system interface that requires a type like size_t, pid_t or
383 Also, if you try to use e.g., "unsigned int" as a type, and that
385 it's best just to use the *wrong* type, if "pulling the thread"
388 Finally, while using descriptive types is important, be careful not to
396 Unless a pointer is used to modify the pointed-to storage,
400 pointer, you're guaranteed that it is used to modify the storage
401 it points to, or it is aliased to another pointer that is.
406 Typedefs are used to eliminate the redundant 'struct' keyword, since type
414 of convenience it is also perfectly fine to use forward struct
416 avoids problems with duplicated typedefs and reduces the need to include
423 where `MSVC has a different way to lay them out than GCC
428 structures which are supposed to exactly match a specific layout in guest
455 there is no need to test for failure (as you would have to with
457 result of a failure to allocate memory is going to be a fatal exit
461 Care should be taken to avoid introducing places where the guest could
463 of the order of 4k, a failure to allocate is likely indicative of an
464 overloaded host and allowing ``g_malloc`` to ``exit`` is a reasonable
466 fall-back to a smaller one if need be we should use functions like
499 guarantee a NULL-terminated buffer, which makes it extremely dangerous to use.
500 It also zeros trailing destination bytes out to the specified length.  Instead,
534 string argument and following "..." in its prototype, be sure to use
544 C code in QEMU should be written to the C11 language specification. A
551 implementation defined behavior (to give compiler authors enough leeway to
555 argument...) However there are a few areas where we allow ourselves to
565 given in C99 and C11 to treat aspects of signed '<<' as undefined, as
574 such it has the freedom to make use of a C language extension for
576 out of scope. This can be used to simplify function cleanup paths,
577 often allowing many goto jumps to be eliminated, through automatic
615 Using g_autofree/g_autoptr enables the code to be written as:
632 are still some caveats to beware of
667 that declaration and the new code. It is also useful to separate
669 to make navigation easier.
694 Note that there is no need to provide typedefs for QOM structures
701 QEMU provides a number of ``_GUARD`` macros intended to make the
703 ``QEMU_LOCK_GUARD`` to take a lock will ensure the lock is released on
720 equivalent code without _GUARD macro makes us to carefully put
755 Reporting errors to the human user
763 Use error_printf() & friends to print additional information.
767 automatically.  To manipulate it manually, use the loc_``*``() from
773 An error can't always be reported to the user right where it's detected,
774 but often needs to be propagated up the call chain to a place that can
780 Use the simplest suitable method to communicate success / failure to
781 callers.  Stick to common methods: non-negative on success / -1 on
789 Example: when a function's callers need to report details on failure
792 Do not report an error to the user when you're also returning an error
793 for somebody else to handle.  Leave the reporting to the place that
803 Do not call exit() or abort() to handle an error that can be triggered
805 translation or device emulation).  Guests should not be able to
808 Note that &error_fatal is just another way to exit(1), and &error_abort
809 is just another way to abort().
818 In trace-events files, use a '0x' prefix to specify hex numbers, as in:
839 Rationale: hex numbers are hard to read in logs when there is no 0x prefix,
842 to not use '0x' because for some things notations like %x.%x.%x are used not
850 Rationale: there are two ways to add a '0x' prefix to printed number: '0x%...'