GPIO con descriptores: controlar un pin sin números mágicos

Un GPIO —General Purpose Input/Output— es la unidad más humilde del hardware: un solo pin que el software puede leer como entrada o forzar como salida a nivel alto o bajo. Enciende un LED, muestrea un botón, resetea un chip, selecciona un dispositivo en un bus. Durante veinte años el kernel controló esos pines con números enteros globales; hoy los controla con descriptores opacos que esconden el número, la polaridad y la propiedad del recurso. Ese cambio no es cosmético: es la diferencia entre un driver atado a una placa concreta y un driver portable que solo expresa su intención.

Un pin y dos actores

Un GPIO físico lo genera un proveedor: el controlador de GPIO del SoC, o un expansor externo colgado de I2C o SPI. Ese proveedor registra un struct gpio_chip y ofrece un banco de líneas numeradas dentro de él. El consumidor es tu driver, que necesita una línea concreta para una función concreta —la de reset, la de habilitación, la del LED de estado— sin saber ni querer saber en qué chip ni en qué número vive.

El puente entre ambos lo tiende el firmware: el device tree o las tablas ACPI declaran, para cada dispositivo, qué línea de qué controlador cumple cada función y con qué polaridad. El consumidor pide la línea por su nombre lógico y recibe un struct gpio_desc *: un descriptor opaco que ya lleva dentro toda esa información.

flowchart LR
DT[Device tree o ACPI] -->|describe la conexion| Core[Núcleo gpiolib]
Driver[Driver consumidor] -->|gpiod_get por nombre| Core
Core -->|devuelve| Desc[struct gpio_desc]
Core -->|resuelve a linea fisica| Chip[gpio_chip proveedor]
Chip --> Pin[Pin fisico del SoC]

La vieja API numérica y sus pecados

La interfaz clásica de <linux/gpio.h> giraba en torno a un entero global. Cada pin del sistema entero recibía un número único dentro de un espacio acotado por ARCH_NR_GPIOS, y el driver operaba sobre ese entero:

/* API antigua basada en enteros: DEPRECADA y en proceso de retirada */
#define LED_GPIO 42        /* numero magico, global, atado a este SoC */

if (gpio_request(LED_GPIO, "status-led"))
        return -EBUSY;
gpio_direction_output(LED_GPIO, 0);
gpio_set_value(LED_GPIO, 1);   /* escribe el nivel CRUDO: ignora la polaridad */
/* ...y no olvidar nunca: */
gpio_free(LED_GPIO);

Cuatro defectos la condenaron. Uno: el número 42 es un dato de la placa incrustado en el driver, que deja de compilar sin cambios en otra máquina donde el mismo LED cuelga del pin 17. Dos: gpio_set_value escribe el nivel eléctrico literal; si el LED es active-low —enciende con 0 voltios— el driver tiene que saberlo y negar a mano, dispersando conocimiento de hardware por todo el código. Tres: el espacio global de enteros no escala a expansores dinámicos que aparecen y desaparecen. Cuatro: la gestión de recursos es manual —gpio_request y gpio_free emparejados a mano— y cualquier camino de error que los desequilibre fuga la línea.

La API de descriptores

La interfaz moderna vive en <linux/gpio/consumer.h> y sustituye el entero por un descriptor. El consumidor pide la línea por su nombre de función y el núcleo gpiolib resuelve el resto:

#include <linux/gpio/consumer.h>
#include <linux/platform_device.h>
#include <linux/property.h>

struct led_priv {
        struct gpio_desc *status;
};

static int led_probe(struct platform_device *pdev)
{
        struct device *dev = &pdev->dev;
        struct led_priv *priv;

        priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
        if (!priv)
                return -ENOMEM;

        /* "status-gpios" en el device tree se resuelve al con_id "status" */
        priv->status = devm_gpiod_get(dev, "status", GPIOD_OUT_LOW);
        if (IS_ERR(priv->status))
                return dev_err_probe(dev, PTR_ERR(priv->status),
                                     "no se pudo reservar el GPIO status\n");

        gpiod_set_value(priv->status, 1);   /* enciende, respetando la polaridad */
        platform_set_drvdata(pdev, priv);
        return 0;
}

Cada pieza corrige un pecado de la vieja API. devm_gpiod_get reserva la línea y la libera automáticamente cuando el driver se desvincula: no hay gpiod_put que olvidar. El segundo argumento, "status", es un nombre lógico que el firmware traduce a una línea concreta —el driver ignora el número físico—. El tercer argumento es una bandera de enum gpiod_flags que fija dirección y estado inicial de una vez: GPIOD_OUT_LOW configura la línea como salida a nivel lógico bajo, GPIOD_OUT_HIGH como salida alta, GPIOD_IN como entrada y GPIOD_ASIS la deja como esté. Y dev_err_probe registra el fallo y propaga el código, silenciando el ruido cuando el error es -EPROBE_DEFER porque el proveedor aún no ha cargado.

Una vez tienes el descriptor, la dirección se puede reconfigurar en caliente y el valor leerse o escribirse en términos lógicos:

gpiod_direction_output(priv->status, 1);   /* pasa a salida, valor logico 1 */
gpiod_direction_input(priv->reset);        /* pasa a entrada */
int nivel = gpiod_get_value(priv->reset);  /* 1 = activo, no "5 voltios" */

El descriptor esconde la polaridad

Aquí está la ganancia conceptual. gpiod_set_value(desc, 1) no significa “pon el pin a nivel eléctrico alto”: significa “activa la función”. Si el device tree declaró la línea como GPIO_ACTIVE_LOW, el núcleo invierte el nivel eléctrico por ti, y tu driver jamás menciona voltajes. El conocimiento de la polaridad vive donde debe —en la descripción de la placa—, no diseminado por la lógica del driver.

/* fragmento del device tree que describe la conexion fisica */
status-led {
        compatible = "myvendor,status-led";
        status-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>;   /* linea 7 del gpio1, activa a 0 V */
};

Cuando de verdad necesites el nivel eléctrico crudo —depurar hardware, hablar con un protocolo por bit-banging— existen las variantes explícitas gpiod_set_raw_value y gpiod_get_raw_value, que saltan la inversión. Que sean casos raros y con nombre feo es intencional: lo normal es pensar en términos lógicos.