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
117 type names are in CamelCase; harder to type but standing out.  Enum type
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
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
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 ----------------------------------
428 Use of the ``malloc/free/realloc/calloc/valloc/memalign/posix_memalign``
436 ``malloc``). Generally using ``g_malloc`` on start-up is fine as the
438 anyway. There may be some start-up cases where failing is unreasonable
446 fall-back to a smaller one if need be we should use functions like
448 for a time/space trade-off like ``tlb_mmu_resize_locked`` in the
453 by using ``g_autofree`` and related annotations. See :ref:`autofree-ref`
466 .. code-block:: c
479 guarantee a NULL-terminated buffer, which makes it extremely dangerous to use.
483 .. code-block:: c
489 .. code-block:: c
498 .. code-block:: c
510 Printf-style functions
513 Whenever you add a new printf-style function, i.e., one with a format
517 This makes it so gcc's -Wformat and -Wformat-security options can do
518 their jobs and cross-check format strings with the number and types
528     `<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1548.pdf>`_
548 .. _autofree-ref:
558 free'ing of memory.
563   `<https://developer.gnome.org/glib/stable/glib-Miscellaneous-Macros.html>`_
567 * g_autofree - will invoke g_free() on the variable going out of scope
569 * g_autoptr - for structs / objects, will invoke the cleanup func created
575 .. code-block:: c
579         int ret = -1;
597 .. code-block:: c
605            return -1;
611 While this generally results in simpler, less leak-prone code, there
623 .. code-block:: c
655 .. code-block:: c
686 .. code-block:: c
690         QEMU_LOCK_GUARD(&s->lock);
693             return -1;
699 will ensure s->lock is released however the function is exited. The
703 .. code-block:: c
707         qemu_mutex_lock(&s->lock);
710             qemu_mutex_unlock(&s->lock);
711             return -1;
714         qemu_mutex_unlock(&s->lock);
721 .. code-block:: c
724         QTAILQ_FOREACH_RCU(kid, &bus->children, sibling) {
725             err = do_the_thing(kid->child);
736 ----------------------------------
739 error_report() or error_vreport() from error-report.h.  This ensures the
748 error-report.h.
751 ------------------
761 callers.  Stick to common methods: non-negative on success / -1 on
762 error, non-negative / -errno, non-null / null, or Error objects.
764 Example: when a function returns a non-null pointer on success, and it
777 ---------------
792 trace-events style
796 ---------
798 In trace-events files, use a '0x' prefix to specify hex numbers, as in:
800 .. code-block:: c
808 .. code-block:: c
815 .. code-block:: c
826 ---------------