Chapitre 2 : Building and Running Modules partie 6

[Michaël]

Discussion réservée à la traduction de la partie 6 du chapitre 2 "Building and Running Modules"

Le pdf en anglais

Pour travailler, vous devez télécharger les xml en pièce jointe et joindre le xml une fois que vous avez fini. Vous ne devez en aucun cas toucher aux balises ni à l'indentation sinon ça va mettre la pagaille dans le xml final. J'ai utilisé kwrite comme éditeur de texte avec les paramètres par défaut.

[buchs]

Initialization and Shutdown

As already mentioned, the module initialization function registers any facility offered by the module. By facility, we mean a new functionality, be it a whole driver or a new software abstraction, that can be accessed by an application. The actual definition of the initialization function always looks like :

static int __init initialization_function(void) 
{ 
/* Initialization code here */
}
module_init(initialization_function);

Initialisation et arrêt

Comme déjà mentionné, la fonction d’initialisation du module enregistre n’importe qu’elle facilité offerte par le noyau. Par <i>facilité</i>, nous entendons une nouvelle fonctionnalité, soit un pilote entier ou un nouveau logicielle, cela peut être accédé par une application. La définition réelle de la fonction d’initialisation ressemble toujours à :

static int __init initialization_function(void) 
{ 
/* Ici, le code de l’initialisation */
}
module_init(initialization_function);

_____________________________________________________________

Initialization functions should be declared static, since they are not meant to be visible outside the specific file; there is no hard rule about this, though, as no function is exported to the rest of the kernel unless explicitly requested. The __init token in the definition may look a little strange; it is a hint to the kernel that the given function is used only at initialization time. The module loader drops the initialization function after the module is loaded, making its memory available for other uses. There is a similar tag (__initdata)for data used only during initialization. Use of __init and __initdata is optional, but it is worth the trouble. Just be sure not to use them for any function (or data structure)you will be using after initialization completes. You may also encounter __devinit and __devinitdata in the kernel source; these translate to __init and __initdata only if the kernel has not been configured for hotpluggable devices. We will look at hotplug support in Chapter 14.

Les fonctions d’initialisations devraient être déclarées en <i>static</i>, puisqu’elles ne sont pas censées être visible à l’extérieur du fichier. Il n’y a pas de règle dure à propos de ça, cependant, comme aucune fonction n’est exportée au reste du noyau sauf si c’est explicitement demandé. Le sigle <i>__init</i> dans la définition peut être un peu étrange. C’est une allusion au noyau que la fonction donnée n’utilise que lors de l’initialisation. Le chargeur de module laisse tomber la fonction d’initialisation après que le module soit chargé, rendant sa mémoire disponible pour les autres utilisateurs. Il y a un tag similaire (<i>__initdata</i>) pour les données utilisées uniquement lors de l’initialisation. L’utilisation de <i>__init</i> et <i>__initdata</i> est optionnelle, mais le mal en vaut la peine. Assurez-vous juste de ne pas les utiliser pour n’importe qu’elle fonction (ou structure de données) que vous allez utiliser après que l’initialisation soit achevée. Vous pouvez aussi rencontrer <i>__devinit</i> et <i>__devinitdata</i> dans les sources du noyau. Ceux-ci ce traduisent à <i>__init et</i> <i>__initdata</i> seulement si le noyau n'a pas été configuré pour des périphériques connectables à chaud. Nous étudierons le support de hotplug dans le chapitre 14.

_____________________________________________________________

The use of module_init is mandatory. This macro adds a special section to the module's object code stating where the module?s initialization function is to be found. Without this definition, your initialization function is never called.

L’utilisation de <i>module_init</i> est obligatoire. Cette macro ajoute une section spéciale à l’objet du module montrant où la fonction d’initialisation doit être trouvée. Sans cette définition, votre fonction d’initialisation ne sera jamais appelée.

_____________________________________________________________

