documentation/ethercat_doc.tex
changeset 1297 129a7224e010
parent 1296 69582b88e8fd
child 1298 de91d633ff6c
equal deleted inserted replaced
1296:69582b88e8fd 1297:129a7224e010
   396 
   396 
   397 \end{description}
   397 \end{description}
   398 
   398 
   399 %------------------------------------------------------------------------------
   399 %------------------------------------------------------------------------------
   400 
   400 
   401 \section{General Behavior} % FIXME
   401 \section{General Behavior}
   402 \index{Master behavior}
   402 \index{Master behavior}
   403 
   403 
   404 \ldots
   404 \ldots
   405 
   405 
   406 %   Behavior (Scanning) TODO
   406 % TODO Behavior (Scanning)
   407 
   407 
   408 %------------------------------------------------------------------------------
   408 %------------------------------------------------------------------------------
   409 
   409 
   410 \section{Master Module}
   410 \section{Master Module}
   411 \label{sec:mastermod}
   411 \label{sec:mastermod}
   559 
   559 
   560 \chapter{Application Interface}
   560 \chapter{Application Interface}
   561 \label{chap:api}
   561 \label{chap:api}
   562 \index{Application interface}
   562 \index{Application interface}
   563 
   563 
   564 %   Interface version
   564 % TODO
   565 %   Master Requesting and Releasing
   565 %
   566 %   Master Locking
   566 % Interface version
   567 %   Configuring Pdo assignment and mapping
   567 % Master Requesting and Releasing
   568 %   Domains (memory)
   568 % Master Locking
   569 %   Pdo entry registration
   569 % Configuring Pdo assignment and mapping
   570 %   Sdo configuration
   570 % Domains (memory)
   571 %   Sdo access
   571 % Pdo entry registration
   572 %   VoE handlers
   572 % Sdo configuration
       
   573 % Sdo access
       
   574 % VoE handlers
   573 
   575 
   574 The application interface provides functions and data structures for
   576 The application interface provides functions and data structures for
   575 applications to access an EtherCAT master. The complete documentation of the
   577 applications to access an EtherCAT master. The complete documentation of the
   576 interface is included as Doxygen~\cite{doxygen} comments in the header file
   578 interface is included as Doxygen~\cite{doxygen} comments in the header file
   577 \textit{include/ecrt.h}. It can either be read directly from the file
   579 \textit{include/ecrt.h}. It can either be read directly from the file
   699 To enter cyclic operation mode, the master has to be ``activated'' to
   701 To enter cyclic operation mode, the master has to be ``activated'' to
   700 calculate the process data image and apply the bus configuration for the first
   702 calculate the process data image and apply the bus configuration for the first
   701 time. After activation, the application is in charge to send and receive
   703 time. After activation, the application is in charge to send and receive
   702 frames.
   704 frames.
   703 
   705 
   704 % TODO PDOS endianess
   706 % TODO
   705 % TODO Datagram injection
   707 %
       
   708 % PDO endianess
       
   709 % Datagram injection
   706 
   710 
   707 %------------------------------------------------------------------------------
   711 %------------------------------------------------------------------------------
   708 
   712 
   709 \section{Concurrent Master Access}
   713 \section{Concurrent Master Access}
   710 \label{sec:concurr}
   714 \label{sec:concurr}
   826 
   830 
   827 \item[\usebox\boxopen] This function is called when network communication has
   831 \item[\usebox\boxopen] This function is called when network communication has
   828 to be started, for example after a command \lstinline+ip link set ethX up+
   832 to be started, for example after a command \lstinline+ip link set ethX up+
   829 from userspace. Frame reception has to be enabled by the driver.
   833 from userspace. Frame reception has to be enabled by the driver.
   830 
   834 
   831 \item[\usebox\boxstop] The purpose of this callback is to ``close'' the device,
   835 \item[\usebox\boxstop] The purpose of this callback is to ``close'' the
   832 i.~e.  make the hardware stop receiving frames.
   836 device, i.~e. make the hardware stop receiving frames.
   833 
   837 
   834 \item[\usebox\boxxmit] This function is called for each frame that has to be
   838 \item[\usebox\boxxmit] This function is called for each frame that has to be
   835 transmitted. The network stack passes the frame as a pointer to an
   839 transmitted. The network stack passes the frame as a pointer to an
   836 \lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
   840 \lstinline+sk_buff+ structure (``socket buffer''\index{Socket buffer}, see
   837 below), which has to be freed after sending.
   841 below), which has to be freed after sending.
  1882 \index{CoE}
  1886 \index{CoE}
  1883 
  1887 
  1884 The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
  1888 The CANopen-over-EtherCAT protocol \cite[sec.~5.6]{alspec} is used to
  1885 configure slaves and exchange data objects on application level.
  1889 configure slaves and exchange data objects on application level.
  1886 
  1890 
  1887 % FIXME
  1891 % TODO
  1888 %
  1892 %
  1889 % Download / Upload
  1893 % Download / Upload
  1890 % Expedited / Normal
  1894 % Expedited / Normal
  1891 % Segmenting
  1895 % Segmenting
  1892 % Sdo Info Services
  1896 % Sdo Info Services
  2013 %------------------------------------------------------------------------------
  2017 %------------------------------------------------------------------------------
  2014 
  2018 
  2015 \section{Command-line Tool}
  2019 \section{Command-line Tool}
  2016 \label{sec:tool}
  2020 \label{sec:tool}
  2017 
  2021 
  2018 % --master
  2022 % TODO --master
  2019 
  2023 
  2020 \subsection{Character Devices}
  2024 \subsection{Character Devices}
  2021 \label{sec:cdev}
  2025 \label{sec:cdev}
  2022 
  2026 
  2023 Each master instance will get a character device as a userspace interface.
  2027 Each master instance will get a character device as a userspace interface.
  2497 
  2501 
  2498 \subsection{Bus Cycle Measuring}
  2502 \subsection{Bus Cycle Measuring}
  2499 \label{sec:timing-bus}
  2503 \label{sec:timing-bus}
  2500 \index{Bus cycle}
  2504 \index{Bus cycle}
  2501 
  2505 
  2502 For measuring the time, a frame is ``on the wire'', two timestamps
  2506 For measuring the time, a frame is ``on the wire'', two timestamps must be
  2503 must be be taken:
  2507 taken:
  2504 
  2508 
  2505 \begin{enumerate}
  2509 \begin{enumerate}
  2506 \item The time, the Ethernet hardware begins with physically sending
  2510 
  2507   the frame.
  2511 \item The time, the Ethernet hardware begins with physically sending the
  2508 \item The time, the frame is completely received by the Ethernet
  2512 frame.
  2509   hardware.
  2513 
       
  2514 \item The time, the frame is completely received by the Ethernet hardware.
       
  2515 
  2510 \end{enumerate}
  2516 \end{enumerate}
  2511 
  2517 
  2512 Both times are difficult to determine. The first reason is, that the
  2518 Both times are difficult to determine. The first reason is, that the
  2513 interrupts are disabled and the master is not notified, when a frame
  2519 interrupts are disabled and the master is not notified, when a frame is sent
  2514 is sent or received (polling would distort the results). The second
  2520 or received (polling would distort the results). The second reason is, that
  2515 reason is, that even with interrupts enabled, the time from the event
  2521 even with interrupts enabled, the time from the event to the notification is
  2516 to the notification is unknown. Therefore the only way to confidently
  2522 unknown. Therefore the only way to confidently determine the bus cycle time is
  2517 determine the bus cycle time is an electrical measuring.
  2523 an electrical measuring.
  2518 
  2524 
  2519 Anyway, the bus cycle time is an important factor when designing realtime
  2525 Anyway, the bus cycle time is an important factor when designing realtime
  2520 code, because it limits the maximum frequency for the cyclic task of the
  2526 code, because it limits the maximum frequency for the cyclic task of the
  2521 application.  In practice, these timing parameters are highly dependent on the
  2527 application.  In practice, these timing parameters are highly dependent on the
  2522 hardware and often a trial and error method must be used to determine the
  2528 hardware and often a trial and error method must be used to determine the
  2523 limits of the system.
  2529 limits of the system.
  2524 
  2530 
  2525 The central question is: What happens, if the cycle frequency is too high? The
  2531 The central question is: What happens, if the cycle frequency is too high? The
  2526 answer is, that the EtherCAT frames that have been sent at the end of the cycle
  2532 answer is, that the EtherCAT frames that have been sent at the end of the
  2527 are not yet received, when the next cycle starts.  First this is noticed by
  2533 cycle are not yet received, when the next cycle starts.  First this is noticed
  2528 \textit{ecrt\_domain\_process()}, because the working counter of the process
  2534 by \textit{ecrt\_domain\_process()}, because the working counter of the
  2529 data datagrams were not increased. The function will notify the user via
  2535 process data datagrams were not increased. The function will notify the user
  2530 Syslog\footnote{To limit Syslog output, a mechanism has been implemented, that
  2536 via Syslog\footnote{To limit Syslog output, a mechanism has been implemented,
  2531 outputs a summarized notification at maximum once a second.}. In this case, the
  2537 that outputs a summarized notification at maximum once a second.}. In this
  2532 process data keeps being the same as in the last cycle, because it is not
  2538 case, the process data keeps being the same as in the last cycle, because it
  2533 erased by the domain. When the domain datagrams are queued again, the master
  2539 is not erased by the domain. When the domain datagrams are queued again, the
  2534 notices, that they are already queued (and marked as sent). The master will
  2540 master notices, that they are already queued (and marked as sent). The master
  2535 mark them as unsent again and output a warning, that datagrams were
  2541 will mark them as unsent again and output a warning, that datagrams were
  2536 ``skipped''.
  2542 ``skipped''.
  2537 
  2543 
  2538 On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
  2544 On the mentioned \unit{2.0}{\giga\hertz} system, the possible cycle frequency
  2539 can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
  2545 can be up to \unit{25}{\kilo\hertz} without skipped frames. This value can
  2540 surely be increased by choosing faster hardware. Especially the RealTek network
  2546 surely be increased by choosing faster hardware. Especially the RealTek
  2541 hardware could be replaced by a faster one. Besides, implementing a dedicated
  2547 network hardware could be replaced by a faster one. Besides, implementing a
  2542 ISR for EtherCAT devices would also contribute to increasing the latency. These
  2548 dedicated ISR for EtherCAT devices would also contribute to increasing the
  2543 are two points on the author's to-do list.
  2549 latency. These are two points on the author's to-do list.
  2544 
  2550 
  2545 %------------------------------------------------------------------------------
  2551 %------------------------------------------------------------------------------
  2546 
  2552 
  2547 \chapter{Installation}
  2553 \chapter{Installation}
  2548 \label{sec:installation}
  2554 \label{sec:installation}
  2683 to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
  2689 to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
  2684 Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
  2690 Ethernet device to use (or \lstinline+ff:ff:ff:ff:ff:ff+ to use the first
  2685 device offered) and selecting the driver(s) to load via the
  2691 device offered) and selecting the driver(s) to load via the
  2686 \lstinline+DEVICE_MODULES+ variable.
  2692 \lstinline+DEVICE_MODULES+ variable.
  2687 
  2693 
  2688 After the basic configuration is done, the master can be started with
  2694 After the basic configuration is done, the master can be started with the
  2689 the below command:
  2695 below command:
  2690 
  2696 
  2691 \begin{lstlisting}
  2697 \begin{lstlisting}
  2692 # `\textbf{/etc/init.d/ethercat start}`
  2698 # `\textbf{/etc/init.d/ethercat start}`
  2693 \end{lstlisting}
  2699 \end{lstlisting}
  2694 
  2700