docs/devel/style.rst

16 getting the right settings for your preferred $EDITOR. See
17 `<https://editorconfig.org/>`_ for details.
51 * while/for
55 for the following lines.
57 In case of if/else, while/for, align the secondary lines just after the
60 For example:
75 For example:
126 A number of short naming conventions exist for variables that use
127 common QEMU types. For example, the architecture independent CPUState
138 prefix to alert readers that they are seeing a wrapped version, for
141 prefix, for example ``pstrcpy`` or bit manipulation functions such as
144 The ``qemu_`` prefix is also used for functions that modify global
145 emulator state, for example ``qemu_add_vm_change_state_handler``.
150 to have a consistent prefix to show where they came from. For example,
151 ``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions
161 pre-processor. Another common suffix is ``_impl``; it is used for the
185 else if/else if/.../else sequence would need an indent for every else
188 An exception is the opening brace for a function; for reasons of tradition
198 Rationale: a consistent (except for functions...) bracing style reduces
208 loop variables inside for loops:
212     for (int i = 0; i < ARRAY_SIZE(thing); i++) {
216 Every now and then, an exception is made for declarations inside a
225 When comparing a variable for (in)equality with a constant, list the
277 For variadic macros, stick with this C99-like syntax:
304 If exceptions are needed for some reason, they must be documented in
317 achieved by making it easy for the compiler to constant fold or using
322 included for expansion.
339 but only for RAM, it may not cover whole guest address space.
349 mandatory for VMState fields.
353 Use hwaddr for guest physical addresses except pcibus_t
354 for PCI addresses.  In addition, ram_addr_t is a QEMU internal address
361 For CPU virtual addresses there are several possible types.
364 virtual address for any target, and it does not change size from target
371 abi_ulong is for the ``*``-user targets, and represents a type the size of
375 the target's ABI must use this type for anything that on the target is defined
381 off_t, use matching types for any corresponding variables.
390 casts, then reconsider or ask for help.
412 them and declare a typedef only in one header file.  For common types,
413 you can use "include/qemu/typedefs.h" for example.  However, as a matter
427 For this reason, we disallow usage of bitfields in packed structures and in any
437 for bitfields.
455 there is no need to test for failure (as you would have to with
459 (for example speculatively loading a large debug symbol table).
462 trigger an exit by causing a large allocation. For small allocations,
465 approach. However for larger allocations where we could realistically
467 ``g_try_new`` and check the result. For example this is valid approach
468 for a time/space trade-off like ``tlb_mmu_resize_locked`` in the
474 for more details.
478 Prefer ``g_new(T, n)`` instead of ``g_malloc(sizeof(T) * n)`` for the following
507 Don't use strcat because it can't check for buffer overflows, but:
524 There are also replacement character processing macros for isxyz and toxyz,
574 such it has the freedom to make use of a C language extension for
580 The GLib2 library provides a number of functions/macros for enabling
589 * g_autoptr - for structs / objects, will invoke the cleanup func created
591   supported for most GLib data types and GObjects
593 For example, instead of
664 The QEMU Object Model (QOM) provides a framework for handling objects
668 backing for properties (options driven by the user) and internal state
671 For a storage structure the first declaration should always be called
672 "parent_obj" and for a class structure the first member should always
694 Note that there is no need to provide typedefs for QOM structures
696 See :ref:`qom` for more details.
702 handling of multiple exit paths easier. For example using
777 The most flexible one is Error objects.  See error.h for usage
793 for somebody else to handle.  Leave the reporting to the place that
824 An exception is made for groups of numbers that are hexadecimal by
832 However, you can use '0x' for such groups if you want. Anyway, be sure that
842 to not use '0x' because for some things notations like %x.%x.%x are used not
851 and '%#...'. For consistency the only one way should be used. Arguments for
855 * '%#' omits the 0x for the value 0 which makes output inconsistent