Modules can register many different types of facilities, including different kinds of devices, filesystems, cryptographic transforms, and more. For each facility, there is a specific kernel function that accomplishes this registration. The arguments passed to the kernel registration functions are usually pointers to data structures describing the new facility and the name of the facility being registered. The data structure usually contains pointers to module functions, which is how functions in the module body get called.

Les modules peuvent enregistrer pleins de types différents d’équipements, incluant différentes sortes de périphériques, de systèmes de fichiers, de transformations cryptographiques, et plus encore. Pour chaque équipement, il y une fonction particulière du noyau qui réalise cet enregistrement. Les arguments passés aux fonctions d’enregistrement du noyau sont habituellement des pointeurs à des structures de données décrivant les nouveaux équipements et les noms de ces derniers sont enregistrés. Les structures de données contiennent habituellement des pointeurs vers les fonctions du module, qui est comment les fonctions sont appelées dans le corps du module.

_____________________________________________________________

The items that can be registered go beyond the list of device types mentioned in Chapter 1. They include, among others, serial ports, miscellaneous devices, sysfs entries, /proc files, executable domains, and line disciplines. Many of those registrable items support functions that aren't directly related to hardware but remain in the "software abstractions" field. Those items can be registered, because they are integrated into the driver's functionality anyway (like /proc files and line disciplines for example).

Les points qui peuvent être enregistrés vont au-delà de la liste des types de périphériques cités dans le chapitre 1. Ils incluent, parmi d’autres, les ports séries, divers périphériques, les entrées <i>sysfs</i>, les fichiers <i>/proc</i>, les exécutables et les disciplines linéaires. Beaucoup de ces points enregistrables supportent des fonctions qui ne sont pas directement relative au matériel mais ils restent dans le champ « abstractions logicielle ». Ces points peuvent être enregistrés car ils sont de toute façon intégrés dans les fonctionnalités des pilotes (comme les fichiers <i>/proc</i> et les disciplines linéaires par exemple).

_____________________________________________________________

There are other facilities that can be registered as add-ons for certain drivers, but their use is so specific that it's not worth talking about them; they use the stacking technique, as described in the section "The Kernel Symbol Table". If you want to probe further, you can grep for EXPORT_SYMBOL in the kernel sources, and find the entry points offered by different drivers. Most registration functions are prefixed with register_, so another possible way to find them is to grep for register_ in the kernel source.

Il y a d’autres équipements qui peuvent être enregistrés en tant qu’extensions pour certains pilotes, mais leur utilisation est tellement spécifique qu’il ne vaut pas la peine d’en parler. Ils utilisent la technique de l’empilement, comme décrit dans la section « La table des symboles du noyau ». Si vous voulez essayer plus tard, vous pouvez faire des recherches sur <i>EXPORT_SYMBOL</i> dans les sources du noyau et trouver les points d’entrées offerts par différents pilotes. La plupart des fonctions d’enregistrement sont préfixées avec <i>register_</i>, ainsi un autre moyen de les trouver est de rechercher <i>register_</i> dans les sources du noyau.

_____________________________________________________________

The Cleanup Function

Every nontrivial module also requires a cleanup function, which unregisters interfaces and returns all resources to the system before the module is removed. This function is defined as :

static void __exit cleanup_function(void) 
{ 
/* Cleanup code here */
}
module_exit(cleanup_function);

La fonction de nettoyage

Tout module non trivial requiert ainsi une fonction de nettoyage, qui efface les interfaces et retourne toutes les ressources au système avant que le module soit déchargé. Cette fonction est définie par :

static void __exit cleanup_function(void) 
{ 
/* Ici, le code de nettoyage */
}
module_exit(cleanup_function);

_____________________________________________________________

The cleanup function has no value to return, so it is declared void. The __exit modifier marks the code as being for module unload only (by causing the compiler to place it in a special ELF section). If your module is built directly into the kernel, or if your kernel is configured to disallow the unloading of modules, functions marked __exit are simply discarded. For this reason, a function marked __exit can be called only at module unload or system shutdown time; any other use is an error. Once again, the module_exit declaration is necessary to enable to kernel to find your cleanup function.

