| Message ID | 20240917141725.466514-5-masahiroy@kernel.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | kbuild: support building external modules in a separate build directory | expand |
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>
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 --------------------------
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(-)