docs/devel/style.rst

41 * It is the QEMU coding style.
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
106   let them keep doing it.
111 * It is the QEMU coding style.
146 However, if there is an obvious subsystem-specific prefix it should be
161 pre-processor. Another common suffix is ``_impl``; it is used for the
189 and clarity it comes on a line by itself:
200 Furthermore, it is the QEMU coding style.
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
296 of core system headers like <stdint.h>.  It must be the first include so that
301 already included it.
315 processor isn't discouraged it can make debugging and code navigation
317 achieved by making it easy for the compiler to constant fold or using
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
334 If a variable is counting something, it should be declared with an
337 If it's host memory-size related, size_t should be a good choice (use
339 but only for RAM, it may not cover whole guest address space.
341 If it's file-size related, use off_t.
342 If it's file-offset related (i.e., signed), use off_t.
343 If it's just counting small numbers use "unsigned int";
358 it would not be correct to store an actual guest physical address in a
363 target-independent code. It is guaranteed to be large enough to hold a
364 virtual address for any target, and it does not change size from target
365 to target. It is always unsigned.
367 it may be 32 or 64 bits depending on which target is being built. It should
385 it's best just to use the *wrong* type, if "pulling the thread"
397 give it the "const" attribute.  That way, the reader knows
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.
414 of convenience it is also perfectly fine to use forward struct
429 memory. Some existing code may use it, and we carefully ensured the layout was
481 * It catches multiplication overflowing size_t;
482 * It returns T ``*`` instead of void ``*``, letting compiler catch more type errors.
498 Do not use the strncpy function.  As mentioned in the man page, it does *not*
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,
507 Don't use strcat because it can't check for buffer overflows, but:
537 This makes it so gcc's -Wformat and -Wformat-security options can do
554 constructs. ("It works fine on the gcc I tested it with" is not a valid
562   the sign bit (ie it is an arithmetic shift, not a logical shift)
574 such it has the freedom to make use of a C language extension for
667 that declaration and the new code. It is also useful to separate
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,
775 handle it.  This can be done in various ways.
784 Example: when a function returns a non-null pointer on success, and it
800 startup.  It's problematic during normal operation.  In particular,
833 it is obvious that numbers are in hex, ex.:
854 * it is more popular