MODULES(2)

NOM
get_kernel_syms, create_module, init_module, delete_module - Support des modules chargeables de Linux.

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
Ces appels systemes ne sont pas encore inclus dans les bibliotheques (au 14 Mai 95) ce qui signifie qu'ils doivent etre appeles avec le mecanisme syscall(__NR_function).

get_kernel_syms(table) propose deux services : premierement, si table est NULL, cet appel retournera simplement le nombre de symboles disponibles, y compris les noms des modules. Cette valeur peut servir a allouer de la memoire pour autant d'elements du type struct kernel_sym. Si table n'est pas NULL, cet appel va copier tous les symboles du noyau et les noms de modules (avec les numeros de version) dans la zone memoire pointee par table. Les donnees sont triees dans l'ordre LIFO d'insertion des modules. Chaque module est decrit par une entree dans cette table, suivi par les entrees decrivant les symboles exportes par le module.

Remarquez que pour les symboles, la partie value de la strcture contiendra l'adresse au sein du noyau de la structure decrivant le module.
La partie name de la structure contient le nom du module precede par #, comme dans #my_module. Le symbole decrivant un module apparaitra avant les symboles definis par le module. A la fin des symboles residents du noyau, apparaitra un symbole dont le nom sera #. Cette information peut servir a construire une table de reference des modules ou ils seront empiles. create_module(module_name, size) allouera size octets dans l'espace du noyau pour un module, et creera egalement les structures internes au noyau pour le nouveau module nomme name. Ce module existera des lors dans l'espace du noyau avec un statut MOD_UNINITIALIZED. init_module(module_name, code, codesize, routines, symtab) est le veritable chargeur (loader) de module, qui va inserer le module nomme name au sein du noyau. Les parametres code et codesize correspondent au code objet binaire du module, qui fait codesize octets de long. Si l'on effectue un OU binaire entre le parametre codesize et MOD_AUTOCLEAN, le module sera soumis au nettoyage automatique, c'est a dire l'elimination periodique des modules inutilises. Les 4 premiers octets de l'image du module seront utilises comme compteur de reference par le noyau, mis a jour par les macros MOD_INC_USE_COUNT et MOD_DEC_USE_COUNT. Ce compteur contiendra egalement le bit MOD_AUTOCLEAN et un bit MOD_VISITED qui sont utilise pour le nettoyage automatique. Les fonctions decrites dans routines serviront a demarrer et arreter le module. Ces pointeurs devrait contenir l'adresse des fonctions init_module() et cleanup_module() definies pour tous les modules chargeables.
Si un module desire exporter des symboles en direction d'autres modules, ou s'il fait reference a des symboles definis par d'autres modules, le parametre symtab doit pointer sur une structure les decrivant. Une valeur NULL pour symtab signifie qu'aucun symbole n'est exporte, et qu'aucune reference aux autres modules n'est effectuee.
La symtab qui sera copiee dans le noyau consiste en une structure symbol_table suivie immediatement par une table de chaines de caracteres contenant les noms des symboles definis par le module. L'element size doit inclure aussi la taille de la table de chaines.

Specificites : Les elements n_symbols et n_refs indiquent combien de symboles et combien de references aux autres modules sont inclus dans la structure symbol_table. Immediatement apres ces entiers se touve la table des symboles. L'element name dans chaque struct internal_symbol ne doit pas etre un pointeur classique, mais l' offset de la chaine correpondante dans la table, relativement au debut de la structure symbol_table.

Apres la liste de tous les symboles definis, la structure symbol_table continue avec une table des references de modules, decrites par les elements struct module_ref. Seul le champ module de ces structures doit etre initialise. Les adresses de modules obtenues precedemment avec get_kernel_syms pour les elements dont le nom commence par # doivent etre copiees dans ces champs.

Si le module peut etre correctement charge, et si l'appel de la fonction init_module() reussit egalement, le statut du module deviendra MOD_RUNNING. Autrement, la memoire du noyau occupee par le module sera liberee. delete_module(module_name) doit etre utilise pour decharger un module. Si le compteur de references montre que le module n'est plus actif, et qu'aucun autre modules n'y fait reference, sa fonction cleanup_module() sera appelee. Si toutes ces etapes reussissent, la memoire du noyau occupee par le module et ses structures sera liberee.

Remarquez que si l'argument de delete_module vaut NULL, le noyau supprimera tous les modules.

DIAGNOSTIQUES
S'il se produit une erreur, toutes ces fonctions renverront -1, et la variable globale errno contiendra le code d'erreur. Un message d'erreur sera egalement affiche sur la console.

CONFORMITE
Ces appels systemes sont specifiques a Linux, et ne doivent pas etre employes dans des programmes destines a etre portables. Le support de module a ete concu par Anonymous (si je me souviens bien).

VOIR AUSSI
insmod(1), rmmod(1), lsmod(1), ksyms(1), genksyms(8)

BUGS
Naah...