Beaglebone PRU GPIO example

Executive Summary

If you're just trying to do ordinary GPIO on your beaglebone, this is not the page you're looking for.

This is about how to use certain GPIO pins on the beaglebone using the two embedded 200MHz PRU microcontrollers using their super-fast Enhanced GPIO mode.  The PRUs can also be used to access other GPIO pins, but not as quickly, and I don't cover that here.

Reading all the way through chapters 6 and 13 of Exploring BeagleBone was the best resource I found for understanding all this, but at the end of the day, here's what I had to do:

1. sudo apt-get update && sudo apt-get dist-upgrade
2. Create a device tree overlay, compile it, reboot, and enable it
3. Assemble my PRU code (just 3 instructions!)
4. Compile a tiny C program to send the code to the PRU.

One challenge is that most of the info out there is from 2013 or 2014, when you had to install PRUSS manually.  Fortunately, that stuff all came by default on my BeagleBone Green and BeagleBone Black.  So you don't have to worry about installing am335x_pru_package to get pasm and libprussdrv!

Turns out programming the PRU is the easy part.  The hard part is sorting out all the different ways of doing GPIO and getting the right mode enabled in the device tree.

Choosing the Right Pins (it's harder than you think)

This table shows which GPIO pins you can access from the PRUs using Enhanced GPIO (EGP).  The "BB Header" column shows you the physical header pin on the BeagleBone.  The R30 and R31 columns show you which pins you'll be writing or reading when you access that bit on those registers from the PRU0 or PRU1 microcontrollers.

But it's not the whole story -- if you  have a BeagleBone Black, all of the pins for PRU1 are used by the HDMI or onboard flash (emmc2).  So to use those pins, you have to disable HDMI or onboard flash (and thereafter boot from a microSD card) first, which requires editing the uEnv.txt file and rebooting.  (BeagleBone Green doesn't come with HDMI, freeing up those pins by default.)

These tables for headers P8 and P9 from Exploring BeagleBone highlight those reserved pins in red, and then show in the rightmost column that they're reserved for HDMI or emmc2.

Note from the first table that even though each PRU supports 16 EGP pins, the BeagleBone headers don't expose them all.  So don't expect to do fast 16-bit parallel I/O from a PRU on your BeagleBone.

