# HG changeset patch # User Florian Pose # Date 1224663454 0 # Node ID 9ce46c40a023edf92ad39940fc34f98e2b1fb9df # Parent 68e7534d28559c32abc7913d5f706a6f6bf6639c Userspace applications. diff -r 68e7534d2855 -r 9ce46c40a023 documentation/ethercat_doc.tex --- a/documentation/ethercat_doc.tex Tue Oct 21 14:37:50 2008 +0000 +++ b/documentation/ethercat_doc.tex Wed Oct 22 08:17:34 2008 +0000 @@ -327,39 +327,41 @@ \begin{figure}[htbp] \centering \includegraphics[width=.9\textwidth]{images/architecture} - \caption{Master architecture} + \caption{Master Architecture} \label{fig:arch} \end{figure} -\paragraph{Master Module} -\index{Master module} - -Kernel module containing one or more EtherCAT master instances (see -sec.~\ref{sec:mastermod}), the ``Device Interface'' (see sec.~\ref{sec:ecdev}) -and the ``Application Interface'' (see chap.~\ref{chap:api}). - -\paragraph{Device Modules} -\index{Device modules} - -EtherCAT-capable Ethernet device driver modules\index{Device modules}, that -offer their devices to the EtherCAT master via the device interface (see -sec.~\ref{sec:ecdev}). These modified network drivers can handle network -devices used for EtherCAT operation and ``normal'' Ethernet devices in -parallel. A master can accept a certain device and then is able to send and -receive EtherCAT frames. Ethernet devices declined by the master module are -connected to the kernel's network stack as usual. - -\paragraph{Application Modules} -\index{Application module} - -Kernel modules, that use the EtherCAT master (usually for cyclic exchange of -process data with EtherCAT slaves). These modules are not part of the EtherCAT -master code\footnote{Although there are some examples provided in the -\textit{examples/} directory.}, but have to be generated or written by the -user. An application module can ``request'' a master through the application -interface (see chap.~\ref{chap:api}). If this succeeds, the module has the -control over the master: It can provide a bus configuration and exchange -process data. +The components of the master environment are described below: + +\begin{description} + +\item[Master Module]\index{Master Module} Kernel module containing one or more +EtherCAT master instances (see sec.~\ref{sec:mastermod}), the ``Device +Interface'' (see sec.~\ref{sec:ecdev}) and the ``Application Interface'' (see +chap.~\ref{chap:api}). + +\item[Device Modules]\index{Device modules} EtherCAT-capable Ethernet device +driver modules\index{Device modules}, that offer their devices to the EtherCAT +master via the device interface (see sec.~\ref{sec:ecdev}). These modified +network drivers can handle network devices used for EtherCAT operation and +``normal'' Ethernet devices in parallel. A master can accept a certain device +and then is able to send and receive EtherCAT frames. Ethernet devices +declined by the master module are connected to the kernel's network stack as +usual. + +\item[Application]\index{Application} A program that uses the EtherCAT master +(usually for cyclic exchange of process data with EtherCAT slaves). These +programs are not part of the EtherCAT master code\footnote{Although there are +some examples provided in the \textit{examples/} directory.}, but have to be +generated or written by the user. An application can ``request'' a master +through the application interface (see chap.~\ref{chap:api}). If this +succeeds, it has the control over the master: It can provide a bus +configuration and exchange process data. Applications can be kernel modules +(that use the kernel application interface directly) or userspace programs, +that use the application interface via the EtherCAT library (see +sec.~\ref{sec:userlib}). + +\end{description} %------------------------------------------------------------------------------ @@ -374,6 +376,7 @@ \caption{Master phases and transitions} \label{fig:phases} \end{figure} + \begin{description} \item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the @@ -590,7 +593,10 @@ sec.~\ref{sec:masterconfig}). \item[Operation] Cyclic code is run, process data is exchanged (see -sec.~\ref{sec:cyclic}). +sec.~\ref{sec:cyclic}). To enter operation mode, the master has to be +``activated'' to calculate the process data image and apply the bus +configuration for the first time. After activation, the application is in +charge to send and receive frames. \end{description} @@ -636,14 +642,15 @@ semaphores, or other methods to protect critical sections. The master itself can not provide locking mechanisms, because it has no chance -to know the appropriate kind of lock. For example if the application uses RTAI -functionality, ordinary kernel semaphores would not be sufficient. For that, an -important design decision was made: The application that reserved a master must -have the total control, therefore it has to take responsibility for providing -the appropriate locking mechanisms. If another instance wants to access the -master, it has to request the master lock by callbacks, that have to be set by -the application. Moreover the application can deny access to the master if it -considers it to be awkward at the moment. +to know the appropriate kind of lock. For example if the application is in +kernelspace and uses RTAI functionality, ordinary kernel semaphores would not +be sufficient. For that, an important design decision was made: The +application that reserved a master must have the total control, therefore it +has to take responsibility for providing the appropriate locking mechanisms. +If another instance wants to access the master, it has to request the master +lock by callbacks, that have to be set by the application. Moreover the +application can deny access to the master if it considers it to be awkward at +the moment. \begin{figure}[htbp] \centering diff -r 68e7534d2855 -r 9ce46c40a023 documentation/images/architecture.fig --- a/documentation/images/architecture.fig Tue Oct 21 14:37:50 2008 +0000 +++ b/documentation/images/architecture.fig Wed Oct 22 08:17:34 2008 +0000 @@ -71,29 +71,29 @@ 4 1 0 50 -1 16 10 0.0000 4 120 465 5445 5760 Device\001 4 1 0 50 -1 16 10 0.0000 4 120 615 5445 5925 Interface\001 -6 -6 3908 4310 4463 5319 -5 1 0 1 0 7 50 -1 -1 0.000 0 0 0 0 3958.125 4815.000 3915 4320 4455 4815 3915 5310 -4 1 0 50 -1 16 10 4.7124 4 150 765 4162 4822 Application\001 -4 1 0 50 -1 16 10 4.7124 4 120 615 3997 4822 Interface\001 +6 3870 4275 4500 5355 +5 1 0 1 0 7 50 -1 20 0.000 0 0 0 0 3958.125 4815.000 3915 4320 4455 4815 3915 5310 +4 1 0 49 -1 16 10 4.7124 4 150 765 4162 4822 Application\001 +4 1 0 49 -1 16 10 4.7124 4 120 615 3997 4822 Interface\001 -6 -6 4538 2648 5813 3293 -5 1 0 1 0 7 50 -1 -1 0.000 0 0 0 0 5175.000 2655.000 5805 2655 5175 3285 4545 2655 -4 1 0 50 -1 16 12 0.0000 4 135 600 5175 3105 Device\001 -4 1 0 50 -1 16 12 0.0000 4 135 825 5175 2880 Character\001 +6 5205 2648 6480 3293 +5 1 0 1 0 7 50 -1 -1 0.000 0 0 0 0 5842.000 2655.000 6472 2655 5842 3285 5212 2655 +4 1 0 50 -1 16 12 0.0000 4 135 600 5842 3105 Device\001 +4 1 0 50 -1 16 12 0.0000 4 135 825 5842 2880 Character\001 -6 -6 1575 2430 7785 2925 -2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 - 7785 2655 1575 2655 -4 0 0 50 -1 16 12 0.0000 4 180 1110 1665 2880 Kernel space\001 -4 0 0 50 -1 16 12 0.0000 4 180 945 1665 2565 User space\001 +6 3870 945 4500 2025 +5 1 0 1 0 7 49 -1 -1 0.000 0 0 0 0 3958.125 1485.000 3915 990 4455 1485 3915 1980 +4 1 0 48 -1 16 10 4.7124 4 150 765 4162 1492 Application\001 +4 1 0 48 -1 16 10 4.7124 4 120 615 3997 1492 Interface\001 -6 -6 4673 1298 5677 2302 -1 4 0 1 0 7 50 -1 -1 4.000 1 0.0000 5175 1800 495 495 5670 2295 4680 1305 -4 1 0 50 -1 16 12 0.0000 4 135 360 5175 2025 Tool\001 -4 1 0 50 -1 16 12 0.0000 4 135 765 5175 1755 'ethercat'\001 +6 2160 855 3420 2115 +1 3 0 1 0 7 50 -1 20 0.000 1 0.0000 2790 1485 585 585 2790 1485 3375 1485 +4 1 0 49 -1 16 12 0.0000 4 180 945 2790 1665 Application\001 +4 1 0 49 -1 16 12 0.0000 4 180 885 2790 1440 Userspace\001 -6 +1 4 0 1 0 7 50 -1 -1 0.000 1 0.0000 2484 4871 459 459 2025 4860 2944 4882 1 2 0 1 0 7 50 -1 -1 0.000 1 0.0000 5445 4815 810 495 4635 4320 6255 5310 -1 4 0 1 0 7 50 -1 -1 0.000 1 0.0000 2484 4871 459 459 2025 4860 2944 4882 +1 4 0 1 0 7 50 -1 -1 4.000 1 0.0000 7058 1658 495 495 7553 2153 6563 1163 2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 5445 7965 5445 7425 2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 @@ -114,8 +114,6 @@ 6255 6885 7335 6885 7335 7425 6255 7425 6255 6885 2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 5445 5490 5445 5310 -2 4 0 1 0 7 50 -1 -1 0.000 0 0 8 0 0 5 - 6435 5985 6435 3645 3915 3645 3915 5985 6435 5985 2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 4635 4815 4455 4815 2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 @@ -126,24 +124,35 @@ 1575 7785 7785 7785 2 4 0 1 0 7 50 -1 -1 0.000 0 0 9 0 0 5 1755 5985 1755 3645 3465 3645 3465 5985 1755 5985 -2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 - 5175 3285 5175 3645 2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 7785 8280 7785 2205 -2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 - 5175 2655 5175 2295 2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 1575 8280 1575 2205 +2 4 0 1 0 7 50 -1 -1 0.000 0 0 8 0 0 5 + 6435 5985 6435 3645 3915 3645 3915 5985 6435 5985 +2 1 1 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 + 7785 2655 1575 2655 +2 1 0 1 0 7 50 -1 -1 4.000 0 0 -1 0 0 2 + 5850 3285 5850 3645 +2 1 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 2 + 3915 1485 3375 1485 +2 4 0 1 0 7 50 -1 20 0.000 0 0 7 0 0 5 + 5040 2250 3915 2250 3915 720 5040 720 5040 2250 3 2 0 1 0 7 50 -1 -1 0.000 0 0 0 3 5580 8910 5355 9045 4770 9090 0.000 -1.000 0.000 3 2 0 1 0 7 50 -1 -1 0.000 0 0 0 3 6931 8910 6390 9270 4770 9450 0.000 -1.000 0.000 +3 2 0 1 0 7 50 -1 -1 0.000 0 0 0 3 + 6570 1665 6120 1890 5985 2655 + 0.000 -1.000 0.000 +3 2 0 1 0 7 50 -1 -1 0.000 0 0 0 3 + 5040 1485 5580 1800 5715 2655 + 0.000 -1.000 0.000 4 1 0 50 -1 16 10 0.0000 4 150 750 5445 7200 net_device\001 4 1 0 50 -1 16 10 0.0000 4 150 750 6795 7200 net_device\001 -4 2 0 50 -1 12 10 0.0000 4 135 810 5355 6210 ecdev_*()\001 -4 2 0 50 -1 12 10 0.0000 4 135 810 7110 6210 netif_*()\001 +4 2 0 50 -1 12 10 0.0000 4 105 810 5355 6210 ecdev_*()\001 4 1 0 50 -1 16 12 0.0000 4 135 1545 6345 6570 EtherCAT Network\001 4 1 0 50 -1 16 12 0.0000 4 135 1200 6345 6750 Driver Module\001 4 0 0 50 -1 16 12 0.0000 4 135 2130 4005 3870 EtherCAT Master Module\001 @@ -153,8 +162,15 @@ 4 2 0 50 -1 16 12 0.0000 4 135 315 4995 8100 NIC\001 4 2 0 50 -1 16 12 0.0000 4 135 315 6345 8100 NIC\001 4 0 0 50 -1 16 12 0.0000 4 135 810 1665 8010 Hardware\001 -4 2 0 50 -1 12 10 4.7124 4 135 720 3645 4725 ecrt_*()\001 +4 2 0 50 -1 12 10 4.7124 4 105 720 3645 4725 ecrt_*()\001 4 0 0 50 -1 16 12 0.0000 4 180 945 1845 3870 Application\001 4 0 0 50 -1 16 12 0.0000 4 135 630 1845 4095 Module\001 -4 1 0 50 -1 16 12 0.0000 4 135 675 5445 4860 Master0\001 4 1 0 50 -1 16 12 0.0000 4 135 390 2475 4950 Task\001 +4 0 0 50 -1 16 12 0.0000 4 180 1050 1665 2880 Kernelspace\001 +4 0 0 50 -1 16 12 0.0000 4 180 885 1665 2565 Userspace\001 +4 1 0 50 -1 16 12 4.7124 4 135 870 4635 1530 libethercat\001 +4 2 0 50 -1 12 10 4.7124 4 105 720 3645 1395 ecrt_*()\001 +4 2 0 50 -1 12 10 0.0000 4 105 810 7155 6210 netif_*()\001 +4 1 0 50 -1 16 12 0.0000 4 135 735 5445 4905 Master 0\001 +4 1 0 50 -1 16 12 0.0000 4 135 360 7065 1845 Tool\001 +4 1 0 50 -1 16 12 0.0000 4 135 765 7065 1620 'ethercat'\001