Referencia general de HAL

1. Nombres de entidades HAL

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.

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. Convenciones generales de nombres en HAL

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 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". ^[1]
Usar solo letras minúsculas y números en los nombres.

3. Convenciones de nombres de controladores de hardware

Note	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

Hardware drivers should use five fields (on three levels) to make up a pin or parameter name, as follows:

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

Los campos individuales son:

<nombre-de-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.
<número-de-canal>: 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.^[2] 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.
<nombre-específico>: 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 de E/S, hay un conjunto estándar de pines y parámetros (denominada "interfaz canónica"), que el controlador debería implementar. Las interfaces canónicas se describen en el capítulo Interfaces canónicas de dispositivos.

Ejemplos

motenc.0.encoder.2.position: La salida de posición del tercer canal (2) del codificador de la primera (0) placa Motenc.
stg.0.din.03.in: El estado de la cuarta entrada digital (03) en la primera (0) placa Servo-to-Go.
ppmc.0.pwm.00-03.frequency: La frecuencia de portadora utilizada para los canales PWM 0 a 3 (cuatro canales) en la primera (0) placa ppmc de Pico Systems.

3.2. Nombres de funciones

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:

<nombre-de-dispositivo>-<número-de-dispositivo>.<tipo-e-s>-<rango-número-de-canal>.read|write

<nombre-de-dispositivo>: El mismo que se usa para pines y parámetros.
<número-de-dispositivo>: El dispositivo específico al que accederá la función.
<tipo-e-s>: Opcional. Una función puede acceder a todas las E/S de una placa, o puede acceder solo a cierto tipo. Por ejemplo, puede haber distintas funciones para leer codificadores contadores y leer E/S digitales. Si tales funciones independientes existen, el campo <tipo-e-s> identifica el tipo de E/S a la que acceden. Si una sola función lee todas las E/S provistas por la placa no se utiliza <tipo-e-s>. ^[3]
<rango-número-de-canal>: Opcional. Se usa solo si <tipo-e-s> E/S se divide en grupos y se acceden por funciones diferentes.
read|write: Indica si la función lee el hardware o escribe en él.

Ejemplos

motenc.0.encoder.read: Lee todos los codificadores en la primera placa motenc.
generic8255.0.din.09-15.read: Lee el segundo puerto de 8 bits en la primera placa de E/S digital genérica basada en 8255.
ppmc.0.write: Escribe todas las salidas (generadores de pasos, pwm, DAC y digitales) en la primera placa ppmc de Pico Systems.

1. 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.

2. 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.

3. Nota para los programadores de controladores: NO implementar funciones por separado para diferentes tipos de E/S a menos que sean interrumpibles y puedan trabajar en hilos independientes. Si se interrumpe una lectura de codificador leyendo entradas digitales y luego la reanudación de la lectura causa problemas, entonces implementar una sola función que lo haga todo.