Referencia general de HAL

1. HAL, nombres de entidades

Todas la entidades HAL son accesibles y manipulables por sus nombres, por lo que es muy importante documentar los nombres de los pines, señales, parámetros, etc. Los nombres en HAL tienen una longitud máxima de 41 caracteres (como se define en HAL_NAME_LEN en hal.h). Muchos nombres serán presentados en la forma general, con el texto fomateado <como-este> representando campos de varios valores.

Cuando se describan por primera vez pines, señales o parámetros, su nombre será precedido por su tipo en paréntesis (float) y seguido por una descripción breve. Las definiciones típicas de pines se ven como estos ejemplos:

(bit) parport.<número-de-puerto>.pin-<número-de-pin>-in: El pin HAL asociado con el pin de entrada física <número-de-pin> de un conector db25.
(float) pid.<número-de-bucle>.output: La salida de bucle PID

Ocasionalmente, se puede usar una versión abreviada del nombre, por ejemplo, el segundo pin de arriba pudo haber sido llamado simplemente con .output cuando se puede hacer sin causar confusión.

2. HAL, convenciones de nombrado

Unas convenciones de nombres consistentes harán que HAL sea mucho más fácil de usar. Por ejemplo, si cada controlador de codificador proporciona el mismo conjunto de pines y los nombra de la misma manera, sería fácil cambiar de un tipo de controlador de codificador a otro. Desafortunadamente, al igual que muchos proyectos de código abierto, HAL es una combinación de cosas que fueron diseñadas, y cosas que simplemente evolucionaron. Como resultado, hay muchas inconsistencias. Esta sección intenta abordar ese problema definiendo algunas convenciones, pero probablemente pasará un tiempo antes de que todos los módulos se conviertan para seguirlas.

Halcmd y otras utilidades HAL de bajo nivel tratan los nombres HAL como entidades simples, sin estructura interna. Sin embargo, la mayoría de los módulos sí tienen alguna estructura implícita. Por ejemplo, una tarjeta proporciona varios bloques funcionales, cada bloque puede tener varios canales, y cada canal tiene uno o más pines. Resulta asi en una estructura que se asemeja a un árbol de directorios. Aunque halcmd no reconoce estructuras de árbol, la elección adecuada de las convenciones de nomenclatura dejará agrupar elementos relacionados (ya que ordena los nombres). Además, se pueden diseñar herramientas de más alto nivel para reconocer dicha estructura, si los nombres proporcionan la información necesaria. Para hacer eso, todos los componentes HAL deberían seguir estas reglas:

Los puntos (".") separan niveles de la jerarquía. Esto es análogo a la barra inclinada ("/") en un nombre de archivo.
Los guiones ("-") separan palabras o campos en el mismo nivel de la jerarquía.
Los componentes HAL no deben usar guiones bajos o "mezcla de mayúsculas y minúsculas".
[Se han eliminado caracteres subrayados, pero aún quedan algunos casos de mezcla errónea, por ejemplo pid.0.Pgain en lugar de pid.0.p-gain.]
Usar solo letras minúsculas y números en los nombres.

3. Convenciones de nombres de controladores de hardware

Nota	En la versión 2.0, la mayoría de los controladores no siguen estas convenciones. Este capítulo es en realidad una guía para desarrollos futuros.

3.1. Nombres de pines/parámetros

Los controladores de hardware deben usar cinco campos (en tres niveles) para formar un pin o nombre de parámetro, de la siguiente manera:

<nombre-de-dispositivo>.<número-de-dispositivo>.<tipo-e-s>.<número-de-canal>.<nombre-específico>

Los campos individuales son:

<nombre-del-dispositivo>: El dispositivo con el que el controlador está diseñado trabajar. Esto es a menudo una placa de interfaz de algún tipo, pero hay otras posibilidades.
<número-de-dispositivo>: Es posible instalar más de un(a) placa servo, puerto paralelo, u otro dispositivo de hardware en una computadora. El número de dispositivo identifica a uno en específico. Los números de dispositivo comienzan en 0 e incrementan.

<tipo-e-s>: La mayoría de los dispositivos proporcionan más de un tipo de E/S. Incluso el simple puerto paralelo tiene entradas y salidas digitales. Placas más complejas pueden tener entradas y salidas digitales, codificadores contadores, generadores pwm o de impulsos de pasos, convertidores analógico a digital y/o digital a analógico u otras capacidades únicas. El tipo de E/S se usa para identificar el tipo de E/S al que está asociado un pin o parámetro. Idealmente, los controladores que implementan el mismo tipo de E/S, incluso si son para dispositivos muy diferentes, deberían proporcionar un conjunto consistente de pines y parámetros, y un comportamiento idéntico. Por ejemplo, todas las entradas digitales deberían comportarse de la misma manera desde el interior del HAL, independientemente del dispositivo.
<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>: Un canal de E/S individual puede tener solo un pin HAL asociado con él, pero la mayoría tiene más de uno. Por ejemplo, una entrada digital tiene dos pines, uno es el estado del pin físico, el otro es la misma cosa pero invertida. Eso le permite al configurador elegir entre entradas activas bajas y activas altas. Para la mayoría de los tipos-io, hay un conjunto estándar de pines y parámetros, (denominada "interfaz canónica") que el driver debería implementar. Las interfaces canónicas se describen en el capítulo Interfaces canonicos de dispositivos.

Ejemplos

motenc.0.encoder.2.position: The position output of the third encoder channel on the first Motenc board.
stg.0.din.03.in: The state of the fourth digital input on the first Servo-to-Go board.
ppmc.0.pwm.00-03.frequency: The carrier frequency used for PWM channels 0 through 3 on the first Pico Systems ppmc board.

3.2. Function Names

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

<nombre-de-dispositivo>: The same as used for pins and parameters.
<número-de-dispositivo>: The specific device that the function will access.
<tipo-es>: 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. Used only if the <io-type> I/O is broken into groups and accessed by different functions.
read|write: Indicates whether the function reads the hardware or writes to it.

Ejemplos

motenc.0.encoder.read: Reads all encoders on the first motenc board.
generic8255.0.din.09-15.read: Reads the second 8 bit port on the first generic 8255 based digital I/O board.
ppmc.0.write: Writes all outputs (step generators, pwm, DACs, and digital) on the first Pico Systems ppmc board.