1. HAL-Entitätsnamen

All HAL entities are accessible and manipulable by their names, so documenting the names of pins, signals, parameters, etc., is very important. Names in HAL have a maximum length of 41 characters (as defined by HAL_NAME_LEN in hal.h). Many names will be presented in the general form, with formatted text <like-this> representing fields of various values.

When pins, signals, or parameters are described for the first time, their name will be preceded by their type in parentheses (float) and followed by a brief description. Typical pins definitions look like these examples:

(bit) parport.<portnum>.pin-<pinnum>-in

Der HAL-Pin, der mit dem physischen Eingangspin <pinnum> des db25-Anschlusses verbunden ist.

(float) pid.<loopnum>.output

Der PID-Regelkreis Ausgang

Gelegentlich kann eine abgekürzte Version des Namens verwendet werden, z. B. könnte der zweite Pin oben einfach mit .output aufgerufen werden, wenn dies möglich ist, ohne dass es zu Verwechslungen kommt.

2. Allgemeine HAL-Namenskonventionen

Consistent naming conventions would make HAL much easier to use. For example, if every encoder driver provided the same set of pins and named them the same way, then it would be easy to change from one type of encoder driver to another. Unfortunately, like many open-source projects, HAL is a combination of things that were designed, and things that simply evolved. As a result, there are many inconsistencies. This section attempts to address that problem by defining some conventions, but it will probably be a while before all the modules are converted to follow them.

Halcmd and other low-level HAL utilities treat HAL names as single entities, with no internal structure. However, most modules do have some implicit structure. For example, a board provides several functional blocks, each block might have several channels, and each channel has one or more pins. This results in a structure that resembles a directory tree. Even though halcmd doesn’t recognize the tree structure, proper choice of naming conventions will let it group related items together (since it sorts the names). In addition, higher level tools can be designed to recognize such structure, if the names provide the necessary information. To do that, all HAL components should follow these rules:

  • Punkte (".") trennen die einzelnen Ebenen der Hierarchie. Dies ist vergleichbar mit dem Schrägstrich ("/") in einem Dateinamen.

  • Bindestriche („-“) trennen Wörter oder Felder auf derselben Hierarchieebene.

  • HAL-Komponenten sollten keine Unterstriche oder "MixedCase" verwenden.
    [Die unterstrichenen Zeichen wurden entfernt, aber es gibt immer noch einige Fälle, in denen die Mischung nicht stimmt, zum Beispiel pid.0.Pgain anstelle von pid.0.p-gain.]

  • Verwenden Sie in Namen nur Kleinbuchstaben und Zahlen.

3. Namenskonventionen für Hardwaretreiber

Anmerkung

Die meisten Treiber folgen diesen Konventionen in Version 2.0 nicht. Dieses Kapitel ist eher ein Leitfaden für zukünftige Entwicklungen.

3.1. Pins/Parameter-Namen

Hardwaretreiber sollten fünf Felder (auf drei Ebenen) verwenden, um einen PIN- oder Parameternamen wie folgt zu bilden:

<Gerätename>.<Gerätenummer>.<E/A-Typ>.<Kanal-Nummer>.<Spezifischer Name>
(engl. <device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>)

Die einzelnen Felder sind:

<device-name>

The device that the driver is intended to work with. This is most often an interface board of some type, but there are other possibilities.

<device-num>

It is possible to install more than one servo board, parallel port, or other hardware device in a computer. The device number identifies a specific device. Device numbers start at 0 and increment.

<io-type>

Most devices provide more than one type of I/O. Even the simple parallel port has both digital inputs and digital outputs. More complex boards can have digital inputs and outputs, encoder counters, pwm or step pulse generators, analog-to-digital converters, digital-to-analog converters, or other unique capabilities. The I/O type is used to identify the kind of I/O that a pin or parameter is associated with. Ideally, drivers that implement the same I/O type, even if for very different devices, should provide a consistent set of pins and parameters and identical behavior. For example, all digital inputs should behave the same when seen from inside the HAL, regardless of the device.

<chan-num>

Virtually every I/O device has multiple channels, and the channel number identifies one of them. Like device numbers, channel numbers start at zero and increment.
[One exception to the "channel numbers start at zero" rule is the parallel port. Its HAL pins are numbered with the corresponding pin number on the DB-25 connector. This is convenient for wiring, but inconsistent with other drivers. There is some debate over whether this is a bug or a feature.]
 If more than one device is installed, the channel numbers on additional devices start over at zero. If it is possible to have a channel number greater than 9, then channel numbers should be two digits, with a leading zero on numbers less than 10 to preserve sort ordering. Some modules have pins and/or parameters that affect more than one channel. For example a PWM generator might have four channels with four independent "duty-cycle" inputs, but one "frequency" parameter that controls all four channels (due to hardware limitations). The frequency parameter should use "0-3" as the channel number.

<specific-name>

An individual I/O channel might have just a single HAL pin associated with it, but most have more than one. For example, a digital input has two pins, one is the state of the physical pin, the other is the same thing inverted. That allows the configurator to choose between active high and active low inputs. For most io-types, there is a standard set of pins and parameters, (referred to as the "canonical interface") that the driver should implement. The canonical interfaces are described in the Canonical Device Interfaces chapter.

Beispiele
motenc.0.encoder.2.position

Der Positionsausgang des dritten Encoderkanals auf der ersten Motenc-Platine.

stg.0.din.03.in

Der Zustand des vierten digitalen Eingangs auf der ersten Servo-to-Go-Karte.

ppmc.0.pwm.00-03.frequency

Die für die PWM-Kanäle 0 bis 3 auf der ersten Pico Systems ppmc-Karte verwendete Trägerfrequenz.

3.2. Funktionsnamen

Hardware drivers usually only have two kinds of HAL functions, ones that read the hardware and update HAL pins, and ones that write to the hardware using data from HAL pins. They should be named as follows:

<device-name>-<device-num>.<io-type>-<chan-num-range>.read|write
<Gerätename> (engl. device-name)

Das gleiche wie für Pins und Parameter.

<Gerät-Nr.> (engl. device-num)

Das spezifische Gerät, auf das die Funktion zugreift.

<E/A-Typ> (engl. io-type)

Optional. A function may access all of the I/O on a board, or it may access only a certain type. For example, there may be independent functions for reading encoder counters and reading digital I/O. If such independent functions exist, the <io-type> field identifies the type of I/O they access. If a single function reads all I/O provided by the board, <io-type> is not used.
[Note to driver programmers: Do NOT implement separate functions for different I/O types unless they are interruptible and can work in independent threads. If interrupting an encoder read, reading digital inputs, and then resuming the encoder read will cause problems, then implement a single function that does everything.]

<chan-num-range>

Optional. Wird nur verwendet, wenn die <io-type> E/A in Gruppen unterteilt ist und verschiedene Funktionen darauf zugreifen.

read|write

Gibt an, ob die Funktion die Hardware liest (engl. read) oder in sie schreibt (engl. write).

Beispiele
motenc.0.encoder.read

Liest alle Encoder auf der ersten Motenc-Platine aus.

generic8255.0.din.09-15.read

Liest den zweiten 8-Bit-Port auf der ersten generischen 8255-basierten digitalen E/A-Karte.

ppmc.0.write

Schreibt alle Ausgänge (Schrittgeneratoren, PWM, DACs und Digital) auf die erste Pico Systems ppmc-Karte.