1 Preparation {#ChaPreparation}
5 This page describes how to
get libpruio working on your system. At the
6 bottom you
'll find a step by step guide to install the complete
7 system. Eager users may skip the theory and jump to \ref
8 SecInstallation directly.
11 Dependencies {#SecDependencies}
14 libpruio depends on the prussdrv library (from am335x_pru_package) to
15 control the PRU subsystems. A further package might be required,
16 depending on what you intend to do:
20 <TH>Executing Binaries</TH>
21 <TH>Compiling C code</TH>
22 <TH>Compiling FB code (and customizing libpruio)</TH>
25 <TD>[am335x_pru_package](https://github.com/beagleboard/am335x_pru_package)</TD>
26 <TD>[am335x_pru_package](https://github.com/beagleboard/am335x_pru_package)</TD>
27 <TD>[FB prussdrv Kit](http://www.freebasic-portal.de/downloads/fb-on-arm/fb-prussdrv-kit-bbb-324.html)</TD>
31 <TD>any C compiler</TD>
32 <TD>[BBB-FBC](http://www.freebasic-portal.de/downloads/fb-on-arm/bbb-fbc-fbc-fuer-beaglebone-black-283.html)</TD>
36 The original am335x_pru_package contains libprussdrv, some examples and
37 the PRU assembler (pasm). It's designed
for C compilers. In contrast
38 the FB prussdrv Kit contains the FreeBASIC headers and a modified pasm
39 that can output FB header files.
41 The BBB-FBC
package contains a minimal configuration of the executable
42 and some essential libraries. Find the complete compiler package
43 including the source code, lots of library bindings and examples in the
47 Preconditions {#SecPreconditions}
50 To execute software based on libpruio you have to ensure that
52 -# the kernel driver *uio_pruss* is loaded,
53 -# the PRU subsystems are enabled, and
54 -# the user has read / write privileges to the `/dev/uio5` system interrupt.
56 The first and second preconditions can be reached at once by loading an
57 appropriate device tree overlay. Either prepare, install and load a
58 customized overlay with fixed pin mode configurations (created by the
59 dts_custom.bas tool, see section \ref SecPinConfig for details). Or
60 install and load the universal overlay (file
61 src/config/libpruio-0A00.dtbo ust get copied to folder /lib/firmware)
62 shipped with the libpruio package by executing
65 sudo echo libpruio > /sys/devices/bone_capemgr.*/slots
68 It's also possible to activate one of the prepared operating systems
69 device tree overlays, ie. by executing
72 sudo echo BB-BONE-PRU-01 > /sys/devices/bone_capemgr.*/slots
75 All these device tree overlays start the PRUSS and also load the kernel
76 driver. The kernel driver allocates external memory for the PRUSS,
77 which is a default of 256 kB. (See section \ref SecERam on how to
80 When your operating systems comes with *capemgr* you can use it to load
81 the overlay at system startup by adapting the configuration file
84 sudo nano /etc/defaults/capemgr
90 # Default settings for capemgr. This file is sourced by /bin/sh from
91 # /etc/init.d/capemgr.sh
93 # Options to pass to capemgr
97 Item 3 of the initial list (privileges) can either be reached by
98 running the software as user `root`. But the prefered method should be
99 preparing privileges for the related users:
101 - create a new user group (ie `addgroup pruio`)
102 - and make yourself (and all related users) a member of this group
104 Then you can apply these group to the interrupt device and activate
105 read / write privileges for it (execute with admin privileges)
108 chgrp pruio /dev/uio5
112 It's best to auto-execute these commands at startup (ie. in the
113 /etc/rc.local script).
115 \note Enabling the PRU subsystem may be a safety risk. A virus running
116 at the PRUSS can access each device register or memory area. The
117 kernel running on the host cannot protect the system.
121 Pin Configuration {#SecPinConfig}
124 Beaglebone hardware contains a TI AM3359 CPU, which includes lots of
125 subsystems with different connectors like analog or digital lines. The
126 number of subsystem connectors is greater than the number of connectors
127 at the CPU housing (= CPU balls), in order to keep the housing small.
128 That's why digital lines (ie. like GPIO or PWM) have to get configured
129 (pinmuxed) before they can be used (in a non-default configuration).
131 Pinmuxing means to connect a CPU ball to
133 - a digital subsystem connector,
135 - an internal pullup or pulldown resistor (or neither of them),
137 - a receiver module for input pins (optional).
139 \note Just a subset of the CPU balls is connected to the Beaglebone
142 When a digital line should get used, libpruio checks first if the
143 pinmuxing matches the required configuration. If this is not the case,
144 libpruio tries to re-configure the CPU ball. This may fail and the API
145 function returns an error message
147 - when the universal device tree overlay (libpruio-0A00.dtbo) isn't
150 - when the code isn't executed with write privileges for folder
151 /sys/devices/ocp.* (admin privileges).
153 To avoid such a failure
155 - either pre-configure the header pins by a customized device tree
156 overlay, ie. generated by the tool dts_custom.bas.
158 - Or load the universal device tree overlay libpruio-0A00.dtbo (shipped
159 with the libpruio package) and execute the program with admin
162 During development, the later might be advantageous (although it
163 requires admin privileges), since a feature can easily get switched
164 from one pin to another. In contrast, changing a customized overlay
165 mostly requires re-booting the system, since unlaoding and reloading a
166 device tree overlay doesn't work reliable (effective September, 2014).
167 When you finished testing and start to use a PCB with fixed wiring,
168 it's time to install your customized device tree overlay and further on
169 work with user privileges.
171 Internaly, libpruio uses the CPU ball number to identify a connector.
172 That's why you can access all connectors, even those which are not
173 connected to a header pin. The (optional) header pruio_pins.bi includes
174 convenience macros to refer to a ball number by its header pin position
175 (as seen from the user point of view).
177 The universal device tree overlay can also get used to pre-configure
178 the pins before executing the program. Therefor `echo` the desired
179 hexadecimal value to the state file in the approprite pin folder. Ie.
180 to configure pin P9_14 as PWM output execute (with admin privileges)
183 echo x0E > /sys/devices/ocp.*/pruio-12.*/state
186 where `x0E` is the hexadecimal value for the Control Module pad
187 register and the number after `pruio-` is the hexadecimal number of the
188 CPU ball. Both hexadecimal values must have two digits. See
189 [ARM Reference Guide, chapter 9](http:
190 for details on the pad registers.
193 Compiling C {#SubPreC}
196 To compile your C source code against libpruio you need the
197 [am335x_pru_package](https:
198 and from the libpruio package the library binary and the header files
200 - src/c_wrapper/libpruio.so
201 - src/c_wrapper/pruio.h
202 - src/c_wrapper/pruio_pins.h
203 - src/c_wrapper/pruio.hp
205 It's recommended to install by
209 apt-get install am335x-pru-package
211 tar xjf libpruio-0.2.tar.bz2
213 cp src/c_wrapper/libpruio.so /usr/local/lib
215 cp src/c_wrapper/pruio*.h* /usr/local/include
219 See file src/c_wrapper/pruio.h for the documentation and find examples
220 in folder src/c_examples.
223 Compiling FB {#SecPreFB}
226 To compile your FreeBASIC source code against libpruio you need the
227 [FB prussdrv Kit](http:
228 and from the libpruio package library binary and the header files.
230 - src/c_wrapper/libpruio.so
231 - src/pruio/pruio*.bi
234 In order to avoid naming conflicts in the headers folder
235 (/usr/local/include/freebasic) place the Beaglebone stuff in a
236 subfolder called BBB. It's recommended to install by
240 mkdir /usr/local/include/freebasic/BBB
242 tar xjf FB_prussdrv-0.0.tar.bz2
353 should result in the table output (13 lines, 8 columns) described
354 in section \ref SubSecExaSimple.
356 -# Prepare system (optional) as described in section \ref
359 \note These commands need admin privileges:
362 - `mkdir ... /usr/...`
365 - `echo ... /sys/...`