knaxuslearn · build · ship

Roadmaps / BeagleBone / Phase 3

Phase 3 of 4 · Study weeks 9-12

PRU real-time control

This phase gives the step engine its deterministic core (start here: the PRU Cookbook, docs.beagleboard.io books/pru-cookbook): the board's two PRUs run your timing loop with a 5 ns instruction cycle, independent of Linux.

Topics every week

  1. Week 98 h
    • PRU-ICSS: two 32-bit cores at 200 MHz, 8 KB program RAM and 8 KB data RAM per core, 12 KB shared RAM, registers R30 and R31
    • toolchains clpru and gnupru
    • remoteproc load and start

    Hand inPRU0 firmware that toggles a pin; the disassembly with cycle counts; a pin map for step, direction, enable, limit and the loopback input, chosen from the PRU Cookbook pin table with each pin's other uses (HDMI, eMMC, audio) checked and disabled, and an overlay (from Week 5) that puts those pins in PRU mode

  2. Week 108 h
    • Linux-to-PRU communication: resource table, RPMsg, shared memory
    • one writer per variable
    • sequence numbers

    Hand inA command and status protocol document, and an RPMsg echo that passes on the pinned v6.12 kernel and the exact bone-rt package (record its version and the device nodes you see; name a fallback such as shared-RAM polling in ADR-3 if it fails), with latency, and a 1 ms heartbeat reaching PRU1 under the Checkpoint 1 load with the missed-heartbeat count recorded

  3. Week 118 h
    • Exact timing: cycle counting, __delay_cycles, the PRU cycle counter, a step pulse with fixed-point ramps
    • what costs more than a register access

    Hand inA 20 kHz step generator at a constant rate (senior and above add the trapezoid ramp)

  4. Week 128 h
    • PRU1 as the observer: capture the step pin by loopback, timestamp edges, watch the limit switch and a heartbeat
    • safe state when Linux stops

    Hand inCheckpoint 3, with predicted and measured step-period error

Practice projects

  1. First firmware. Load and stop PRU firmware from remoteproc. Done when the pin toggles at 1 MHz, you can show the 1 MHz period on the analyzer and the 5 ns cycle by the PRU cycle counter (a 24 MHz analyzer cannot resolve 5 ns), and a script loads and stops it 100 times.
  2. Command channel. Send start, stop and speed commands over RPMsg and read status back over RPMsg. Done when a test sends 10,000 commands in a random order with no lost or duplicated command.
  3. Cycle budget. Write a table of the PRU cycles each instruction path takes in your loop. Done when measured edge spacing matches the table within 2 cycles.

Optional: write the step generator in both TI C and PRU assembly and compare cycle counts. Optional: read the open-source GCC port and list what changes in your code.

GitHub repos to study

RepoWhat to readWeek
dinuxbg/gnupru (May 2026)The README (install on Beagle Debian with gcc-pru) and the examples/9
beagleboard/docs.beagleboard.io (Apr 2026)books/pru-cookbook: the PRU Cookbook9 to 11

TI's PRU Software Support Package (resource table, RPMsg library and register headers) is documented in the Processor SDK Linux for AM335x manual; its repository was not checked (see Sources). TI's PRU code generation tools (clpru) are at version 2.3.3, released 31 Oct 2019, the latest at the check date. That is a maintenance risk, so ADR-3 names gnupru as the second option.

Milestone checkpoint

Build the PRU step engine (Checkpoint 3). PRU0 generates the steps (a constant rate; senior and above add the trapezoid ramp). PRU1 captures every step edge by loopback, counts steps and timestamps them. Linux sends moves and the 1 ms heartbeat over RPMsg. If the heartbeat stops for the timeout, the safe state in "Terms" applies. Done when the Checkpoint 3 row passes with the load running. Evidence: raw captures from PRU1 and from the logic analyzer, a table like the worked reference above, the step rate at which an RT thread first misses the 1 µs budget (your crossover), and ADR-3 on PRU against RT thread against microcontroller.

Check yourself

Answer each question in your head first, then open it to check.

  1. What makes PRU timing exact, and what access can break it?
    No cache, no pipeline surprises, and one cycle per most instructions, so a register loop is exact. Reads from system memory over the interconnect can take a variable number of cycles.
  2. What is a resource table, and what fails if it is missing?
    It tells the kernel's remoteproc which resources the firmware needs (memory, RPMsg buffers). Without it the core may still start, but RPMsg and the memory the firmware expects are not set up; read the kernel log.
  3. Why must each shared variable have one writer?
    Two writers need a lock or atomic operations, and waiting on them breaks the timing. One writer plus sequence numbers lets the reader detect torn data.
  4. What should the PRU do when the heartbeat stops, and why?
    Enter a defined safe state. For a stage that means stop stepping, flag the position as uncertain, hold torque and wait for homing, because nobody can supervise the move. The stop is abrupt and can lose position, which is why homing exists.
  5. What does the PRU not give you compared with a microcontroller running an RTOS?
    No operating system, small program memory, a minimal C runtime, and a smaller tool and debug ecosystem.