On Thu, 6 Aug 2020 12:40:36 +0100 Alex Bennée <alex.ben...@linaro.org> wrote:
> 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> > --- > CODING_STYLE.rst | 23 +++++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/CODING_STYLE.rst b/CODING_STYLE.rst > index 427699e0e42..17cb42ba761 100644 > --- a/CODING_STYLE.rst > +++ b/CODING_STYLE.rst > @@ -109,9 +109,32 @@ 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. > > +Variable Naming Conventions > +--------------------------- > + > +A number of common short naming conventions exist for variables that use > +common QEMU types. For example when dealing with the architecture s/example/example,/ > +independent CPUState this is often in a ``cs`` pointer variable "the architecture independent CPUState is often held in 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 s/Likewise/Likewise,/ > +called ``dev`` with the actual state structure often the very terse "while the actual statue structure often uses..." ? > +``s`` or maybe ``foodev``. > + > +Function Naming Conventions > +--------------------------- > + > When wrapping standard library functions, use the prefix ``qemu_`` to alert > readers that they are seeing a wrapped version; otherwise avoid this prefix. > > +Functions that are expected to be called with some sort of lock held > +usually have the suffix ``_locked``. Hm, I think this is mostly for those cases where you have two versions? What about: "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 usually uses the suffix ``_locked``." > + > +Public functions (i.e. declared in public headers) tend to be prefixes s/prefixes/prefixed/ > +with the subsystem or file they came from. For example ``tlb_`` for s/example/example,/ > +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c. > + > Block structure > =============== >
