docs/devel/style.rst

1 .. _coding-style:
39 * Tabs are rendered badly in patches, causing off-by-one errors in almost
46 ----------------
62 .. code-block:: c
77 .. code-block:: c
100 as a guard against obviously-overlength lines, not a target.)
109 * The four-space indentation makes the most common excuse ("But look
124 ---------------------------
135 ---------------------------
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
174 .. code-block:: c
191 .. code-block:: c
207 of blocks. To avoid accidental re-use it is permissible to declare
210 .. code-block:: c
228 .. code-block:: c
236 Besides, good compilers already warn users when '==' is mis-typed as '=',
242 We use traditional C-style /``*`` ``*``/ comments and avoid // comments.
250 .. code-block:: c
275 ---------------
277 For variadic macros, stick with this C99-like syntax:
279 .. code-block:: c
285 ------------------
289 .. code-block:: c
292     #include <...>           /* then system headers... */
296 of core system headers like <stdint.h>.  It must be the first include so that
297 core system headers included by external libraries get the preprocessor macros
311 -------------------
313 QEMU makes fairly extensive use of the macro pre-processor to
331 -------
337 If it's host memory-size related, size_t should be a good choice (use
341 If it's file-size related, use off_t.
342 If it's file-offset related (i.e., signed), use off_t.
363 target-independent code. It is guaranteed to be large enough to hold a
368 therefore be used only in target-specific code, and in some
369 performance-critical built-per-target core code such as the TLB code.
371 abi_ulong is for the ``*``-user targets, and represents a type the size of
380 to use some system interface that requires a type like size_t, pid_t or
393 --------
395 Ensure that all of your pointers are "const-correct".
396 Unless a pointer is used to modify the pointed-to storage,
398 up-front that this is a read-only pointer.  Perhaps more
399 importantly, if we're diligent about this, when you see a non-const
404 --------
420 ---------
422 C bitfields can be a cause of non-portability issues, especially under windows
424 <https://gcc.gnu.org/onlinedocs/gcc/x86-Type-Attributes.html>`_, or where
440 ----------------------------------
456 ``malloc``). Generally using ``g_malloc`` on start-up is fine as the
458 anyway. There may be some start-up cases where failing is unreasonable
466 fall-back to a smaller one if need be we should use functions like
468 for a time/space trade-off like ``tlb_mmu_resize_locked`` in the
473 by using ``g_autofree`` and related annotations. See :ref:`autofree-ref`
486 .. code-block:: c
493 ``qemu_vfree``, since breaking this will cause problems on Win32.
499 guarantee a NULL-terminated buffer, which makes it extremely dangerous to use.
503 .. code-block:: c
509 .. code-block:: c
518 .. code-block:: c
530 Printf-style functions
533 Whenever you add a new printf-style function, i.e., one with a format
537 This makes it so gcc's -Wformat and -Wformat-security options can do
538 their jobs and cross-check format strings with the number and types
548     `<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1548.pdf>`_
568 .. _autofree-ref:
583   `<https://developer.gnome.org/glib/stable/glib-Miscellaneous-Macros.html>`_
587 * g_autofree - will invoke g_free() on the variable going out of scope
589 * g_autoptr - for structs / objects, will invoke the cleanup func created
595 .. code-block:: c
599         int ret = -1;
617 .. code-block:: c
625            return -1;
631 While this generally results in simpler, less leak-prone code, there
643 .. code-block:: c
675 .. code-block:: c
706 .. code-block:: c
710         QEMU_LOCK_GUARD(&s->lock);
713             return -1;
719 will ensure s->lock is released however the function is exited. The
723 .. code-block:: c
727         qemu_mutex_lock(&s->lock);
730             qemu_mutex_unlock(&s->lock);
731             return -1;
734         qemu_mutex_unlock(&s->lock);
741 .. code-block:: c
744         QTAILQ_FOREACH_RCU(kid, &bus->children, sibling) {
745             err = do_the_thing(kid->child);
756 ----------------------------------
759 error_report() or error_vreport() from error-report.h.  This ensures the
768 error-report.h.
771 ------------------
781 callers.  Stick to common methods: non-negative on success / -1 on
782 error, non-negative / -errno, non-null / null, or Error objects.
784 Example: when a function returns a non-null pointer on success, and it
797 ---------------
812 trace-events style
816 ---------
818 In trace-events files, use a '0x' prefix to specify hex numbers, as in:
820 .. code-block:: c
828 .. code-block:: c
835 .. code-block:: c
846 ---------------