604 |
604 |
605 \chapter{Application Interface} |
605 \chapter{Application Interface} |
606 \label{sec:ecrt} |
606 \label{sec:ecrt} |
607 \index{Application interface} |
607 \index{Application interface} |
608 |
608 |
609 %------------------------------------------------------------------------------ |
609 The application interface provides functions and data structures for |
610 |
610 applications to access and use an EtherCAT master. The complete documentation |
611 \section{The Realtime Interface} % FIXME move information to ecrt.h, reference |
611 of the interface is included as Doxygen~\cite{doxygen} comments in the header |
612 \label{sec:ecrt} |
612 file \textit{include/ecrt.h}. You can either directly view the file comments |
613 \index{Realtime interface} |
613 or generate an HTML documentation as described in section~\ref{sec:gendoc}. |
614 |
614 |
615 The realtime interface provides functions and data structures for applications |
615 The following sections cover a general description of the application |
616 to access and use an EtherCAT master. |
616 interface. |
617 |
617 |
618 % \paragraph{Master Phases} |
618 Every application should use the master in two steps: |
619 % |
619 |
620 % Every application should use the master in three phases: |
620 \begin{description} |
621 % |
621 |
622 % \begin{enumerate} |
622 \item[Configuration] The master is requested and the configuration is applied. |
623 % \item \textit{Startup} - The master is requested and the bus is |
623 Domains are created Slaves are configured and Pdo entries are registered (see |
624 % validated. Domains are created and Pdos are registered. Slave |
624 section~\ref{sec:masterconfig}). |
625 % configurations are applied. |
625 |
626 % \item \textit{Operation} - Cyclic code is run, process data is |
626 \item[Operation] Cyclic code is run, process data is exchanged (see |
627 % exchanged and the master state machine is executed. |
627 section~\ref{sec:cyclic}). |
628 % \item \textit{Shutdown} - Cyclic code is stopped and the master |
628 |
629 % is released. |
629 \end{description} |
630 % \end{enumerate} |
630 |
631 |
631 %------------------------------------------------------------------------------ |
632 \subsubsection{Master Requesting and Releasing} |
632 |
633 |
633 \section{Master Configuration} |
634 Before an application can access an EtherCAT master provided by the |
634 \label{sec:masterconfig} |
635 master module, it has to reserve one for exclusive use. After use, it |
635 |
636 has to release the requested master and make it available for other |
636 \ldots |
637 modules. This is done with the following functions: |
637 |
638 |
638 \begin{figure}[htbp] |
639 \begin{lstlisting}[gobble=2,language=C] |
639 \centering |
640 ec_master_t *ecrt_request_master(unsigned int master_index); |
640 \includegraphics[width=.8\textwidth]{images/app-config} |
641 void ecrt_release_master(ec_master_t *master); |
641 \caption{Master configuration structures} |
642 \end{lstlisting} |
642 \label{fig:app-config} |
643 |
643 \end{figure} |
644 The \textit{ecrt\_request\_master()} function has to be the first function a |
644 |
645 module has to call, when using EtherCAT. The function takes the index of the |
645 %------------------------------------------------------------------------------ |
646 master as its argument. The first master has index 0, the $n$th master has |
646 |
647 index $n - 1$. The number of existent masters has to be specified when loading |
647 \section{Cyclic Operation} |
648 the master module (see section~\ref{sec:mastermod}). The function tries to |
648 \label{sec:cyclic} |
649 reserve the specified master and scans for slaves. It returns a pointer to the |
649 |
650 reserved master object upon success, or \textit{NULL} if an error occurred. |
650 \ldots |
651 |
651 % FIXME PDOS endianess |
652 The \textit{ecrt\_release\_master()} function releases a reserved |
652 |
653 master after use. It takes the pointer to the master object returned |
653 |
654 by \textit{ecrt\_request\_master()} as its argument and can never |
654 %------------------------------------------------------------------------------ |
655 fail. |
655 |
656 |
656 \section{Concurrent Master Access} % FIXME |
657 \subsubsection{Master Methods} |
|
658 \label{sec:ecrt-master} |
|
659 |
|
660 \paragraph{Domain Creation} |
|
661 |
|
662 For process data exchange, at least one process data domain is needed |
|
663 (see section~\ref{sec:processdata}). |
|
664 |
|
665 \begin{lstlisting}[gobble=2,language=C] |
|
666 ec_domain_t *ecrt_master_create_domain(ec_master_t *master); |
|
667 \end{lstlisting} |
|
668 |
|
669 The \textit{ecrt\_master\_create\_domain()} method creates a new |
|
670 process data domain and returns a pointer to the new domain object. |
|
671 This object can be used for registering process data objects and |
|
672 exchange process data in cyclic operation. On failure, the function |
|
673 returns \textit{NULL}. |
|
674 |
|
675 \paragraph{Slave Handlers} |
|
676 |
|
677 To access a certain slave, there is a method to get a slave handler: |
|
678 |
|
679 \begin{lstlisting}[gobble=2,language=C] |
|
680 ec_slave_t *ecrt_master_get_slave(const ec_master_t *, |
|
681 const char *); |
|
682 \end{lstlisting} |
|
683 |
|
684 The \textit{ecrt\_master\_get\_slave()} method returns a pointer to a |
|
685 certain slave object, specified by its ASCII address (see |
|
686 section~\ref{sec:addr}). If the address is invalid, \textit{NULL} is |
|
687 returned. |
|
688 |
|
689 \paragraph{Master Activation} |
|
690 |
|
691 When all domains are created, and all process data objects are |
|
692 registered, the master can be activated: |
|
693 |
|
694 \begin{lstlisting}[gobble=2,language=C] |
|
695 int ecrt_master_activate(ec_master_t *master); |
|
696 void ecrt_master_deactivate(ec_master_t *master); |
|
697 \end{lstlisting} |
|
698 |
|
699 By calling the \textit{ecrt\_master\_activate()} method, all slaves |
|
700 are configured according to the prior method calls and are brought |
|
701 into OP state. In this case, the method has a return value of 0. |
|
702 Otherwise (wrong configuration or bus failure) the method returns |
|
703 non-zero. |
|
704 |
|
705 The \textit{ecrt\_master\_deactivate()} method is the counterpart to |
|
706 the activate call: It brings all slaves back into INIT state again. |
|
707 This method should be called prior to |
|
708 \textit{ecrt\_\-master\_\-release()}. |
|
709 |
|
710 \paragraph{Locking Callbacks} |
|
711 |
|
712 For concurrent master access, the application has to provide a locking |
|
713 mechanism (see section~\ref{sec:concurr}): |
|
714 |
|
715 \begin{lstlisting}[gobble=2,language=C] |
|
716 void ecrt_master_callbacks(ec_master_t *master, |
|
717 int (*request_cb)(void *), |
|
718 void (*release_cb)(void *), |
|
719 void *cb_data); |
|
720 \end{lstlisting} |
|
721 |
|
722 The ``request lock'' and ``release lock'' callbacks can be set with |
|
723 the \textit{ecrt\_master\_call\-backs()} method. It takes two function |
|
724 pointers and a data value as additional arguments. The arbitrary data |
|
725 value will be passed as argument on every callback. Asynchronous |
|
726 master access (like EoE processing) is only possible if these |
|
727 callbacks have been set. |
|
728 |
|
729 \paragraph{Preparation of Cyclic Data Exchange} |
|
730 |
|
731 Cyclic operation mostly consists of the three steps input, processing and |
|
732 output. In EtherCAT terms this would mean: Receive datagrams, evaluate process |
|
733 data and send datagrams. The first cycle differs from this principle, because |
|
734 no datagrams have been sent yet, so there is nothing to receive. To avoid |
|
735 having a case differentiation (in terms of an \textit{if} clause), the |
|
736 following method exists: |
|
737 |
|
738 \begin{lstlisting}[gobble=2,language=C] |
|
739 void ecrt_master_prepare(ec_master_t *master); |
|
740 \end{lstlisting} |
|
741 |
|
742 As a last thing before cyclic operation, a call to the |
|
743 \textit{ecrt\_master\_prepare()} method should be issued. It makes all |
|
744 process data domains queue their datagrams and issues a send command, |
|
745 so that the first receive call in cyclic operation will not fail. |
|
746 |
|
747 \paragraph{Frame Sending and Receiving} |
|
748 |
|
749 To send all queued datagrams and to later receive the sent datagrams |
|
750 there are two methods: |
|
751 |
|
752 \begin{lstlisting}[gobble=2,language=C] |
|
753 void ecrt_master_send(ec_master_t *master); |
|
754 void ecrt_master_receive(ec_master_t *master); |
|
755 \end{lstlisting} |
|
756 |
|
757 The \textit{ecrt\_master\_send()} method takes all datagrams, that |
|
758 have been queued for transmission, packs them into frames, and passes |
|
759 them to the network device for sending. |
|
760 |
|
761 The \textit{ecrt\_master\_receive()} queries the network device for |
|
762 received frames (by calling the ISR\index{ISR}), extracts received |
|
763 datagrams and dispatches the results to the datagram objects in the |
|
764 queue. Received datagrams, and the ones that timed out, will be |
|
765 marked, and then dequeued. |
|
766 |
|
767 \paragraph{Running the Operation State Machine} |
|
768 |
|
769 The master's operation state machine (see section~\ref{sec:fsm-op}) |
|
770 monitors the bus in cyclic operation and reconfigures slaves, if |
|
771 necessary. Therefore, the following method should be called |
|
772 cyclically: |
|
773 |
|
774 \begin{lstlisting}[gobble=2,language=C] |
|
775 void ecrt_master_run(ec_master_t *master); |
|
776 \end{lstlisting} |
|
777 |
|
778 The \textit{ecrt\_master\_run()} method executes the master's |
|
779 operation state machine step by step. It returns after processing one |
|
780 state and queuing a datagram. Calling this function is not mandatory, |
|
781 but highly recommended. |
|
782 |
|
783 \paragraph{Master Monitoring} |
|
784 |
|
785 It is also highly recommended to evaluate the master's error state. In |
|
786 this way it is possible to notice lost network links, failed bus |
|
787 segments, and other issues: |
|
788 |
|
789 \begin{lstlisting}[gobble=2,language=C] |
|
790 int ecrt_master_state(const ec_master_t *master); |
|
791 \end{lstlisting} |
|
792 |
|
793 The \textit{ecrt\_master\_state()} method returns the master's error |
|
794 state. The following states are defined as part of the realtime |
|
795 interface: |
|
796 |
|
797 \begin{description} |
|
798 \item[EC\_MASTER\_OK] means, that no error has occurred. |
|
799 \item[EC\_MASTER\_LINK\_ERROR] means, that the network link is |
|
800 currently down. |
|
801 \item[EC\_MASTER\_BUS\_ERROR] means, that one or more slaves do not |
|
802 respond. |
|
803 \end{description} |
|
804 |
|
805 \subsubsection{Domain Methods} |
|
806 \label{sec:ecrt-domain} |
|
807 |
|
808 \paragraph{Pdo Registration} |
|
809 |
|
810 To access data of a slave's Pdo in cyclic operation, it is necessary |
|
811 to make it part of a process data domain: |
|
812 |
|
813 \begin{lstlisting}[gobble=2,language=C] |
|
814 ec_slave_t *ecrt_domain_register_pdo(ec_domain_t *domain, |
|
815 const char *address, |
|
816 uint32_t vendor_id, |
|
817 uint32_t product_code, |
|
818 const char *pdo_name |
|
819 void **data_ptr); |
|
820 int ecrt_domain_register_pdo_list(ec_domain_t *domain, |
|
821 const ec_pdo_reg_t *pdos); |
|
822 \end{lstlisting} |
|
823 |
|
824 The \textit{ecrt\_domain\_register\_pdo()} method registers a certain |
|
825 Pdo as part of the domain and takes the address of the process data |
|
826 pointer. This pointer will be set on master activation and then can be |
|
827 parameter to the \textit{EC\_READ\_*} and \textit{EC\_WRITE\_*} macros |
|
828 described below. |
|
829 |
|
830 A perhaps easier way to register multiple Pdos at the same time is to |
|
831 fill an array of \textit{ec\_pdo\_reg\_t} and hand it to the |
|
832 \textit{ecrt\_domain\_register\_pdo\_list()} method. Attention: This |
|
833 array has to be terminated by an empty structure (\textit{\{\}})! |
|
834 |
|
835 \paragraph{Evaluating Domain Data} |
|
836 |
|
837 To evaluate domain data, the following method has to be used: |
|
838 |
|
839 \begin{lstlisting}[gobble=2,language=C] |
|
840 void ecrt_domain_process(ec_domain_t *domain); |
|
841 \end{lstlisting} |
|
842 |
|
843 The \textit{ecrt\_domain\_process()} method sets the domains state and |
|
844 re-queues its datagram for sending. |
|
845 |
|
846 \paragraph{Domain State} |
|
847 |
|
848 Similar to the master state, a domain has an own error state: |
|
849 |
|
850 \begin{lstlisting}[gobble=2,language=C] |
|
851 int ecrt_domain_state(const ec_domain_t *domain); |
|
852 \end{lstlisting} |
|
853 |
|
854 The \textit{ecrt\_domain\_state()} method returns the domain's error state. It |
|
855 is non-zero if \textbf{not} all process data values could be exchanged, and |
|
856 zero otherwise. |
|
857 |
|
858 \subsubsection{Slave Methods} |
|
859 \label{sec:ecrt-slave} |
|
860 |
|
861 \paragraph{Sdo Configuration} |
|
862 |
|
863 To configure slave Sdos, the function interface below can be used: |
|
864 |
|
865 \begin{lstlisting}[gobble=2,language=C] |
|
866 int ecrt_slave_conf_sdo8(ec_slave_t *slave, |
|
867 uint16_t sdo_index, |
|
868 uint8_t sdo_subindex, |
|
869 uint8_t value); |
|
870 int ecrt_slave_conf_sdo16(ec_slave_t *slave, |
|
871 uint16_t sdo_index, |
|
872 uint8_t sdo_subindex, |
|
873 uint16_t value); |
|
874 int ecrt_slave_conf_sdo32(ec_slave_t *slave, |
|
875 uint16_t sdo_index, |
|
876 uint8_t sdo_subindex, |
|
877 uint32_t value); |
|
878 \end{lstlisting} |
|
879 |
|
880 The \textit{ecrt\_slave\_conf\_sdo*()} methods prepare the configuration of a |
|
881 certain Sdo. The index and subindex of the Sdo, and the value have to be |
|
882 specified. The configuration is done each time, the slave is reconfigured. The |
|
883 methods only differ in the Sdo's data type. If the configuration could be |
|
884 prepared, zero is returned. If an error occurred, non-zero is returned. |
|
885 |
|
886 \paragraph{Variable-sized Pdos} |
|
887 |
|
888 For specifying the size of variable-sized Pdos, the following method |
|
889 can be used: |
|
890 |
|
891 \begin{lstlisting}[gobble=2,language=C] |
|
892 int ecrt_slave_pdo_size(ec_slave_t *slave, |
|
893 const char *pdo_name, |
|
894 size_t size); |
|
895 \end{lstlisting} |
|
896 |
|
897 The \textit{ecrt\_slave\_pdo\_size()} method takes the name of the Pdo |
|
898 and the size. It returns zero on success, otherwise non-zero. |
|
899 |
|
900 \subsubsection{Process Data Access} |
|
901 \label{sec:macros} |
|
902 |
|
903 The endianess of the process data could differ from that of the CPU. |
|
904 Therefore, process data access has to be done by the macros below, |
|
905 that are also provided by the realtime interface: |
|
906 |
|
907 \begin{lstlisting}[gobble=2,language=C] |
|
908 #define EC_READ_BIT(DATA, POS) |
|
909 #define EC_WRITE_BIT(DATA, POS, VAL) |
|
910 |
|
911 #define EC_READ_U8(DATA) |
|
912 #define EC_READ_S8(DATA) |
|
913 #define EC_READ_U16(DATA) |
|
914 #define EC_READ_S16(DATA) |
|
915 #define EC_READ_U32(DATA) |
|
916 #define EC_READ_S32(DATA) |
|
917 |
|
918 #define EC_WRITE_U8(DATA, VAL) |
|
919 #define EC_WRITE_S8(DATA, VAL) |
|
920 #define EC_WRITE_U16(DATA, VAL) |
|
921 #define EC_WRITE_S16(DATA, VAL) |
|
922 #define EC_WRITE_U32(DATA, VAL) |
|
923 #define EC_WRITE_S32(DATA, VAL) |
|
924 \end{lstlisting} |
|
925 |
|
926 There are macros for bitwise access (\textit{EC\_READ\_BIT()}, |
|
927 \textit{EC\_WRITE\_BIT()}), and byte-wise access (\textit{EC\_READ\_*()}, |
|
928 \textit{EC\_WRITE\_*()}). The byte-wise macros carry the data type in their |
|
929 name. Example: \textit{EC\_WRITE\_S16()} writes a 16 bit signed value to |
|
930 EtherCAT data. The \textit{DATA} parameter is supposed to be a process data |
|
931 pointer, as provided at Pdo registration. |
|
932 |
|
933 The macros use the kernel's endianess conversion macros, that are |
|
934 preprocessed to empty macros in case of equal endianess. This is the |
|
935 definition for the \textit{EC\_\-READ\_\-U16()} macro: |
|
936 |
|
937 \begin{lstlisting}[gobble=2,language=C] |
|
938 #define EC_READ_U16(DATA) \ |
|
939 ((uint16_t) le16_to_cpup((void *) (DATA))) |
|
940 \end{lstlisting} |
|
941 |
|
942 The \textit{le16\_to\_cpup()} macro converts a little-endian, 16 bit |
|
943 value to the CPU's architecture and takes a pointer to the input value |
|
944 as its argument. If the CPU's architecture is little-endian, too (for |
|
945 example on X86 and compatible), nothing has to be converted. In this |
|
946 case, the macro is replaced with an empty macro by the preprocessor |
|
947 and so there is no unneeded function call or case differentiation in |
|
948 the code. |
|
949 |
|
950 For keeping it portable, it is highly recommended to make use of these |
|
951 macros. |
|
952 |
|
953 %------------------------------------------------------------------------------ |
|
954 |
|
955 \subsection{Slave Addressing} |
|
956 \label{sec:addr} |
|
957 \index{Slave!Addressing} |
|
958 |
|
959 The master offers the several slave addressing schemes (for Pdo |
|
960 registration or configuration) via the realtime interface. For this |
|
961 reason, slave addresses are ASCII\nomenclature{ASCII}{American |
|
962 Standard Code for Information Interchange}-coded and passed as a |
|
963 string. The addressing schemes are independent of the EtherCAT |
|
964 protocol and represent an additional feature of the master. |
|
965 |
|
966 Below, the allowed addressing schemes are described. The descriptions |
|
967 are followed by a regular expression formally defining the addressing |
|
968 scheme, and one or more examples. |
|
969 |
|
970 \begin{description} |
|
971 |
|
972 \item[Position Addressing] This is the normal addressing scheme, where each |
|
973 slave is addressed by its ring position. The first slave has address 0, and the |
|
974 $n$th slave has address $n - 1$. This addressing scheme is useful for small |
|
975 buses that have a fixed number of slaves. |
|
976 |
|
977 RegEx: \texttt{[0-9]+} --- Example: \texttt{"42"} |
|
978 |
|
979 \item[Advanced Position Addressing] Bus couplers segment the bus into |
|
980 (physical) blocks. Though the logical ring positions keep being the same, it is |
|
981 easier to address a slave with its block number and the relative position |
|
982 inside the block. This addressing is done by passing the (zero-based) index of |
|
983 the bus coupler (not the coupler's ring position), followed by a colon and the |
|
984 relative position of the actual slave starting at the bus coupler. |
|
985 |
|
986 RegEx: \texttt{[0-9]+:[0-9]+} --- Examples: \texttt{"0:42"}, \texttt{"2:7"} |
|
987 |
|
988 \item[Alias Addressing] Each slave can have a ``secondary slave address'' or |
|
989 ``alias address''\footnote{Information about how to set the alias can be found |
|
990 in section~\ref{sec:eepromaccess}} stored in its E$^2$PROM. The alias is |
|
991 evaluated by the master and can be used to address the slave, which is useful |
|
992 when a clearly defined slave has to be addressed and the ring position is not |
|
993 known or can change over time. This scheme is used by starting the address |
|
994 string with a mesh (\#) followed by the alias address. The latter can also be |
|
995 provided as hexadecimal value, prefixed with \textit{0x}. |
|
996 |
|
997 RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+)} --- Examples: \texttt{"\#6622"}, |
|
998 \texttt{"\#0xBEEF"} |
|
999 |
|
1000 \item[Advanced Alias Addressing] This is a mixture of the ``Alias Addressing'' |
|
1001 and ``Advanced Position Addressing'' schemes. A certain slave is addressed by |
|
1002 specifying its relative position after an aliased slave. This is very useful, |
|
1003 if a complete block of slaves can vary its position in the bus. The bus coupler |
|
1004 preceding the block should get an alias. The block slaves can then be addressed |
|
1005 by specifying this alias and their position inside the block. This scheme is |
|
1006 used by starting the address string with a mesh (\#) followed by the alias |
|
1007 address (which can be hexadecimal), then a colon and the relative position of |
|
1008 the slave to address. |
|
1009 |
|
1010 RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+):[0-9]+} --- Examples: |
|
1011 \texttt{"\#0xBEEF:7"}, \texttt{"\#6:2"} |
|
1012 |
|
1013 \end{description} |
|
1014 |
|
1015 In anticipation of section~\ref{sec:ecrt}, the functions accepting |
|
1016 these address strings are \textit{ecrt\_\-master\_\-get\_slave()}, |
|
1017 \textit{ecrt\_domain\_register\_pdo()} and |
|
1018 \textit{ecrt\_domain\_register\_pdo\_list()} (the latter through the |
|
1019 \textit{ec\_pdo\_reg\_t} structure). |
|
1020 |
|
1021 %------------------------------------------------------------------------------ |
|
1022 |
|
1023 \subsection{Concurrent Master Access} |
|
1024 \label{sec:concurr} |
657 \label{sec:concurr} |
1025 \index{Concurrency} |
658 \index{Concurrency} |
1026 |
659 |
1027 In some cases, one master is used by several instances, for example when an |
660 In some cases, one master is used by several instances, for example when an |
1028 application does cyclic process data exchange, and there are EoE-capable slaves |
661 application does cyclic process data exchange, and there are EoE-capable slaves |