🛠 Écrire un overlay device tree pour les nappes cape sous K3

Objectifs

Débloquer les fonctions muxées des broches P8/P9 (UART, I2C, SPI, CAN...) en écrivant un overlay device tree, avec la méthode moderne configfs. Attention : le AI-64 est un SoC K3 (J721E) — l'ancien capemanager /sys/devices/platform/bone_capemanager des BeagleBone Black n'existe PAS ici, et la table de muxmodes par broche (ex. P8_03 en GPIO0_20 au muxmode 7) se lit dans le chapitre 7 du System Reference Manual.

Matériel

• 1 BeagleBone AI-64, image Debian à jour
• Paquets device-tree-compiler ; accès à la table de muxing du SRM (docs.beagleboard.org)

Code complet

/* cape-uart.dtso — squelette : activer un périphérique muxé sur P8/P9.
   Les offsets et macros EXACTS se lisent dans la table SRM ch.7 et dans
   dt-bindings/pinctrl/k3.h du noyau — ne pas deviner, vérifier. */
/dts-v1/;
/plugin/;
#include <dt-bindings/pinctrl/k3.h>

&main_pmx0 {
    pinctrl_cape_uart: cape-uart-default {
        pinctrl-single,pins = <
            /* offset broche (offset mux) choisis dans la table SRM */
            0x0a0 (PIN_INPUT  | MUX_MODE0)   /* exemple RX */
            0x0a4 (PIN_OUTPUT | MUX_MODE0)   /* exemple TX */
        >;
    };
};

&main_uart1 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_cape_uart>;
};

dtc -@ -I dts -O dtb -o cape-uart.dtbo cape-uart.dtso
sudo mkdir -p /sys/kernel/config/device-tree/overlays/cape_uart
cat cape-uart.dtbo | sudo tee /sys/kernel/config/device-tree/overlays/cape_uart/dtbo
ls /dev/ttyS* ; sudo dmesg | tail   # le port doit apparaître

Vérification attendue

Le périphérique activé apparaît (nouveau /dev/ttySx, /dev/i2c-N...) et dmesg ne montre pas de conflit de pinmux. Loopback fil entre RX et TX de la nappe : echo test > /dev/ttySx avec cat en parallèle renvoie test.

Erreurs fréquentes

• Chercher bone_capemanager : propre à l'AM335x legacy ; sous K3 on utilise configfs (ou /lib/firmware + chargeur pour la persistance au boot).
• Se tromper de muxmode : la mauvaise fonction muxée sur une broche produit un périphérique fantôme ou un conflit — toujours recopier la table SRM broche par broche.
• Écraser une broche déjà utilisée par l'image (LED, eMMC, CSI) : vérifier gpioinfo/pinmux-status (cat /sys/kernel/debug/pinctrl/*/pinmux-pins) avant.
• Oublier la persistance : un overlay configfs disparaît au reboot ; pour le boot, le charger via le gestionnaire de boot de l'image.
• 5 V sur une broche : toutes les nappes sont en 3,3 V sous peine de dommages irréversibles.