1. Nombres de entidades HAL

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

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

<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 primer (0) placa Motenc.

stg.0.din.03.in

El estado de la cuarta entrada digital (03) en la primer (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 primer (0) placa ppmc de Pico Systems.

3.2. Nombres de funciones

Los controladores de hardware generalmente solo tienen dos tipos de funciones HAL, unas que leen el hardware y actualizan los pines HAL, y otras que escriben en el hardware utilizando datos de pines HAL. Deben nombrarse de la siguiente manera:

<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>.
[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.]

<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 primer placa motenc.

generic8255.0.din.09-15.read

Lee el segundo puerto de 8 bits en la primer 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.