[PATCH 0/4] coding-style: recommend reusing macros from split headers instead of kernel.h

[PATCH 0/4] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

This series of patches targets the "Linux kernel coding style"
documentation and recommend reusing macros inside the include/linux
directory instead of the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[1][2] and help deprecating "kernel.h".

If applied, developers will no longer be confused by the contradiction
between "Linux kernel style guide" suggestions and the deprecation
notice on top of "kernel.h".

There's also a patch that adds an example to show how reusing macro
definition from shared headers help prevent naming collisions.

This series contains the update to the zh_TW and zh_CN translation of
the corresponding documentation changes.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[2]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/

Yueh-Shun Li (4):
  coding-style: recommend split headers instead of kernel.h
  coding-style: show how reusing macros prevents naming collisions
  doc/zh_TW: coding-style: update content for section 18
  doc/zh_CN: coding-style: update content of section 18

 Documentation/process/coding-style.rst        | 41 +++++++++++++++----
 .../zh_CN/process/coding-style.rst            | 39 ++++++++++++++----
 .../zh_TW/process/coding-style.rst            | 39 ++++++++++++++----
 3 files changed, 95 insertions(+), 24 deletions(-)

-- 
2.42.0

[PATCH 1/4] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

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>
---
 Documentation/process/coding-style.rst | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 6db37a46d305..2504cb00a961 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1048,27 +1048,30 @@ 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 in ``include/linux/minmax.h``
+that do strict type checking if you need them.
 
-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.
+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
-- 
2.42.0

[PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Yueh-Shun Li]

In section "18) Don't re-invent the kernel macros" in "Linux kernel
coding style":

Show how reusing macros from shared headers prevents naming collisions
using "stringify", the one of the most widely reinvented macro, as an
example.

This patch aims to provide a stronger reason to reuse shared macros,
by showing the risk of improvised macro variants.

Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
---
 Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 2504cb00a961..1e79aba4b346 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some structure member, use
 There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
 that do strict type checking if you need them.
 
+Using existing macros provided by the shared headers also prevents naming
+collisions. For example, if one developer define in ``foo.h``
+
+.. code-block:: c
+
+	#define __stringify(x) __stringify_1(x)
+	#define __stringify_1(x) #x
+
+and another define in ``bar.h``
+
+.. code-block:: c
+
+	#define stringify(x) __stringify(x)
+	#define __stringify(x) #x
+
+When both headers are ``#include``-d into the same file, the facilities provided
+by ``foo.h`` might be broken by ``bar.h``.
+
+If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` provided by
+``include/linux/stringify.h``, they wouldn't have stepped onto each other's
+toes.
+
 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.
 
-- 
2.42.0

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li <shamrocklee@posteo.net> writes:

> In section "18) Don't re-invent the kernel macros" in "Linux kernel
> coding style":
>
> Show how reusing macros from shared headers prevents naming collisions
> using "stringify", the one of the most widely reinvented macro, as an
> example.
>
> This patch aims to provide a stronger reason to reuse shared macros,
> by showing the risk of improvised macro variants.
>
> Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
> ---
>  Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 2504cb00a961..1e79aba4b346 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of some structure member, use
>  There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
>  that do strict type checking if you need them.
>  
> +Using existing macros provided by the shared headers also prevents naming
> +collisions. For example, if one developer define in ``foo.h``
> +
> +.. code-block:: c
> +
> +	#define __stringify(x) __stringify_1(x)
> +	#define __stringify_1(x) #x
> +
> +and another define in ``bar.h``
> +
> +.. code-block:: c
> +
> +	#define stringify(x) __stringify(x)
> +	#define __stringify(x) #x
> +
> +When both headers are ``#include``-d into the same file, the facilities provided
> +by ``foo.h`` might be broken by ``bar.h``.
> +
> +If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` provided by
> +``include/linux/stringify.h``, they wouldn't have stepped onto each other's
> +toes.
> +

So everything we add to our documentation has a cost in terms of reader
attention.  We ask people to read through a lot of material now, and
should only increase that ask for good reason.

With that context, I have to wonder whether we really need to tell our
readers, who are supposed to be capable developers, that reuse can help
to avoid name collisions?

