81 *****************************************************************************/ |
119 *****************************************************************************/ |
82 |
120 |
83 struct ec_master; |
121 struct ec_master; |
84 typedef struct ec_master ec_master_t; /**< \see ec_master */ |
122 typedef struct ec_master ec_master_t; /**< \see ec_master */ |
85 |
123 |
|
124 struct ec_slave_config; |
|
125 typedef struct ec_slave_config ec_slave_config_t; /**< \see ec_slave_config */ |
|
126 |
86 struct ec_domain; |
127 struct ec_domain; |
87 typedef struct ec_domain ec_domain_t; /**< \see ec_domain */ |
128 typedef struct ec_domain ec_domain_t; /**< \see ec_domain */ |
88 |
129 |
89 struct ec_slave; |
130 /*****************************************************************************/ |
90 typedef struct ec_slave ec_slave_t; /**< \see ec_slave */ |
131 |
91 |
132 /** Bus state. |
92 /*****************************************************************************/ |
133 * |
93 |
134 * This is used in ec_master_state_t. |
94 /** Bus status. |
|
95 * This is used in ec_master_status_t. |
|
96 */ |
135 */ |
97 typedef enum { |
136 typedef enum { |
98 EC_BUS_FAILURE = -1, /**< At least one slave with process data exchange |
137 EC_BUS_FAILURE = -1, /**< At least one configured slave is offline. */ |
99 is offline. */ |
138 EC_BUS_OK /**< All configured slaves are online. */ |
100 EC_BUS_OK /**< All slaves with process data exchange are |
139 } ec_bus_state_t; |
101 online. */ |
140 |
102 } |
141 /*****************************************************************************/ |
103 ec_bus_status_t; |
142 |
104 |
143 /** Master state. |
105 /*****************************************************************************/ |
144 * |
106 |
145 * This is used for the output parameter of ecrt_master_state(). |
107 /** Master status. |
|
108 * This is used for the output parameter of ecrt_master_get_status(). |
|
109 */ |
146 */ |
110 typedef struct { |
147 typedef struct { |
111 ec_bus_status_t bus_status; /**< \see ec_bus_status_t */ |
148 ec_bus_state_t bus_state; /**< \see ec_bus_state_t */ |
112 unsigned int bus_tainted; /**< non-zero, if the bus topology is invalid */ |
149 unsigned int bus_tainted; /**< Non-zero, if the bus topology differs from |
113 unsigned int slaves_responding; /**< number of responding slaves */ |
150 the requested configuration. */ |
114 } |
151 unsigned int slaves_responding; /**< Number of slaves in the bus. */ |
115 ec_master_status_t; |
152 } ec_master_state_t; |
116 |
153 |
117 /*****************************************************************************/ |
154 /*****************************************************************************/ |
118 |
155 |
119 /** List entry for domain PDO registrations. |
156 /** Slave configuration state. |
120 * This type is used as a parameter for the ecrt_domain_register_pdo_list() |
157 * |
121 * convenience function. |
158 * \see ecrt_slave_config_state(). |
|
159 */ |
|
160 typedef struct { |
|
161 unsigned int online : 1; /**< The slave is online. */ |
|
162 unsigned int configured : 1; /**< The slave was configured according to |
|
163 the specified configuration. */ |
|
164 } ec_slave_config_state_t; |
|
165 |
|
166 /*****************************************************************************/ |
|
167 |
|
168 /** Domain working counter interpretation. |
|
169 * |
|
170 * This is used in ec_domain_state_t. |
|
171 */ |
|
172 typedef enum { |
|
173 EC_WC_ZERO = 0, /**< No Pdos were exchanged. */ |
|
174 EC_WC_INCOMPLETE, /**< Some of the registered Pdos were exchanged. */ |
|
175 EC_WC_COMPLETE /**< All registered Pdos were exchanged. */ |
|
176 } ec_wc_state_t; |
|
177 |
|
178 /*****************************************************************************/ |
|
179 |
|
180 /** Domain state. |
|
181 * |
|
182 * This is used for the output parameter of ecrt_domain_state(). |
122 */ |
183 */ |
123 typedef struct { |
184 typedef struct { |
124 const char *slave_address; /**< slave address string |
185 unsigned int working_counter; /**< Value of the last working counter. */ |
125 \see ec_master_parse_slave_address() */ |
186 ec_wc_state_t wc_state; /**< Working counter interpretation. */ |
126 uint32_t vendor_id; /**< vendor ID */ |
187 } ec_domain_state_t; |
127 uint32_t product_code; /**< product code */ |
188 |
128 uint16_t pdo_entry_index; /**< PDO entry index */ |
189 /*****************************************************************************/ |
129 uint8_t pdo_entry_subindex; /**< PDO entry subindex */ |
190 |
130 void **data_ptr; /**< address of the process data pointer */ |
191 /** Direction type for Pdo mapping functions. |
131 } |
|
132 ec_pdo_reg_t; |
|
133 |
|
134 /*****************************************************************************/ |
|
135 |
|
136 /** Direction type for PDO mapping and range registration functions. |
|
137 */ |
192 */ |
138 typedef enum { |
193 typedef enum { |
139 EC_DIR_OUTPUT, /**< values written by master */ |
194 EC_DIR_OUTPUT, /**< Values written by the master. */ |
140 EC_DIR_INPUT /**< values read by master */ |
195 EC_DIR_INPUT /**< Values read by the master. */ |
141 } |
196 } ec_direction_t; |
142 ec_direction_t; |
197 |
|
198 /*****************************************************************************/ |
|
199 |
|
200 /** Pdo entry mapping. |
|
201 * |
|
202 * \see ecrt_slave_config_mapping(). |
|
203 */ |
|
204 typedef struct { |
|
205 uint16_t index; /**< Index of the Pdo entry to add to the Pdo |
|
206 configuration. */ |
|
207 uint8_t subindex; /**< Subindex of the Pdo entry to add to the |
|
208 Pdo configuration. */ |
|
209 uint8_t bit_length; /**< Size of the Pdo entry in bit. */ |
|
210 } ec_pdo_entry_info_t; |
|
211 |
|
212 /*****************************************************************************/ |
|
213 |
|
214 /** Pdo information. |
|
215 * |
|
216 * \see ecrt_slave_config_mapping(). |
|
217 */ |
|
218 typedef struct { |
|
219 ec_direction_t dir; /**< Pdo direction (input/output). */ |
|
220 uint16_t index; /**< Index of the Pdo to map. */ |
|
221 unsigned int n_entries; /**< Number of Pdo entries for the Pdo |
|
222 configuration. Zero means, that the default Pdo |
|
223 configuration shall be used. */ |
|
224 const ec_pdo_entry_info_t entries[]; /**< Pdo configuration list. */ |
|
225 } ec_pdo_info_t; |
|
226 |
|
227 /*****************************************************************************/ |
|
228 |
|
229 /** List record type for Pdo entry mass-registration. |
|
230 * |
|
231 * This type is used for the array parameter of the |
|
232 * ecrt_domain_reg_pdo_entry_list() convenience function. |
|
233 */ |
|
234 typedef struct { |
|
235 uint16_t alias; /**< Slave alias address. */ |
|
236 uint16_t position; /**< Slave position. */ |
|
237 uint32_t vendor_id; /**< Slave vendor ID. */ |
|
238 uint32_t product_code; /**< Slave product code. */ |
|
239 uint16_t index; /**< Pdo entry index. */ |
|
240 uint8_t subindex; /**< Pdo entry subindex. */ |
|
241 uint8_t *offset; /**< Pointer to a variable to store the Pdo's |
|
242 offset in the process data. */ |
|
243 } ec_pdo_entry_reg_t; |
143 |
244 |
144 /****************************************************************************** |
245 /****************************************************************************** |
145 * Global functions |
246 * Global functions |
146 *****************************************************************************/ |
247 *****************************************************************************/ |
147 |
248 |
148 ec_master_t *ecrt_request_master(unsigned int master_index); |
249 /** Returns the version magic of the realtime interface. |
149 void ecrt_release_master(ec_master_t *master); |
250 * |
150 |
251 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. |
|
252 */ |
151 unsigned int ecrt_version_magic(void); |
253 unsigned int ecrt_version_magic(void); |
152 |
254 |
|
255 /** Requests an EtherCAT master for realtime operation. |
|
256 * |
|
257 * \return pointer to reserved master, or NULL on error |
|
258 */ |
|
259 ec_master_t *ecrt_request_master( |
|
260 unsigned int master_index /**< Index of the master to request. */ |
|
261 ); |
|
262 |
|
263 /** Releases a requested EtherCAT master. |
|
264 */ |
|
265 void ecrt_release_master( |
|
266 ec_master_t *master /**< EtherCAT master */ |
|
267 ); |
|
268 |
153 /****************************************************************************** |
269 /****************************************************************************** |
154 * Master methods |
270 * Master methods |
155 *****************************************************************************/ |
271 *****************************************************************************/ |
156 |
272 |
157 void ecrt_master_callbacks(ec_master_t *master, int (*request_cb)(void *), |
273 /** Sets the locking callbacks. |
158 void (*release_cb)(void *), void *cb_data); |
274 * |
159 |
275 * The request_cb function must return zero, to allow another instance |
160 ec_domain_t *ecrt_master_create_domain(ec_master_t *master); |
276 * (the EoE process for example) to access the master. Non-zero means, |
161 |
277 * that access is forbidden at this time. |
162 ec_slave_t *ecrt_master_get_slave(const ec_master_t *master, |
278 */ |
163 const char *address, uint32_t vendor_id, uint32_t product_code); |
279 void ecrt_master_callbacks( |
164 ec_slave_t *ecrt_master_get_slave_by_pos(const ec_master_t *master, |
280 ec_master_t *master, /**< EtherCAT master */ |
165 uint16_t position, uint32_t vendor_id, uint32_t product_code); |
281 int (*request_cb)(void *), /**< Lock request function. */ |
166 |
282 void (*release_cb)(void *), /**< Lock release function. */ |
167 int ecrt_master_activate(ec_master_t *master); |
283 void *cb_data /**< Arbitrary user data. */ |
168 |
284 ); |
169 void ecrt_master_send(ec_master_t *master); |
285 |
170 void ecrt_master_receive(ec_master_t *master); |
286 /** Creates a new domain. |
171 |
287 * |
172 void ecrt_master_get_status(const ec_master_t *master, ec_master_status_t *s); |
288 * \return Pointer to the new domain on success, else NULL. |
|
289 */ |
|
290 ec_domain_t *ecrt_master_create_domain( |
|
291 ec_master_t *master /**< EtherCAT master. */ |
|
292 ); |
|
293 |
|
294 /** Obtains a slave configuration. |
|
295 * |
|
296 * Creates a slave configuration object for the given \a alias and \a position |
|
297 * tuple and returns it. If a configuration with the same \a alias and \a |
|
298 * position already exists, it will be re-used. In the latter case, the given |
|
299 * vendor ID and product code are compared to the stored ones. On mismatch, an |
|
300 * error message is raised and the function returns \a NULL. |
|
301 * |
|
302 * Slaves are addressed with the \a alias and \a position parameters. |
|
303 * - If \a alias is zero, \a position is interpreted as the desired slave's |
|
304 * ring position. |
|
305 * - If \a alias is non-zero, it matches a slave with the given alias. In this |
|
306 * case, \a position is interpreted as ring offset, starting from the |
|
307 * aliased slave, so a position of zero means the aliased slave itself and a |
|
308 * positive value matches the n-th slave behind the aliased one. |
|
309 * |
|
310 * If the slave with the given address is found during the bus configuration, |
|
311 * its vendor ID and product code are matched against the given value. On |
|
312 * mismatch, the slave is not configured and an error message is raised. |
|
313 * |
|
314 * If different slave configurations are pointing to the same slave during bus |
|
315 * configuration, a warning is raised and only the first configuration is |
|
316 * applied. |
|
317 * |
|
318 * \retval >0 Pointer to the slave configuration structure. |
|
319 * \retval NULL in the error case. |
|
320 */ |
|
321 ec_slave_config_t *ecrt_master_slave_config( |
|
322 ec_master_t *master, /**< EtherCAT master */ |
|
323 uint16_t alias, /**< Slave alias. */ |
|
324 uint16_t position, /**< Slave position. */ |
|
325 uint32_t vendor_id, /**< Expected vendor ID. */ |
|
326 uint32_t product_code /**< Expected product code. */ |
|
327 ); |
|
328 |
|
329 /** Applies the bus configuration and switches to realtime mode. |
|
330 * |
|
331 * Does the complete configuration and activation for all slaves. Sets sync |
|
332 * managers and FMMUs, and does the appropriate transitions, until the slave |
|
333 * is operational. |
|
334 * |
|
335 * \return 0 in case of success, else < 0 |
|
336 */ |
|
337 int ecrt_master_activate( |
|
338 ec_master_t *master /**< EtherCAT master. */ |
|
339 ); |
|
340 |
|
341 /** Sends all datagrams in the queue. |
|
342 * |
|
343 * \todo doc |
|
344 */ |
|
345 void ecrt_master_send( |
|
346 ec_master_t *master /**< EtherCAT master. */ |
|
347 ); |
|
348 |
|
349 /** Fetches received frames from the hardware and processes the datagrams. |
|
350 */ |
|
351 void ecrt_master_receive( |
|
352 ec_master_t *master /**< EtherCAT master. */ |
|
353 ); |
|
354 |
|
355 /** Reads the current master state. |
|
356 * |
|
357 * Stores the master state information in the given \a state structure. |
|
358 */ |
|
359 void ecrt_master_state( |
|
360 const ec_master_t *master, /**< EtherCAT master. */ |
|
361 ec_master_state_t *state /**< Structure to store the information. */ |
|
362 ); |
|
363 |
|
364 /****************************************************************************** |
|
365 * Slave configuration methods |
|
366 *****************************************************************************/ |
|
367 |
|
368 /** Specify the Pdo mapping and (optionally) the Pdo configuration. |
|
369 * |
|
370 * The following example shows, how to specify a complete Pdo mapping |
|
371 * including the Pdo configuration. With this information, the master is able |
|
372 * to reserve the complete process data, even if the slave is not present |
|
373 * at configuration time: |
|
374 * |
|
375 * \code |
|
376 * const ec_pdo_info_t complete_mapping[] = { |
|
377 * {EC_DIR_INPUT, 0x1600, 2, { // channel 1 |
|
378 * {0x7000, 0, 16}, // value |
|
379 * {0x7000, 1, 8}, // status |
|
380 * }}, |
|
381 * {EC_DIR_INPUT, 0x1601, 2, { // channel 2 |
|
382 * {0x7001, 0, 16}, // value |
|
383 * {0x7001, 1, 8}, // status |
|
384 * }} |
|
385 * }; |
|
386 * |
|
387 * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, complete_mapping)) { |
|
388 * // error |
|
389 * } |
|
390 * \endcode |
|
391 * |
|
392 * The next example shows, how to configure only the Pdo mapping. The entries |
|
393 * for each mapped Pdo are taken from the default Pdo configuration. Please |
|
394 * note, that Pdo entry registration will fail, if no Pdo configuration is |
|
395 * specified and the slave is offline. |
|
396 * |
|
397 * \code |
|
398 * const ec_pdo_info_t pdo_mapping[] = { |
|
399 * {EC_DIR_INPUT, 0x1600}, // Channel 1 |
|
400 * {EC_DIR_INPUT, 0x1601} // Channel 2 |
|
401 * }; |
|
402 * |
|
403 * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, pdo_mapping)) { |
|
404 * // error |
|
405 * } |
|
406 * \endcode |
|
407 * |
|
408 * \return zero on success, else non-zero |
|
409 */ |
|
410 int ecrt_slave_config_mapping( |
|
411 ec_slave_config_t *sc, /**< Slave configuration. */ |
|
412 unsigned int n_entries, /**< Number of Pdos in \a pdos to map. */ |
|
413 const ec_pdo_info_t pdos[] /**< List with Pdo mapping. */ |
|
414 ); |
|
415 |
|
416 /** Add a configuration value for an 8-bit SDO. |
|
417 * |
|
418 * \todo doc |
|
419 * \return 0 in case of success, else < 0 |
|
420 */ |
|
421 int ecrt_slave_config_sdo8( |
|
422 ec_slave_config_t *sc, /**< Slave configuration */ |
|
423 uint16_t sdo_index, /**< Index of the SDO to configure. */ |
|
424 uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ |
|
425 uint8_t value /**< Value to set. */ |
|
426 ); |
|
427 |
|
428 /** Add a configuration value for a 16-bit SDO. |
|
429 * |
|
430 * \todo doc |
|
431 * \return 0 in case of success, else < 0 |
|
432 */ |
|
433 int ecrt_slave_config_sdo16( |
|
434 ec_slave_config_t *sc, /**< Slave configuration */ |
|
435 uint16_t sdo_index, /**< Index of the SDO to configure. */ |
|
436 uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ |
|
437 uint16_t value /**< Value to set. */ |
|
438 ); |
|
439 |
|
440 /** Add a configuration value for a 32-bit SDO. |
|
441 * |
|
442 * \todo doc |
|
443 * \return 0 in case of success, else < 0 |
|
444 */ |
|
445 int ecrt_slave_config_sdo32( |
|
446 ec_slave_config_t *sc, /**< Slave configuration */ |
|
447 uint16_t sdo_index, /**< Index of the SDO to configure. */ |
|
448 uint8_t sdo_subindex, /**< Subindex of the SDO to configure. */ |
|
449 uint32_t value /**< Value to set. */ |
|
450 ); |
|
451 |
|
452 /** Outputs the state of the slave configuration. |
|
453 * |
|
454 * Stores the state information in the given \a state structure. |
|
455 */ |
|
456 void ecrt_slave_config_state( |
|
457 const ec_slave_config_t *sc, /**< Slave configuration */ |
|
458 ec_slave_config_state_t *state /**< State object to write to. */ |
|
459 ); |
173 |
460 |
174 /****************************************************************************** |
461 /****************************************************************************** |
175 * Domain methods |
462 * Domain methods |
176 *****************************************************************************/ |
463 *****************************************************************************/ |
177 |
464 |
178 int ecrt_domain_register_pdo(ec_domain_t *domain, ec_slave_t *slave, |
465 /** Registers a single Pdo entry for a domain. |
179 uint16_t pdo_entry_index, uint8_t pdo_entry_subindex, void **data_ptr); |
466 * |
180 |
467 * \return On success, the function returns the offset in the domain's process |
181 int ecrt_domain_register_pdo_range(ec_domain_t *domain, ec_slave_t *slave, |
468 * data, which can be zero or greater. On failure, it returns a value |
182 ec_direction_t direction, uint16_t offset, uint16_t length, |
469 * less than zero. |
183 void **data_ptr); |
470 */ |
184 |
471 |
185 int ecrt_domain_register_pdo_list(ec_domain_t *domain, |
472 int ecrt_domain_reg_pdo_entry( |
186 const ec_pdo_reg_t *pdos); |
473 ec_domain_t *domain, /**< Domain. */ |
187 |
474 ec_slave_config_t *sc, /**< Slave configuration. */ |
188 void ecrt_domain_process(ec_domain_t *domain); |
475 uint16_t entry_index, /**< Index of the Pdo entry to register. */ |
189 void ecrt_domain_queue(ec_domain_t *domain); |
476 uint8_t entry_subindex /**< Subindex of the Pdo entry to register. */ |
190 |
477 ); |
191 int ecrt_domain_state(const ec_domain_t *domain); |
478 |
192 |
479 /** Registers a bunch of Pdo entries for a domain. |
193 /****************************************************************************** |
480 * |
194 * Slave methods |
481 * \todo doc |
195 *****************************************************************************/ |
482 * \attention The registration array has to be terminated with an empty |
196 |
483 * structure, or one with the \a index field set to zero! |
197 int ecrt_slave_conf_sdo8(ec_slave_t *slave, uint16_t sdo_index, |
484 * \return 0 on success, else non-zero. |
198 uint8_t sdo_subindex, uint8_t value); |
485 */ |
199 int ecrt_slave_conf_sdo16(ec_slave_t *slave, uint16_t sdo_index, |
486 int ecrt_domain_reg_pdo_entry_list( |
200 uint8_t sdo_subindex, uint16_t value); |
487 ec_domain_t *domain, /**< Domain. */ |
201 int ecrt_slave_conf_sdo32(ec_slave_t *slave, uint16_t sdo_index, |
488 const ec_pdo_entry_reg_t *pdo_entry_regs /**< Array of Pdo |
202 uint8_t sdo_subindex, uint32_t value); |
489 registrations. */ |
203 |
490 ); |
204 void ecrt_slave_pdo_mapping_clear(ec_slave_t *, ec_direction_t); |
491 |
205 int ecrt_slave_pdo_mapping_add(ec_slave_t *, ec_direction_t, uint16_t); |
492 /** Returns the current size of the domain's process data. |
206 int ecrt_slave_pdo_mapping(ec_slave_t *, ec_direction_t, unsigned int, ...); |
493 * |
|
494 * \return Size of the process data image. |
|
495 */ |
|
496 size_t ecrt_domain_size( |
|
497 ec_domain_t *domain /**< Domain. */ |
|
498 ); |
|
499 |
|
500 /** Provide memory to store the domain's process data. |
|
501 * |
|
502 * Call this after all Pdo entries have been registered. Since interface |
|
503 * version 1.4, you'll have to provide an external memory for the domain |
|
504 * process data. |
|
505 * |
|
506 * The size of the allocated memory must be at least the return value of |
|
507 * ecrt_domain_size(), after all Pdo entries have been registered. |
|
508 */ |
|
509 void ecrt_domain_memory( |
|
510 ec_domain_t *domain, /**< Domain. */ |
|
511 uint8_t *memory /**< Address of the memory to store the process |
|
512 data in. */ |
|
513 ); |
|
514 |
|
515 /** Processes received datagrams. |
|
516 * |
|
517 * \todo doc |
|
518 */ |
|
519 void ecrt_domain_process( |
|
520 ec_domain_t *domain /**< Domain. */ |
|
521 ); |
|
522 |
|
523 /** (Re-)queues all domain datagrams in the master's datagram queue. |
|
524 * |
|
525 * \todo doc |
|
526 */ |
|
527 void ecrt_domain_queue( |
|
528 ec_domain_t *domain /**< Domain. */ |
|
529 ); |
|
530 |
|
531 /** Reads the state of a domain. |
|
532 * |
|
533 * Stores the domain state in the giveb \a state structure. |
|
534 */ |
|
535 void ecrt_domain_state( |
|
536 const ec_domain_t *domain, /**< Domain. */ |
|
537 ec_domain_state_t *state /**< Pointer to a state object to store the |
|
538 information. */ |
|
539 ); |
207 |
540 |
208 /****************************************************************************** |
541 /****************************************************************************** |
209 * Bitwise read/write macros |
542 * Bitwise read/write macros |
210 *****************************************************************************/ |
543 *****************************************************************************/ |
211 |
544 |