Mention a few of the more common naming conventions we follow in the code base including common variable names and function prefix and suffix examples.
Signed-off-by: Alex Bennée <alex.ben...@linaro.org> --- v2 - punctuation fixes suggested by Cornelia - re-worded section on qemu_ prefix - expanded on _locked suffix --- CODING_STYLE.rst | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 427699e0e42..e7ae44aed7f 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -109,8 +109,34 @@ names are lower_case_with_underscores_ending_with_a_t, like the POSIX uint64_t and family. Note that this last convention contradicts POSIX and is therefore likely to be changed. -When wrapping standard library functions, use the prefix ``qemu_`` to alert -readers that they are seeing a wrapped version; otherwise avoid this prefix. +Variable Naming Conventions +--------------------------- + +A number of short naming conventions exist for variables that use +common QEMU types. For example, the architecture independent CPUState +this is often held as a ``cs`` pointer variable, whereas the concrete +CPUArchState us usually held in a pointer called ``env``. + +Likewise, in device emulation code the common DeviceState is usually +called ``dev`` with the actual status structure often uses the terse +``s`` or maybe ``foodev``. + +Function Naming Conventions +--------------------------- + +The ``qemu_`` prefix is used for utility functions that are widely +called from across the code-base. This includes wrapped versions of +standard library functions (e.g. qemu_strtol) where the prefix is +added to the function name to alert readers that they are seeing a +wrapped version; otherwise avoid this prefix. + +If there are two versions of a function to be called with or without a +lock held, the function that expects the lock to be already held +usually uses the suffix ``_locked``. + +Public functions (i.e. declared in public headers) tend to be prefixed +with the subsystem or file they came from. For example, ``tlb_`` for +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c. Block structure =============== -- 2.20.1
