Add PRU backend for stock mainline-kernel images: PRU_BACKEND=genirq.

Recent BeagleBone Debian images ship neither uio_pruss nor PRU rpmsg
support, leaving BeagleG without a way to run there. The genirq
backend needs no PRU kernel driver: a small device-tree overlay binds
the PRU to the kernel uio_pdrv_genirq driver, exposing the PRU0
memories as the UIO device mmap regions and the completion interrupt
(PRU system event 19, routed with the same event->channel->host INTC
mapping that prussdrv programs) as its blocking read. The host resets
the core, copies the pasm-assembled firmware into IRAM through that
mapping (with a readback check: IRAM writes are silently dropped on a
core that is not freshly reset) and enables it. Everything goes
through one /dev/uioN node, so its permissions govern PRU access; no
/dev/mem needed.

The overlay also disables the PRU0 remoteproc node while loaded:
pru_rproc and this backend would otherwise be two independent writers
of the same IRAM and control registers. Loaded through the
uboot_overlay_pru slot -- which u-boot applies after the generic cape
slots -- the lockout stays the effective last word; PRU1 remains
available to remoteproc. All magic addresses and register bits are
cited against the AM335x TRM (SPRUH73, tables verified in revision
Q), the interrupt cells against the ti,pruss-intc binding, and the
UIO mmap region convention against the kernel uio-howto.

Firmware and default build are unchanged: same motor-interface-pru.p,
same pasm flow; the uio_pruss backend stays the default.

Verified end-to-end on a factory BeagleBone Black Rev D on both
kernel flavors, same binary and overlay: mainline 6.12.28-bone25
(1.72s wall, 2404Hz average step rate, ~4000 register-sampled steps
on a two-move G-code smoke test) and TI 5.10.168-ti-r84 (1.73s,
2410Hz); with the overlay loaded, /sys/class/remoteproc lists only
wkup_m3 and PRU1 on both. Earlier oscilloscope checks confirmed the
pulse timing of the same firmware/queue path.

Author: lromor

.github/workflows/ci.yml

@@ -52,6 +52,33 @@ jobs:
       run: |
         make valgrind-test
 
+  build-genirq-backend:
+    runs-on: ubuntu-latest
+    name: Build PRU_BACKEND=genirq
+    steps:
+    - name: Prepare
+      run: |
+        sudo apt-get update -qq
+        sudo apt install -y g++ clang pkg-config libgtest-dev libgmock-dev
+
+    - uses: actions/checkout@v7
+      with:
+        submodules: recursive
+
+    - name: Configure shell
+      run: |
+        echo "ARM_COMPILE_FLAGS=" >> $GITHUB_ENV
+        echo "BEAGLEG_OPT_CFLAGS=-O2 -Werror" >> $GITHUB_ENV
+
+    - name: Build with g++
+      run: |
+        make -C src PRU_BACKEND=genirq ../machine-control
+
+    - name: Build with clang++
+      run: |
+        make -C src clean
+        CXX=clang++ make -C src PRU_BACKEND=genirq ../machine-control
+
   build-and-test_cpp11:
     runs-on: ubuntu-latest
     strategy:

INSTALL.md

