====== flink Userspace Library ======

<box blue right 38% | **Downloads**>
  * [[https://github.com/flink-project/flinklib | flink Userspace Library on Github]]
</box>

This is the user documentation for the flink userspace library in C. It provides a device and bus independent interface to the underlying driver modules. For more information about the inner workings see [[https://github.com/flink-project/flinklib | flink Userspace Library on Github]]. The API of the library can be found under [[http://api.flink-project.ch/doc/flinklib/html|API]]

===== Overview =====
<box green right 38% | **Examples**>
  * [[.:flink_lib:high_level_example | Use GPIO using high-level API]]
  * [[.:flink_lib:low_level_example | Use low-level API for custom function]]
</box>
When flink is used on a Linux based system the flink userspace library offers an simple interface to communicate with the underlying kernel modules. The userspace library is split in two parts. 
  * High-Level API: Interface to predefined subdevices, such as PWM or GPIO.
  * Low-Level API: Can be used to access user-defined subdevices.

[{{ libraryapis.png?220 | //High-level and low-level API//}}]
The library must be built for the desired target platform architecture.  

===== Requirements =====
  * Linux based operating system
  * GCC 4.6 or newer
  * CMake 2.8 or newer
  * GNU make

===== Building =====
  - Clone git repository and all submodules: <code>git clone https://github.com/flink-project/flinklib.git --recursive
cd flinklib
git submodule init
git submodule update
</code>
  - Checkout a stable version<code>git checkout v1.1.2</code>
  - Create a build directory: <code>mkdir build-local</code>
  - Change to the build directory and setup your build environment with CMake: <code>cmake ..</code> Optional: you can specify an installation prefix path with <code>cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/ ..</code>
  - Build the source code: <code>make</code>

===== Building for a different platform architecture =====
  - Clone git repository and all submodules: <code>git clone https://github.com/flink-project/flinklib.git --recursive
cd flinklib
git submodule init
git submodule update</code>
  - Checkout a stable version <code>git checkout v1.1.2</code>
  - Create a build directory for the target platform, e.g.: <code>mkdir build-powerpc</code>
  - Create a CMake toolchain file. For more informations, please have a look at the [[http://www.cmake.org/Wiki/CMake_Cross_Compiling|CMake Wiki]]. This file has to specify which compiler has to be used and where it can be found on the system. 
  - Change to the build directory and setup your build environment with CMake: <code>cmake -DCMAKE_TOOLCHAIN_FILE:PATH=/path/to/your/toolchain/file.cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr/powerpc-linux-gnu/ ..</code>
  - Build the source code: <code>make</code>

===== Generating the documentation =====
Create the makefile with cmake (in the root directory): <code>cmake .</code>
After this generate the documentation as given in the ''Doxyfile'' by : <code>make doc</code>
===== Installation =====
Install the library and header files on your system: <code>make install</code>

===== Using a flink Device =====
A flink device must be opened before use (see [[flink_lib:high_level_example|Example using high-level API]]). 
<code>flink_dev* dev = flink_open("/dev/flink0");</code>
As a next step one has to choose an appropriate subdevice. This could be done by
<code>flink_subdev* subdev = flink_get_subdevice_by_id(dev, 2);</code> 
Here, the second subdevice is selected. You could also select a subdevice by its uniqe id. <code>flink_subdev* subdev = flink_get_subdevice_by_unique_id(dev, 0x23a5);</code>
Here, the subdevice with ''unique_id = 0x23a5'' is selected. This has the advantage that this unique_id does not change even in the case where subdevices are arranged differently in a FPGA design.
Now you can communicate with this selected subdevice. Assuming that it's of type GPIO you could configure it as an input or output.
<code>flink_dio_set_direction(subdev, 0, true);
flink_dio_set_value(subdev, 0, false);</code>
This sets channel 0 to output and writes a logical 0.As a last step you have to close the device.
<code>flink_close(dev);</code>