Changes between Version 12 and Version 13 of linux/kernel

Timestamp:

04/08/2019 05:12:23 PM (6 years ago)

Author:

Tim Harvey

Comment:

added external module documentation and fixed some inaccuracies in with modules_install and headers_install (env vs params)

linux/kernel

@@ -101 +101 @@
 
 [=#building]
-== Building the Linux kernel (out-of-tree) ==
-Building the Linux kernel 'out-of-tree' refers to building it outside of the Board Support Package development environment. Each BSP that Gateworks provides builds the kernel for you, but doing constant kernel development within those BSP's may not be very time efficient.
+== Building the Linux kernel (cross-compiling)
+Building the Linux kernel for a target board that differs from your development host outside various Board Support Package development environments is easily accomplished.
 
 Gateworks developers typically do kernel development out-of-tree and boot the kernel over the network to speed up development.
@@ -180 +180 @@
 export ARCH=arm
 export CROSS_COMPILE=arm-openwrt-linux-
-export INSTALL_MOD_PATH=install
 export LOADADDR=0x10008000
 }}}
@@ -227 +226 @@
  * uImage - compressed kernel wrapped in a U-Boot image header (use this for Ventana/IMX6) which requires the $LOADADDR env variable to tell U-Boot where to uncompress the kernel to
  * modules - for building loadable kernel modules (*.ko)
- * modules_install - for installing the loadable kernel modules to $INSTALL_MOD_PATH (env)
- * headers_install - for installing kernel header files to INSTALL_HDR_PATH (which must be passed in to make)
+ * modules_install - for installing the loadable kernel modules (set the INSTALL_MOD_PATH parameter to the location you wish to install to)
+ * headers_install - for installing kernel header files for development of userspace applications that use the kernel APIs (set the INSTALL_HDR_PATH parameter to the location you wish to install to)
  * dtbs - for building device-tree blobs (*.dtb) from kernel source tree (Ventana/IMX6; for Newport we use out-of-kernel tree device-tree)
  * Examples:
   - Newport/CN80XX:
 {{{#!bash
-make Image modules modules_install INSTALL_HDR_PATH=install/usr headers_install
+mkdir install
+make INSTALL_MOD_PATH=install INSTALL_HDR_PATH=install/usr Image modules modules_install headers_install
 }}}
   - Ventana/IMX6:
 {{{#!bash
-make uImage dtbs modules modules_install INSTALL_HDR_PATH=install/usr headers_install
+mkdir install
+make INSTALL_MOD_PATH=install INSTALL_HDR_PATH=install/usr uImage dtbs modules modules_install headers_install
 }}}
 
@@ -243 +244 @@
  * kernel images (Image/uImage) will be in arch/$ARCH/boot
  * dtbs will be in arch/$ARCH/boot/dts
- * modules will be in $INSTALL_MOD_PATH. You can create a tarball via:
-{{{#!bash
-tar -C $INSTALL_MOD_PATH --owner=0 --group=0 -cvJf modules.tar.xz .
-}}}
-
+ * modules will be in the directory specified by the INSTALL_MOD_PATH parameter. You can create a tarball via:
+{{{#!bash
+tar -C <INSTALL_MOD_PATH dir> --owner=0 --group=0 -cvJf modules.tar.xz .
+}}}
+
+
+[=#headers]
+== Installing Kernel Headers
+The 'make headers_install' command exports the kernel's header files in a form suitable for use by userspace programs. These headers describe the API for user space programs attempting to use kernel services and are used by the system's C library (ie glibc or uClibc) to define available system calls as well as constants and structures to be used with these system calls. The C library's header files are usually installed in /usr/include and the kernel's headers are usually in /usr/include/linux and /usr/include/asm. Kernel headers are backwards compatible but not forwards compatible meaning a program built against a C library using older kernel headers should run on a newr kernel (although possibly missing access to new features) but a program built against newer kernel headers may not work on an older kernel.
+
+The 'make headers_install' command uses two optional arguments to define the architecture (ARCH) and the location to install the files (INSTALL_HDR_PATH)
+
+Reference:
+ - https://www.kernel.org/doc/Documentation/kbuild/headers_install.txt
+
+
+[=#modules]
+== Building external (out of tree) kernel modules
+The Linux 'kbuild' system is used by the Linux kernel for kernel configuration. Linux kernel modules must use kbuild to stay compatible with the changes in the build infrastructure. A kernel module can be built stand-alone either 'in tree' (within the directory structure of the linux kernel) or 'out of tree' (aka 'external') meaning it exists in a directory of its own outside of the linux source tree.
+
+An external module must always include a wrapper makefile that supports building the module using 'make' with no arguments. See [https://www.kernel.org/doc/Documentation/kbuild/modules.txt modules.txt] for details.
+
+To build external modules you must have a prebuilt kernel available that contains the configuration and header files used in the build. Also the kernel must have been built with modules enabled.
+
+To build an external kernel module you typically would use:
+{{{#!bash
+cd <external-module-directory>
+make -C <path-to-prebuilt-kernel> M=$PWD
+}}}
+ * this will build the modules located in the current directory pointed to by the M param
+ * you can then manually copy or load your kernel modules or use the modules_install make target to install them to a specific path
+ * if cross-compiling make sure to define ARCH and CROSS_COMPILE env variables and have the $(CROSS_COMPILE)-gcc in your path
+
+As an example consider the following files in a directory called 'hello-driver':
+ * hello.c:
+{{{#!bash
+#include <linux/init.h>
+#include <linux/module.h>
+MODULE_LICENSE("Dual BSD/GPL");
+
+static int hello_init(void)
+{
+    printk(KERN_ALERT "Hello, world\n");
+    return 0;
+}
+
+static void hello_exit(void)
+{
+    printk(KERN_ALERT "Goodbye, cruel world\n");
+}
+
+module_init(hello_init);
+module_exit(hello_exit);
+}}}
+ * Makefile:
+{{{#!bash
+obj-m := hello.o
+}}}
+ * building:
+{{{#!bash
+make -C <path-to-prebuilt-kernel> M=$PWD
+ls hello.ko
+}}}
+
+
+References:
+ - https://www.kernel.org/doc/Documentation/kbuild/modules.txt
+ - https://www.oreilly.com/library/view/linux-device-drivers/0596005903/ch02.html
 
 
 [=#backports]
-== Building the Latest Kernel Modules - Wireless Backports ==
-Because we don't use mainline linux, but require the latest drivers in wireless, we use the {{{backports}}} project. For more detail on this project, please visit their [https://backports.wiki.kernel.org/index.php/Main_Page documentation] site.
+== Building the Latest Kernel Modules for an older kernel - Linux Backports
+Sometimes you may be using a kernel is not as new as the mainline kernel at kernel.org and you desire a driver or newer driver from the latest kernel. The [https://backports.wiki.kernel.org/index.php/Main_Page Linux Backports] project aims at providing this capability.
 
 In order to build this, you will need a kernel tree already built. In this example, I will assume the {{{gateworks_fslc_3.14_1.0.x_ga}}} kernel is being used.
@@ -370 +434 @@
 
 
-
-[=#modules]
-= Kernel Modules
+[=#insmod]
+= Loading Kernel Modules
 Kernel modules are dynamically loadable portions of the kernel that can be loaded or unloaded at runtime. It is generally not feasible to build every kernel driver statically into a modern Linux kernel so instead only options required to load further modules are build static.