The use of shipped files is discouraged in the upstream kernel these
days. [1]

Downstream Makefiles have the freedom to use shipped files or other
options to handle binaries, but this is not what should be advertised
in the upstream document.

[1]: https://lore.kernel.org/all/CAHk-=wgSEi_ZrHdqr=20xv+d6dr5G895CbOAi8ok+7-CQUN=fQ@mail.gmail.com/

Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
---

 Documentation/kbuild/modules.rst | 35 +++-----------------------------
 1 file changed, 3 insertions(+), 32 deletions(-)

diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
index 7eceb9a65e9c..1afa6b1b4090 100644
--- a/Documentation/kbuild/modules.rst
+++ b/Documentation/kbuild/modules.rst
@@ -180,7 +180,6 @@ module 8123.ko, which is built from the following files::
 	8123_if.c
 	8123_if.h
 	8123_pci.c
-	8123_bin.o_shipped	<= Binary blob
 
 3.1 Shared Makefile
 -------------------
@@ -198,7 +197,7 @@ module 8123.ko, which is built from the following files::
 		ifneq ($(KERNELRELEASE),)
 		# kbuild part of makefile
 		obj-m  := 8123.o
-		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
+		8123-y := 8123_if.o 8123_pci.o
 
 		else
 		# normal makefile
@@ -207,10 +206,6 @@ module 8123.ko, which is built from the following files::
 		default:
 			$(MAKE) -C $(KDIR) M=$$PWD
 
-		# Module specific targets
-		genbin:
-			echo "X" > 8123_bin.o_shipped
-
 		endif
 
 	The check for KERNELRELEASE is used to separate the two parts
@@ -232,7 +227,7 @@ module 8123.ko, which is built from the following files::
 
 		--> filename: Kbuild
 		obj-m  := 8123.o
-		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
+		8123-y := 8123_if.o 8123_pci.o
 
 		--> filename: Makefile
 		KDIR ?= /lib/modules/`uname -r`/build
@@ -240,35 +235,11 @@ module 8123.ko, which is built from the following files::
 		default:
 			$(MAKE) -C $(KDIR) M=$$PWD
 
-		# Module specific targets
-		genbin:
-			echo "X" > 8123_bin.o_shipped
-
 	The split in example 2 is questionable due to the simplicity of
 	each file; however, some external modules use makefiles
 	consisting of several hundred lines, and here it really pays
 	off to separate the kbuild part from the rest.
 
-3.3 Binary Blobs
-----------------
-
-	Some external modules need to include an object file as a blob.
-	kbuild has support for this, but requires the blob file to be
-	named <filename>_shipped. When the kbuild rules kick in, a copy
-	of <filename>_shipped is created with _shipped stripped off,
-	giving us <filename>. This shortened filename can be used in
-	the assignment to the module.
-
-	Throughout this section, 8123_bin.o_shipped has been used to
-	build the kernel module 8123.ko; it has been included as
-	8123_bin.o::
-
-		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
-
-	Although there is no distinction between the ordinary source
-	files and the binary file, kbuild will pick up different rules
-	when creating the object file for the module.
-
 3.4 Building Multiple Modules
 =============================
 
@@ -329,7 +300,7 @@ according to the following rule:
 		obj-m := 8123.o
 
 		ccflags-y := -I $(src)/include
-		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
+		8123-y := 8123_if.o 8123_pci.o
 
 4.3 Several Subdirectories
 --------------------------
-- 
2.43.0

On Tue, Sep 17, 2024 at 11:16:32PM +0900, Masahiro Yamada wrote:
> The use of shipped files is discouraged in the upstream kernel these
> days. [1]
> 
> Downstream Makefiles have the freedom to use shipped files or other
> options to handle binaries, but this is not what should be advertised
> in the upstream document.
> 
> [1]: https://lore.kernel.org/all/CAHk-=wgSEi_ZrHdqr=20xv+d6dr5G895CbOAi8ok+7-CQUN=fQ@mail.gmail.com/
> 
> Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
> ---
> 
>  Documentation/kbuild/modules.rst | 35 +++-----------------------------
>  1 file changed, 3 insertions(+), 32 deletions(-)

Do you want to remove the TODO point refering to *_shipped files from
Documentation/kbuild/makefiles.rst as well?

$ git grep -Hrne _shipped Documentation/
Documentation/kbuild/makefiles.rst:1668:- Describe how kbuild supports shipped files with _shipped.

