diff options
author | Alex Bennée <alex.bennee@linaro.org> | 2020-09-09 12:27:32 +0100 |
---|---|---|
committer | Alex Bennée <alex.bennee@linaro.org> | 2020-09-10 10:34:58 +0100 |
commit | bc3bde84484e39cd922486ac7e755d3e29e8a22f (patch) | |
tree | 5ae96c1ee3a617f9a4f59d469e6a259a267946cb /CODING_STYLE.rst | |
parent | 9435a8b3dd35f1f926f1b9127e8a906217a5518a (diff) | |
download | qemu-bc3bde84484e39cd922486ac7e755d3e29e8a22f.zip qemu-bc3bde84484e39cd922486ac7e755d3e29e8a22f.tar.gz qemu-bc3bde84484e39cd922486ac7e755d3e29e8a22f.tar.bz2 |
CODING_STYLE.rst: flesh out our naming conventions.
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.bennee@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20200909112742.25730-2-alex.bennee@linaro.org>
Diffstat (limited to 'CODING_STYLE.rst')
-rw-r--r-- | CODING_STYLE.rst | 37 |
1 files changed, 35 insertions, 2 deletions
diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst index 427699e..8b13ef0 100644 --- a/CODING_STYLE.rst +++ b/CODING_STYLE.rst @@ -109,8 +109,41 @@ 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 +is often held as a ``cs`` pointer variable, whereas the concrete +CPUArchState is usually held in a pointer called ``env``. + +Likewise, in device emulation code the common DeviceState is usually +called ``dev``. + +Function Naming Conventions +--------------------------- + +Wrapped version of standard library or GLib functions use a ``qemu_`` +prefix to alert readers that they are seeing a wrapped version, for +example ``qemu_strtol`` or ``qemu_mutex_lock``. Other utility functions +that are widely called from across the codebase should not have any +prefix, for example ``pstrcpy`` or bit manipulation functions such as +``find_first_bit``. + +The ``qemu_`` prefix is also used for functions that modify global +emulator state, for example ``qemu_add_vm_change_state_handler``. +However, if there is an obvious subsystem-specific prefix it should be +used instead. + +Public functions from a file or subsystem (declared in headers) tend +to have a consistent prefix to show where they came from. For example, +``tlb_`` for functions from ``cputlb.c`` or ``cpu_`` for functions +from cpus.c. + +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``. + Block structure =============== |