1  :lang: fr
  2  :toc:
  3  
  4  = Conventions générales
  5  
  6  [[cha:References-generales]]
  7  
  8  == Les noms
  9  
 10  Toutes les entités de HAL sont accessibles et manipulées par leurs
 11  noms, donc, documenter les noms des pins, signaux, paramètres, etc, est
 12  très important. Les noms dans HAL ont un maximum de 41 caractères de
 13  long (comme défini par HAL_NAME_LEN dans hal.h). De nombreux noms
 14  seront présentés dans la forme générale, avec un texte mis en forme
 15  _<comme-cela>_ représentant les champs de valeurs diverses.
 16  
 17  Quand les pins, signaux, ou paramètres sont décrits pour la première
 18  fois, leur nom sera précédé par leur type entre parenthèses (_float_) et
 19  suivi d'une brève description. Les définitions typiques de pins
 20  ressemblent à ces exemples:
 21  
 22  (bit) parport.<portnum>.pin-<pinnum>-in::
 23      La HAL pin associée avec la broche physique d'entrée _<pinnum>_ du 
 24      connecteur db25.
 25  
 26  (float) pid.<loopnum>.output::
 27      La sortie de la boucle PID.
 28  
 29  De temps en temps, une version abrégée du nom peut être utilisée, par
 30  exemple la deuxième pin ci-dessus pourrait être appelée simplement
 31  avec _.output_ quand cela peut être fait sans prêter à confusion.
 32  
 33  == Conventions générales de nommage[[sec:GR-Conventions-nommage]]
 34  
 35  Le but des conventions de nommage est de rendre l'utilisation de HAL
 36  plus facile. Par exemple, si plusieurs interfaces de codeur fournissent
 37  le même jeu de pins et qu'elles sont nommées de la même façon, il
 38  serait facile de changer l'interface d'un codeur à un autre.
 39  Malheureusement, comme tout projet open-source, HAL est la combinaison
 40  de choses diversement conçues et comme les choses simples évoluent. Il
 41  en résulte de nombreuses incohérences. Cette section vise à remédier à
 42  ce problème en définissant certaines conventions, mais il faudra
 43  certainement un certain temps avant que tous les modules soient
 44  convertis pour les suivre.
 45  
 46  Halcmd et d'autres utilitaires HAL de bas niveau, traitent les noms
 47  HAL comme de simples entités, sans structure. Toutefois, la plupart des
 48  modules ont une certaine structure implicite. Par exemple, une carte
 49  fournit plusieurs blocs fonctionnels, chaque bloc peut avoir plusieurs
 50  canaux et chaque canal, une ou plusieurs broches. La structure qui en
 51  résulte ressemble à une arborescence de répertoires. Même si halcmd ne
 52  reconnait pas la structure arborescente, la convention de nommage est
 53  un bon choix, elles lui permettra de regrouper ensemble, les items du
 54  même groupe, car il trie les noms. En outre, les outils de haut niveau
 55  peuvent être conçus pour reconnaitre de telles structures si les noms
 56  fournissent les informations nécessaires. Pour cela, tous les modules
 57  de HAL devraient suivrent les règles suivantes:
 58  
 59   - Les points (_._) séparent les niveaux hiérarchiques. C'est analogue à
 60     la barre de fraction (_/_) dans les noms de fichiers.
 61   - Le tiret (_-_) sépare les mots ou les champs dans la même hiérarchie.
 62   - Les modules HAL ne doivent pas utiliser le caractère souligné ou les
 63     casses mélangées. footnote:[Les caractères souslignés ont été enlevés,
 64     mais il reste quelques cas
 65     de mélange de casses, par exemple _pid.0.Pgain_ au lieux de 
 66     _pid.0.p-gain_.]
 67   - Utiliser seulement des caractères minuscules, lettres et chiffres.
 68  
 69  == Conventions de nommage des pilotes de matériels[[sec:GR-Nommage-pilotes-materiel]]
 70  footnote:[La plupart des pilotes ne suivent pas ces conventions dans la version 2.0. 
 71  Ce chapitre est réellement un guide pour les développements futurs.]
 72  
 73  === Noms de pin/paramètre
 74  
 75  Les pilotes matériels devraient utiliser cinq champs (sur trois
 76  niveaux) pour obtenir un nom de pin ou de paramètre, comme le suivant:
 77  ----
 78  <device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>
 79  ----
 80  
 81  Les champs individuels sont:
 82  
 83  <device-name>::
 84        Le matériel avec lequel le pilote est sensé travailler. Il s'agit le
 85      plus souvent d'une carte d'interface d'un certain type, mais il existe
 86      d'autres possibilités. 
 87  
 88  <device-num>::
 89        Il est possible d'installer plusieurs cartes servo, ports parallèles
 90      ou autre périphérique matériel dans un ordinateur. Le numéro du
 91      périphérique identifie un périphérique spécifique. Les numéros de
 92      périphériques commencent à 0 et s'incrémentent.footnote:[Certains
 93      matériels utilisent des cavaliers ou d'autres dispositifs
 94      pour définir une identification spécifique à chacun. Idéalement, le
 95      pilote fournit une manière à l'utilisateur de dire, le _device-num 0
 96      est spécifique au périphérique qui a l'ID XXX_, ses sous-ensembles
 97      porterons tous un numéro commençant par 0. Mais à l'heure actuelle,
 98      certains pilotes utilisent l'ID directement comme numéro de
 99      périphérique. Ce qui signifie qu'il est possible d'avoir un
