pbio/drv/rproc: Introduce remote coprocessor subsystem

This is currently going to be used to manage the EV3 PRUs,
which involve a number of implicit dependencies between
unrelated modules. This begins by moving the EV3 PWM logic
to depend on the new subsystem.

Author: ArcaneNibble

bricks/_common/sources.mk

@@ -175,6 +175,7 @@ PBIO_SRC_C = $(addprefix lib/pbio/,\
 	drv/reset/reset_nxt.c \
 	drv/reset/reset_stm32.c \
 	drv/resistor_ladder/resistor_ladder.c \
+	drv/rproc/rproc_ev3.c \
 	drv/sound/beep_sampled.c \
 	drv/sound/sound_ev3.c \
 	drv/sound/sound_nxt.c \

lib/pbio/drv/core.c

@@ -25,6 +25,7 @@
 #include "pwm/pwm.h"
 #include "random/random.h"
 #include "reset/reset.h"
+#include "rproc/rproc.h"
 #include "sound/sound.h"
 #include "uart/uart.h"
 #include "uart/uart_debug_first_port.h"
@@ -55,6 +56,7 @@ void pbdrv_init(void) {
     pbdrv_pwm_init();
     pbdrv_random_init();
     pbdrv_reset_init();
+    pbdrv_rproc_init();
     pbdrv_sound_init();
     pbdrv_uart_init();
     pbdrv_uart_debug_init();

lib/pbio/drv/pwm/pwm_ev3.c

@@ -5,75 +5,36 @@
 
 #if PBDRV_CONFIG_PWM_TIAM1808
 
-#include <stdio.h>
-#include <string.h>
-
 #include <pbdrv/pwm.h>
 #include <pbdrv/gpio.h>
 #include <pbio/error.h>
 
-#include <tiam1808/hw/hw_syscfg0_AM1808.h>
-#include <tiam1808/hw/hw_types.h>
-#include <tiam1808/hw/soc_AM1808.h>
-#include <tiam1808/pruss.h>
-#include <tiam1808/psc.h>
-#include <tiam1808/timer.h>
-
 #include "../drv/pwm/pwm.h"
 #include "../../drv/led/led_pwm.h"
 #include "../../drv/pwm/pwm_ev3.h"
 #include "../../drv/gpio/gpio_ev3.h"
 
-// This needs to match the interface expected by the PRU firmware
-typedef struct shared_ram {
-    uint8_t pwms[PBDRV_PWM_EV3_NUM_CHANNELS];
-} shared_ram;
-static volatile shared_ram pru1_shared_ram __attribute__((section(".shared1")));
-
 static pbio_error_t pbdrv_pwm_tiam1808_set_duty(pbdrv_pwm_dev_t *dev, uint32_t ch, uint32_t value) {
     // Blue not available.
     if (ch == PBDRV_LED_PWM_CHANNEL_INVALID) {
         return PBIO_SUCCESS;
     }
 
-    pru1_shared_ram.pwms[ch] = value;
+    pbdrv_rproc_ev3_pru1_shared_ram.pwms[ch] = value;
     return PBIO_SUCCESS;
 }
 
 static const pbdrv_pwm_driver_funcs_t pbdrv_pwm_tiam1808_funcs = {
     .set_duty = pbdrv_pwm_tiam1808_set_duty,
 };
 
-extern char _pru1_start;
-extern char _pru1_end;
-
 #define PINMUX_ALT_PRU1     4
 
 void pbdrv_pwm_tiam1808_init(pbdrv_pwm_dev_t *devs) {
-    // Enable Timer0 "34" half to count up to 256 * 256
-    // This is used by the PRU to time the PWM
-    TimerPreScalarCount34Set(SOC_TMR_0_REGS, 0);
-    TimerPeriodSet(SOC_TMR_0_REGS, TMR_TIMER34, 256 * 256 - 1);
-    TimerEnable(SOC_TMR_0_REGS, TMR_TIMER34, TMR_ENABLE_CONT);
-
-    // Clear shared command memory
-    memset((void *)&pru1_shared_ram, 0, sizeof(shared_ram));
-
-    // Enable PRU1 and load its firmware
-    PSCModuleControl(SOC_PSC_0_REGS, HW_PSC_PRU, PSC_POWERDOMAIN_ALWAYS_ON, PSC_MDCTL_NEXT_ENABLE);
-    PRUSSDRVPruDisable(1);
-    PRUSSDRVPruReset(1);
-    unsigned int *fw_start = (unsigned int *)&_pru1_start;
-    uint32_t fw_sz = &_pru1_end - &_pru1_start;
-    PRUSSDRVPruWriteMemory(PRUSS0_PRU1_IRAM, 0, fw_start, fw_sz);
-    // Set constant table C30 to point to shared memory
-    PRUSSDRVPruSetCTable(1, 30, (((uint32_t)&pru1_shared_ram) >> 8) & 0xffff);
-    PRUSSDRVPruEnable(1);
-
     devs[0].funcs = &pbdrv_pwm_tiam1808_funcs;
 
     // Set GPIO alt modes for the PRU
-    for (int j = 0; j < PBDRV_PWM_EV3_NUM_CHANNELS; j++) {
+    for (int j = 0; j < PBDRV_RPROC_EV3_PRU1_NUM_PWM_CHANNELS; j++) {
         pbdrv_gpio_alt(&pbdrv_pwm_tiam1808_platform_data.gpios[j], PINMUX_ALT_PRU1);
     }
 }

lib/pbio/drv/pwm/pwm_ev3.h

@@ -12,13 +12,12 @@
 
 #include <pbdrv/pwm.h>
 #include <pbdrv/gpio.h>
-
-#define PBDRV_PWM_EV3_NUM_CHANNELS  4
+#include "../rproc/rproc_ev3.h"
 
 /** Platform-specific device information. */
 typedef struct {
     uint8_t id;
-    pbdrv_gpio_t gpios[PBDRV_PWM_EV3_NUM_CHANNELS];
+    pbdrv_gpio_t gpios[PBDRV_RPROC_EV3_PRU1_NUM_PWM_CHANNELS];
 } pbdrv_pwm_tiam1808_platform_data_t;
 
 // Defined in platform.c

lib/pbio/drv/rproc/rproc.h

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 The Pybricks Authors
+
+#ifndef _INTERNAL_PBDRV_RPROC_H_
+#define _INTERNAL_PBDRV_RPROC_H_
+
+#include <stdbool.h>
+
+#include <pbdrv/config.h>
+
+#if PBDRV_CONFIG_RPROC
+
+/**
+ * Initializes "remote" coprocessors early during the startup sequence
+ */
+void pbdrv_rproc_init(void);
+
+/**
+ * Determines whether remote coprocessors have been initialized
+ */
+bool pbdrv_rproc_is_ready(void);
+
+#else // PBDRV_CONFIG_RPROC
+
+#define pbdrv_rproc_init()
+#define pbdrv_rproc_is_ready()  true
+
+#endif // PBDRV_CONFIG_RPROC
+
+#endif // _INTERNAL_PBDRV_RPROC_H_

lib/pbio/drv/rproc/rproc_ev3.c

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 The Pybricks Authors
+
+// Manages EV3 PRU coprocessor initialization
+
+#include <pbdrv/config.h>
+
+#if PBDRV_CONFIG_RPROC_EV3
+
+#include <stdbool.h>
+#include <string.h>
+
+#include <tiam1808/hw/hw_syscfg0_AM1808.h>
+#include <tiam1808/hw/soc_AM1808.h>
+#include <tiam1808/pruss.h>
+#include <tiam1808/psc.h>
+#include <tiam1808/timer.h>
+
+#include "rproc_ev3.h"
+
+volatile pbdrv_rproc_ev3_pru1_shared_ram_t pbdrv_rproc_ev3_pru1_shared_ram __attribute__((section(".shared1")));
+
+static bool pbdrv_ev3_rproc_is_ready;
+
+extern char _pru1_start;
+extern char _pru1_end;
+
+void pbdrv_rproc_init(void) {
+    // Enable PRU subsystem
+    PSCModuleControl(SOC_PSC_0_REGS, HW_PSC_PRU, PSC_POWERDOMAIN_ALWAYS_ON, PSC_MDCTL_NEXT_ENABLE);
+
+    // PRU1 initialization
+
+    // Enable Timer0 "34" half to count up to 256 * 256
+    // This is used by the PRU to time the PWM
+    TimerPreScalarCount34Set(SOC_TMR_0_REGS, 0);
+    TimerPeriodSet(SOC_TMR_0_REGS, TMR_TIMER34, 256 * 256 - 1);
+    TimerEnable(SOC_TMR_0_REGS, TMR_TIMER34, TMR_ENABLE_CONT);
+
+    // Clear shared command memory
+    memset((void *)&pbdrv_rproc_ev3_pru1_shared_ram, 0, sizeof(pbdrv_rproc_ev3_pru1_shared_ram));
+
+    // Enable PRU1 and load its firmware
+    PRUSSDRVPruDisable(1);
+    PRUSSDRVPruReset(1);
+    unsigned int *fw_start = (unsigned int *)&_pru1_start;
+    uint32_t fw_sz = &_pru1_end - &_pru1_start;
+    PRUSSDRVPruWriteMemory(PRUSS0_PRU1_IRAM, 0, fw_start, fw_sz);
+    // Set constant table C30 to point to shared memory
+    PRUSSDRVPruSetCTable(1, 30, (((uint32_t)&pbdrv_rproc_ev3_pru1_shared_ram) >> 8) & 0xffff);
+    PRUSSDRVPruEnable(1);
+
+    // All good
+    pbdrv_ev3_rproc_is_ready = true;
+}
+
+bool pbdrv_rproc_is_ready(void) {
+    return pbdrv_ev3_rproc_is_ready;
+}
+
+#endif // PBDRV_CONFIG_RPROC_EV3

lib/pbio/drv/rproc/rproc_ev3.h

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 The Pybricks Authors
+
+#ifndef _INTERNAL_PBDRV_RPROC_EV3_H_
+#define _INTERNAL_PBDRV_RPROC_EV3_H_
+
+#include <stdint.h>
+
+// EV3 PRU interfaces and ABI
+// These need to match the interface expected by the PRU firmware
+
+// PRU1 interface
+
+#define PBDRV_RPROC_EV3_PRU1_NUM_PWM_CHANNELS   4
+
+typedef struct {
+    uint8_t pwms[PBDRV_RPROC_EV3_PRU1_NUM_PWM_CHANNELS];
+} pbdrv_rproc_ev3_pru1_shared_ram_t;
+
+extern volatile pbdrv_rproc_ev3_pru1_shared_ram_t pbdrv_rproc_ev3_pru1_shared_ram;
+
+#endif // _INTERNAL_PBDRV_RPROC_EV3_H_

lib/pbio/platform/ev3/pbdrvconfig.h

@@ -70,6 +70,9 @@
 #define PBDRV_CONFIG_RESET                          (1)
 #define PBDRV_CONFIG_RESET_EV3                      (1)
 
+#define PBDRV_CONFIG_RPROC                          (1)
+#define PBDRV_CONFIG_RPROC_EV3                      (1)
+
 #define PBDRV_CONFIG_SOUND                          (1)
 #define PBDRV_CONFIG_SOUND_EV3                      (1)
 #define PBDRV_CONFIG_SOUND_DEFAULT_VOLUME           75