From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mout02.posteo.de (mout02.posteo.de [185.67.36.66]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AAE2F15B126 for ; Mon, 6 May 2024 23:18:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=185.67.36.66 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1715037485; cv=none; b=XUhesikFZawmhC8kgR3xy8VYsOZZRt8q4kwC+hKI+rrUr03nTlPk7Dvj5kukIbsT381tkPq9Ms/8Si6bBArNiQy4ZGDS4rskbR+7lYmfXWse9+J4C8HsHI3RSfECpVprLHyJ13oXVGfOaQyZud5iSuMYxclnaoNena+7nIMHpn0= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1715037485; c=relaxed/simple; bh=mGW9+K91pwJSeBCqfEmqJmTNvzjWv33S8x3z8z3Hc1k=; h=MIME-Version:Content-Type:Date:From:To:Cc:Subject:In-Reply-To: References:Message-ID; b=AWOgjpYdge2bmi3Rd9MMx+I+usJKboGvqdt+gOJa6IOwmeBJrGTE47k37Vz4mMMzSpvw3sIDvtbSUzPkF4CvWEYOjrTqD1aeoKhdcTFFJcgUCeWHg4u7fdSEH/lNRbcwgIZnjNbfpp5NmDh4sDY08718AJy0CshZ7BBBUMz6whI= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net; spf=pass smtp.mailfrom=posteo.net; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b=YgYAxv60; arc=none smtp.client-ip=185.67.36.66 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=posteo.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=posteo.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=posteo.net header.i=@posteo.net header.b="YgYAxv60" Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 883BC240103 for ; Tue, 7 May 2024 01:17:54 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1715037474; bh=mGW9+K91pwJSeBCqfEmqJmTNvzjWv33S8x3z8z3Hc1k=; h=MIME-Version:Content-Type:Content-Transfer-Encoding:Date:From:To: Cc:Subject:Message-ID:From; b=YgYAxv60it9j+0wJBKZIO2LFltJQLwcKuK6wYdG02viEcNv5AhwxQggZWxkPVVUD4 omrUOrInOKGM6OlsJmrg0qKAMC+RxqiYef/NeLU2ikM0WmDdnVH045OA0lsmeeobTK VGrYPyBOWiLMEMpXBhpMeXBI6NxPdmIpt5F1zolqiI4JX8yoQG5aDT2OEEehtzHx0/ acnt47zdOtrdLDmGKp64bNY9xgJBCiHUpJUwTsL0tOssYaxOSptLFAqeyDMW4FcSrz zSHDcXuGNSUuwsKP5a8hf21GqnhvojZlm+9PJJEjU//4wTAntSW0rHPWZib5EEw92U +Y6WM/porbKgQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VYHPs1tCcz9rxB; Tue, 7 May 2024 01:17:53 +0200 (CEST) Precedence: bulk X-Mailing-List: linux-doc@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Date: Mon, 06 May 2024 23:17:53 +0000 From: Yueh-Shun Li To: Randy Dunlap Cc: Jonathan Corbet , Hu Haowen , Alex Shi , Yanteng Si , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h In-Reply-To: <7a0f057c-1544-49e2-9bbe-a46eb33dc8ac@infradead.org> References: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org> <20240108201851.191604-1-shamrocklee@posteo.net> <20240108202217.191839-1-shamrocklee@posteo.net> <7a0f057c-1544-49e2-9bbe-a46eb33dc8ac@infradead.org> Message-ID: On 2024-01-28 14:26, Randy Dunlap wrote: > On 1/8/24 12:22, Yueh-Shun Li wrote: > > In section "18) Don't re-invent the kernel macros" in "Linux kernel > > coding style": > > > > Recommend reusing macros from headers inside include/linux, instead of > > the obsolete include/linux/kernel.h > > > > Change wording > > > > - "The header file contains macros" -> "the header files provide macros" > > Some macros are intended to use inside the header file only, or are > > considered the implementation detail of other facilities. Developers > > are expected to determine if a macro is meant to be used outside the > > header file. > > > > Signed-off-by: Yueh-Shun Li > > Acked-by: Randy Dunlap > Thanks. > Thank you for acknowledging. Anything I could help to push it forward? > > --- > > Documentation/process/coding-style.rst | 24 +++++++++++++----------- > > 1 file changed, 13 insertions(+), 11 deletions(-) > > > > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst > > index 6db37a46d305..2a5c4f4c568c 100644 > > --- a/Documentation/process/coding-style.rst > > +++ b/Documentation/process/coding-style.rst > > @@ -1048,27 +1048,29 @@ readable alternative if the call-sites have naked true/false constants. > > Otherwise limited use of bool in structures and arguments can improve > > readability. > > > > + > > 18) Don't re-invent the kernel macros > > ------------------------------------- > > > > -The header file include/linux/kernel.h contains a number of macros that > > -you should use, rather than explicitly coding some variant of them yourself. > > +The header files in the ``include/linux`` directory provide a number of macros > > +that you should use, rather than explicitly coding some variant of them > > +yourself. > > + > > For example, if you need to calculate the length of an array, take advantage > > -of the macro > > +of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by > > > > .. code-block:: c > > > > - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) > > + #include > > + ARRAY_SIZE(x) // The size of array x > > > > Similarly, if you need to calculate the size of some structure member, use > > +``sizeof_field()`` from ``include/linux/stddef.h``. > > > > -.. code-block:: c > > - > > - #define sizeof_field(t, f) (sizeof(((t*)0)->f)) > > - > > -There are also min() and max() macros that do strict type checking if you > > -need them. Feel free to peruse that header file to see what else is already > > -defined that you shouldn't reproduce in your code. > > +There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h`` > > +that do strict type checking if you need them. Feel free to search across and > > +peruse the header files to see what else is already defined that you shouldn't > > +reproduce in your code. > > > > > > 19) Editor modelines and other cruft Best regards, Yueh-Shun