izmod - Load an out of tree kernel module
=========================================

The most up to date version of this information is included
in the izmod(8) manual page.

Most Linux kernel modules are distributed inside the main kernel
source code tree. Some however are not, for many reasons like
licensing, independent development by hardware vendors or third
parties, etc. Those modules are generally called "out of tree modules".

izmod loads an out of tree kernel module. It first tries to download
and install it from the system package repositories. If that fails then
it attempts to build it locally using GAR.

izmod homepage:
   https://iztaci.com/software/izmod

izmod author:
   Felipe Sanchez <izto@asic-linux.com.mx>


Quickstart
----------

These examples assume the module has already been packaged for use by izmod.

Load the 'zfs' module:

  izmod load zfs

Rebuild the module from source and load it:

  izmod -R load zfs


Kernel configuration files
--------------------------

Kernel modules should be compiled using the same configuration options
used to build the kernel they will be loaded in. Therefore izmod must
know three things in order to build a kernel module:

  1) Kernel version
  2) Path to the kernel configuration file
  3) Path to the kernel Module.symvers file

If you omit the kernel version when invoking izmod then it will use the
currently running kernel version.

If you omit the path to the kernel configuration file then it will attempt
to load the 'configs.ko' kernel module and read the configuration from
/proc/config.gz.

If you omit the Module.symvers file and you ask it to build the module
from source then it will attempt to run the build process without one. Not
all modules can be built without a Module.symvers file.


A fully specified module load command would be for example:

izmod -k 4.19.162 -f /boot/vmlinuz.config -k /boot/vmlinuz.symvers load zfs



izmod packages
--------------

izmod uses GAR as a backend for building packages from source. This means
it needs to find a package directory inside the GAR build tree, normally
located at /usr/gar/izmod/izmod-meta-<module_name>.

Other backends may be available in the future such as DKMS, for example.

Your distribution may have several izmod module packages available, such as
izmod-zfs, izmod-r8019, etc. izmod will attempt to find and automatically
download and install the required package for the module you are trying
to load.

If there is no such package available you can define your own GAR package
directory for a package.

Read the iztaci-gar documentation at https://iztaci.com/software/iztaci-gar
for general instructions on how to create a new package directory.

A simple example is included in the izmod source distribution under the
examples/izmod-meta-zfs directory. It will build a ZFS on Linux module and can
be used as a starting point for creating your own izmod module packages.


How to create your own izmod package
------------------------------------

1) Create a basic gar package directory. You can use izmod-meta-zfs as a starting point.

2) Place it under /usr/gar/izmod/izmod-meta-<module_name>

3) Set the variables for the GENERAL section in the main Makefile.

4) Set tye BUILDING section variables. If your module's source uses the
   common GNU autotools (./configure; make) workflow then you shouldn't
   need to modify much there.

5) Make sure the izmod-gar.lib.mk file is included.

6) Edit/Add any custom rules necessary. The default post-install: rule
   should handle most cases.

7) Try it: Run 'izmod load <module_name>'


TODO: Add examples
