For timing-critical tasks, the Beaglebone Black has two built-in microprocessors, the PRUs (Processing real-time units). It is not obvious how to use the PRUs; in this post, I try to put together some information on the PRUs.
The PRUs can currently only be programmed in assembler. This is not as bad as it sounds: the assembler instruction set is fairly easy to use, and since it is straightforward to share data between the PRU and the Beaglebone, we only have to write the time-critical code parts in assembler and can write the glue logic in a normal C or C++ program on the Beaglebone black.
At first, you have to install the assembler and the C-library for communication between the PRU and the Beaglebone. You can find an instruction at https://npmjs.org/package/pru under "Driver Library and Assembler". The install also comes with a few example programs.
After installation, you have to enable the PRU via a device tree overlay. On your Beaglebone, navigate to /lib/firmware, create a file called BB-BONE-PRU-00A0.dts and copy the following into the file:
This enables the PRU and gives the PRU direct access to the GPIO1_12-pin. This is achieved with the lines 14-23; in particular with the line 0x30 0x06. Where do these numbers come from? This is actually fairly non-obvious since both the reference manual and the technical reference manual are silent on this question.
Have a look at selsinork's table in post 5 at http://www.element14.com/community/thread/23952?tstart=0.
Oddly, a similar, but less informative table appears in the reference manual, which you may find at http://www.farnell.com/datasheets/1701090.pdf, and I do not know in which official argument the table linked above appears - it seems to be correct, however. You should see columns up to mode 7; if not, you find a PDF version of the table in the post after the table.
Looking at the columns mode 6 and mode 7, we see that mode 6 of the gpio1_12 pin is pr1_pru0_pru_r30_14. In this mode, we can control the behaviour of that particular pin directly in the assembler code of the PRU. This is why we have the 0x06 in the above code: it tells the Beaglebone that we want to switch a pin to mode 6. The other number, 0x30, tells the Beaglebone which pin to switch. The helpful table linked above actually gives the memory address of the pin: it has an offset of 0x830. This is the offset of the pin conf_gpmc_ad12 in the Control module part of the memory of the Beaglebone, as you can find in the technical reference manual http://elinux.org/images/6/65/Spruh73c.pdf of the (processor used in the) Beaglebone in Chapter 9, Control module. Consulting selsinork's table, we see that the pin conf_gpmc_ad12 is indeed GPIO1, pin 12. Since the registers actually controlling the behaviour of the pins start at 0x800, we only pass the offset after this memory address, which is 0x30.
Now we have to compile the device tree overlay. In /lib/firmware, the command
compiles the .dts file to a file usable by Linux. Should the compiler not be installed on your system, you can find instructions at https://npmjs.org/package/pru under "Device tree" .To enable the overlay, go to /sys/devices/bone_capemgr.8 (or maybe 9, depending on your version of Linux) and load the device tree overlay:
It should now appear at the end of the list you get with
Now you have enabled the PRU. This is not a permanent way to enable the device tree overlay - you will have to do it again after each reboot; forgetting to load the overlay is usually the reason for weird error messages you get when starting the PRU. Some googling should give you good results if you want to make this overlay permanent.
The device tree stuff is unfortunately quite confusing, but you can forget about all this right now. But while we are at the command line, we also enable the PRU drivers via
I think they are only required if you actually want to access the memory of the Beaglebone via the PRUs, but safe is safe.
Finally, we can program our PRU. The following two programs will ask the user for an input and move a servo motor connected to GPIO1_12 accordingly. This already requires timing in the lower microseconds range, which is really tricky to reach with direct GPIO manipulations via Linux, leading to a jittery servo. It could probably also be done with a pwm pin, but getting pwm to work also seems to be tricky.
To play it safe, you should use a separate battery for the servo motor if you try this (remember to connect the grounds!) since the servo can pull quite a lot of peak current. I would also advice to use a 10k resistor in the line from the pin to the servo, just in case something goes wrong.
The assembler code compiles to a bin-file; the following C-program shows how to upload the bin-file to the PRU.
We start by defining a memory map into that part of the memory which can be directly accessed from both the PRU and the Beaglebone. The first part of that memory is for storing the sourcecode; offset 0x12000 is in the shared RAM of the PRUs. We can now write something to this place in memory and easily read it into the PRU. The pruss library is supposed to have its own function doing that, but I could not get it to work, and the memory map approach is more transparent anyway.
After that, we initiliaze the PRU interrupt, which allows the PRU to notify our C-program once it is finished, and load the bin file in line 58. After that, we read in a number representing the angle we want to move the servo to. If this number is 255, we pass 255 to the PRU and break the loop; otherwise, we pass a rough estimate of the length of the pulses needed to reach the desired servo position. Finally, we wait until the PRU tells us he is done and do some cleanup. Depending on your servo, you probably have to tweak the numbers a bit.
To compile the code, you need to link to several libraries. From the command line,
does the job.
Now for the assembler code:
You should save this in a .p file - at least, that is what the examples do. It can be compiled via
and you should change the C-code in line 58 to reflect your filename.
You can find a description of all the instructions at http://processors.wiki.ti.com/index.php/PRU_Assembly_Instructions.
In the very first line, we change the register used for storing return addresses of function calls: By default, it is r30, which interferes with our program since r30 also is the register we use to control the pin. More precisely, bit 14 of r30 now controls the gpio1_12 pin thanks to our device tree overlay; you can see it set and cleared in lines 41 and 44.
The lines 34-36 enable access of the PRU to the actual memory of the Beaglebone, not only the parts dedicated to the PRU. We do not actually use it here; you should be a bit careful with direct manipulation of the Beaglebone memory.You may find the information at http://hipstercircuits.com/beaglebone-pru-ddr-memory-access-the-right-way/ useful if you are interested in this.
In line 39, the LBCO command loads the content of memory at the location stored in the register r3 into the register r4. In our case, this is the same location (0x12000) our memory map in the preceding C-program pointed to, so this command loads the value we have stored there (and before that, passed to the C-program via the command line) into register r4.If this value is 255, we jump to the end of the program. Everything else should be fairly straightforward if you have programmed any assembler before or can be easily found in the instruction set wiki linked above. Line 60 enables the interrupt, notifying the C-program that it can quit now.
Hoepfully, this is useful for someone - it likely will be useful for me in 6 months once I have forgotten everything again.