100      périphérique Numéro 2, sans en avoir en Numéro 0. C'est un bug qui
101      devrait disparaître en version 2.1.]
102  
103  <io-type>::
104        La plupart des périphériques fournissent plus d'un type d'I/O. Même
105      le simple port parallèle a, à la fois plusieurs entrées et plusieurs
106      sorties numériques. Les cartes commerciales plus complexes peuvent
107      avoir des entrées et des sorties numériques, des compteurs de codeurs,
108      des générateurs d'impulsions de pas ou de PWM, des convertisseurs
109      numérique/analogique, analogique/numérique et d'autres possibilités
110      plus spécifiques. Le _I/O type_ est utilisé pour identifier le type
111      d'I/O avec lequel la pin ou le paramètre est associé. Idéalement, les
112      pilotes qui implémentent les mêmes type d'I/O, même sur des dispositifs
113      très différents, devraient fournir un jeu de pins et de paramètres
114      cohérents et de comportements identiques. Par exemple, toutes les
115      entrées numériques doivent se comporter de la même manière quand elles
116      sont vues de l'intérieur de HAL, indépendamment du périphérique.
117  
118  <chan-num>::
119        Quasiment tous les périphériques d'I/O ont plusieurs canaux, le
120      numéro de canal _chan-num_ identifie un de ceux ci. Comme les numéros
121      de périphériques _device-num_, les numéros de canaux, _chan-num_, 
122      commencent à zéro et s'incrémentent.footnote:[Une exception à la règle
123      du _numéro de canal commençant à zéro_ est le
124      port parallèle. Ses _HAL pins_ sont numérotées avec le numéro de la
125      broche correspondante du connecteur DB-25. C'est plus pratique pour le
126      câblage, mais non cohérent avec les autres pilotes. Il y a débat pour
127      savoir si c'est un bogue ou une fonctionnalité.] 
128      Si plusieurs périphériques sont installés, les numéro de canaux des
129      périphériques supplémentaires recommencent à zéro. Comme il est
130      possible d'avoir un numéro de canal supérieur à 9, les numéros de
131      canaux doivent avoir deux chiffres, avec un zéro en tête pour les
132      nombres inférieur à 10 pour préserver l'ordre des tris. Certains
133      modules ont des pins et/ou des paramètres qui affectent plusieurs
134      canaux. Par exemple un générateur de PWM peut avoir quatre canaux avec
135      quatre entrées _duty-cycle_ indépendantes, mais un seul paramètre
136      _frequency_ qui contrôle les quatres canaux (à cause de limitations
137      matérielles). Le paramètre _frequency_ doit utiliser les numéros de
138      canaux de _00-03_. 
139  
140  <specific-name>::
141        Un canal individuel d'I/O peut avoir une seule HAL pin associée avec
142      lui, mais la plupart en ont plus. Par exemple, une entrée numérique a
143      deux pins, une qui est l'état de la broche physique, l'autre qui est la
144      même chose mais inversée. Cela permet au configurateur de choisir entre
145      les deux états de l'entrée, active haute ou active basse. Pour la
146      plupart des types d' entrée/sortie, il existe un jeu standard de
147      broches et de paramètres, (appelé l'_interface canonique_) que le
148      pilote doit implémenter. Les interfaces canoniques sont décrites
149      <<sec:Peripheriques-canoniques, dans ce chapitre qui leur est dédié>>.
150  
151  ==== Exemples
152  
153  motenc.0.encoder.2.position::
154       La sortie position du troisième canal codeur sur la première carte Motenc.
155  
156  stg.0.din.03.in::
157       L'état de la quatrième entrée numérique sur la première carte Servo-to-Go.
158  
159  ppmc.0.pwm.00-03.frequency::
160       La fréquence porteuse utilisée sur les canaux PWM de 0 à 3 sur la 
161      première carte Pico Systems ppmc.
162  
163  === Noms des fonctions
164  
165  Les pilotes matériels ont généralement seulement deux types de
166  fonctions HAL, une qui lit l'état du matériel et met à jour les pins
167  HAL, l'autre qui écrit sur le matériel en utilisant les données
168  fournies sur les pins HAL. Ce qui devrait être nommé de la façon
169  suivante:
170  ----
171  <device-name>-<device-num>.<io-type>-<chan-num-range>.read|write
172  ----
173  
174  <device-name>::
175       Le même que celui utilisé pour les pins et les paramètres.
176  
177  <device-num>::
178       Le périphérique spécifique auquel la fonction aura accès.
179  
180  <io-type>::
181        Optionnel. Une fonction peut accéder à toutes les d'entrées/sorties
182      d'une carte ou, elle peut accéder seulement à un certain type. Par
183      exemple, il peut y avoir des fonctions indépendantes pour lire les
184      compteurs de codeurs et lire les entrées/sorties numériques. Si de
185      telles fonctions indépendantes existent, le champ <io-type> identifie
186      le type d'I/O auxquelles elles auront accès. Si une simple fonction lit
187      toutes les entrés/sorties fournies par la carte, <io-type> n'est pas
188      utilisé.footnote:[Note aux programmeurs de pilotes: ne PAS implémenter
189      des fonctions
190      séparées pour différents types d'I/O à moins qu'elles ne soient
191      interruptibles et puissent marcher dans des threads indépendants. Si
192      l'interruption de la lecture d'un codeur pour lire des entrées
193      numériques, puis reprendre la lecture du codeur peut poser problème,
194      alors implémentez une fonction unique qui fera tout.] 
195  
196  <chan-num-range>::
197        Optionnel. Utilisé seulement si l'entrée/sortie <io-type> est cassée
198      dans des groupes et est accédée par différentes fonctions.
199  
200  read|write::
201       Indique si la fonction lit le matériel ou lui écrit.
202  
203  ==== Exemples
204  
205  motenc.0.encoder.read::
206       Lit tous les codeurs sur la première carte motenc.
207  
208  generic8255.0.din.09-15.read::
209       Lit le deuxième port 8 bits sur la première carte
210      d'entrées/sorties à base de 8255.
211  
212  ppmc.0.write::
213       Écrit toutes les sorties (générateur de pas, pwm, DAC et ADC) sur
214      la première carte Pico Systems ppmc.
215  
216  [[sec:Peripheriques-canoniques]]
217  == Périphériques d'interfaces canoniques
218  (((Périphériques canoniques)))
219  
220  Les sections qui suivent expliquent les pins, paramètres et fonctions
221  qui sont fournies par les _périphériques canoniques_. Tous les pilotes
222  de périphériques HAL devraient fournir les mêmes pins et paramètres et
223  implémenter les mêmes comportements.
224  
225  Noter que seuls les champs _<io-type>_ et _<specific-name>_ sont
226  définis pour un périphérique canonique. Les champs _<device-name>_,
227  _<device-num>_ et _<chan-num>_ sont définis en fonction des
228  caractéristiques du périphérique réel.
229  
230  == Entrée numérique (Digital Input)[[sec:CanonDigIn]]
231  
232  L'entrée numérique canonique (I/O type: _digin_) est assez simple.
233  
234  === Pins
235  
236  (bit) _in_::
237     État de l'entrée matérielle.
238  (bit) _in-not_::
239     État inversé de l'entrée matérielle.
240  
241  === Paramètres
242  
243  Aucun
244  
245  === Fonctions
246  
247  (funct) _read_::
248       Lire le matériel et ajuster les HAL pins _in_ et _in-not_.
249  
250  == Sortie numérique (Digital Output)[[sec:CanonDigOut]]
251  
252  La sortie numérique canonique est également très simple (I/O type: _digout_).
253  
254  === Pins
255  
256  (bit) _out_::
257      Valeur à écrire (éventuellement inversée) sur une sortie matérielle.
258  
259  === Paramètres
260  
261  (bit) _invert_::
262      Si TRUE, _out_ est inversée avant écriture sur la sortie matérielle.
263  
264  === Fonctions
265  
266  (funct) _write_::
267      Lit _out_ et _invert_ et ajuste la sortie en conséquence.
268  
269  == Entrée analogique (Analog Input)
270  
271  L'entrée analogique canonique (I/O type: _adcin_ ). Devrait être
272  utilisée pour les convertisseurs
273  analogiques/numériques, qui convertissent par exemple, les tensions en
274  une échelle continue de valeurs.
275  
276  === Pins
277  
278  (float) _value_::
279       Lecture du matériel, avec mise à l'échelle ajustée par les 
280      paramètres _scale_ et _offset_. _Value_ = ((lecture entrée, en unités 
281      dépendantes du matériel) x _scale_) - _offset_
282  
283  === Paramètres
284  
285  (float) _scale_::
286       La tension d'entrée (ou l'intensité) sera
287      multipliée par _scale_ avant d'être placée dans _value_.
288  (float) _offset_::
289       Sera soustrait à la tension d'entrée (ou l'intensité) après que 
290      la mise à l'échelle par scale ait été appliquée.
291  (float) _bit_weight_::
292       Valeur du bit le moins significatif (LSB). C'est effectivement, la 
293      granularité de lecture en entrée.
294  (float) _hw_offset_::
295       Valeur présente sur l'entrée quand aucune tension n'est appliquée sur la 
296      pin.
297  
298  === Fonctions
299  
300  (funct) _read_::
301       Lit les valeurs de ce canal d'entrée analogique. Peut être utilisé pour 
302      lire un canal individuellement, ou pour lire tous les canaux à la fois. 
303  
304  == Sortie analogique (Analog Output)
305  
306  La sortie analogique canonique (I/O Type: _adcout_ ). Elle est
307  destinée à tout type de matériel capable de sortir une
308  échelle plus ou moins étendue de valeurs. Comme par exemple les
309  convertisseurs numérique/analogique ou les générateurs de PWM.
310  
311  === Pins
312  
313  (float) _value_::
314       La valeur à écrire. La valeur réelle sur la sortie matérielle dépends 
315      de la mise à l'échelle des paramètres d'offset.
316  (bit) _enable_::
317       Si fausse, la sortie matérielle passera à 0, indépendamment de la pin _value_.
318  
319  === Paramètres
320  
321  (float) _offset_::
322       Sera ajouté à _value_ avant l'actualisation du
323     matériel.
324  (float) _scale_::
325       Doit être défini de sorte qu'une entrée avec 1 dans _value_ produira 1V 
326  (float) _high_limit_::
327       (optionnel) Quand la valeur en sortie matérielle est calculée, 
328      si _value_ + _offset_ est plus grande que _high_limit_, alors _high_limit_ 
329      lui sera substitué.
330  (float) _low_limit_::
331       (optionnel) Quand la valeur en sortie matérielle est calculée, 
332      si _value_ + _offset_ est plus petite que _low_limit_, alors _low_limit_ 
333      lui sera substitué.
334  (float) _bit_weight_::
335       (optionnel) La valeur du bit le moins significatif (LSB), en Volts
336      (ou mA, pour les sorties courant)
337  (float) _hw_offset_::
338       (optionnel) La tension actuelle (ou l'intensité) présente sur la
339      sortie quand 0 est écrit sur le matériel.
340  
341  === Fonctions
342  
343  (funct) _write_::
344       Ecrit la valeur calculée sur la sortie matérielle. Si enable est FALSE, 
345      la sortie passera à 0, indépendamment des valeurs de _value_, _scale_ et 
346      _offset_ . La signification de _0_ dépend du matériel. Par exemple, un 
347      convertisseur A/D 12 bits peut vouloir écrire 0x1FF (milieu d'échelle)
348      alors que le convertisseur D/A reçoit 0 Volt de la broche matérielle.
349      Si enable est TRUE, l'échelle, l'offset et la valeur sont traités et
350      (_scale_ _ _value_) + _offset_ sont envoyés à la sortie du DAC . Si
351      enable est FALSE, la sortie passe à 0.
352  
353