MODULES(2)

NAME
get_kernel_syms, create_module, init_module, delete_module - loadable module support

SYNOPSIS
#include <linux/module.h>

int get_kernel_syms(struct kernel_sym *table);

int create_module(char *module_name, unsigned long size);

int init_module(char *module_name, char *code, unsigned codesize,
    struct mod_routines *routines, struct symbol_table *symtab);

int delete_module(char *module_name);

struct kernel_sym {
	unsigned long value;
	char name[SYM_MAX_NAME];
};
struct mod_routines {
	int (*init)(void);
	void (*cleanup)(void);
};
struct module_ref {
	struct module *module;
	struct module_ref *next;
};
struct internal_symbol {
	void *addr;
	char *name;
};
struct symbol_table {
	int size; /* total, including string table!!! */
	int n_symbols;
	int n_refs;
	struct internal_symbol symbol[0];
	struct module_ref ref[0];
};

DESCRIPTION
These system calls have not yet been included in any library, which means that they have to be called by the syscall(__NR_function) mechanism.

get_kernel_syms(table);
    has two uses: first, if table is NULL, this call will only return the number of symbols, including module names, that are available. This number should be used to reserve memory for that many items of struct kernel_sym.
    If table is not NULL, this call will copy all kernel symbols and module names (and version info) from the kernel to the space pointed to by table. The entries are ordered in module LIFO order. For each module an entry that decribes the module will be followed by entries describing the symbols exported by this module.

    Note that for symbols that describe a module, the value part of the structure will contain the kernel adress of the structure that describes the module.
    The name part of the structure is the module name prepended with #, as in #my_module. The symbol that describes a module will appear before the symbols defined by this module.
    Ahead of the kernel resident symbols, a module name symbol with the "dummy" name # will appear. This information can be used to build a table of module references when modules are stacked (or layered).

create_module(module_name, size);
    will allocate size bytes of kernel space for a module, and also create the necessary kernel structures for the new module called name. The module will now exist in kernel space, with the status MOD_UNINITIALIZED.

init_module(module_name, code, codesize, routines, symtab);
    This is the actual "module loader", that will load the module named name into the kernel. The parameters code and codesize refer to the relocated binary object module that is codesize bytes long. Note that the first 4 bytes will be used as a reference counter in kernel space, updated by the MOD_INC_USE_COUNT and MOD_DEC_USE_COUNT macros.
    The functions described in routines will be used to start and stop the module. These pointers should therefore contain the adresses of the init_module() and cleanup_module() functions that have to be defined for all loadable modules.
    If a module wants to export symbols for use by other modules, or if the module makes references to symbols defined by other modules, the parameter symtab has to point to a structure that describes these. A NULL value for symtab means that no symbols are exported and no references to other modules are made.
    The symtab that will be copied into the kernel consist of a symbol_table structure immediately followed by a string table, containing the names of the symbols defined by the module. The size element has to include the size of this string table as well.

    Special considerations:
    The n_symbols and n_refs elements tells how many symbols and how many module references are included in the symbol_table structure. Immediately after these integers, the array of symbol definitions follow. The name element in each struct internal_symbol should actually not be an ordinary pointer, but instead the offset of the corresponding string table entry relative to the start of the symbol_table structure.

    When all defined symbols have been listed, the symbol_table structure continues with the array of module references, as described by the struct module_ref elements. Only the module field of these structures have to be initialized. The module adresses that were obtained from a previous get_kernel_syms call, for elements with names starting with # should be copied to this field.

    If the module could be successfully loaded, and if the call to the module function init_module() also succeeds, the status of the module will be changed to MOD_RUNNING. Otherwise, the kernel memory occupied by module will be freed.

delete_module(module_name);
    should be used to unload a module. If the module reference count shows that the module is not active, and if there are no references to this module from other modules, the module function cleanup_module() will be called. If all these steps succeed, the kernel memory occupied by the module and its structures will be freed.

DIAGNOSTICS
If there are any errors, these functions will return the value -1, and the global variable errno will contain the error number. A descriptive text will also be written on the console device.

SEE ALSO
insmod(1), rmmod(1), lsmod(1), ksyms(1)

HISTORY
The module support was first concieved by Anonymous (as far as I know...).
Linux version by Bas Laarhoven <bas@vimec.nl>,
0.99.14 version by Jon Tombs <jon@gtex02.us.es>,
extended by Bjorn Ekwall <bj0rn@blox.se>.

BUGS
Naah...