Commit e873fb94 authored by Masahiro Yamada's avatar Masahiro Yamada
Browse files

kbuild: doc: remove the description about shipped files 

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 should not 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: default avatarMasahiro Yamada <masahiroy@kernel.org>
Reviewed-by: default avatarNicolas Schier <n.schier@avm.de>
parent 803d5059

Documentation/kbuild/makefiles.rst

+0 −1
Original line number Diff line number Diff line
@@ -1665,6 +1665,5 @@ Credits 
TODO

====



- Describe how kbuild supports shipped files with _shipped.

- Generating offset header files.

- Add more variables to chapters 7 or 9?

Documentation/kbuild/modules.rst

+3 −32
Original line number Diff line number Diff line
@@ -152,7 +152,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



Shared Makefile

---------------
@@ -170,7 +169,7 @@ Shared Makefile 
		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
@@ -179,10 +178,6 @@ Shared Makefile 
		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
@@ -204,7 +199,7 @@ Separate Kbuild File and Makefile 


		--> 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
@@ -212,35 +207,11 @@ Separate Kbuild File and Makefile 
		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.



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.



Building Multiple Modules

-------------------------
@@ -301,7 +272,7 @@ Single Subdirectory 
		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



Several Subdirectories

----------------------