From: Yueh-Shun Li <shamrocklee@posteo.net>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>,
Hu Haowen <src.res.211@gmail.com>, Alex Shi <alexs@kernel.org>,
Yanteng Si <siyanteng@loongson.cn>,
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
Date: Mon, 06 May 2024 23:17:53 +0000 [thread overview]
Message-ID: <f20b378af31b080a01bfdef0e15b01d8@posteo.net> (raw)
In-Reply-To: <7a0f057c-1544-49e2-9bbe-a46eb33dc8ac@infradead.org>
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 <shamrocklee@posteo.net>
>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> 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 <linux/array_size.h>
> > + 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
prev parent reply other threads:[~2024-05-06 23:18 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-17 23:46 Irrelevant documentation recommending the use of "include/linux/kernel.h" Yueh-Shun Li
2024-01-05 22:49 ` Randy Dunlap
2024-01-08 16:03 ` [PATCH 0/4] coding-style: recommend reusing macros from split headers instead of kernel.h Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 1/4] coding-style: recommend " Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions Yueh-Shun Li
2024-01-08 16:28 ` Jonathan Corbet
2024-01-08 18:23 ` Yueh-Shun Li
2024-01-08 18:27 ` Jonathan Corbet
2024-01-08 16:03 ` [PATCH 3/4] doc/zh_TW: coding-style: update content for section 18 Yueh-Shun Li
2024-01-08 16:03 ` [PATCH 4/4] doc/zh_CN: coding-style: update content of " Yueh-Shun Li
2024-01-08 19:37 ` [PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h Yueh-Shun Li
2024-01-08 20:17 ` Yueh-Shun Li
2024-01-08 20:18 ` [PATCH v3 0/1] " Yueh-Shun Li
2024-01-08 20:22 ` [PATCH v3 1/1] coding-style: recommend " Yueh-Shun Li
2024-01-28 6:26 ` Randy Dunlap
2024-05-06 23:17 ` Yueh-Shun Li [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f20b378af31b080a01bfdef0e15b01d8@posteo.net \
--to=shamrocklee@posteo.net \
--cc=alexs@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=rdunlap@infradead.org \
--cc=siyanteng@loongson.cn \
--cc=src.res.211@gmail.com \
--cc=workflows@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).