[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 01/10] CODING_STYLE.rst: flesh out our naming conventions.
From: |
Alex Bennée |
Subject: |
[PULL 01/10] CODING_STYLE.rst: flesh out our naming conventions. |
Date: |
Thu, 10 Sep 2020 14:14:55 +0100 |
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>
diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst
index 427699e0e42..8b13ef0669e 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
===============
--
2.20.1
- [PULL 00/10] testing and other mix fixes, Alex Bennée, 2020/09/10
- [PULL 01/10] CODING_STYLE.rst: flesh out our naming conventions.,
Alex Bennée <=
- [PULL 02/10] usb-host: restrict workaround to new libusb versions, Alex Bennée, 2020/09/10
- [PULL 05/10] docs/system/deprecated: mark ppc64abi32-linux-user for deprecation, Alex Bennée, 2020/09/10
- [PULL 04/10] target/mips: simplify gen_compute_imm_branch logic, Alex Bennée, 2020/09/10
- [PULL 03/10] tests/meson.build: fp tests don't need CONFIG_TCG, Alex Bennée, 2020/09/10
- [PULL 07/10] hw/i386: make explicit clearing of pch_rev_id, Alex Bennée, 2020/09/10
- [PULL 06/10] configure: don't enable ppc64abi32-linux-user by default, Alex Bennée, 2020/09/10
- [PULL 10/10] plugins: move the more involved plugins to contrib, Alex Bennée, 2020/09/10