La fonction de nettoyage n’a pas de valeur de retour, aussi elle est déclarée avec <i>void</i>. Le modificateur <i>__exit</i> marque le code comme étant un module se décharge seulement (en obligeant le compilateur à le placer dans une section ELF spéciale). Si votre module est directement construit dans le noyau ou si votre noyau est configuré pour interdire aux modules de se décharger, les fonctions marquées avec <i>__exit</i> sont simplement écartées. Pour cette raison, une fonction marquée avec <i>__exit</i> peut être appelée <i>seulement</i> en déchargement de module ou si le système s’éteint. N’importe qu’elle autre utilisation est une erreur. Une fois encore, la déclaration <i>module_exit</i> est nécessaire pour permettre au noyau de trouver vos fonctions de nettoyage.

_____________________________________________________________

If your module does not define a cleanup function, the kernel does not allow it to be unloaded.

Si votre module ne définit pas une fonction de nettoyage, le noyau n’autorise pas le module à être déchargé.

[buchs]

Suis désolé, mais j'aurai pas le temps de finir la traduction de cette partie, ni d'en entamer une autre pour l'instant, pour la bonne et simple raison que je bosse plus de 10h par jours, donc si vous quelqu'un voudrait terminer cette partie, je lui en serais reconnaissant

[koopajah]

Je veux bien finir la traduction, pourrais tu donner le xml a jour actuellement?

[buchs]

Bien sûr, le voici en pièce jointe, au passage, j'ai remarqué que j'ai pas traduit le nom des fonctions, faudrait il le faire?

[buchs]

J'ai eu le temps de traduire un § en plus, voici donc le nouveau XML

[PRomu@ld]

Ceux-ci ce traduisent à <i>__init et</i> <i>__initdata</i> seulement si le noyau n'a pas été configuré pour des périphériques connectables à chaud.

Ceux ci sont traduit en <i>__init et </i> <i>__initdata</i> uniquement si le noyau n'a pas été configuré pour des périphériques connectables à chaud.

Les points qui peuvent être enregistrés vont au-delà de la liste

Les éléments qui ...

line disciplines

Ici, j'ai pas de traduction toute faite (pour l'instant), mais une line discipline, c'est un essemble de règle qui indique génériquement comment doit se comporter un périphérique (ce qu'il est possible de faire et de ne pas faire). Je vais chercher si on a pas un terme francisé.

Pour ce qui est de la table des symboles du noyau, c'est bon.

[buchs]

Après un long moment d'absence, voici un § supplémentaire :

If any errors occur when you register utilities, the first order of business is to decide whether the module can continue initializing itself anyway. Often, the module can continue to operate after a registration failure, with degraded functionality if necessary. Whenever possible, your module should press forward and provide what capabilities it can after things fail.

Si n'importe quelles erreurs surviennent quand vous enregistrez des utilités, la première chose à faire est de décider si le module peut continuer à s'initialisation malgré tout. Souvent, le module peut continuer à fonctionner après un échec d'enregistrement, avec la fonctionnalité dégradée si nécessaire. Votre module devrait pouvoir anticiper et fournir les possibilités il peut offrir après que les choses échoues.

[buchs]

Et un second :

If it turns out that your module simply cannot load after a particular type of failure, you must undo any registration activities performed before the failure. Linux doesn't keep a per-module registry of facilities that have been registered, so the module must back out of everything itself if initialization fails at some point. If you ever fail to unregister what you obtained, the kernel is left in an unstable state; it contains internal pointers to code that no longer exists. In such situations, the only recourse, usually, is to reboot the system. You really do want to take care to do the right thing when an initialization error occurs.

