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

Objectives

Unlock the multiplexed functions of the P8/P9 pins (UART, I2C, SPI, CAN...) by writing a device tree overlay, using the modern configfs method. Note: The AI-64 is a K3 SoC (J721E) — the old capemanager /sys/devices/platform/bone_capemanager found on the BeagleBone Black does NOT exist here, and the per-pin muxmode table (e.g., P8_03 as GPIO0_20 at muxmode 7) is found in Chapter 7 of the System Reference Manual.

Hardware

• 1 BeagleBone AI-64, up-to-date Debian image
• device-tree-compiler packages; access to the SRM muxing table (docs.beagleboard.org)

Complete Code

/* 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

Expected Verification

The enabled device appears (new /dev/ttySx, /dev/i2c-N...) and dmesg shows no pinmux conflicts. With a wire loopback between the RX and TX of the ribbon cable: echo test > /dev/ttySx run in parallel with cat returns test.

Common Errors

• Looking for bone_capemanager: specific to legacy AM335x; on K3, use configfs (or /lib/firmware + loader for persistence at boot).
• Choosing the wrong muxmode: the wrong multiplexed function on a pin results in a phantom device or a conflict — always copy the SRM table pin by pin.
• Overwriting a pin already used by the image (LED, eMMC, CSI): check gpioinfo/pinmux-status (cat /sys/kernel/debug/pinctrl/*/pinmux-pins) beforehand.
• Forgetting persistence: a configfs overlay disappears upon reboot; for boot, load it via the image's boot manager.
• 5 V on a pin: all ribbon cables are 3.3 V, otherwise irreversible damage may occur.