Changes between Version 12 and Version 13 of linux/kernel


Ignore:
Timestamp:
04/08/2019 05:12:23 PM (5 months ago)
Author:
Tim Harvey
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • linux/kernel

    v12 v13  
    101101
    102102[=#building]
    103 == Building the Linux kernel (out-of-tree) ==
    104 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.
     103== Building the Linux kernel (cross-compiling)
     104Building the Linux kernel for a target board that differs from your development host outside various Board Support Package development environments is easily accomplished.
    105105
    106106Gateworks developers typically do kernel development out-of-tree and boot the kernel over the network to speed up development.
     
    180180export ARCH=arm
    181181export CROSS_COMPILE=arm-openwrt-linux-
    182 export INSTALL_MOD_PATH=install
    183182export LOADADDR=0x10008000
    184183}}}
     
    227226 * 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
    228227 * modules - for building loadable kernel modules (*.ko)
    229  * modules_install - for installing the loadable kernel modules to $INSTALL_MOD_PATH (env)
    230  * headers_install - for installing kernel header files to INSTALL_HDR_PATH (which must be passed in to make)
     228 * modules_install - for installing the loadable kernel modules (set the INSTALL_MOD_PATH parameter to the location you wish to install to)
     229 * 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)
    231230 * dtbs - for building device-tree blobs (*.dtb) from kernel source tree (Ventana/IMX6; for Newport we use out-of-kernel tree device-tree)
    232231 * Examples:
    233232  - Newport/CN80XX:
    234233{{{#!bash
    235 make Image modules modules_install INSTALL_HDR_PATH=install/usr headers_install
     234mkdir install
     235make INSTALL_MOD_PATH=install INSTALL_HDR_PATH=install/usr Image modules modules_install headers_install
    236236}}}
    237237  - Ventana/IMX6:
    238238{{{#!bash
    239 make uImage dtbs modules modules_install INSTALL_HDR_PATH=install/usr headers_install
     239mkdir install
     240make INSTALL_MOD_PATH=install INSTALL_HDR_PATH=install/usr uImage dtbs modules modules_install headers_install
    240241}}}
    241242
     
    243244 * kernel images (Image/uImage) will be in arch/$ARCH/boot
    244245 * dtbs will be in arch/$ARCH/boot/dts
    245  * modules will be in $INSTALL_MOD_PATH. You can create a tarball via:
    246 {{{#!bash
    247 tar -C $INSTALL_MOD_PATH --owner=0 --group=0 -cvJf modules.tar.xz .
    248 }}}
    249 
     246 * modules will be in the directory specified by the INSTALL_MOD_PATH parameter. You can create a tarball via:
     247{{{#!bash
     248tar -C <INSTALL_MOD_PATH dir> --owner=0 --group=0 -cvJf modules.tar.xz .
     249}}}
     250
     251
     252[=#headers]
     253== Installing Kernel Headers
     254The '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.
     255
     256The 'make headers_install' command uses two optional arguments to define the architecture (ARCH) and the location to install the files (INSTALL_HDR_PATH)
     257
     258Reference:
     259 - https://www.kernel.org/doc/Documentation/kbuild/headers_install.txt
     260
     261
     262[=#modules]
     263== Building external (out of tree) kernel modules
     264The 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.
     265
     266An 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.
     267
     268To 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.
     269
     270To build an external kernel module you typically would use:
     271{{{#!bash
     272cd <external-module-directory>
     273make -C <path-to-prebuilt-kernel> M=$PWD
     274}}}
     275 * this will build the modules located in the current directory pointed to by the M param
     276 * you can then manually copy or load your kernel modules or use the modules_install make target to install them to a specific path
     277 * if cross-compiling make sure to define ARCH and CROSS_COMPILE env variables and have the $(CROSS_COMPILE)-gcc in your path
     278
     279As an example consider the following files in a directory called 'hello-driver':
     280 * hello.c:
     281{{{#!bash
     282#include <linux/init.h>
     283#include <linux/module.h>
     284MODULE_LICENSE("Dual BSD/GPL");
     285
     286static int hello_init(void)
     287{
     288    printk(KERN_ALERT "Hello, world\n");
     289    return 0;
     290}
     291
     292static void hello_exit(void)
     293{
     294    printk(KERN_ALERT "Goodbye, cruel world\n");
     295}
     296
     297module_init(hello_init);
     298module_exit(hello_exit);
     299}}}
     300 * Makefile:
     301{{{#!bash
     302obj-m := hello.o
     303}}}
     304 * building:
     305{{{#!bash
     306make -C <path-to-prebuilt-kernel> M=$PWD
     307ls hello.ko
     308}}}
     309
     310
     311References:
     312 - https://www.kernel.org/doc/Documentation/kbuild/modules.txt
     313 - https://www.oreilly.com/library/view/linux-device-drivers/0596005903/ch02.html
    250314
    251315
    252316[=#backports]
    253 == Building the Latest Kernel Modules - Wireless Backports ==
    254 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.
     317== Building the Latest Kernel Modules for an older kernel - Linux Backports
     318Sometimes 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.
    255319
    256320In 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.
     
    370434
    371435
    372 
    373 [=#modules]
    374 = Kernel Modules
     436[=#insmod]
     437= Loading Kernel Modules
    375438Kernel 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.
    376439