Thanks,

jon

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Yueh-Shun Li]

Dear Mr. Corbet,

Thank you very much for your feed back.

On 2024-01-09 00:28, Jonathan Corbet wrote:
> Yueh-Shun Li <shamrocklee@posteo.net> writes:
> 
>> In section "18) Don't re-invent the kernel macros" in "Linux kernel
>> coding style":
>> 
>> Show how reusing macros from shared headers prevents naming collisions
>> using "stringify", the one of the most widely reinvented macro, as an
>> example.
>> 
>> This patch aims to provide a stronger reason to reuse shared macros,
>> by showing the risk of improvised macro variants.
>> 
>> Signed-off-by: Yueh-Shun Li <shamrocklee@posteo.net>
>> ---
>>  Documentation/process/coding-style.rst | 22 ++++++++++++++++++++++
>>  1 file changed, 22 insertions(+)
>> 
>> diff --git a/Documentation/process/coding-style.rst 
>> b/Documentation/process/coding-style.rst
>> index 2504cb00a961..1e79aba4b346 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -1070,6 +1070,28 @@ Similarly, if you need to calculate the size of 
>> some structure member, use
>>  There are also ``min()`` and ``max()`` macros in 
>> ``include/linux/minmax.h``
>>  that do strict type checking if you need them.
>> 
>> +Using existing macros provided by the shared headers also prevents 
>> naming
>> +collisions. For example, if one developer define in ``foo.h``
>> +
>> +.. code-block:: c
>> +
>> +	#define __stringify(x) __stringify_1(x)
>> +	#define __stringify_1(x) #x
>> +
>> +and another define in ``bar.h``
>> +
>> +.. code-block:: c
>> +
>> +	#define stringify(x) __stringify(x)
>> +	#define __stringify(x) #x
>> +
>> +When both headers are ``#include``-d into the same file, the 
>> facilities provided
>> +by ``foo.h`` might be broken by ``bar.h``.
>> +
>> +If both ``foo.h`` and ``bar.h``  use the macro ``__stringify()`` 
>> provided by
>> +``include/linux/stringify.h``, they wouldn't have stepped onto each 
>> other's
>> +toes.
>> +
> 
> So everything we add to our documentation has a cost in terms of reader
> attention.  We ask people to read through a lot of material now, and
> should only increase that ask for good reason.
> 
> With that context, I have to wonder whether we really need to tell our
> readers, who are supposed to be capable developers, that reuse can help
> to avoid name collisions?
> 

The motivation comes from existing inconsistency of the "__stringify()" 
macro
definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.

I agree that increasing the length of the documentation without 
substantial
benefits would not be helpful for the readers, and doubling the length 
of a
section is too much for its purpose.

Should I shorten it into one sentence, like

```
On the other hand, locally-defined variants, such as ``#define 
__stringify(x) #x``,
could lead to naming collisions that break otherwise functioning 
facilities.
```

or just omit it in the next version of patches?

> Thanks,
> 
> jon

Thank you for your time and guidance.

Shamrock

Re: [PATCH 2/4] coding-style: show how reusing macros prevents naming collisions

[Jonathan Corbet]

Yueh-Shun Li <shamrocklee@posteo.net> writes:

>> So everything we add to our documentation has a cost in terms of reader
>> attention.  We ask people to read through a lot of material now, and
>> should only increase that ask for good reason.
>> 
>> With that context, I have to wonder whether we really need to tell our
>> readers, who are supposed to be capable developers, that reuse can help
>> to avoid name collisions?
>> 
>
> The motivation comes from existing inconsistency of the "__stringify()" 
> macro
> definition between e.g. "samples/bpf/tracex5.bpf.c" and other files.
>
> I agree that increasing the length of the documentation without
> substantial benefits would not be helpful for the readers, and
> doubling the length of a section is too much for its purpose.
>
> Should I shorten it into one sentence, like
>
> ```
> On the other hand, locally-defined variants, such as ``#define 
> __stringify(x) #x``,
> could lead to naming collisions that break otherwise functioning 
> facilities.
> ```
>
> or just omit it in the next version of patches?