> 
> diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
> index 7eceb9a65e9c..1afa6b1b4090 100644
> --- a/Documentation/kbuild/modules.rst
> +++ b/Documentation/kbuild/modules.rst
[...]
> @@ -240,35 +235,11 @@ module 8123.ko, which is built from the following files::
>  		default:
>  			$(MAKE) -C $(KDIR) M=$$PWD
>  
> -		# Module specific targets
> -		genbin:
> -			echo "X" > 8123_bin.o_shipped
> -
>  	The split in example 2 is questionable due to the simplicity of
>  	each file; however, some external modules use makefiles
>  	consisting of several hundred lines, and here it really pays
>  	off to separate the kbuild part from the rest.
>  
> -3.3 Binary Blobs
> -----------------
> -
> -	Some external modules need to include an object file as a blob.
> -	kbuild has support for this, but requires the blob file to be
> -	named <filename>_shipped. When the kbuild rules kick in, a copy
> -	of <filename>_shipped is created with _shipped stripped off,
> -	giving us <filename>. This shortened filename can be used in
> -	the assignment to the module.
> -
> -	Throughout this section, 8123_bin.o_shipped has been used to
> -	build the kernel module 8123.ko; it has been included as
> -	8123_bin.o::
> -
> -		8123-y := 8123_if.o 8123_pci.o 8123_bin.o
> -
> -	Although there is no distinction between the ordinary source
> -	files and the binary file, kbuild will pick up different rules
> -	when creating the object file for the module.
> -

I think renumbering the following sections would provide a more consistent document.  If you think that keeping the numbering constant:  would you mind adding a note about section 3.3 being removed?
(And possibly as well in the table of contents?)

Either way,

Reviewed-by: Nicolas Schier <n.schier@avm.de>

On Thu, Sep 19, 2024 at 1:24 AM Nicolas Schier <n.schier@avm.de> wrote:
>
> On Tue, Sep 17, 2024 at 11:16:32PM +0900, Masahiro Yamada wrote:
> > The use of shipped files is discouraged in the upstream kernel these
> > days. [1]
> >
> > Downstream Makefiles have the freedom to use shipped files or other
> > options to handle binaries, but this is not what should be advertised
> > in the upstream document.
> >
> > [1]: https://lore.kernel.org/all/CAHk-=wgSEi_ZrHdqr=20xv+d6dr5G895CbOAi8ok+7-CQUN=fQ@mail.gmail.com/
> >
> > Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
> > ---
> >
> >  Documentation/kbuild/modules.rst | 35 +++-----------------------------
> >  1 file changed, 3 insertions(+), 32 deletions(-)
>
> Do you want to remove the TODO point refering to *_shipped files from
> Documentation/kbuild/makefiles.rst as well?


Yes.

Good catch.



> $ git grep -Hrne _shipped Documentation/
> Documentation/kbuild/makefiles.rst:1668:- Describe how kbuild supports shipped files with _shipped.
>
> >
> > diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
> > index 7eceb9a65e9c..1afa6b1b4090 100644
> > --- a/Documentation/kbuild/modules.rst
> > +++ b/Documentation/kbuild/modules.rst
> [...]
> > @@ -240,35 +235,11 @@ module 8123.ko, which is built from the following files::
> >               default:
> >                       $(MAKE) -C $(KDIR) M=$$PWD
> >
> > -             # Module specific targets
> > -             genbin:
> > -                     echo "X" > 8123_bin.o_shipped
> > -
> >       The split in example 2 is questionable due to the simplicity of
> >       each file; however, some external modules use makefiles
> >       consisting of several hundred lines, and here it really pays
> >       off to separate the kbuild part from the rest.
> >
> > -3.3 Binary Blobs
> > -----------------
> > -
> > -     Some external modules need to include an object file as a blob.
> > -     kbuild has support for this, but requires the blob file to be
> > -     named <filename>_shipped. When the kbuild rules kick in, a copy
> > -     of <filename>_shipped is created with _shipped stripped off,
> > -     giving us <filename>. This shortened filename can be used in
> > -     the assignment to the module.
> > -
> > -     Throughout this section, 8123_bin.o_shipped has been used to
> > -     build the kernel module 8123.ko; it has been included as
> > -     8123_bin.o::
> > -
> > -             8123-y := 8123_if.o 8123_pci.o 8123_bin.o
> > -
> > -     Although there is no distinction between the ordinary source
> > -     files and the binary file, kbuild will pick up different rules
> > -     when creating the object file for the module.
> > -
>
> I think renumbering the following sections would provide a more consistent document.  If you think that keeping the numbering constant:  would you mind adding a note about section 3.3 being removed?
> (And possibly as well in the table of contents?)

Rather, I'd like to remove section numbers.

Let me do that way.


> Either way,
>
> Reviewed-by: Nicolas Schier <n.schier@avm.de>



-- 
Best Regards
Masahiro Yamada