libpruio  0.2
Input/Output driver for digital/analog lines on Beagleboard hardware
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/preparation.md
1 Preparation {#ChaPreparation}
2 ===========
3 \tableofcontents
4 
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.
9 
10 
11 Dependencies {#SecDependencies}
12 ============
13 
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:
17 
18 <TABLE>
19 <TR>
20 <TH>Executing Binaries</TH>
21 <TH>Compiling C code</TH>
22 <TH>Compiling FB code (and customizing libpruio)</TH>
23 </TR>
24 <TR>
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>
28 </TR>
29 <TR>
30 <TD></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>
33 </TR>
34 </TABLE>
35 
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.
40 
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
44 [GIT repo](https://github.com/freebasic/fbc).
45 
46 
47 Preconditions {#SecPreconditions}
48 =============
49 
50 To execute software based on libpruio you have to ensure that
51 
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.
55 
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
63 
64 ~~~{.sh}
65 sudo echo libpruio > /sys/devices/bone_capemgr.*/slots
66 ~~~
67 
68 It's also possible to activate one of the prepared operating systems
69 device tree overlays, ie. by executing
70 
71 ~~~{.sh}
72 sudo echo BB-BONE-PRU-01 > /sys/devices/bone_capemgr.*/slots
73 ~~~
74 
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
78 customize this.)
79 
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
82 
83 ~~~{.sh}
84 sudo nano /etc/defaults/capemgr
85 ~~~
86 
87 to make it look like
88 
89 ~~~{.txt}
90 # Default settings for capemgr. This file is sourced by /bin/sh from
91 # /etc/init.d/capemgr.sh
92 
93 # Options to pass to capemgr
94 CAPE=libpruio
95 ~~~
96 
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:
100 
101 - create a new user group (ie `addgroup pruio`)
102 - and make yourself (and all related users) a member of this group
103 
104 Then you can apply these group to the interrupt device and activate
105 read / write privileges for it (execute with admin privileges)
106 
107 ~~~{.sh}
108 chgrp pruio /dev/uio5
109 chmod g+rw /dev/uio5
110 ~~~
111 
112 It's best to auto-execute these commands at startup (ie. in the
113 /etc/rc.local script).
114 
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.
118 
119 
120 
121 Pin Configuration {#SecPinConfig}
122 =================
123 
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).
130 
131 Pinmuxing means to connect a CPU ball to
132 
133 - a digital subsystem connector,
134 
135 - an internal pullup or pulldown resistor (or neither of them),
136 
137 - a receiver module for input pins (optional).
138 
139 \note Just a subset of the CPU balls is connected to the Beaglebone
140  header pins.
141 
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
146 
147 - when the universal device tree overlay (libpruio-0A00.dtbo) isn't
148  loaded, or
149 
150 - when the code isn't executed with write privileges for folder
151  /sys/devices/ocp.* (admin privileges).
152 
153 To avoid such a failure
154 
155 - either pre-configure the header pins by a customized device tree
156  overlay, ie. generated by the tool dts_custom.bas.
157 
158 - Or load the universal device tree overlay libpruio-0A00.dtbo (shipped
159  with the libpruio package) and execute the program with admin
160  privileges.
161 
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.
170 
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).
176 
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)
181 
182 ~~~{.sh}
183 echo x0E > /sys/devices/ocp.*/pruio-12.*/state
184 ~~~
185 
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://www.ti.com/lit/pdf/spruh73)
190 for details on the pad registers.
191 
192 
193 Compiling C {#SubPreC}
194 ===========
195 
196 To compile your C source code against libpruio you need the
197 [am335x_pru_package](https://github.com/beagleboard/am335x_pru_package)
198 and from the libpruio package the library binary and the header files
199 
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
204 
205 It's recommended to install by
206 
207 ~~~{.sh}
208 sudo su
209 apt-get install am335x-pru-package
210 wget http://www.freebasic-portal.de/dlfiles/539/libpruio-0.2.tar.bz2
211 tar xjf libpruio-0.2.tar.bz2
212 cd libpruio-0.2
213 cp src/c_wrapper/libpruio.so /usr/local/lib
214 ldconfig
215 cp src/c_wrapper/pruio*.h* /usr/local/include
216 exit
217 ~~~
218 
219 See file src/c_wrapper/pruio.h for the documentation and find examples
220 in folder src/c_examples.
221 
222 
223 Compiling FB {#SecPreFB}
224 ============
225 
226 To compile your FreeBASIC source code against libpruio you need the
227 [FB prussdrv Kit](http://www.freebasic-portal.de/downloads/fb-on-arm/fb-prussdrv-kit-bbb-324.html)
228 and from the libpruio package library binary and the header files.
229 
230 - src/c_wrapper/libpruio.so
231 - src/pruio/pruio*.bi
232 - src/pruio/pruio.hp
233 
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
237 
238 ~~~{.sh}
239 sudo su
240 mkdir /usr/local/include/freebasic/BBB
241 wget http://www.freebasic-portal.de/dlfiles/539/FB_prussdrv-0.0.tar.bz2
242 tar xjf FB_prussdrv-0.0.tar.bz2
243 cd FB_prussdrv-0.0
244 cp include/* /usr/local/include/freebasic/BBB
245 cp bin/pasm /usr/local/bin
246 cd ..
247 wget http://www.freebasic-portal.de/dlfiles/539/libpruio-0.2.tar.bz2
248 tar xjf libpruio-0.2.tar.bz2
249 cd libpruio-0.2
250 cp src/c_wrapper/libpruio.so /usr/local/lib
251 ldconfig
252 cp src/c_wrapper/pruio*.h* /usr/local/include
253 cp src/config/libpruio-0A00.dtbo /lib/firmware
254 cp src/pruio/pruio*.bi /usr/local/include/freebasic/BBB
255 cp src/pruio/pruio.hp /usr/local/include/freebasic/BBB
256 exit
257 ~~~
258 
259 In that case you've to adapt the `INCLUDE ONCE "..."` lines in your
260 code
261 
262 ~~~{.sh}
263 #INCLUDE ONCE "pruio.bi"
264 ~~~
265 becomes
266 ~~~{.sh}
267 #INCLUDE ONCE "BBB/pruio.bi"
268 ~~~
269 
270 Find example code in folder src/examples.
271 
272 To customize libpruio itself, you must observe this order
273 
274 -# Compile PRU code (pasm_init.p and pasm_run.p).
275 
276 -# Compile libpruio code (either pruio_c_wrapper.bas or pruio.bas).
277 
278 Find the command line to invoke the compilers at the top of each file.
279 
280 
281 Installation {#SecInstallation}
282 ============
283 
284 Here's a step by step guide for a complete libpruio installation on a
285 vanilla Debian (Ubuntu) system, based on a Rafael Vega post (find the
286 [original text here](http://beagleboard.org/Community/Forums?place=msg%2Fbeagleboard%2F9NYdGWOT_Mg%2F6X0v2XVEeUAJ)
287 ).
288 
289 -# Install FreeBasic compiler in BBB
290  -# Download and uncompress package from [BBB-FBC (fbc für Beaglebone Black)](http://www.freebasic-portal.de/downloads/fb-on-arm/bbb-fbc-fbc-fuer-beaglebone-black-283.html)
291 ~~~{.sh}
292 wget http://www.freebasic-portal.de/dlfiles/452/BBB_fbc-1.00.tar.bz2
293 tar xjf BBB_fbc-1.00.tar.bz2
294 ~~~
295  -# Copy files
296 ~~~{.sh}
297 cd BBB_fbc-1.00
298 cp usr/local/bin/fbc /usr/local/bin/
299 cp -R usr/local/lib/freebasic /usr/local/lib/
300 ~~~
301  -# Test compiler
302 ~~~{.sh}
303 fbc -version
304 ~~~
305  should result in
306 ~~~{.sh}
307 FreeBASIC Compiler - Version 1.01.0 (10-14-2014), built for linux-arm (32bit)
308 Copyright (C) 2004-2014 The FreeBASIC development team.
309 ~~~
310 
311 -# Install pruss driver kit.
312  -# Install original am335x-pru-package
313 ~~~{.sh}
314 apt-get install am335x-pru-package
315 ~~~
316  -# Download and uncompress FB package from [FB prussdrv Kit (BBB)](http://www.freebasic-portal.de/downloads/fb-on-arm/fb-prussdrv-kit-bbb-324.html)
317 ~~~{.sh}
318 wget http://www.freebasic-portal.de/dlfiles/539/FB_prussdrv-0.0.tar.bz2
319 tar xjf FB_prussdrv-0.0.tar.bz2
320 ~~~
321  -# Copy files
322 ~~~{.sh}
323 cd FB_prussdrv-0.0
324 mkdir /usr/local/include/freebasic/BBB
325 cp include/* /usr/local/include/freebasic/BBB
326 cp bin/pasm /usr/local/bin
327 ~~~
328 
329 -# Install libpruio
330  -# Download and uncompress package from [libpruio (D/A - I/O schnell und einfach)](http://www.freebasic-portal.de/downloads/fb-on-arm/libpruio-325.html)
331 ~~~{.sh}
332 wget http://www.freebasic-portal.de/dlfiles/539/libpruio-0.2.tar.bz2
333 tar xjf libpruio-0.2.tar.bz2
334 ~~~
335  -# Copy files
336 ~~~{.sh}
337 cd libpruio-0.2
338 cp src/c_wrapper/libpruio.so /usr/local/lib
339 ldconfig
340 cp src/c_wrapper/pruio*.h* /usr/local/include
341 cp src/config/libpruio-0A00.dtbo /lib/firmware
342 cp src/pruio/pruio*.bi /usr/local/include/freebasic/BBB
343 cp src/pruio/pruio.hp /usr/local/include/freebasic/BBB
344 ~~~
345  -# Activate the PRUSS by enabling the tree overlay. This must be done everytime, after each boot or before running your programs.
346 ~~~{.sh}
347 echo libpruio > /sys/devices/bone_capemgr.*/slots
348 ~~~
349  -# Test example
350 ~~~{.sh}
351 sudo src/examples/1
352 ~~~
353  should result in the table output (13 lines, 8 columns) described
354  in section \ref SubSecExaSimple.
355 
356 -# Prepare system (optional) as described in section \ref
357  SecPreconditions.
358 
359 \note These commands need admin privileges:
360  - `apt-get ...`
361  - `ldconfig`
362  - `mkdir ... /usr/...`
363  - `cp ... /usr/...`
364  - `cp ... /lib/...`
365  - `echo ... /sys/...`