On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" <[email protected]> wrote: > Standardize parameters ordering in some typical cases to minimize > confusion. > > Signed-off-by: Yury Norov (NVIDIA) <[email protected]> > --- > Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++ > 1 file changed, 48 insertions(+) > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index d1a8e5465ed9..dde24148305c 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -523,6 +523,54 @@ below, compared to the **declaration** example above):: > ... > } > > +6.2) Function parameters order > +------------------------------ > + > +The order of parameters is important both for code generation and > readability. > +Passing parameters in an unusual order is a common source of bugs. Listing > +them in standard widely adopted order helps to avoid confusion. > + > +Many ABIs put first function parameter and return value in R0. If your > +function returns one of its parameters, passing it at the very beginning > +would lead to a better code generation. For example:: > + > + void *memset64(uint64_t *s, uint64_t v, size_t count); > + void *memcpy(void *dest, const void *src, size_t count); > + > +If your function doesn't propagate a parameter, but has a meaning of copying > +and/or processing data, the best practice is following the traditional order: > +destination, source, options, flags. > + > +for_each()-like iterators should take an enumerator the first. For example:: > + > + for_each_set_bit(bit, mask, nbits); > + do_something(bit); > + > + list_for_each_entry(pos, head, member); > + do_something(pos); > + > +If function operates on a range or ranges of data, corresponding parameters > +may be described as ``start - end`` or ``start - size`` pairs. In both cases, > +the parameters should follow each other. For example:: > + > + int > + check_range(unsigned long vstart, unsigned long vend, > + unsigned long kstart, unsigned long kend); > + > + static inline void flush_icache_range(unsigned long start, unsigned > long end); > + > + static inline void flush_icache_user_page(struct vm_area_struct *vma, > + struct page *page, > + unsigned long addr, int len); > + > +Both ``start`` and ``end`` of the interval are inclusive. > + > +Describing intervals in order ``end - start`` is unfavorable. One notable > +example is the ``GENMASK(high, low)`` macro. While such a notation is popular > +in hardware context, particularly to describe registers structure, in context > +of software development it looks counter intuitive and confusing. Please > switch > +to an equivalent ``BITS(low, high)`` version. > +
GENMASK when used for defining hardware registers is completely fine, and *much* easier to deal with when you cross check against the specs that almost invariably define high:low. Which other parts of coding style take on specific interfaces and tell you to switch? Weird. I for one don't want to encourage an influx of trivial patches doing GENMASK to BITS conversions, and then keep rejecting them. It's just a huge collective waste of time. Anyway, that's a lot of text on "function parameter order" to justify BITS(), but completely skips more important principles such as "context parameter first", or "destination first". BR, Jani. > 7) Centralized exiting of functions > ----------------------------------- -- Jani Nikula, Intel