Finally, it looks like pins 41 and 42 on P9 are yet another special case, and are overloaded with other GPIO pins somehow, and so you have to set those pins as inputs before using them from the PRU.  (I didn't try).

Let's avoid all those special cases and pick two pins that aren't already spoken for.  We'll use pin 11 on header P8 for output.  The tables show us that P8_11 correspond to PRU 0, register 30, bit 15.  In the PRUs, R30 is a "magic" register, and writing to it lets us set the state of output pins.

Let's also pick a pin for input, pin 16 on P8.  There the tables show us that P8_16 corresponds to PRU 0, register 31 bit 14.  R31 is the other "magic" PRU register, and reading from it reads input pins.

Get the Pin Configuration Right!

This is really easy to screw up.  The first thing we need to find is the multiplexer mode, which determines whether the pin will be hooked up to the PRU, HDMI port, etc.

The modes are nicely laid out as 7 columns in the P8 and P9 tables from the book.  At first you might think that Mode6 is "PRU input" mode, since there are lots of green cells like "pru_pruX_r31_XX", and r31 is the magic PRU input register.  But P8_11 and P8_12 break this rule.  So it's better to assume the pinmux modes were assigned at random, and check carefully in the tables.  I'm glad I printed them out, since I've had to stare at them a lot.

We want P8_11 to be our output pin, because the P8 table doesn't list it as colliding with anything important, and because it's highlighted in green, showing that it can work with PRU EGP.  Its name in that cell is pr1_pru0_pru_r30_15.  "pru0" tells us it's for PRU0.  "r30" tells us it can be used as an output, since r30 is the magic output register.  And it's in the "mode6" column, so we know we need to set that pin to mode 6 if we want to use it from the PRU0's register 30.

We can also get that from the elinux.org table, since the "Pinmux Mode" to the right of the R30(output) column is Mode_6.

For our input pin P8_16, when we follow the tables we see that it's also mode 6 in this case.

But as explained in the Exploring BeagleBone book (and less clearly in table 9-60 of the TRM), we're not done yet!  There are 4 other settings that can apply to each pin:

Bits 0..2 are the multiplexer mode (these two pins are both 6)
Bit 3 enables (0) or disables (1) the internal pullup/pulldown resistor
Bit 4 is 0 for pulldown, 1 for pullup
Bit 5 is 0 to disable input, 1 to enable input.
Bit 6 is 1 if you want slow rise/fall times (for long i2c buses)

So for our output pin, P8_11, our configuration value is just 0x6, since none of the other bits are set.

But for our input pin P8_16, we need to turn on bit 5, so the value is 0x26  (10000 binary ORed with 110 binary).

Device Tree Overlays (there is NO escape!)

I looked all over, and there doesn't seem to be a way around creating and editing device tree overlays.

Now that we've picked what pins we want to use with the PRU, we have to use the device tree to enable the PRUs and put those pins into the right mode.

Here's a DTS file that sets up P8_11 for output via PRU EGP, and P8_16 for input via PRU EGP.  It's much shorter than it looks because I added a lot of comments:

 // This DTS overlay sets up one input and one output pin for use by  
 // PRU0 via its Enhanced GPIO mode, which will let us access those pins  
 // by writing to R30 bit 15 or reading from R31 bit 14.  
   
 // Save this file wherever you want (but I recommend /lib/firmware), as  
 // "PRU-GPIO-EXAMPLE-00A0.dts".
   
 // Compile with:
 // dtc -O dtb -I dts -o /lib/firmware/PRU-GPIO-EXAMPLE-00A0.dtbo -b 0 -@ PRU-GPIO-EXAMPLE-00A0.dts  
   
 // You'll have to reboot, after which you can do this as root to activate it:  
 // echo PRU-GPIO-EXAMPLE > /sys/devices/bone_capemgr.?/slots  
 
 /dts-v1/;  
 /plugin/;  
 
 / {  
   // This determines which boards can use this DTS overlay  
   compatible = "ti,beaglebone", "ti,beaglebone-green", "ti,beaglebone-black";  
   
   // I think part-number is supposed to correspond with the filename,  
   // so we'd save this as "PRU-GPIO-EXAMPLE-00A0.dts".  
   part-number = "PRU-GPIO-EXAMPLE";  
   
   // This always seems to be 00A0, and all the .dtbo files in /lib/firmware  
   // seem to be named foo-00A0.dtbo, but then are loaded without that suffix.  So
   // for foo-00A0.dtbo we'd do 'echo foo > /sys/devices/bone_capemgr.?/slots'
   version = "00A0";
   
   // List the pins and resources we'll be using. This table:  
   // http://elinux.org/Ti_AM33XX_PRUSSv2#Beaglebone_PRU_connections_and_modes  
   // shows which pins can be used with PRU0 and PRU1 for input and output via  
   // registers R31 and R30.  
   // Our output pin, P8_11, corresponds to PRU 0, register 30, bit 15  
   // Our input pin, P8_16, corresponds to PRU 0, register 31, bit 14  
   //  
   // Beware: Many other PRU EGP pins are reserved by HDMI or onboard flash, which  
   // would need to be disabled first by editing uEnv.txt and rebooting.  
   exclusive-use =  
      "P8.11", "P8.16", "pru0";  
   
   fragment@0 {  
    target = <&am33xx_pinmux>;  
    __overlay__ {  
      example_pins: pinmux_pru_pru_pins {  
   
       // The offset and mode for pins P8_11 and P8_16 also come from the table linked above.
       //  
       // That table gives offset 0x34 for P8_11, and 0x38 for P8_16.
       // It also shows us we want pinmux mode 6 for P8_11 in output mode,  
       // and again pinmux mode 6 for P8_16 in input mode.
       // 
       // Table 9-60 in the TRM: http://www.ti.com/lit/ug/spruh73l/spruh73l.pdf  
       // helps us calculate the rest of the configuration value.  
       //  
       // For P8_11, the other fields are all 0, so the value is just 0x06.  
       //  
       // For P8_16, we want it to be an input, so we also set bit 5, yielding  
       // a value of 0x26. We could also set bits 3 and 4 to enable a pullup  
       // or pulldown.  
       pinctrl-single,pins = <  
         0x34 0x06  
         0x38 0x26  
       >;  
      };  
    };  
   };  
   
   // This enables the PRU and assigns the GPIO pins to it for use in EGP mode.  
   fragment@1 {  
    target = <&pruss>;  
    __overlay__ {  
      status = "okay";  
      pinctrl-names = "default";  
      pinctrl-0 = <&example_pins>;  
    };  
   };  
 };  
   

After saving that to /lib/firmware/PRU-GPIO-EXAMPLE-00A0.dts, I compiled it:

 root@beaglebone:/lib/firmware# dtc -O dtb -I dts -o /lib/firmware/PRU-GPIO-EXAMPLE-00A0.dtbo -b 0 -@ PRU-GPIO-EXAMPLE-00A0.dts  

And then I had to reboot before the system would let me load it.  The "PRU-GPIO-EXAMPLE" and the  "L" in "P-O-L" shows me that the overlay loaded successfully.

 root@beaglebone:/lib/firmware# echo PRU-GPIO-EXAMPLE > /sys/devices/bone_capemgr.?/slots  
 root@beaglebone:/lib/firmware# cat /sys/devices/bone_capemgr.?/slots  
  0: 54:PF---   
  1: 55:PF---   
  2: 56:PF---   
  3: 57:PF---   
  4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G  
  5: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-UART2  
  6: ff:P-O-L Override Board Name,00A0,Override Manuf,PRU-GPIO-EXAMPLE  

Writing Code (finally!)

Now that the hard part's done, we can write some assembly code for the PRU and some C code to load it.  Here's the C code that runs on the main CPU and lets us load an arbitrary PRU .bin file into PRU 0:

 // Loads an arbitrary .bin file into PRU0 and waits for it to signal  
 // that it has finished.  
 //  
 // Pass in the filename of the .bin file on the command line, eg:  
 // $ ./pru_loader foo.bin  
 //  
 // Compile with:  
 // gcc -o pru_loader pru_loader.c -lprussdrv  
   
 #include <stdio.h>  
 #include <prussdrv.h>  
 #include <pruss_intc_mapping.h>  
   
 int main(int argc, char **argv) {  
  if (argc != 2) {  
   printf("Usage: %s pru_code.bin\n", argv[0]);  
   return 1;  
  }  
   
  // If this segfaults, make sure you're executing as root.  
  prussdrv_init();  
  if (prussdrv_open(PRU_EVTOUT_0) == -1) {  
   printf("prussdrv_open() failed\n");  
   return 1;  
  }  
    
  tpruss_intc_initdata pruss_intc_initdata = PRUSS_INTC_INITDATA;  
  prussdrv_pruintc_init(&pruss_intc_initdata);  
   
  // Change to 1 to use PRU1  
  int which_pru = 0;  
  printf("Executing program and waiting for termination\n");  
  prussdrv_exec_program(which_pru, argv[1]);  
   
  // Wait for the PRU to let us know it's done  
  prussdrv_pru_wait_event(PRU_EVTOUT_0);  
  printf("All done\n");  
   
  prussdrv_pru_disable(which_pru);  
  prussdrv_exit();  
   
  return 0;  
 }  
   

And here, finally, is the assembly code that runs on the PRU.  "set r30, r30, 15" is all it takes to turn on our pin, and "clr r30, r30, 15" is all it takes to shut it off!

Here's a lovely PRU instruction set quick reference, also from the book.  Print it out too.

 // Demonstrates using Enhanced GPIO (EGP), the fast way to  
 // do GPIO on certain pins with a PRU.  
 //  
 // Writing to r30 with PRU0 or PRU1 sets the pins given in this table:  
 // http://elinux.org/Ti_AM33XX_PRUSSv2#Beaglebone_PRU_connections_and_modes  
 //  
 // But only if the Pinmux Mode has been set correctly with a device  
 // tree overlay!  
 //  
 // Assemble with:  
 // pasm -b pru_egp_output.p  
   
 // Boilerplate  
 .origin 0  
 .entrypoint TOP  
   
 TOP:  
  // Writing bit 15 in the magic PRU GPIO output register  
  // PRU0, register 30, bit 15 turns on pin 11 on BeagleBone  
  // header P8.  
  set r30, r30, 15  
   
  // Uncomment to turn the pin off instead.  
  //clr r30, r30, 15  
   
  // Interrupt the host so it knows we're done  
  mov r31.b0, 19 + 16  
   
 // Don't forget to halt or the PRU will keep executing and probably  
 // require rebooting the system before it'll work again!  
 halt  
   

I assembled with "pasm -b pru_egp_output.p", loaded it with "sudo ./pru_loader pru_egp_output.bin", and verified with my voltmeter that P8_11 showed 3.3v.  Then I uncommented the clr, reassembled, re-ran and verified that it dropped to 0.  Success!

Now we're ready for the big leagues, 5 whole instructions to copy the value of the input pin to the output pin:

 // Demonstrates using Enhanced GPIO (EGP), the fast way to  
 // do GPIO on certain pins with a PRU.  
 //  
 // Writing to r30 or reading from r31 with PRU0 or PRU1 sets or reads the pins  
 // given in this table:  
 // http://elinux.org/Ti_AM33XX_PRUSSv2#Beaglebone_PRU_connections_and_modes  
 //  
 // But only if the Pinmux Mode has been set correctly with a device  
 // tree overlay!  
 //  
 // Assemble with:  
 // pasm -b pru_egp_io.p  
   
 // Boilerplate  
 .origin 0  
 .entrypoint TOP  
   
 TOP:  
  // Reading bit 14 in the magic PRU GPIO input register 31  
  // bit 14 for PRU0 reads pin 16 on BeagleBone header P8.  
  // If the input bit is high, set the output bit high, and vice versa.  
  QBBS HIGH, r31, 14  
  QBBC LOW, r31, 14  
   
 HIGH:  
  // Writing bit 15 in the magic PRU GPIO output register  
  // register 30, bit 15 for PRU0 turns on pin 11 on BeagleBone  
  // header P8.  
  set r30, r30, 15  
  QBA DONE  
   
 LOW:  
  clr r30, r30, 15  
   
 DONE:  
  // Interrupt the host so it knows we're done  
  mov r31.b0, 19 + 16  
   
 // Don't forget to halt or the PRU will keep executing and probably  
 // require rebooting the system before it'll work again!  
 halt  
   

I tested it by installing a jumper from P9_01 (GND) or P9_03 (DC_3.3V) to P8_16.  Be sure not to connect to P9_05 or P9_06 though, since those are at 5V and could blow up your board!

Where to now?

If you're still with me, you probably have something fancier in mind than just turning a pin on or off.  Even though am335x_pru_package came installed on my BBB, the examples weren't there.  You can find them here on github: https://github.com/beagleboard/am335x_pru_package/tree/master/pru_sw/example_apps

In particular, PRU_memAccessPRUDataRam was super helpful.  It doesn't use any GPIO pins, so it only requires that the PRUs are enabled (which you get if you use my overlay above).  I was trying to get some assembly code to work, and couldn't get any signal back from the PRU to know if it wasn't working or if it just couldn't toggle any GPIO pins.  I had deleted that pesky "interrupt the host" instruction at the end of my listing above, so I was running the code totally blind.  When I discovered that PRU_memAccessPRUDataRam worked fine on a clean boot, but would no longer work after running my code, I quickly realized that I had forgotten to put a HALT instruction at the end of my code.

One other thing to explore is the new C compiler for the PRUs, PRUSS-C.  It's also installed by default on my beaglebones.  It looks pretty neat, but I haven't managed to get the code onto a PRU yet.  Something to do with .cmd scripts for hexpru, I think.

Finally, TI also has a GUI development suite for their processors.  I was tempted to try it, but they make you create a login to myTI first, and I'd rather use command line tools anyway.