libpruio  0.0
AM33xx-PRU driver for digital input / output and analog input
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/_Preparation.md
Go to the documentation of this file.
1 Preparation {#ChaPreparation}
2 ===========
3 
4 When using libpruio you neither need device tree compilers nor overlays
5 for analog or digital pin configurations. All setup gets done in single
6 source inside your program, controlling the driver that is running on a
7 co-processor (PRUSS). All you have to ensure to load the kernel driver
8 for the PRU subsystem and start it once at system startup.
9 
10 \note All following installation commands are to be executed with
11  system administrator privilegues on the Beaglebone hardware with
12  a Debian based LINUX operating system.
13 
14 Once the library is installed, selected users can use it without the
15 need of admin privilegues.
16 
17 
18 Dependencies {#SubPreDeps}
19 ============
20 
21 libpruio is based on *libprussdrv* from the package
22 [am335x_pru_package](https://github.com/beagleboard/am335x_pru_package).
23 You've to download and install the [FB prussdrv Kit
24 (de)](http://www.freebasic-portal.de//downloads/fb-on-arm/fb-prussdrv-kit-bbb-324.html)
25 first. Find English installation instructions in
26 [this link at the bottom of the German page](http://www.freebasic.net/forum/viewtopic.php?f=14&t=22461#p197061).
27 
28 To compile changes in the examples or in the library source code, you
29 need an ARM version of the FreeBASIC compiler. The binaries in this
30 package were compiled by [BBB-FBC
31 (de)](http://www.freebasic-portal.de/downloads/fb-on-arm/bbb-fbc-fbc-fuer-beaglebone-black-283.html),
32 an english discussion on this project should be available at [this
33 site](http://www.freebasic.net/forum/viewtopic.php?f=5&t=21372)
34 (contact admins if the link is still down).
35 
36 
37 System preparation {#SubPreSystem}
38 ==================
39 
40 To execute software based on libpruio driver you have to ensure that
41 
42 -# the kernel driver *uio_pruss* is loaded.
43 -# the PRU subsystem is powered on,
44 -# the user has read / write privilegues to the `/dev/uio5` system interrupt
45 
46 The first and second preconditions can be reached at once. Either activate
47 one of the prepared operating systems device tree overlays. Ie. execute
48 
49 ~~~{.sh}
50 sudo echo BB-BONE-PRU-01 > /sys/devices/bone_capemgr.9/slots
51 ~~~
52 
53 Or you use the minimal overlay provided in the above mentioned FB
54 prussdrv Kit package, which needs to get installed in the right folder
55 (/lib/firmware), first. Then execute
56 
57 ~~~{.sh}
58 sudo echo PRUSSDRV > /sys/devices/bone_capemgr.9/slots`
59 ~~~
60 
61 Both device tree overlays start the PRUSS and also load the kernel
62 driver. The kernel driver allocates external memory for the PRUSS,
63 which is a default of 256 kB. (See section \ref SubERam on how to
64 customize this.)
65 
66 Item 3 can either be reached by running the software as user `root`.
67 But the prefered method should be installing privilegues for the
68 related users:
69 
70 - create a new user group (ie `addgroup pruio`)
71 - adapt this group to the interrupt device (ie `chgrp pruio /dev/uio5`)
72 - activate read / write privilegues for this group (ie `chmod g+rw /dev/uio5`)
73 - and make yourself (and all related users) a member of this group
74 
75 \note Enabling the PRU subsystem may be a safety risk. A virus running
76  at the PRUSS can access each device register or memory area. The
77  kernel running on the host cannot protect the system.
78 
79 
80 Library preparation {#SecPrePruio}
81 ===================
82 
83 This package contains a pre-compiled version of the libpruio binaries
84 in the folder src/c_wrapper. It's the universal (all-in) version,
85 including the C wrapper functions. This section is about the
86 installation instructions.
87 
88 
89 FreeBASIC {#SubPreFB}
90 ---------
91 
92 To install libpruio on your system and use it in your FreeBASIC code,
93 you have to copy the binaries to a folder where the linker can find
94 them. Futhermore copy the headers to a propper place where the compiler
95 can find them. Starting from the basis folder of the unpacked libpruio
96 package and execute:
97 
98 ~~~{.sh}
99 sudo su
100 cd src/c_wrapper/
101 cp libpruio.so /usr/local/lib
102 cp libpruio.a /usr/local/lib
103 ldconfig
104 cd ../pruio/
105 mkdir /usr/local/include/freebasic/BBB
106 cp pruio.bi /usr/local/include/freebasic/BBB
107 cp pruio.hp /usr/local/include/freebasic/BBB
108 cp pruio_pins.bi /usr/local/include/freebasic/BBB
109 exit
110 ~~~
111 
112 \note For testing only, you can skip the header files (*.bi and *.hp)
113  part. Just execute until ldconfig and then exit.
114 
115 
116 C Compiler {#SubPreC}
117 ----------
118 
119 The author isn't a C expert and doesn't know if if this is a propper
120 insatallation. To compile the C examples the following was done
121 (starting from the basis folder of the unpacked libpruio package):
122 
123 ~~~{.sh}
124 sudo su
125 cd src/c_wrapper/
126 cp libpruio.so /usr/local/lib
127 cp libpruio.a /usr/local/lib
128 ldconfig
129 cp pruio.h /usr/local/include
130 cp pruio_c_wrapper.h /usr/local/include
131 cp pruio_pins.h /usr/local/include
132 cp ../pruio/pruio.hp /usr/local/include
133 exit
134 ~~~
135 
136 \note For testing only, you can skip the header files (*.h and *.hp)
137  part. Just execute until ldconfig and then exit.