S'il s'avère que votre module ne peut simplement pas se charger après un type d'échec particulier, vous devez défaire toutes les activités d'enregistrements excutées avant l'échec. Linux ne garde pas un per-module d'enregistrement des équipements qui ont été enregistrés, ainsi le module doit pouvoir revenir en arrière lui-même si l'initialisation échoue à un certain point. Si vous échouez toujours à décharger ce que vous avez obtenu, le noyau est laissé dans un état instable. Il contient des pointeurs internes pour coder ce qui n'existe plus. Dans certaines situations, le seul recours, habituellement, est de redémarrer le système. Vous devez vraiment faire attention de faire le bon choix quand une erreur d'initialisation intervient.

[buchs]

Error recovery is sometimes best handled with the goto statement. We normally hate to use goto, but in our opinion, this is one situation where it is useful. Careful use of goto in error situations can eliminate a great deal of complicated, highly-indented, "structured" logic. Thus, in the kernel, goto is often used as shown here to deal with errors.

La récupération des erreurs est quelques fois le mieux traité avec la déclaration <i>goto</i>. Nous avons normalement horreur d'utiliser <i>goto</i>, mais à notre avis, c'est une situation où c'est utile. Une utilisation prudente de <i>goto</i> dans le cas d'erreurs peut éliminer beaucoup de complications, fortement indenté, "structure" la logique. Ainsi, dans le noyau, <i>goto</i> est souvent utilisé comme indiqué ci-dessous pour traiter les erreurs.

---

The following sample code (using fictitious registration and unregistration functions) behaves correctly if initialization fails at any point :

L'exemple de code suivant (utilisant des fonctions d'enregistrements et de déchargement fictives) s'exécute correctement si l'initialisation échoue à n'importe quel point :

---

int __init my_init_function(void)  
                       {  
                       int err;  
                        
                       /* registration takes a pointer and a name */ err = register_this(ptr1, "skull");  
                       if (err) goto fail_this;  
                       err = register_that(ptr2, "skull");  
                       if (err) goto fail_that;  
                       err = register_those(ptr3, "skull");  
                       if (err) goto fail_those;  
                        
                       return 0; /* success */  
                        
                       fail_those: unregister_that(ptr2, "skull");  
                       fail_that: unregister_this(ptr1, "skull");  
                       fail_this: return err; /* propagate the error */  
                       }

 
                            int __init my_init_function(void)  
                       {  
                       int err;  
                        
                       /* l'enregistrement reçoit un pointeur et un nom */ err = register_this(ptr1, "skull");  
                       if (err) goto fail_this;  
                       err = register_that(ptr2, "skull");  
                       if (err) goto fail_that;  
                       err = register_those(ptr3, "skull");  
                       if (err) goto fail_those;  
                        
                       return 0; /* success */  
                        
                       fail_those: unregister_that(ptr2, "skull");  
                       fail_that: unregister_this(ptr1, "skull");  
                       fail_this: return err; /* propage l'erreur */  
                       }

---

This code attempts to register three (fictitious)facilities. The goto statement is used in case of failure to cause the unregistration of only the facilities that had been successfully registered before things went bad.

Ce code tente d'enregistrer trois équipements (fictifs). La déclaration <i>goto</i> est utilisée dans le cas d'un échec pour provoquer seulement le déchargement des équipements enregistrés avant que les choses ne se soit mal passées.

---

Another option, requiring no hairy goto statements, is keeping track of what has been successfully registered and calling your module's cleanup function in case of any error. The cleanup function unrolls only the steps that have been successfully accomplished. This alternative, however, requires more code and more CPU time, so in fast paths you still resort to goto as the best error-recovery tool.

Une autre option, ne nécessitant pas de déclaration <i>goto</i>, garde une piste de ce qui a été enregistré avec succès et appelle la fonction de nettoyage de votre module au cas une erreur surviendrait. La fonction de nettoyage ne défait que les étapes qui ont été accomplies avec succès. Cependant, cette alternative nécessite plus de code et plus de temps CPU, ainsi dans quelques cas vous aurez quand même recours à <i>goto</i> comme meilleur outil de recouvrement d'erreurs.

---