@@ -48,6 +48,58 @@ look like this:
 uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo
 ```
 
+### Alternative: images without uio_pruss (PRU_BACKEND=genirq)
+
+Recent BeagleBone Debian images (mainline kernel) ship neither the
+`uio_pruss` driver nor the `PRU-UIO` overlay above. There, build
+BeagleG with `make PRU_BACKEND=genirq`: it needs no PRU kernel driver
+at all — the PRU memories and the motion interrupt are exposed to
+BeagleG by the kernel's generic UIO driver, so PRU access is governed
+by the permissions of `/dev/uio0` alone.
+
+Which backend do I need? The kernel flavor suffix alone does not tell
+you: older kernels of either flavor shipped `uio_pruss` (TI kernels
+up to 5.10, older `-bone` kernels carried it as a patch), current
+kernels of both flavors do not. Check your kernel directly:
+
+```
+ls /lib/modules/$(uname -r)/kernel/drivers/uio/
+```
+
+If `uio_pruss.ko*` is listed, the default `uio` backend and the
+`PRU-UIO` overlay above work. If it is not — the case on all current
+images — use `genirq`; it works on any kernel >= 5.10, either
+flavor.
+
+One-time setup: compile the overlay that exports the PRU to userspace
+
+```
+sudo apt install device-tree-compiler
+sudo dtc -@ -o /lib/firmware/BEAGLEG-PRU-IRQ.dtbo dts/BEAGLEG-PRU-IRQ.dts
+```
+
+then in `/boot/uEnv.txt` enable u-boot overlays, select ours, and
+allow `uio_pdrv_genirq` to bind to it (append to the existing
+`cmdline=` line):
+
+```
+enable_uboot_overlays=1
+uboot_overlay_pru=/lib/firmware/BEAGLEG-PRU-IRQ.dtbo
+cmdline=coherent_pool=1M net.ifnames=0 quiet uio_pdrv_genirq.of_id=generic-uio
+```
+
+Use the `uboot_overlay_pru` slot specifically, not a generic
+`uboot_overlay_addrN` one: overlays merge last-writer-wins, and
+u-boot applies the PRU slot after all the generic cape slots, so this
+overlay's claim on PRU0 (it disables the PRU0 remoteproc node so the
+kernel and BeagleG never fight over the core) cannot be silently
+overridden by a cape overlay.
+
+After a reboot, `cat /sys/class/uio/uio0/name` should print
+`beagleg_pru_irq` (newer kernels append the node's `@4a300000`
+unit-address). BeagleG needs read/write access to that `/dev/uio0`
+device node.
+
 ## Install BeagleG
 
 

README.md

@@ -58,6 +58,10 @@ _enable_ the line containing the `PRU-UIO` (remove `#` in front).
 uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo
 ```
 
+Note: current images no longer ship the `uio_pruss` driver this setup
+relies on. On those, build with the `genirq` backend instead — see
+the "images without uio_pruss" section in [INSTALL.md](./INSTALL.md).
+
 Reboot.
 
 ### Enable Output Pins for your board

dts/BEAGLEG-PRU-IRQ.dts

@@ -0,0 +1,93 @@
+/* BeagleG: expose the PRU to userspace as /dev/uioN via the kernel's
+ * generic uio_pdrv_genirq driver -- no PRU-specific kernel driver
+ * needed. Two things are wired up:
+ *
+ *  - interrupts: PRU system event 19, raised by the firmware when a
+ *    motion segment completes (must match PRU0_ARM_INTERRUPT in
+ *    src/motor-interface-pru.p), routed through the PRUSS interrupt
+ *    controller as event 19 -> INTC channel 2 -> host interrupt 2.
+ *    This is the same routing libprussdrv's PRUSS_INTC_INITDATA
+ *    programs for the uio_pruss backend. Cell meaning per the binding
+ *    https://www.kernel.org/doc/Documentation/devicetree/bindings/interrupt-controller/ti,pruss-intc.yaml
+ *  - reg: the PRU0 memories, exported as UIO mmap regions in
+ *    declaration order: map 0 = PRU0 data RAM, map 1 = PRU0 control,
+ *    map 2 = PRU0 instruction RAM. This order is the backend's mmap
+ *    contract (src/uio-genirq-interface.cc); the offset-selects-region
+ *    mmap convention is
+ *    https://www.kernel.org/doc/html/latest/driver-api/uio-howto.html
+ *
+ * The addresses come from the AM335x Technical Reference Manual, TI
+ * document SPRUH73 (page anchors per revision Q): the PRU-ICSS sits
+ * on the L4_FAST interconnect, occupying 0x4a30_0000..0x4a37_ffff --
+ * Table 2-4 "L4 Fast Peripheral Memory Map",
+ * https://www.ti.com/lit/pdf/spruh73#page=185 -- and within it PRU0
+ * data RAM is at offset 0x00000 (8 KiB), the PRU0 control registers
+ * at 0x22000 and PRU0 instruction RAM at 0x34000 (8 KiB) -- section
+ * 4.3.2, Table 4-8 "Global Memory Map",
+ * https://www.ti.com/lit/pdf/spruh73#page=207. The kernel's hardware
+ * description carries the same values in
+ * arch/arm/boot/dts/ti/omap/am33xx.dtsi (pruss node).
+ *
+ * Needs uio_pdrv_genirq.of_id=generic-uio on the kernel command line;
+ * see INSTALL.md for the full setup.
+ */
+/dts-v1/;
+/plugin/;
+
+/ {
+	/* This overlay depends only on the AM335x chip (its PRU-ICSS),
+	 * not on any board, so it declares the chip-level compatible.
+	 * Boards list their identity from most to least specific -- the
+	 * BeagleBone Green, for example: "ti,am335x-bone-green",
+	 * "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx" -- and
+	 * a match on any entry suffices. This single generic string
+	 * therefore covers every AM335x board (Black, Green, Green
+	 * Wireless, PocketBeagle, ...), including boards that do not
+	 * exist yet, while an explicit board list would only assert a
+	 * board dependence this overlay does not have.
+	 */
+	compatible = "ti,am33xx";
+
+	fragment@0 {
+		target-path = "/";
+		__overlay__ {
+			#address-cells = <1>;
+			#size-cells = <1>;
+			beagleg_pru_irq@4a300000 {
+				compatible = "generic-uio";
+				reg = <0x4a300000 0x2000>,	/* PRU0 data RAM */
+				      <0x4a322000 0x1000>,	/* PRU0 control */
+				      <0x4a334000 0x2000>;	/* PRU0 instruction RAM */
+				interrupt-parent = <&pruss_intc>;
+				interrupts = <19 2 2>;	/* sysevent 19, channel 2, host 2 */
+			};
+		};
+	};
+
+	/* BeagleG owns PRU0, so keep the kernel's pru_rproc from binding
+	 * it: with two independent writers of the same IRAM/control
+	 * registers, a remoteproc "start" while BeagleG runs would race.
+	 * Same mutual exclusion the historical PRU-UIO overlays used;
+	 * PRU1 is left available to remoteproc.
+	 *
+	 * Ordering matters: overlays merge last-writer-wins with no
+	 * conflict detection, so an overlay applied after this one that
+	 * touches &pru0 would silently undo the lockout. Load this file
+	 * through the uboot_overlay_pru slot of /boot/uEnv.txt -- u-boot
+	 * applies that slot after all generic uboot_overlay_addrN cape
+	 * slots (bb.org u-boot, include/configs/ti_armv7_common.h), so
+	 * the PRU0 claim stays the effective last word -- and keep
+	 * PRU-touching overlays out of the even-later slots
+	 * (uboot_overlay_pru_add, dtb_overlay). All merging happens in
+	 * u-boot before Linux boots, so pru_rproc never probes PRU0; the
+	 * result is verifiable at runtime:
+	 * /proc/device-tree/ocp/interconnect@4a000000/segment@0/
+	 * target-module@300000/pruss@0/pru@34000/status == "disabled".
+	 */
+	fragment@1 {
+		target = <&pru0>;
+		__overlay__ {
+			status = "disabled";
+		};
+	};
+};

src/Makefile

@@ -54,6 +54,23 @@ PRUSS_LIBS=$(LIBDIR_APP_LOADER)/libprussdrv.a
 COMMON_LIBS=common/libbeaglegbase.a gcode-parser/libgcodeparser.a
 SUBDIRS=common gcode-parser
 
+# Host-side PRU backend. "uio" talks to the legacy uio_pruss driver via
+# libprussdrv (needs the PRU-UIO device-tree overlay). "genirq" needs
+# no PRU-specific kernel driver: it drives the PRU through the memory
+# maps of a generic UIO device and gets completion interrupts through
+# its blocking read -- uio_pdrv_genirq, wired up by the overlay in
+# ../dts/, see INSTALL.md; use it on stock mainline-kernel BeagleBone
+# Debian images.
+PRU_BACKEND?=uio
+ifeq ($(PRU_BACKEND),genirq)
+  PRU_BACKEND_OBJ=uio-genirq-interface.o
+  PRU_BACKEND_LIBS=
+  CFLAGS+=-DBEAGLEG_PRU_BACKEND_GENIRQ
+else
+  PRU_BACKEND_OBJ=uio-pruss-interface.o
+  PRU_BACKEND_LIBS=$(PRUSS_LIBS)
+endif
+
 # Assembled binary from *.p file.
 PRU_BIN=motor-interface-pru_bin.h
 
@@ -62,7 +79,7 @@ GCODE_OBJECTS=gcode-machine-control.o determine-print-stats.o \
               generic-gpio.o pwm-timer.o config-parser.o \
 	      machine-control-config.o hardware-mapping.o \
 	      spindle-control.o planner.o adc.o
-OBJECTS=motion-queue-motor-operations.o sim-firmware.o sim-audio-out.o pru-motion-queue.o uio-pruss-interface.o $(GCODE_OBJECTS)
+OBJECTS=motion-queue-motor-operations.o sim-firmware.o sim-audio-out.o pru-motion-queue.o $(PRU_BACKEND_OBJ) $(GCODE_OBJECTS)
 MAIN_OBJECTS=machine-control.o gcode-print-stats.o gcode2ps.o
 
 TARGETS=../machine-control ../gcode-print-stats gcode2ps
@@ -82,7 +99,7 @@ gcode-parser/libgcodeparser.a: FORCE
 	$(CROSS_COMPILE)$(CXX) -o $@ $^ $(COMMON_LIBS) $(LDFLAGS)
 
 ../machine-control: machine-control.o $(OBJECTS) $(COMMON_LIBS)
-	$(CROSS_COMPILE)$(CXX) -o $@ $^ $(COMMON_LIBS) $(PRUSS_LIBS) $(LDFLAGS)
+	$(CROSS_COMPILE)$(CXX) -o $@ $^ $(COMMON_LIBS) $(PRU_BACKEND_LIBS) $(LDFLAGS)
 
 # While this is developed and does not have a final name yet, let's not make
 # it a toplevel tool in ../
@@ -122,7 +139,7 @@ $(PRU_BIN) : motor-interface-constants.h \
 	     $(CAPE_INCLUDE)/pru-io-routines.hp
 
 %_test: %_test.o $(OBJECTS) $(COMMON_LIBS) compiler-flags
-	$(CROSS_COMPILE)$(CXX) -o $@ $< $(OBJECTS) $(COMMON_LIBS) $(PRUSS_LIBS) $(GTEST_LIBS) $(LDFLAGS)
+	$(CROSS_COMPILE)$(CXX) -o $@ $< $(OBJECTS) $(COMMON_LIBS) $(PRU_BACKEND_LIBS) $(GTEST_LIBS) $(LDFLAGS)
 
 %.o: %.cc compiler-flags
 	$(CROSS_COMPILE)$(CXX) $(CXXFLAGS)  -c  $< -o $@
@@ -144,6 +161,7 @@ $(PASM):
 
 # Explicit dependencies
 uio-pruss-interface.o : $(PRU_BIN)
+uio-genirq-interface.o : $(PRU_BIN)
 
 # Auto generated dependencies
 -include $(DEPENDENCY_RULES)

src/machine-control.cc

@@ -578,7 +578,11 @@ int main(int argc, char *argv[]) {
         "Use the dryrun option -n to not write to GPIO).");
       return 1;
     }
+#ifdef BEAGLEG_PRU_BACKEND_GENIRQ
+    pru_hw_interface = new UioGenirqInterface();
+#else
     pru_hw_interface = new UioPrussInterface();
+#endif
     motion_backend = new PRUMotionQueue(&hardware_mapping, pru_hw_interface);
   }
 

src/pru-hardware-interface.h

@@ -21,6 +21,7 @@
 #define BEAGLEG_PRU_HARDWARE_INTERFACE_
 
 #include <cstddef>
+#include <cstdint>
 
 // Pru hardware controls
 class PruHardwareInterface {
@@ -44,7 +45,11 @@ class PruHardwareInterface {
   virtual bool Shutdown() = 0;
 };
 
-class UioPrussInterface : public PruHardwareInterface {
+// PRU control via the uio_pruss kernel driver and TI's libprussdrv:
+// the historical BeagleG setup, for TI-flavor kernels booted with the
+// PRU-UIO device-tree overlay (see INSTALL.md, "Enable PRU"). Default
+// backend, PRU_BACKEND=uio.
+class UioPrussInterface final : public PruHardwareInterface {
  public:
   bool Init() final;
   bool AllocateSharedMem(void **pru_mmap, size_t size) final;
@@ -53,4 +58,42 @@ class UioPrussInterface : public PruHardwareInterface {
   bool Shutdown() final;
 };
 
+// PRU hardware control without any PRU-specific kernel driver, for
+// kernels >= 5.10 that carry the pruss interrupt-controller driver --
+// notably the mainline-flavor kernels of current BeagleBone images,
+// which ship neither uio_pruss nor PRU rpmsg. Firmware load, start/stop
+// and the shared motion queue go through the memory maps of a generic
+// UIO device, per-segment completion interrupts through its blocking
+// read, all wired up by the device-tree overlay in
+// dts/BEAGLEG-PRU-IRQ.dts (see INSTALL.md). PRU_BACKEND=genirq.
+class UioGenirqInterface final : public PruHardwareInterface {
+ public:
+  UioGenirqInterface();
+  ~UioGenirqInterface() final;
+
+  bool Init() final;
+  bool AllocateSharedMem(void **pru_mmap, size_t size) final;
+  bool StartExecution() final;
+  unsigned WaitEvent() final;
+  bool Shutdown() final;
+
+ private:
+  // Volatile is applied at the dereference points, not the storage:
+  // ctrl_ is MMIO, so every access must really happen and in order.
+  // The queue memory is only memset here before the PRU starts, then
+  // handed out via AllocateSharedMem(); the consumer accesses it
+  // through the volatile PRUCommunication fields (pru-motion-queue.cc)
+  // while the PRU concurrently writes it. iram_ is bulk-copied
+  // (memcpy cannot take volatile) only while the core is halted after
+  // the reset pulse, so it never has a concurrent accessor. The uio
+  // mappings
+  // are non-cached device memory, so the CPU preserves the access
+  // order the compiler emits -- the same contract the uio_pruss
+  // mapping always provided.
+  int uio_fd_;
+  void *data_ram_;           // Motion queue, shared with the PRU.
+  volatile uint32_t *ctrl_;  // PRU0 control register.
+  void *iram_;               // PRU0 instruction RAM.
+};
+
 #endif  // BEAGLEG_PRU_HARDWARE_INTERFACE_