My own feeling (others may well disagree) is that this isn't worth
mentioning in the coding-style document.  What you *could* do is to fix
the redefinitions (if that hasn't happened yet) and make sure that the
macros in question are covered in our kernel documentation.

Thanks,

jon

[PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

In this version of patch series, I drop the patch abouth the nameing
conflicts caused by locally-defined macro variants to streamline the
documentation.[1]

This series of patches targets the "Linux kernel coding style"
documentation and recommend reusing macros inside the include/linux
directory instead of the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[2][3] and help deprecating "kernel.h".

This series contains the update to the zh_TW and zh_CN translation of
the corresponding documentation changes.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/
[2]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[3]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/

Yueh-Shun Li (3):
  coding-style: recommend split headers instead of kernel.h
  doc/zh_TW: coding-style: update content for section 18
  doc/zh_CN: coding-style: update content of section 18

 Documentation/process/coding-style.rst        | 24 ++++++++++---------
 .../zh_CN/process/coding-style.rst            | 22 ++++++++---------
 .../zh_TW/process/coding-style.rst            | 22 ++++++++---------
 3 files changed, 35 insertions(+), 33 deletions(-)

-- 
2.42.0

Re: [PATCH v2 0/3] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

On 2024-01-09 03:37, Yueh-Shun Li wrote:
> Dear Maintainers,
> 
> In this version of patch series, I drop the patch abouth the nameing
> conflicts caused by locally-defined macro variants to streamline the
> documentation.[1]
> 
> This series of patches targets the "Linux kernel coding style"
> documentation and recommend reusing macros inside the include/linux
> directory instead of the obsolete header "include/linux/kernel.h".
> 
> This addresses the issue 'Irrelevant documentation recommending the use
> of "include/linux/kernel.h"'[2][3] and help deprecating "kernel.h".
> 
> This series contains the update to the zh_TW and zh_CN translation of
> the corresponding documentation changes.
> 
> Best regards,
> 
> Shamrock
> 
> [1]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/
> [2]:
> https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
> [3]:
> https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/
> 
> Yueh-Shun Li (3):
>   coding-style: recommend split headers instead of kernel.h
>   doc/zh_TW: coding-style: update content for section 18
>   doc/zh_CN: coding-style: update content of section 18
> 
>  Documentation/process/coding-style.rst        | 24 ++++++++++---------
>  .../zh_CN/process/coding-style.rst            | 22 ++++++++---------
>  .../zh_TW/process/coding-style.rst            | 22 ++++++++---------
>  3 files changed, 35 insertions(+), 33 deletions(-)

This series of patches didn't make it to the lists due to my loose ends.
Sorry for the noise.

Sincerely,

Shamrock

[PATCH v3 0/1] coding-style: recommend reusing macros from split headers instead of kernel.h

[Yueh-Shun Li]

Dear Maintainers,

This patch targets the "Linux kernel coding style" documentation and
recommend reusing macros inside the include/linux directory instead of
the obsolete header "include/linux/kernel.h".

This addresses the issue 'Irrelevant documentation recommending the use
of "include/linux/kernel.h"'[1][2] and help deprecating "kernel.h".

Changes in this roll:

Drop the patch mentioning the naming collisions caused by
locally-defined macro variants.[3]

Drop the patches that updates the zh_TW and zh_CN translation. I'll
send them again once the change of the untranslated documentation gets
ready.

Best regards,

Shamrock

[1]: https://lore.kernel.org/linux-doc/bc63acd7ef43bdd8d9609fa48dbf92f9@posteo.net/
[2]: https://lore.kernel.org/linux-doc/107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org/
[3]: https://lore.kernel.org/linux-doc/87ederwuid.fsf@meer.lwn.net/

Yueh-Shun Li (1):
  coding-style: recommend split headers instead of kernel.h

 Documentation/process/coding-style.rst | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

-- 
2.42.0

[PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

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>
---
 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
-- 
2.42.0

Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Randy Dunlap]

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.

> ---
>  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

-- 
#Randy

Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

[Yueh-Shun Li]

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