The return value of my_init_function, err, is an error code. In the Linux kernel, error codes are negative numbers belonging to the set defined in &lt;linux/errno.h&gt;. If you want to generate your own error codes instead of returning what you get from other functions, you should include &lt;linux/errno.h&gt; in order to use symbolic values such as -ENODEV, -ENOMEM, and so on. It is always good practice to return appropriate error codes, because user programs can turn them to meaningful strings using perror or similar means.

La valeur de retour de la fonction <i>my_init_function</i>, <i>err</i>, est un code d'erreur. Dans le noyau Linux, les codes d'erreurs ont des nombres négatifs appartenant au définitions dans &lt;linux/errno.h&gt;. Si vous voulez générer vos propres codes d'erreurs plutôt que de retourner ce que vous recevez d'autres fonctions, vous devriez importer &lt;linux/errno.h&gt; afin de pouvoir utiliser des valeurs symboliques comme <b>-ENODEV</b>, <b>-ENOMEM</b>, etc. C'est toujours un bon exercice de retourner des codes d'erreurs appropriés parce que les programmes de l'utilisateur peuvent les interpréter sous forme de chaînes de caractères en utilisant la fonction <i>perror</i> ou fonction similaire.

---

Obviously, the module cleanup function must undo any registration performed by the initialization function, and it is customary (but not usually mandatory)to unregister facilities in the reverse order used to register them :

Évidemment, la fonction de nettoyage du module doit défaire n'importe quel enregistrement réalisé par la fonction d'initialisation, et c'est usuel (mais non obligatoire) de décharger les équipements dans le sens inverse où on les a enregistrées :

---

If your initialization and cleanup are more complex than dealing with a few items, the goto approach may become difficult to manage, because all the cleanup code must be repeated within the initialization function, with several labels intermixed. Sometimes, therefore, a different layout of the code proves more successful.

Si votre initialisation et nettoyage sont plus complexe que le traitement de quelques objets, l'approche par <i>goto</i> peut devenir difficile à gérer parce que tout le code de nettoyage doit être répété à l'intérieur de la fonction d'initialisation, avec plusieurs étiquettes interchangées. Parfois, donc, une couche différente du code se révèle plus convaincante.

---

What you'd do to minimize code duplication and keep everything streamlined is to call the cleanup function from within the initialization whenever an error occurs. The cleanup function then must check the status of each item before undoing its registration. In its simplest form, the code looks like the following :

Ce que vous pouvez faire pour minimiser la duplication de code et garder le tout linéaire est d'appeler la fonction de nettoyage à l'intérieur de la fonction d'initialisation à chaque fois qu'une erreur apparaît. La fonction de nettoyage doit ensuite vérifier le statut de chaque point avant de défaire son enregistrement. Dans sa forme la plus simple, le code ressemble à celui ci-dessous :

---

As shown in this code, you may or may not need external flags to mark success of the initialization step, depending on the semantics of the registration/allocation function you call. Whether or not flags are needed, this kind of initialization scales well to a large number of items and is often better than the technique shown earlier. Note, however, that the cleanup function cannot be marked __exit when it is called by nonexit code, as in the previous example.

Comme montré dans ce code, vous pouvez ou ne pouvez pas avoir besoin des drapeaux externes pour marquer le succès de l'étape d'initialisation, selon la sémantique de la fonction d'enregistrement/allocation que vous appelez. Si les drapeaux sont vraiment nécessaires, ce genre d'initialisation correspond bien à un grand nombre de points et est souvent meilleure que la méthode montrée plus tôt. Notez, cependant, que la fonction de nettoyage ne peut pas être notée <i>__exit</i> quand elle est appelée par un code non-sortant comme dans l'exemple précédent.

Fin du chapitre et XML disponible dans le premier post

Comme d'habitude, une relecture technique s'impose car rien que les mots "équipement" et "fonction de nettoyage" me chiffonnent

Fin de la partie

++

[Michaël]

il ne reste plus que la relecture orthographique