From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id BF70ACCF9E5 for ; Mon, 27 Oct 2025 18:43:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender:List-Subscribe:List-Help :List-Post:List-Archive:List-Unsubscribe:List-Id:Content-Transfer-Encoding: Content-Type:In-Reply-To:From:References:To:Subject:MIME-Version:Date: Message-ID:Reply-To:Cc:Content-ID:Content-Description:Resent-Date:Resent-From :Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=kuIVSUiix3AgqKsXyCQ0motbBK2F3l1jAUwSf8sfp9Q=; b=br+E7ztN5YiGBljvGwxkL0lW8u bOGIhHqVR3Fs6bp5PP+VbCbMKcZS9zv083Bi4cgOiopGTMR6jXusmdsEFInmNgbfr4uLUzHutiP+v EBEGqcxiiF4m2hxWeZ+b9ROIUN+LsdmopbijhSCRkRJWwLo/q1uK69L+tFSrZGCW1//H3QBimHJMx jgEqoczI1rlHeK+GvMSEE4vDJiy9BBrKm5eHLet9UvC33vsix50lu2XHlUGLAHyOojzqtv5z76reK iLqbNAxMQQ56GSs3UO0BylB6oB9Cx/XyHbpSn52Sn2jAEuxNyjE+8Mvm4H0z0ER7sbxt0P8lVAOA3 m4gSRaYA==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.98.2 #2 (Red Hat Linux)) id 1vDSBk-0000000EYti-0I3p; Mon, 27 Oct 2025 18:43:28 +0000 Received: from [50.53.43.113] (helo=[192.168.254.34]) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1vDSBj-0000000EYtK-2mcO; Mon, 27 Oct 2025 18:43:27 +0000 Message-ID: <2ab04392-f133-4ebe-943a-c58050b36f13@infradead.org> Date: Mon, 27 Oct 2025 11:43:27 -0700 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH 21/21] Docs: add Functions parameters order section To: Jani Nikula , "Yury Norov (NVIDIA)" , Linus Walleij , Lee Jones , linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, Jonathan Corbet , workflows@vger.kernel.org, linux-doc@vger.kernel.org References: <20251025162858.305236-1-yury.norov@gmail.com> <20251025163305.306787-14-yury.norov@gmail.com> <723c936f92352352c3b1a84b858d684f5b7a0834@intel.com> Content-Language: en-US From: Randy Dunlap In-Reply-To: <723c936f92352352c3b1a84b858d684f5b7a0834@intel.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org On 10/27/25 2:02 AM, Jani Nikula wrote: > On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" wrote: >> Standardize parameters ordering in some typical cases to minimize >> confusion. >> >> Signed-off-by: Yury Norov (NVIDIA) >> --- >> 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". and usually flags or gfp_t last (if they are used). There are several exceptions to these, but consistency helps and lack of it has caused some argument problems in the past. -- ~Randy