36 * |
36 * |
37 * EtherCAT interface for realtime applications. This interface is designed |
37 * EtherCAT interface for realtime applications. This interface is designed |
38 * for realtime modules that want to use EtherCAT. There are functions to |
38 * for realtime modules that want to use EtherCAT. There are functions to |
39 * request a master, to map process data, to communicate with slaves via CoE |
39 * request a master, to map process data, to communicate with slaves via CoE |
40 * and to configure and activate the bus. |
40 * and to configure and activate the bus. |
|
41 * |
|
42 * Changed since 1.5: |
|
43 * |
|
44 * - Added redundancy_active flag to ec_domain_state_t. |
|
45 * - Added ecrt_master_link_state() method and ec_master_link_state_t to query |
|
46 * the state of a redundant link. |
|
47 * - Added the EC_HAVE_REDUNDANCY define, to check, if the interface contains |
|
48 * redundancy features. |
41 * |
49 * |
42 * Changes in version 1.5: |
50 * Changes in version 1.5: |
43 * |
51 * |
44 * - Added the distributed clocks feature and the respective method |
52 * - Added the distributed clocks feature and the respective method |
45 * ecrt_slave_config_dc() to configure a slave for cyclic operation, and |
53 * ecrt_slave_config_dc() to configure a slave for cyclic operation, and |
117 |
125 |
118 /** EtherCAT realtime interface version word. |
126 /** EtherCAT realtime interface version word. |
119 */ |
127 */ |
120 #define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR) |
128 #define ECRT_VERSION_MAGIC ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR) |
121 |
129 |
|
130 /****************************************************************************** |
|
131 * Feature flags |
|
132 *****************************************************************************/ |
|
133 |
|
134 /** Defined, if the redundancy features are available. |
|
135 * |
|
136 * I. e. if the \a redundancy_active flag in ec_domain_state_t and the |
|
137 * ecrt_master_link_state() method are available. |
|
138 */ |
|
139 #define EC_HAVE_REDUNDANCY |
|
140 |
122 /*****************************************************************************/ |
141 /*****************************************************************************/ |
123 |
142 |
124 /** End of list marker. |
143 /** End of list marker. |
125 * |
144 * |
126 * This can be used with ecrt_slave_config_pdos(). |
145 * This can be used with ecrt_slave_config_pdos(). |
177 * This is used for the output parameter of ecrt_master_state(). |
196 * This is used for the output parameter of ecrt_master_state(). |
178 * |
197 * |
179 * \see ecrt_master_state(). |
198 * \see ecrt_master_state(). |
180 */ |
199 */ |
181 typedef struct { |
200 typedef struct { |
182 unsigned int slaves_responding; /**< Number of slaves in the bus. */ |
201 unsigned int slaves_responding; /**< Sum of responding slaves on all |
|
202 Ethernet devices. */ |
183 unsigned int al_states : 4; /**< Application-layer states of all slaves. |
203 unsigned int al_states : 4; /**< Application-layer states of all slaves. |
184 The states are coded in the lower 4 bits. |
204 The states are coded in the lower 4 bits. |
185 If a bit is set, it means that at least one |
205 If a bit is set, it means that at least one |
186 slave in the bus is in the corresponding |
206 slave in the bus is in the corresponding |
187 state: |
207 state: |
188 - Bit 0: \a INIT |
208 - Bit 0: \a INIT |
189 - Bit 1: \a PREOP |
209 - Bit 1: \a PREOP |
190 - Bit 2: \a SAFEOP |
210 - Bit 2: \a SAFEOP |
191 - Bit 3: \a OP */ |
211 - Bit 3: \a OP */ |
192 unsigned int link_up : 1; /**< \a true, if the network link is up. */ |
212 unsigned int link_up : 1; /**< \a true, if at least one Ethernet link is |
|
213 up. */ |
193 } ec_master_state_t; |
214 } ec_master_state_t; |
|
215 |
|
216 /*****************************************************************************/ |
|
217 |
|
218 /** Redundant link state. |
|
219 * |
|
220 * This is used for the output parameter of ecrt_master_link_state(). |
|
221 * |
|
222 * \see ecrt_master_link_state(). |
|
223 */ |
|
224 typedef struct { |
|
225 unsigned int slaves_responding; /**< Sum of responding slaves on the given |
|
226 link. */ |
|
227 unsigned int al_states : 4; /**< Application-layer states of the slaves on |
|
228 the given link. The states are coded in the |
|
229 lower 4 bits. If a bit is set, it means |
|
230 that at least one slave in the bus is in the |
|
231 corresponding state: |
|
232 - Bit 0: \a INIT |
|
233 - Bit 1: \a PREOP |
|
234 - Bit 2: \a SAFEOP |
|
235 - Bit 3: \a OP */ |
|
236 unsigned int link_up : 1; /**< \a true, if the given Ethernet link is up. |
|
237 */ |
|
238 } ec_master_link_state_t; |
194 |
239 |
195 /*****************************************************************************/ |
240 /*****************************************************************************/ |
196 |
241 |
197 /** Slave configuration state. |
242 /** Slave configuration state. |
198 * |
243 * |
302 * This is used for the output parameter of ecrt_domain_state(). |
347 * This is used for the output parameter of ecrt_domain_state(). |
303 */ |
348 */ |
304 typedef struct { |
349 typedef struct { |
305 unsigned int working_counter; /**< Value of the last working counter. */ |
350 unsigned int working_counter; /**< Value of the last working counter. */ |
306 ec_wc_state_t wc_state; /**< Working counter interpretation. */ |
351 ec_wc_state_t wc_state; /**< Working counter interpretation. */ |
|
352 unsigned int redundancy_active; /**< Redundant link is in use. */ |
307 } ec_domain_state_t; |
353 } ec_domain_state_t; |
308 |
354 |
309 /*****************************************************************************/ |
355 /*****************************************************************************/ |
310 |
356 |
311 /** Direction type for PDO assignment functions. |
357 /** Direction type for PDO assignment functions. |
846 ); |
892 ); |
847 |
893 |
848 /** Reads the current master state. |
894 /** Reads the current master state. |
849 * |
895 * |
850 * Stores the master state information in the given \a state structure. |
896 * Stores the master state information in the given \a state structure. |
|
897 * |
|
898 * This method returns a global state. For the link-specific states in a |
|
899 * redundant bus topology, use the ecrt_master_link_state() method. |
851 */ |
900 */ |
852 void ecrt_master_state( |
901 void ecrt_master_state( |
853 const ec_master_t *master, /**< EtherCAT master. */ |
902 const ec_master_t *master, /**< EtherCAT master. */ |
854 ec_master_state_t *state /**< Structure to store the information. */ |
903 ec_master_state_t *state /**< Structure to store the information. */ |
|
904 ); |
|
905 |
|
906 /** Reads the current state of a redundant link. |
|
907 * |
|
908 * Stores the link state information in the given \a state structure. |
|
909 * |
|
910 * \return Zero on success, otherwise negative error code. |
|
911 */ |
|
912 int ecrt_master_link_state( |
|
913 const ec_master_t *master, /**< EtherCAT master. */ |
|
914 unsigned int dev_idx, /**< Index of the device (0 = main device, 1 = |
|
915 first backup device, ...). */ |
|
916 ec_master_link_state_t *state /**< Structure to store the information. |
|
917 */ |
855 ); |
918 ); |
856 |
919 |
857 /** Sets the application time. |
920 /** Sets the application time. |
858 * |
921 * |
859 * The master has to know the application's time when operating slaves with |
922 * The master has to know the application's time when operating slaves with |