changeset 1204 | 4e3e8400c338 |
parent 1203 | acb649738601 |
child 1214 | 63802a52dd69 |
1203:acb649738601 | 1204:4e3e8400c338 |
---|---|
80 \begin{center} |
80 \begin{center} |
81 \rule{\textwidth}{1.5mm} |
81 \rule{\textwidth}{1.5mm} |
82 |
82 |
83 {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat} |
83 {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat} |
84 Master \masterversion\\[1ex] |
84 Master \masterversion\\[1ex] |
85 Documentation} |
85 Preliminary Documentation} |
86 |
86 |
87 \vspace{1ex} |
87 \vspace{1ex} |
88 \rule{\textwidth}{1.5mm} |
88 \rule{\textwidth}{1.5mm} |
89 |
89 |
90 \vspace{\fill} |
90 \vspace{\fill} {\Large Dipl.-Ing. (FH) Florian Pose, |
91 {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex] |
91 \url{fp@igh-essen.com}\\[1ex] Ingenieurgemeinschaft \IgH} |
92 Ingenieurgemeinschaft \IgH} |
|
93 |
92 |
94 \vspace{\fill} |
93 \vspace{\fill} |
95 {\Large Essen, \SVNDate\\[1ex] |
94 {\Large Essen, \SVNDate\\[1ex] |
96 Revision \SVNRevision} |
95 Revision \SVNRevision} |
97 \end{center} |
96 \end{center} |
100 %------------------------------------------------------------------------------ |
99 %------------------------------------------------------------------------------ |
101 |
100 |
102 \tableofcontents |
101 \tableofcontents |
103 \listoftables |
102 \listoftables |
104 \listoffigures |
103 \listoffigures |
105 \lstlistoflistings |
104 %\lstlistoflistings |
106 |
105 |
107 %------------------------------------------------------------------------------ |
106 %------------------------------------------------------------------------------ |
108 |
107 |
109 \newpage |
108 \newpage |
110 \pagestyle{scrheadings} |
109 \pagestyle{scrheadings} |
197 |
196 |
198 \item It runs well even without realtime extensions. |
197 \item It runs well even without realtime extensions. |
199 |
198 |
200 \end{itemize} |
199 \end{itemize} |
201 |
200 |
202 \item Common ``realtime interface'' for applications, that want to use |
201 \item Common ``Application Interface'' for applications, that want to use |
203 EtherCAT functionality (see section~\ref{sec:ecrt}). |
202 EtherCAT functionality (see section~\ref{sec:ecrt}). |
204 |
203 |
205 \item \textit{Domains} are introduced, to allow grouping of process |
204 \item \textit{Domains} are introduced, to allow grouping of process |
206 data transfers with different slave groups and task periods. |
205 data transfers with different slave groups and task periods. |
207 |
206 |
330 \paragraph{Master Module} |
329 \paragraph{Master Module} |
331 \index{Master module} |
330 \index{Master module} |
332 |
331 |
333 Kernel module containing one or more EtherCAT master instances (see |
332 Kernel module containing one or more EtherCAT master instances (see |
334 section~\ref{sec:mastermod}), the ``Device Interface'' (see |
333 section~\ref{sec:mastermod}), the ``Device Interface'' (see |
335 section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see |
334 section~\ref{sec:ecdev}) and the ``Application Interface'' (see |
336 section~\ref{sec:ecrt}). |
335 section~\ref{sec:ecrt}). |
337 |
336 |
338 \paragraph{Device Modules} |
337 \paragraph{Device Modules} |
339 \index{Device modules} |
338 \index{Device modules} |
340 |
339 |
350 \index{Application module} |
349 \index{Application module} |
351 |
350 |
352 Kernel modules, that use the EtherCAT master (usually for cyclic exchange of |
351 Kernel modules, that use the EtherCAT master (usually for cyclic exchange of |
353 process data with EtherCAT slaves). These modules are not part of the EtherCAT |
352 process data with EtherCAT slaves). These modules are not part of the EtherCAT |
354 master code\footnote{Although there are some examples provided in the |
353 master code\footnote{Although there are some examples provided in the |
355 \textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to |
354 \textit{examples/} directory.}, but have to be generated or written by the |
356 be generated or written by the user. An application module can ``request'' a |
355 user. An application module can ``request'' a master through the application |
357 master through the realtime interface (see section~\ref{sec:ecrt}). If this |
356 interface (see section~\ref{sec:ecrt}). If this succeeds, the module has the |
358 succeeds, the module has the control over the master: It can provide a bus |
357 control over the master: It can provide a bus configuration and exchange |
359 configuration and exchange process data. |
358 process data. |
360 |
359 |
361 %------------------------------------------------------------------------------ |
360 %------------------------------------------------------------------------------ |
362 |
361 |
363 \section{Phases} |
362 \section{Phases} |
364 \index{Master phases} |
363 \index{Master phases} |
426 # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}` |
425 # `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}` |
427 \end{lstlisting} |
426 \end{lstlisting} |
428 |
427 |
429 The two masters can be addressed by their indices 0 and 1 respectively (see |
428 The two masters can be addressed by their indices 0 and 1 respectively (see |
430 figure~\ref{fig:masters}). The master index is needed for the |
429 figure~\ref{fig:masters}). The master index is needed for the |
431 \lstinline+ecrt_master_request()+ function of the realtime interface (see |
430 \lstinline+ecrt_master_request()+ function of the application interface (see |
432 section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the |
431 section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the |
433 \textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which |
432 \textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which |
434 defaults to $0$. |
433 defaults to $0$. |
435 |
434 |
436 \begin{figure}[htbp] |
435 \begin{figure}[htbp] |
591 \item[Operation] Cyclic code is run, process data is exchanged (see |
590 \item[Operation] Cyclic code is run, process data is exchanged (see |
592 section~\ref{sec:cyclic}). |
591 section~\ref{sec:cyclic}). |
593 |
592 |
594 \end{description} |
593 \end{description} |
595 |
594 |
595 \paragraph{Example Applications} \index{Example Applications} There are a few |
|
596 example applications in the \textit{examples/} subdirectory of the master |
|
597 code. They are documented in the source code. |
|
598 |
|
596 %------------------------------------------------------------------------------ |
599 %------------------------------------------------------------------------------ |
597 |
600 |
598 \section{Master Configuration} |
601 \section{Master Configuration} |
599 \label{sec:masterconfig} |
602 \label{sec:masterconfig} |
600 |
603 |
601 \ldots |
604 \ldots |
605 % FIXME Attaching |
|
602 |
606 |
603 \begin{figure}[htbp] |
607 \begin{figure}[htbp] |
604 \centering |
608 \centering |
605 \includegraphics[width=.8\textwidth]{images/app-config} |
609 \includegraphics[width=.8\textwidth]{images/app-config} |
606 \caption{Master Configuration} |
610 \caption{Master Configuration} |
644 \includegraphics[width=.6\textwidth]{images/master-locks} |
648 \includegraphics[width=.6\textwidth]{images/master-locks} |
645 \caption{Concurrent master access} |
649 \caption{Concurrent master access} |
646 \label{fig:locks} |
650 \label{fig:locks} |
647 \end{figure} |
651 \end{figure} |
648 |
652 |
649 Figure~\ref{fig:locks} exemplary shows, how two processes share one master: The |
653 Figure~\ref{fig:locks} exemplary shows, how two processes share one master: |
650 application's cyclic task uses the master for process data exchange, while the |
654 The application's cyclic task uses the master for process data exchange, while |
651 master-internal EoE process uses it to communicate with EoE-capable slaves. |
655 the master-internal EoE process uses it to communicate with EoE-capable |
652 Both have to acquire the master lock before access: The application task can |
656 slaves. Both have to acquire the master lock before access: The application |
653 access the lock natively, while the EoE process has to use the callbacks. |
657 task can access the lock natively, while the EoE process has to use the |
654 Section~\ref{sec:concurrency} gives an example, of how to implement this. |
658 callbacks. See the application interface documentation |
659 (section~\ref{sec:ecrt} of how to use the locking callbacks. |
|
655 |
660 |
656 %------------------------------------------------------------------------------ |
661 %------------------------------------------------------------------------------ |
657 |
662 |
658 \chapter{Ethernet Devices} |
663 \chapter{Ethernet Devices} |
659 \label{sec:devices} |
664 \label{sec:devices} |
1439 is skipped. |
1444 is skipped. |
1440 |
1445 |
1441 \item[PREOP] The state change FSM is used to bring the slave to PREOP state. |
1446 \item[PREOP] The state change FSM is used to bring the slave to PREOP state. |
1442 If this is the requested state, the state machine is finished. |
1447 If this is the requested state, the state machine is finished. |
1443 |
1448 |
1444 \item[Sdo Configuration] If there is a slave configuration attached |
1449 \item[Sdo Configuration] If there is a slave configuration attached (see |
1445 (see section~\ref{sec:attach}), and there are any Sdo configurations are |
1450 section~\ref{sec:masterconfig}), and there are any Sdo configurations are |
1446 provided by the application, these are sent to the slave. |
1451 provided by the application, these are sent to the slave. |
1447 |
1452 |
1448 \item[Pdo Configuration] The Pdo configuration state machine is executed to |
1453 \item[Pdo Configuration] The Pdo configuration state machine is executed to |
1449 apply all necessary Pdo configurations. |
1454 apply all necessary Pdo configurations. |
1450 |
1455 |
1575 section~\ref{sec:coeimp}), so the slave must support the CoE mailbox protocol. |
1580 section~\ref{sec:coeimp}), so the slave must support the CoE mailbox protocol. |
1576 |
1581 |
1577 \paragraph{Pdo Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read}) |
1582 \paragraph{Pdo Reading FSM} This state machine (fig.~\ref{fig:fsm-pdo-read}) |
1578 has the purpose to read the complete Pdo configuration of a slave. It reads |
1583 has the purpose to read the complete Pdo configuration of a slave. It reads |
1579 the Pdo assignment for each Sync Manager and uses the Pdo Entry Reading FSM |
1584 the Pdo assignment for each Sync Manager and uses the Pdo Entry Reading FSM |
1580 (fig.~\ref{fig:fsm_pdo_entry_read}) to read the mapping for each assigned Pdo. |
1585 (fig.~\ref{fig:fsm-pdo-entry-read}) to read the mapping for each assigned Pdo. |
1581 |
1586 |
1582 \begin{figure}[htbp] |
1587 \begin{figure}[htbp] |
1583 \centering |
1588 \centering |
1584 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read} |
1589 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_read} |
1585 \caption{Transition Diagram of the Pdo Reading State Machine} |
1590 \caption{Transition Diagram of the Pdo Reading State Machine} |
1591 Pdos for this sync manager and then reads out the subindices of the Sdo to get |
1596 Pdos for this sync manager and then reads out the subindices of the Sdo to get |
1592 the assigned Pdo's indices. When a Pdo index is read, the Pdo Entry Reading |
1597 the assigned Pdo's indices. When a Pdo index is read, the Pdo Entry Reading |
1593 FSM is executed to read the Pdo's mapped Pdo entries. |
1598 FSM is executed to read the Pdo's mapped Pdo entries. |
1594 |
1599 |
1595 \paragraph{Pdo Entry Reading FSM} This state machine |
1600 \paragraph{Pdo Entry Reading FSM} This state machine |
1596 (fig.~\ref{fig:fsm_pdo_entry_reading}) reads the Pdo mapping (the Pdo entries) |
1601 (fig.~\ref{fig:fsm-pdo-entry-read}) reads the Pdo mapping (the Pdo entries) of |
1597 of a Pdo. It reads the respective mapping Sdo (\lstinline+0x1600+ - |
1602 a Pdo. It reads the respective mapping Sdo (\lstinline+0x1600+ - |
1598 \lstinline+0x17ff+, or \lstinline+0x1a00+ - \lstinline+0x1bff+) for the given |
1603 \lstinline+0x17ff+, or \lstinline+0x1a00+ - \lstinline+0x1bff+) for the given |
1599 Pdo by reading first the subindex zero (number of elements) to determine the |
1604 Pdo by reading first the subindex zero (number of elements) to determine the |
1600 number of mapped Pdo entries. After that, each subindex is read to get the |
1605 number of mapped Pdo entries. After that, each subindex is read to get the |
1601 mapped Pdo entry index, subindex and bit size. |
1606 mapped Pdo entry index, subindex and bit size. |
1602 |
1607 |
1603 \begin{figure}[htbp] |
1608 \begin{figure}[htbp] |
1604 \centering |
1609 \centering |
1605 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read} |
1610 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_read} |
1606 \caption{Transition Diagram of the Pdo Entry Reading State Machine} |
1611 \caption{Transition Diagram of the Pdo Entry Reading State Machine} |
1607 \label{fig:fsm-pdo-read} |
1612 \label{fig:fsm-pdo-entry-read} |
1608 \end{figure} |
1613 \end{figure} |
1609 |
1614 |
1610 \begin{figure}[htbp] |
1615 \begin{figure}[htbp] |
1611 \centering |
1616 \centering |
1612 \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf} |
1617 \includegraphics[width=.9\textwidth]{graphs/fsm_pdo_conf} |
1613 \caption{Transition Diagram of the Pdo Configuration State Machine} |
1618 \caption{Transition Diagram of the Pdo Configuration State Machine} |
1614 \label{fig:fsm-pdo-read} |
1619 \label{fig:fsm-pdo-conf} |
1615 \end{figure} |
1620 \end{figure} |
1616 |
1621 |
1617 \begin{figure}[htbp] |
1622 \begin{figure}[htbp] |
1618 \centering |
1623 \centering |
1619 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf} |
1624 \includegraphics[width=.4\textwidth]{graphs/fsm_pdo_entry_conf} |
1620 \caption{Transition Diagram of the Pdo Entry Configuration State Machine} |
1625 \caption{Transition Diagram of the Pdo Entry Configuration State Machine} |
1621 \label{fig:fsm-pdo-read} |
1626 \label{fig:fsm-pdo-entry-conf} |
1622 \end{figure} |
1627 \end{figure} |
1623 |
1628 |
1624 %------------------------------------------------------------------------------ |
1629 %------------------------------------------------------------------------------ |
1625 |
1630 |
1626 \chapter{Mailbox Protocol Implementations} |
1631 \chapter{Mailbox Protocol Implementations} |
1778 To overcome this problem, an own cyclic process is needed to asynchronously |
1783 To overcome this problem, an own cyclic process is needed to asynchronously |
1779 execute the EoE state machines. For that, the master owns a kernel timer, that |
1784 execute the EoE state machines. For that, the master owns a kernel timer, that |
1780 is executed each timer interrupt. This guarantees a constant bandwidth, but |
1785 is executed each timer interrupt. This guarantees a constant bandwidth, but |
1781 poses the new problem of concurrent access to the master. The locking |
1786 poses the new problem of concurrent access to the master. The locking |
1782 mechanisms needed for this are introduced in section~\ref{sec:concurr}. |
1787 mechanisms needed for this are introduced in section~\ref{sec:concurr}. |
1783 Section~\ref{sec:concurrency} gives practical implementation examples. |
|
1784 |
1788 |
1785 \paragraph{Automatic Configuration} |
1789 \paragraph{Automatic Configuration} |
1786 |
1790 |
1787 By default, slaves are left in PREOP state, if no configuration is applied. If |
1791 By default, slaves are left in PREOP state, if no configuration is applied. If |
1788 an EoE interface link is set to ``up'', the requested slave's |
1792 an EoE interface link is set to ``up'', the requested slave's |
1799 |
1803 |
1800 % FIXME |
1804 % FIXME |
1801 % |
1805 % |
1802 % Download / Upload |
1806 % Download / Upload |
1803 % Expedited / Normal |
1807 % Expedited / Normal |
1804 % Segmentung |
1808 % Segmenting |
1805 % Sdo Info Services |
1809 % Sdo Info Services |
1806 % |
1810 % |
1807 |
1811 |
1808 \ldots |
1812 \ldots |
1809 |
1813 |
1914 % rights |
1918 % rights |
1915 |
1919 |
1916 %------------------------------------------------------------------------------ |
1920 %------------------------------------------------------------------------------ |
1917 |
1921 |
1918 \subsection{Setting Alias Addresses} |
1922 \subsection{Setting Alias Addresses} |
1923 \label{sec:alias} % FIXME |
|
1919 |
1924 |
1920 \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias} |
1925 \lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias} |
1921 |
1926 |
1922 %------------------------------------------------------------------------------ |
1927 %------------------------------------------------------------------------------ |
1923 |
1928 |
2067 |
2072 |
2068 The EtherCAT master init script conforms to the requirements of the ``Linux |
2073 The EtherCAT master init script conforms to the requirements of the ``Linux |
2069 Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to |
2074 Standard Base'' (LSB\index{LSB}, \cite{lsb}). The script is installed to |
2070 \textit{etc/init.d/ethercat} below the installation prefix and has to be |
2075 \textit{etc/init.d/ethercat} below the installation prefix and has to be |
2071 copied (or better: linked) to the appropriate location (see |
2076 copied (or better: linked) to the appropriate location (see |
2072 section~\ref{sec:install}), before the master can be inserted as a service. |
2077 section~\ref{sec:installation}), before the master can be inserted as a |
2073 Please note, that the init script depends on the sysconfig file described |
2078 service. Please note, that the init script depends on the sysconfig file |
2074 below. |
2079 described below. |
2075 |
2080 |
2076 To provide service dependencies (i.~e. which services have to be started before |
2081 To provide service dependencies (i.~e. which services have to be started before |
2077 others) inside the init script code, LSB defines a special comment block. |
2082 others) inside the init script code, LSB defines a special comment block. |
2078 System tools can extract this information to insert the EtherCAT init script at |
2083 System tools can extract this information to insert the EtherCAT init script at |
2079 the correct place in the startup sequence: |
2084 the correct place in the startup sequence: |
2154 |
2159 |
2155 %------------------------------------------------------------------------------ |
2160 %------------------------------------------------------------------------------ |
2156 |
2161 |
2157 \subsection{Application Interface Profiling} |
2162 \subsection{Application Interface Profiling} |
2158 \label{sec:timing-profile} |
2163 \label{sec:timing-profile} |
2159 \index{Realtime!Profiling} |
2164 \index{Profiling} |
2165 % FIXME |
|
2160 |
2166 |
2161 One of the most important timing aspects are the execution times of the |
2167 One of the most important timing aspects are the execution times of the |
2162 realtime interface functions, that are called in cyclic context. These |
2168 application interface functions, that are called in cyclic context. These |
2163 functions make up an important part of the overall timing of the application. |
2169 functions make up an important part of the overall timing of the application. |
2164 To measure the timing of the functions, the following code was used: |
2170 To measure the timing of the functions, the following code was used: |
2165 |
2171 |
2166 \begin{lstlisting}[gobble=2,language=C] |
2172 \begin{lstlisting}[gobble=2,language=C] |
2167 c0 = get_cycles(); |
2173 c0 = get_cycles(); |
2185 \unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the |
2191 \unit{100}{\micro\second}. The measuring was repeated $n = 100$ times and the |
2186 results were averaged. These can be seen in table~\ref{tab:profile}. |
2192 results were averaged. These can be seen in table~\ref{tab:profile}. |
2187 |
2193 |
2188 \begin{table}[htpb] |
2194 \begin{table}[htpb] |
2189 \centering |
2195 \centering |
2190 \caption{Profiling of a Realtime Cycle on a \unit{2.0}{\giga\hertz} |
2196 \caption{Profiling of an Application Cycle on a \unit{2.0}{\giga\hertz} |
2191 Processor} |
2197 Processor} |
2192 \label{tab:profile} |
2198 \label{tab:profile} |
2193 \vspace{2mm} |
2199 \vspace{2mm} |
2194 \begin{tabular}{l|r|r} |
2200 \begin{tabular}{l|r|r} |
2195 Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\ |
2201 Element & Mean Duration [\second] & Standard Deviancy [\micro\second] \\ |
2254 is sent or received (polling would distort the results). The second |
2260 is sent or received (polling would distort the results). The second |
2255 reason is, that even with interrupts enabled, the time from the event |
2261 reason is, that even with interrupts enabled, the time from the event |
2256 to the notification is unknown. Therefore the only way to confidently |
2262 to the notification is unknown. Therefore the only way to confidently |
2257 determine the bus cycle time is an electrical measuring. |
2263 determine the bus cycle time is an electrical measuring. |
2258 |
2264 |
2259 Anyway, the bus cycle time is an important factor when designing realtime code, |
2265 Anyway, the bus cycle time is an important factor when designing realtime |
2260 because it limits the maximum frequency for the cyclic task of the application. |
2266 code, because it limits the maximum frequency for the cyclic task of the |
2261 In practice, these timing parameters are highly dependent on the hardware and |
2267 application. In practice, these timing parameters are highly dependent on the |
2262 often a trial and error method must be used to determine the limits of the |
2268 hardware and often a trial and error method must be used to determine the |
2263 system. |
2269 limits of the system. |
2264 |
2270 |
2265 The central question is: What happens, if the cycle frequency is too high? The |
2271 The central question is: What happens, if the cycle frequency is too high? The |
2266 answer is, that the EtherCAT frames that have been sent at the end of the cycle |
2272 answer is, that the EtherCAT frames that have been sent at the end of the cycle |
2267 are not yet received, when the next cycle starts. First this is noticed by |
2273 are not yet received, when the next cycle starts. First this is noticed by |
2268 \textit{ecrt\_domain\_process()}, because the working counter of the process |
2274 \textit{ecrt\_domain\_process()}, because the working counter of the process |
2378 |
2384 |
2379 \begin{lstlisting} |
2385 \begin{lstlisting} |
2380 $ `\textbf{make doc}` |
2386 $ `\textbf{make doc}` |
2381 \end{lstlisting} |
2387 \end{lstlisting} |
2382 |
2388 |
2383 The interface documentation can be viewed by pointing a browser to |
2389 The interface documentation can be viewed by pointing a browser to the file |
2384 \textit{doxygen-output/html/index.html}. |
2390 \textit{doxygen-output/html/index.html}. |
2385 |
2391 |
2386 \section{Installing the Software} |
2392 \section{Installing the Software} |
2387 |
2393 |
2388 The below commands have to be entered as \textit{root}: The first one will |
2394 The below commands have to be entered as \textit{root}: The first one will |
2479 |
2485 |
2480 \end{description} |
2486 \end{description} |
2481 |
2487 |
2482 %------------------------------------------------------------------------------ |
2488 %------------------------------------------------------------------------------ |
2483 |
2489 |
2484 \chapter{Application Examples} |
|
2485 \label{chapter:examples} |
|
2486 |
|
2487 This chapter will give practical examples of how to use the EtherCAT master |
|
2488 via the realtime interface by writing an application module. |
|
2489 |
|
2490 % FIXME remove examples? |
|
2491 |
|
2492 %------------------------------------------------------------------------------ |
|
2493 |
|
2494 \section{Minimal Example} |
|
2495 \label{sec:mini} |
|
2496 \index{Examples!Minimal} |
|
2497 |
|
2498 This section will explain the use of the EtherCAT master from a minimal kernel |
|
2499 module. The complete module code is obtainable as a part of the EtherCAT master |
|
2500 code release (see~\cite{etherlab}, file \textit{examples/mini/mini.c}). |
|
2501 |
|
2502 The minimal example uses a kernel timer (software interrupt) to generate a |
|
2503 cyclic task. After the timer function is executed, it re-adds itself with a |
|
2504 delay of one \textit{jiffy}\index{jiffies}, which results in a timer frequency |
|
2505 of \textit{HZ}\nomenclature{HZ}{Kernel macro containing the timer interrupt |
|
2506 frequency} |
|
2507 |
|
2508 The module-global variables, needed to operate the master can be seen |
|
2509 in listing~\ref{lst:minivar}. |
|
2510 |
|
2511 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal |
|
2512 variables},label=lst:minivar] |
|
2513 struct timer_list timer; |
|
2514 |
|
2515 ec_master_t *master = NULL; |
|
2516 ec_domain_t *domain1 = NULL; |
|
2517 |
|
2518 void *r_dig_in, *r_ana_out; |
|
2519 |
|
2520 ec_pdo_reg_t domain1_pdos[] = { |
|
2521 {"1", Beckhoff_EL1014_Inputs, &r_dig_in}, |
|
2522 {"2", Beckhoff_EL4132_Ouput1, &r_ana_out}, |
|
2523 {} |
|
2524 }; |
|
2525 \end{lstlisting} |
|
2526 |
|
2527 \begin{description} |
|
2528 \item[\linenum{1}] There is a timer object |
|
2529 declared, that is needed to tell the kernel to install a timer and |
|
2530 execute a certain function, if it runs out. This is done by a |
|
2531 variable of the \textit{timer\_list} structure. |
|
2532 \item[\linenum{3} -- \linenum{4}] There |
|
2533 is a pointer declared, that will later point to a requested EtherCAT |
|
2534 master. Additionally there is a pointer to a domain object needed, |
|
2535 that will manage process data IO. |
|
2536 \item[\linenum{6}] The pointers \textit{r\_*} |
|
2537 will later point to the \underline{r}aw process data values inside |
|
2538 the domain memory. The addresses they point to will be set during a |
|
2539 call to \textit{ec\_\-master\_\-activate()}, that will create the |
|
2540 domain memory and configure the mapped process data image. |
|
2541 \item[\linenum{8} -- \linenum{12}] The |
|
2542 configuration of the mapping of certain Pdos in a domain can easily |
|
2543 be done with the help of an initialization array of the |
|
2544 \textit{ec\_pdo\_reg\_t} type, defined as part of the realtime |
|
2545 interface. Each record must contain the ASCII bus-address of the |
|
2546 slave (see section~\ref{sec:addr}), the slave's vendor ID and |
|
2547 product code, and the index and subindex of the Pdo to map (these |
|
2548 four fields can be specified in junction, by using one of the |
|
2549 defines out of the \textit{include/ecdb.h} header). The last field |
|
2550 has to be the address of the process data pointer, so it can later |
|
2551 be redirected appropriately. Attention: The initialization array |
|
2552 must end with an empty record (\textit{\{\}})! |
|
2553 \end{description} |
|
2554 |
|
2555 The initialization of the minimal application is done by the ``Minimal init |
|
2556 function'' in listing~\ref{lst:miniinit}. |
|
2557 |
|
2558 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal init |
|
2559 function},label={lst:miniinit}] |
|
2560 int __init init_mini_module(void) |
|
2561 { |
|
2562 if (!(master = ecrt_request_master(0))) { |
|
2563 goto out_return; |
|
2564 } |
|
2565 |
|
2566 if (!(domain1 = ecrt_master_create_domain(master))) { |
|
2567 goto out_release_master; |
|
2568 } |
|
2569 |
|
2570 if (ecrt_domain_register_pdo_list(domain1, |
|
2571 domain1_pdos)) { |
|
2572 goto out_release_master; |
|
2573 } |
|
2574 |
|
2575 if (ecrt_master_activate(master)) { |
|
2576 goto out_release_master; |
|
2577 } |
|
2578 |
|
2579 ecrt_master_prepare(master); |
|
2580 |
|
2581 init_timer(&timer); |
|
2582 timer.function = run; |
|
2583 timer.expires = jiffies + 10; |
|
2584 add_timer(&timer); |
|
2585 |
|
2586 return 0; |
|
2587 |
|
2588 out_release_master: |
|
2589 ecrt_release_master(master); |
|
2590 out_return: |
|
2591 return -1; |
|
2592 } |
|
2593 \end{lstlisting} |
|
2594 |
|
2595 \begin{description} |
|
2596 \item[\linenum{3}] It is tried to request the |
|
2597 first EtherCAT master (index 0). On success, the |
|
2598 \textit{ecrt\_\-request\_\-master()} function returns a pointer to |
|
2599 the reserved master, that can be used as an object to following |
|
2600 functions calls. On failure, the function returns \textit{NULL}. |
|
2601 \item[\linenum{7}] In order to exchange process |
|
2602 data, a domain object has to be created. The |
|
2603 \textit{ecrt\_\-master\_\-create\_domain()} function also returns a |
|
2604 pointer to the created domain, or \textit{NULL} in error case. |
|
2605 \item[\linenum{11}] The registration of domain |
|
2606 Pdos with an initialization array results in a single function call. |
|
2607 Alternatively the data fields could be registered with individual |
|
2608 calls of \textit{ecrt\_domain\_register\_pdo()}. |
|
2609 \item[\linenum{16}] After the configuration of |
|
2610 process data mapping, the master can be activated for cyclic |
|
2611 operation. This will configure all slaves and bring them into |
|
2612 OP state. |
|
2613 \item[\linenum{20}] This call is needed to avoid |
|
2614 a case differentiation in cyclic operation: The first operation in |
|
2615 cyclic mode is a receive call. Due to the fact, that there is |
|
2616 nothing to receive during the first cycle, there had to be an |
|
2617 \textit{if}-statement to avoid a warning. A call to |
|
2618 \textit{ec\_master\_prepare()} sends a first datagram containing a |
|
2619 process data exchange datagram, so that the first receive call will |
|
2620 not fail. |
|
2621 \item[\linenum{22} -- \linenum{25}] The |
|
2622 master is now ready for cyclic operation. The kernel timer that |
|
2623 cyclically executes the \textit{run()} function is initialized and |
|
2624 started. |
|
2625 \end{description} |
|
2626 |
|
2627 The coding of a cleanup function fo the minimal module can be seen in |
|
2628 listing~\ref{lst:miniclean}. |
|
2629 |
|
2630 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cleanup |
|
2631 function},label={lst:miniclean}] |
|
2632 void __exit cleanup_mini_module(void) |
|
2633 { |
|
2634 del_timer_sync(&timer); |
|
2635 ecrt_master_deactivate(master); |
|
2636 ecrt_release_master(master); |
|
2637 } |
|
2638 \end{lstlisting} |
|
2639 |
|
2640 \begin{description} |
|
2641 \item[\linenum{3}] To cleanup the module, it it |
|
2642 necessary to stop the cyclic processing. This is done by a call to |
|
2643 \textit{del\_timer\_sync()} which safely removes a queued timer |
|
2644 object. It is assured, that no cyclic work will be done after this |
|
2645 call returns. |
|
2646 \item[\linenum{4}] This call deactivates the |
|
2647 master, which results in all slaves being brought to their INIT |
|
2648 state again. |
|
2649 \item[\linenum{5}] This call releases the master, |
|
2650 removes any existing configuration and silently starts the idle |
|
2651 mode. The value of the master pointer is invalid after this call and |
|
2652 the module can be safely unloaded. |
|
2653 \end{description} |
|
2654 |
|
2655 The final part of the minimal module is that for the cyclic work. Its |
|
2656 coding can be seen in listing~\ref{lst:minirun}. |
|
2657 |
|
2658 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Minimal cyclic |
|
2659 function},label={lst:minirun}] |
|
2660 void run(unsigned long data) |
|
2661 { |
|
2662 static uint8_t dig_in_0; |
|
2663 |
|
2664 ecrt_master_receive(master); |
|
2665 ecrt_domain_process(domain1); |
|
2666 |
|
2667 dig_in_0 = EC_READ_BIT(r_dig_in, 0); |
|
2668 EC_WRITE_S16(r_ana_out, dig_in_0 * 0x3FFF); |
|
2669 |
|
2670 ecrt_master_run(master); |
|
2671 ecrt_master_send(master); |
|
2672 |
|
2673 timer.expires += 1; // frequency = HZ |
|
2674 add_timer(&timer); |
|
2675 } |
|
2676 \end{lstlisting} |
|
2677 |
|
2678 \begin{description} |
|
2679 |
|
2680 \item[\linenum{5}] The cyclic processing starts with receiving datagrams, that |
|
2681 were sent in the last cycle. The frames containing these datagrams have to be |
|
2682 received by the network interface card prior to this call. |
|
2683 |
|
2684 \item[\linenum{6}] The process data of domain 1 has been automatically copied |
|
2685 into domain memory while datagram reception. This call checks the working |
|
2686 counter for changes and re-queues the domain's datagram for sending. |
|
2687 |
|
2688 \item[\linenum{8}] This is an example for reading out a bit-oriented process |
|
2689 data value (i.~e. bit 0) via the \textit{EC\_READ\_BIT()} macro. See |
|
2690 section~\ref{sec:macros} for more information about those macros. |
|
2691 |
|
2692 \item[\linenum{9}] This line shows how to write a signed, 16-bit process data |
|
2693 value. In this case, the slave is able to output voltages of |
|
2694 \unit{-10--+10}{\volt} with a resolution of \unit{16}{bit}. This write command |
|
2695 outputs either \unit{0}{\volt} or \unit{+5}{\volt}, depending of the value of |
|
2696 \textit{dig\_in\_0}. |
|
2697 |
|
2698 \item[\linenum{11}] This call runs the master's operation state machine (see |
|
2699 section~\ref{sec:fsm-op}). A single state is processed, and datagrams are |
|
2700 queued. Mainly bus observation is done: The bus state is determined and in case |
|
2701 of slaves that lost their configuration, reconfiguration is tried. |
|
2702 |
|
2703 \item[\linenum{12}] This method sends all queued datagrams, in this case the |
|
2704 domain's datagram and one of the master state machine. In best case, all |
|
2705 datagrams fit into one frame. |
|
2706 |
|
2707 \item[\linenum{14} -- \linenum{15}] Kernel timers are implemented as |
|
2708 ``one-shot'' timers, so they have to be re-added after each execution. The time |
|
2709 of the next execution is specified in \textit{jiffies} and will happen at the |
|
2710 time of the next system timer interrupt. This results in the \textit{run()} |
|
2711 function being executed with a frequency of \textit{HZ}. |
|
2712 |
|
2713 \end{description} |
|
2714 |
|
2715 %------------------------------------------------------------------------------ |
|
2716 |
|
2717 \section{RTAI Example} |
|
2718 \label{sec:rtai} |
|
2719 \index{Examples!RTAI} |
|
2720 |
|
2721 The whole code can be seen in the EtherCAT master code release |
|
2722 (see~\cite{etherlab}, file \textit{examples/rtai/rtai\_sample.c}). |
|
2723 |
|
2724 Listing~\ref{lst:rtaivar} shows the defines and global variables |
|
2725 needed for a minimal RTAI module with EtherCAT processing. |
|
2726 |
|
2727 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI task |
|
2728 declaration},label={lst:rtaivar}] |
|
2729 #define FREQUENCY 10000 |
|
2730 #define TIMERTICKS (1000000000 / FREQUENCY) |
|
2731 |
|
2732 RT_TASK task; |
|
2733 \end{lstlisting} |
|
2734 |
|
2735 \begin{description} |
|
2736 \item[\linenum{1} -- \linenum{2}] RTAI |
|
2737 takes the cycle period as nanoseconds, so the easiest way is to |
|
2738 define a frequency and convert it to a cycle time in nanoseconds. |
|
2739 \item[\linenum{4}] The \textit{task} variable |
|
2740 later contains information about the running RTAI task. |
|
2741 \end{description} |
|
2742 |
|
2743 Listing~\ref{lst:rtaiinit} shows the module init function for the RTAI |
|
2744 module. Most lines are the same as in listing~\ref{lst:miniinit}, |
|
2745 differences come up when starting the cyclic code. |
|
2746 |
|
2747 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module init |
|
2748 function},label={lst:rtaiinit}] |
|
2749 int __init init_mod(void) |
|
2750 { |
|
2751 RTIME requested_ticks, tick_period, now; |
|
2752 |
|
2753 if (!(master = ecrt_request_master(0))) { |
|
2754 goto out_return; |
|
2755 } |
|
2756 |
|
2757 if (!(domain1 = ecrt_master_create_domain(master))) { |
|
2758 goto out_release_master; |
|
2759 } |
|
2760 |
|
2761 if (ecrt_domain_register_pdo_list(domain1, |
|
2762 domain1_pdos)) { |
|
2763 goto out_release_master; |
|
2764 } |
|
2765 |
|
2766 if (ecrt_master_activate(master)) { |
|
2767 goto out_release_master; |
|
2768 } |
|
2769 |
|
2770 ecrt_master_prepare(master); |
|
2771 |
|
2772 requested_ticks = nano2count(TIMERTICKS); |
|
2773 tick_period = start_rt_timer(requested_ticks); |
|
2774 |
|
2775 if (rt_task_init(&task, run, 0, 2000, 0, 1, NULL)) { |
|
2776 goto out_stop_timer; |
|
2777 } |
|
2778 |
|
2779 now = rt_get_time(); |
|
2780 if (rt_task_make_periodic(&task, now + tick_period, |
|
2781 tick_period)) { |
|
2782 goto out_stop_task; |
|
2783 } |
|
2784 |
|
2785 return 0; |
|
2786 |
|
2787 out_stop_task: |
|
2788 rt_task_delete(&task); |
|
2789 out_stop_timer: |
|
2790 stop_rt_timer(); |
|
2791 out_deactivate: |
|
2792 ecrt_master_deactivate(master); |
|
2793 out_release_master: |
|
2794 ecrt_release_master(master); |
|
2795 out_return: |
|
2796 return -1; |
|
2797 } |
|
2798 \end{lstlisting} |
|
2799 |
|
2800 \begin{description} |
|
2801 \item[\linenum{24} -- \linenum{25}] The |
|
2802 nanoseconds are converted to RTAI timer ticks and an RTAI timer is |
|
2803 started. \textit{tick\_period} will be the ``real'' number of ticks |
|
2804 used for the timer period (which can be different to the requested |
|
2805 one). |
|
2806 \item[\linenum{27}] The RTAI task is initialized |
|
2807 by specifying the cyclic function, the parameter to hand over, the |
|
2808 stack size, priority, a flag that tells, if the function will use |
|
2809 floating point operations and a signal handler. |
|
2810 \item[\linenum{32}] The task is made periodic by |
|
2811 specifying a start time and a period. |
|
2812 \end{description} |
|
2813 |
|
2814 The cleanup function of the RTAI module in listing~\ref{lst:rtaiclean} |
|
2815 is nearly as simple as that of the minimal module. |
|
2816 |
|
2817 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module |
|
2818 cleanup function},label={lst:rtaiclean}] |
|
2819 void __exit cleanup_mod(void) |
|
2820 { |
|
2821 rt_task_delete(&task); |
|
2822 stop_rt_timer(); |
|
2823 ecrt_master_deactivate(master); |
|
2824 ecrt_release_master(master); |
|
2825 rt_sem_delete(&master_sem); |
|
2826 } |
|
2827 \end{lstlisting} |
|
2828 |
|
2829 \begin{description} |
|
2830 \item[\linenum{2}] The RTAI task will be stopped |
|
2831 and deleted. |
|
2832 \item[\linenum{3}] After that, the RTAI timer can |
|
2833 be stopped. |
|
2834 \end{description} |
|
2835 |
|
2836 The rest is the same as for the minimal module. |
|
2837 |
|
2838 Worth to mention is, that the cyclic function of the RTAI module |
|
2839 (listing~\ref{lst:rtairun}) has a slightly different architecture. The |
|
2840 function is not executed until returning for every cycle, but has an |
|
2841 infinite loop in it, that is placed in a waiting state for the rest of |
|
2842 each cycle. |
|
2843 |
|
2844 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module cyclic |
|
2845 function},label={lst:rtairun}] |
|
2846 void run(long data) |
|
2847 { |
|
2848 while (1) { |
|
2849 ecrt_master_receive(master); |
|
2850 ecrt_domain_process(domain1); |
|
2851 |
|
2852 k_pos = EC_READ_U32(r_ssi_input); |
|
2853 |
|
2854 ecrt_master_run(master); |
|
2855 ecrt_master_send(master); |
|
2856 |
|
2857 rt_task_wait_period(); |
|
2858 } |
|
2859 } |
|
2860 \end{lstlisting} |
|
2861 |
|
2862 \begin{description} |
|
2863 \item[\linenum{3}] The \textit{while (1)} loop |
|
2864 executes for the lifetime of the RTAI task. |
|
2865 \item[\linenum{12}] The |
|
2866 \textit{rt\_task\_wait\_period()} function sets the process into a |
|
2867 sleeping state until the beginning of the next cycle. It also |
|
2868 checks, if the cyclic function has to be terminated. |
|
2869 \end{description} |
|
2870 |
|
2871 %------------------------------------------------------------------------------ |
|
2872 |
|
2873 \section{Concurrency Example} |
|
2874 \label{sec:concurrency} |
|
2875 \index{Examples!Concurrency} |
|
2876 |
|
2877 As mentioned before, there can be concurrent access to the EtherCAT master. The |
|
2878 application and a EoE\index{EoE} process can compete for master access, for |
|
2879 example. In this case, the module has to provide the locking mechanism, because |
|
2880 it depends on the module's architecture which lock has to be used. The module |
|
2881 makes this locking mechanism available to the master through the master's |
|
2882 locking callbacks. |
|
2883 |
|
2884 In case of RTAI, the lock can be an RTAI semaphore, as shown in |
|
2885 listing~\ref{lst:convar}. A normal Linux semaphore would not be appropriate, |
|
2886 because it could not block the RTAI task due to RTAI running in a higher domain |
|
2887 than the Linux kernel (see~\cite{rtai}). |
|
2888 |
|
2889 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI semaphore for |
|
2890 concurrent access},label={lst:convar}] |
|
2891 SEM master_sem; |
|
2892 \end{lstlisting} |
|
2893 |
|
2894 The module has to implement the two callbacks for requesting and |
|
2895 releasing the master lock. An exemplary coding can be seen in |
|
2896 listing~\ref{lst:conlock}. |
|
2897 |
|
2898 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI locking |
|
2899 callbacks for concurrent access},label={lst:conlock}] |
|
2900 int request_lock(void *data) |
|
2901 { |
|
2902 rt_sem_wait(&master_sem); |
|
2903 return 0; |
|
2904 } |
|
2905 |
|
2906 void release_lock(void *data) |
|
2907 { |
|
2908 rt_sem_signal(&master_sem); |
|
2909 } |
|
2910 \end{lstlisting} |
|
2911 |
|
2912 \begin{description} |
|
2913 \item[\linenum{1}] The \textit{request\_lock()} |
|
2914 function has a data parameter. The master always passes the value, |
|
2915 that was specified when registering the callback function. This can |
|
2916 be used for handing the master pointer. Notice, that it has an |
|
2917 integer return value (see line 4). |
|
2918 \item[\linenum{3}] The call to |
|
2919 \textit{rt\_sem\_wait()} either returns at once, when the semaphore |
|
2920 was free, or blocks until the semaphore is freed again. In any case, |
|
2921 the semaphore finally is reserved for the process calling the |
|
2922 request function. |
|
2923 \item[\linenum{4}] When the lock was requested |
|
2924 successfully, the function should return 0. The module can prohibit |
|
2925 requesting the lock by returning non-zero (see paragraph ``Tuning |
|
2926 the jitter'' below). |
|
2927 \item[\linenum{7}] The \textit{release\_lock()} |
|
2928 function gets the same argument passed, but has a void return value, |
|
2929 because is always succeeds. |
|
2930 \item[\linenum{9}] The \textit{rt\_sem\_signal()} |
|
2931 function frees the semaphore, that was prior reserved with |
|
2932 \textit{rt\_sem\_wait()}. |
|
2933 \end{description} |
|
2934 |
|
2935 In the module's init function, the semaphore must be initialized, and |
|
2936 the callbacks must be passed to the EtherCAT master: |
|
2937 |
|
2938 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Module init |
|
2939 function for concurrent access},label={lst:coninit}] |
|
2940 int __init init_mod(void) |
|
2941 { |
|
2942 RTIME tick_period, requested_ticks, now; |
|
2943 |
|
2944 rt_sem_init(&master_sem, 1); |
|
2945 |
|
2946 if (!(master = ecrt_request_master(0))) { |
|
2947 goto out_return; |
|
2948 } |
|
2949 |
|
2950 ecrt_master_callbacks(master, request_lock, |
|
2951 release_lock, NULL); |
|
2952 // ... |
|
2953 \end{lstlisting} |
|
2954 |
|
2955 \begin{description} |
|
2956 \item[\linenum{5}] The call to |
|
2957 \textit{rt\_sem\_init()} initializes the semaphore and sets its |
|
2958 value to 1, meaning that only one process can reserve the semaphore |
|
2959 without blocking. |
|
2960 \item[\linenum{11}] The callbacks are passed to |
|
2961 the master with a call to \textit{ecrt\_master\_callbacks()}. The |
|
2962 last parameter is the argument, that the master should pass with |
|
2963 each call to a callback function. Here it is not used and set to |
|
2964 \textit{NULL}. |
|
2965 \end{description} |
|
2966 |
|
2967 For the cyclic function being only one competitor for master access, |
|
2968 it has to request the lock like any other process. There is no need to |
|
2969 use the callbacks (which are meant for processes of lower priority), |
|
2970 so it can access the semaphore directly: |
|
2971 |
|
2972 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI cyclic |
|
2973 function for concurrent access},label={lst:conrun}] |
|
2974 void run(long data) |
|
2975 { |
|
2976 while (1) { |
|
2977 rt_sem_wait(&master_sem); |
|
2978 |
|
2979 ecrt_master_receive(master); |
|
2980 ecrt_domain_process(domain1); |
|
2981 |
|
2982 k_pos = EC_READ_U32(r_ssi_input); |
|
2983 |
|
2984 ecrt_master_run(master); |
|
2985 ecrt_master_send(master); |
|
2986 |
|
2987 rt_sem_signal(&master_sem); |
|
2988 rt_task_wait_period(); |
|
2989 } |
|
2990 } |
|
2991 \end{lstlisting} |
|
2992 |
|
2993 \begin{description} |
|
2994 |
|
2995 \item[\linenum{4}] Every access to the master has to be preceded by a call to |
|
2996 \textit{rt\_sem\_wait()}, because another instance might currently access the |
|
2997 master. |
|
2998 |
|
2999 \item[\linenum{14}] When cyclic processing finished, the semaphore has to be |
|
3000 freed again, so that other processes have the possibility to access the master. |
|
3001 |
|
3002 \end{description} |
|
3003 |
|
3004 A little change has to be made to the cleanup function in case of |
|
3005 concurrent master access. |
|
3006 |
|
3007 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={RTAI module |
|
3008 cleanup function for concurrent access},label={lst:conclean}] |
|
3009 void __exit cleanup_mod(void) |
|
3010 { |
|
3011 rt_task_delete(&task); |
|
3012 stop_rt_timer(); |
|
3013 ecrt_master_deactivate(master); |
|
3014 ecrt_release_master(master); |
|
3015 rt_sem_delete(&master_sem); |
|
3016 } |
|
3017 \end{lstlisting} |
|
3018 |
|
3019 \begin{description} |
|
3020 \item[\linenum{7}] Upon module cleanup, the |
|
3021 semaphore has to be deleted, so that memory can be freed. |
|
3022 \end{description} |
|
3023 |
|
3024 \paragraph{Tuning the Jitter} |
|
3025 \index{Jitter} |
|
3026 |
|
3027 Concurrent access leads to higher jitter for the application task, because |
|
3028 there are situations, in which the task has to wait for a process of lower |
|
3029 priority to finish accessing the master. In most cases this is acceptable, |
|
3030 because a master access cycle (receive/process/send) only takes |
|
3031 \unit{10-20}{\micro\second} on recent systems, what would be the maximum |
|
3032 additional jitter. However some applications demand a minimum jitter. For this |
|
3033 reason the master access can be prohibited by the application: If the time, |
|
3034 another process wants to access the master, is to close to the beginning of the |
|
3035 next application cycle, the module can disallow, that the lock is taken. In |
|
3036 this case, the request callback has to return $1$, meaning that the lock has |
|
3037 not been taken. The foreign process must abort its master access and try again |
|
3038 next time. |
|
3039 |
|
3040 This measure helps to significantly reducing the jitter produced by concurrent |
|
3041 master access. Below are excerpts of an example coding: |
|
3042 |
|
3043 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Variables for |
|
3044 jitter reduction},label={lst:redvar}] |
|
3045 #define FREQUENCY 10000 // RTAI task frequency in Hz |
|
3046 // ... |
|
3047 cycles_t t_last_cycle = 0; |
|
3048 const cycles_t t_critical = cpu_khz * 1000 / FREQUENCY |
|
3049 - cpu_khz * 30 / 1000; |
|
3050 \end{lstlisting} |
|
3051 |
|
3052 \begin{description} |
|
3053 |
|
3054 \item[\linenum{3}] The variable \textit{t\_last\_cycle} holds the timer ticks |
|
3055 at the beginning of the last realtime cycle. |
|
3056 |
|
3057 \item[\linenum{4}] \textit{t\_critical} contains the number of ticks, that may |
|
3058 have passed since the beginning of the last cycle, until there is no more |
|
3059 foreign access possible. It is calculated by subtracting the ticks for |
|
3060 \unit{30}{\micro\second} from the ticks for a complete cycle. |
|
3061 |
|
3062 \end{description} |
|
3063 |
|
3064 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Cyclic function |
|
3065 with reduced jitter},label={lst:redrun}] |
|
3066 void run(long data) |
|
3067 { |
|
3068 while (1) { |
|
3069 t_last_cycle = get_cycles(); |
|
3070 rt_sem_wait(&master_sem); |
|
3071 // ... |
|
3072 \end{lstlisting} |
|
3073 |
|
3074 \begin{description} |
|
3075 \item[\linenum{4}] The ticks of the beginning of |
|
3076 the current realtime cycle are taken before reserving the semaphore. |
|
3077 \end{description} |
|
3078 |
|
3079 \begin{lstlisting}[gobble=2,language=C,numbers=left,caption={Request callback |
|
3080 for reduced jitter},label={lst:redreq}] |
|
3081 int request_lock(void *data) |
|
3082 { |
|
3083 // too close to the next RT cycle: deny access. |
|
3084 if (get_cycles() - t_last_cycle > t_critical) |
|
3085 return -1; |
|
3086 |
|
3087 // allow access |
|
3088 rt_sem_wait(&master_sem); |
|
3089 return 0; |
|
3090 } |
|
3091 \end{lstlisting} |
|
3092 |
|
3093 \begin{description} |
|
3094 |
|
3095 \item[\linenum{4}] If the time of request is too close to the next realtime |
|
3096 cycle (here: \unit{<30}{\micro\second} before the estimated beginning), the |
|
3097 locking is denied. The requesting process must abort its cycle. |
|
3098 |
|
3099 \end{description} |
|
3100 |
|
3101 %------------------------------------------------------------------------------ |
|
3102 |
|
3103 \begin{thebibliography}{99} |
2490 \begin{thebibliography}{99} |
3104 |
2491 |
3105 \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit |
2492 \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit |
3106 for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT |
2493 for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT |
3107 technology. \url{http://etherlab.org/en}, 2008. |
2494 technology. \url{http://etherlab.org/en}, 2008. |