Claudio Fontana <cfont...@suse.de> writes:
> On 8/6/20 1:40 PM, Alex Bennée 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 >> +independent CPUState this is often 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 >> +called ``dev`` with the actual state structure often the very terse >> +``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``. >> + >> +Public functions (i.e. declared in public headers) tend to be prefixes >> +with the subsystem or file they came from. For example ``tlb_`` for >> +functions from ``cputlb.c`` or ``cpu_`` for functions from cpus.c. > > Hi Alex, > > agree with the sentiment, for cpus.c I would suggest cpus_ though. > > There are otherwise so many cpu_ functions and cpu.c modules.. using > cpus_ would help a lot to understand that it is part of softmmu/cpus.c > > Wdyt? I was mainly documenting existing conventions - I guess cpus is a poor example to follow as it has so many cpu_ functions in them. I guess the prefix is a loose association at best. > Also cpus.c contains a lot of qemu_ that is not used to wrap standard > library functions. Certainly a lot of the static internal functions could be shorted names dropping the qemu_ prefix. Most uses of qemu_ across the code base are utility functions although not all wrap existing functions. > After the current cpus refactoring, I could take care of improving the > naming conventions in cpus.c I wouldn't expend a lot of effort on a grand re-naming but certainly it's worth cleaning stuff up as you go moving things about. > > Thanks, > > Claudio > > >> + >> Block structure >> =============== >> >> -- Alex Bennée