OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

CODING_STYLE.rst: flesh out our naming conventions.

Browse Source 
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>
This commit is contained in:
Alex Bennée 2020-09-09 12:27:32 +01:00
parent 9435a8b3dd
commit bc3bde8448
1 changed files with 35 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
CODING_STYLE.rst
View File

@ -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
===============