1926 character interface and a userspace library (see sec.~\ref{sec:userlib}).

  1926 character device and a userspace library (see sec.~\ref{sec:userlib}).

  2104 \ldots

  2104 The native application interface (see chap.~\ref{sec:ecrt}) resides in

  2105 kernelspace and hence is only accessible from inside the kernel. To make the

  2106 application interface available from userspace programs, a userspace library

  2107 has been created, that can be linked to programs under the terms and

  2108 conditions of the LGPL, version 2 \cite{lgpl}.

  2109 

  2110 The library is named \textit{libethercat}. Its sources reside in the

  2111 \textit{lib/} subdirectory and are build by default when using

  2112 \lstinline+make+. It is installed in the \textit{lib/} path below the

  2113 installation prefix as \textit{libethercat.a} (for static linking),

  2114 \textit{libethercat.la} (for the use with \textit{libtool}) and

  2115 \textit{libethercat.so} (for dynamic linking).

  2116 

  2117 \subsection{Usage}

  2118 

  2119 The application interface header \textit{ecrt.h} can be used both in kernel

  2120 and in user context.

  2121 

  2122 The following minimal example shows how to build a program with EtherCAT

  2123 functionality. An entire example can be found in the \textit{examples/user/}

  2124 path of the master sources.

  2125 

  2126 \begin{lstlisting}[language=C]

  2127 #include <ecrt.h>

  2128 

  2129 int main(void)

  2130 {

  2131     ec_master_t *master = ecrt_request_master(0);

  2132 

  2133     if (!master)

  2134         return 1; // error

  2135 

  2136     pause(); // wait for signal

  2137     return 0;

  2138 }

  2139 \end{lstlisting}

  2140 

  2141 The program can be compiled and dynamically linked to the library with the

  2142 below command:

  2143 

  2144 \begin{lstlisting}

  2145 gcc ethercat.c -o ectest -I/opt/etherlab/include \

  2146     -L/opt/etherlab/lib -lethercat \

  2147     -Wl,--rpath -Wl,/opt/etherlab/lib

  2148 \end{lstlisting}

  2149 

  2150 The library can also be linked statically to the program:

  2151 

  2152 \begin{lstlisting}

  2153 gcc -static ectest.c -o ectest -I/opt/etherlab/include \

  2154     /opt/etherlab/lib/libethercat.a

  2155 \end{lstlisting}

  2156 

  2157 \subsection{Implementation}

  2158 \label{sec:userimp}

  2159 

  2160 Basically the kernel API was transferred into userspace via the master

  2161 character device (see sec.~\ref{sec:cdev}).

  2162 

  2163 The function calls of the kernel API are mapped to the userspace via an

  2164 \lstinline+ioctl()+ interface. Each function has its own \lstinline+ioctl()+

  2165 call. The kernel part of the interface calls the according API functions

  2166 directly, what results in a minimum additional delay (see

  2167 sec.~\ref{sec:usertiming}).

  2168 

  2169 Also for performance reasons, the actual domain process data (see

  2170 chap.~ref{sec:ecrt}) are not copied between kernel and user memory on every

  2171 access: Instead, the data are memory-mapped to the userspace application. Once

  2172 the master is configured and activated, the master module creates one big

  2173 process data memory area for all domains and maps it to userspace, so that the

  2174 application can directly access the process data. For that, there is no

  2175 additional delay accessing the process data from userspace.

  2160 The test results show, that for this configuration, the userspace API adds

  2231 The test results show, that for this configuration, the userspace API causes

  2161 about \unit{1}{\micro\second} delay for each function.

  2232 about \unit{1}{\micro\second} additional delay for each function, compared to

  2233 the kernel API.