35 * |
35 * |
36 * EtherCAT Realtime Interface. |
36 * EtherCAT Realtime Interface. |
37 * |
37 * |
38 * \defgroup RealtimeInterface EtherCAT Realtime Interface |
38 * \defgroup RealtimeInterface EtherCAT Realtime Interface |
39 * |
39 * |
40 * EtherCAT interface for realtime modules. This interface is designed for |
40 * EtherCAT interface for realtime applications. This interface is designed |
41 * realtime modules that want to use EtherCAT. There are functions to request |
41 * for realtime modules that want to use EtherCAT. There are functions to |
42 * a master, to map process data, to communicate with slaves via CoE and to |
42 * request a master, to map process data, to communicate with slaves via CoE |
43 * configure and activate the bus. |
43 * and to configure and activate the bus. |
44 * |
44 * |
45 * Changes in Version 1.4: |
45 * Changes in Version 1.4: |
46 * |
46 * |
47 * - Replaced ec_slave_t with ec_slave_config_t, separating the slave objects |
47 * - Replaced ec_slave_t with ec_slave_config_t, separating the slave objects |
48 * from the requested bus configuration. Therefore, renamed |
48 * from the requested bus configuration. Therefore, renamed |
62 * ecrt_slave_config_reg_pdo_entry(). This was necessary for the external |
62 * ecrt_slave_config_reg_pdo_entry(). This was necessary for the external |
63 * domain memory. An additional advantage is, that the returned offset value |
63 * domain memory. An additional advantage is, that the returned offset value |
64 * is directly usable. If the domain's process data is allocated internally, |
64 * is directly usable. If the domain's process data is allocated internally, |
65 * the start address can be retrieved with ecrt_domain_data(). |
65 * the start address can be retrieved with ecrt_domain_data(). |
66 * - Replaced ecrt_slave_pdo_mapping/add/clear() with |
66 * - Replaced ecrt_slave_pdo_mapping/add/clear() with |
67 * ecrt_slave_config_pdo() to add a Pdo to the mapping and |
67 * ecrt_slave_config_pdo_assign_add() to add a Pdo to a sync manager's Pdo |
68 * ecrt_slave_config_pdo_entry() to add a Pdo entry to a Pdo configuration. |
68 * assignment and ecrt_slave_config_pdo_mapping_add() to add a Pdo entry to a |
69 * ecrt_slave_config_mapping() is a convenience function for |
69 * Pdo's mapping. ecrt_slave_config_pdos() is a convenience function |
70 * both, that uses the new data types ec_pdo_info_t and ec_pdo_entry_info_t. |
70 * for both, that uses the new data types ec_pdo_info_t and |
71 * Mapped Pdo entries can now immediately be registered. |
71 * ec_pdo_entry_info_t. Pdo entries, that are mapped with these functions |
|
72 * can now immediately be registered, even if the bus is offline. |
72 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and |
73 * - Renamed ec_bus_status_t, ec_master_status_t to ec_bus_state_t and |
73 * ec_master_state_t, respectively. Renamed ecrt_master_get_status() to |
74 * ec_master_state_t, respectively. Renamed ecrt_master_get_status() to |
74 * ecrt_master_state(), for consistency reasons. |
75 * ecrt_master_state(), for consistency reasons. |
75 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter |
76 * - Added ec_domain_state_t and ec_wc_state_t for a new output parameter |
76 * of ecrt_domain_state(). The domain state object does now contain |
77 * of ecrt_domain_state(). The domain state object does now contain |
228 |
233 |
229 /*****************************************************************************/ |
234 /*****************************************************************************/ |
230 |
235 |
231 /** Pdo information. |
236 /** Pdo information. |
232 * |
237 * |
233 * \see ecrt_slave_config_mapping(). |
238 * This can be use to assign multiple Pdos to a sync manager using |
|
239 * ecrt_slave_config_pdos(). |
234 */ |
240 */ |
235 typedef struct { |
241 typedef struct { |
236 ec_direction_t dir; /**< Pdo direction (input/output). */ |
242 ec_direction_t dir; /**< Pdo direction (input/output). */ |
237 uint16_t index; /**< Index of the Pdo to map. */ |
243 uint16_t index; /**< Index of the Pdo to map. */ |
238 unsigned int n_entries; /**< Number of Pdo entries for the Pdo |
244 unsigned int n_entries; /**< Number of Pdo entries in \a entries to map. |
239 configuration. Zero means, that the default Pdo |
245 Zero means, that the default mapping shall be |
240 configuration shall be used. */ |
246 used. */ |
241 ec_pdo_entry_info_t *entries; /**< Pdo configuration array. This |
247 ec_pdo_entry_info_t *entries; /**< Array of Pdo entries to map. This must |
242 array must contain at least \a |
248 contain at least \a n_entries values. */ |
243 n_entries values. */ |
|
244 } ec_pdo_info_t; |
249 } ec_pdo_info_t; |
245 |
250 |
246 /*****************************************************************************/ |
251 /*****************************************************************************/ |
247 |
252 |
248 /** List record type for Pdo entry mass-registration. |
253 /** List record type for Pdo entry mass-registration. |
356 uint16_t position, /**< Slave position. */ |
361 uint16_t position, /**< Slave position. */ |
357 uint32_t vendor_id, /**< Expected vendor ID. */ |
362 uint32_t vendor_id, /**< Expected vendor ID. */ |
358 uint32_t product_code /**< Expected product code. */ |
363 uint32_t product_code /**< Expected product code. */ |
359 ); |
364 ); |
360 |
365 |
361 /** Applies the bus configuration and switches to realtime mode. |
366 /** Finishes the configuration phase and prepares for realtime mode. |
362 * |
367 * |
363 * Does the complete configuration and activation for all slaves. Sets sync |
368 * This function has to be called after all Pdo entries are registered. It |
364 * managers and FMMUs, and does the appropriate transitions, until the slave |
369 * tells the master that the configuration phase is finished and the realtime |
365 * is operational. |
370 * operation will begin. The function allocates internal memory for the |
|
371 * domains and calculates the logical FMMU addresses for domain members. It |
|
372 * tells the master state machine that the bus configuration is now to be |
|
373 * applied. |
|
374 * |
|
375 * \attention After this function has been called, the realtime application is |
|
376 * in charge of cyclically calling ecrt_master_send() and |
|
377 * ecrt_master_receive() to ensure bus communication. Before calling this |
|
378 * function, the master thread is responsible for that, so these functions may |
|
379 * not be called! |
366 * |
380 * |
367 * \return 0 in case of success, else < 0 |
381 * \return 0 in case of success, else < 0 |
368 */ |
382 */ |
369 int ecrt_master_activate( |
383 int ecrt_master_activate( ec_master_t *master /**< EtherCAT master. */); |
370 ec_master_t *master /**< EtherCAT master. */ |
|
371 ); |
|
372 |
384 |
373 /** Sends all datagrams in the queue. |
385 /** Sends all datagrams in the queue. |
374 * |
386 * |
375 * \todo doc |
387 * This has to be called cyclically by the realtime application after |
|
388 * ecrt_master_activate() has returned. |
376 */ |
389 */ |
377 void ecrt_master_send( |
390 void ecrt_master_send( |
378 ec_master_t *master /**< EtherCAT master. */ |
391 ec_master_t *master /**< EtherCAT master. */ |
379 ); |
392 ); |
380 |
393 |
381 /** Fetches received frames from the hardware and processes the datagrams. |
394 /** Fetches received frames from the hardware and processes the datagrams. |
|
395 * |
|
396 * This has to be called cyclically by the realtime application after |
|
397 * ecrt_master_activate() has returned. |
382 */ |
398 */ |
383 void ecrt_master_receive( |
399 void ecrt_master_receive( |
384 ec_master_t *master /**< EtherCAT master. */ |
400 ec_master_t *master /**< EtherCAT master. */ |
385 ); |
401 ); |
386 |
402 |
395 |
411 |
396 /****************************************************************************** |
412 /****************************************************************************** |
397 * Slave configuration methods |
413 * Slave configuration methods |
398 *****************************************************************************/ |
414 *****************************************************************************/ |
399 |
415 |
400 /** Add a Pdo to the slave's Pdo mapping for the given direction. |
416 /** Add a Pdo to a sync manager's Pdo assignment. |
401 * |
417 * |
402 * The first call of this function for a given \a dir will clear the default |
418 * \see ecrt_slave_config_pdos() |
403 * mapping. |
|
404 * |
|
405 * \see ecrt_slave_config_mapping() |
|
406 * \return zero on success, else non-zero |
419 * \return zero on success, else non-zero |
407 */ |
420 */ |
408 int ecrt_slave_config_pdo( |
421 int ecrt_slave_config_pdo_assign_add( |
409 ec_slave_config_t *sc, /**< Slave configuration. */ |
422 ec_slave_config_t *sc, /**< Slave configuration. */ |
410 ec_direction_t dir, /**< Pdo direction (input/output). */ |
423 ec_direction_t dir, /**< Sync manager direction (input/output). */ |
411 uint16_t index /**< Index of the Pdo to map. */ |
424 uint16_t index /**< Index of the Pdo to assign. */ |
412 ); |
425 ); |
413 |
426 |
414 /** Add a Pdo entry to the given Pdo's configuration. |
427 /** Clear a sync manager's Pdo assignment. |
415 * |
428 * |
416 * The first call of this function for a given \a pdo_index will clear the |
429 * This can be called before assigning Pdos via |
417 * default Pdo configuration. |
430 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment. |
418 * |
431 */ |
419 * \see ecrt_slave_config_mapping() |
432 void ecrt_slave_config_pdo_assign_clear( |
|
433 ec_slave_config_t *sc, /**< Slave configuration. */ |
|
434 ec_direction_t dir /**< Sync manager direction (input/output). */ |
|
435 ); |
|
436 |
|
437 /** Add a Pdo entry to the given Pdo's mapping. |
|
438 * |
|
439 * \see ecrt_slave_config_pdos() |
420 * \return zero on success, else non-zero |
440 * \return zero on success, else non-zero |
421 */ |
441 */ |
422 int ecrt_slave_config_pdo_entry( |
442 int ecrt_slave_config_pdo_mapping_add( |
423 ec_slave_config_t *sc, /**< Slave configuration. */ |
443 ec_slave_config_t *sc, /**< Slave configuration. */ |
424 uint16_t pdo_index, /**< Index of the Pdo to configure. */ |
444 uint16_t pdo_index, /**< Index of the Pdo. */ |
425 uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's |
445 uint16_t entry_index, /**< Index of the Pdo entry to add to the Pdo's |
426 configuration. */ |
446 mapping. */ |
427 uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the |
447 uint8_t entry_subindex, /**< Subindex of the Pdo entry to add to the |
428 Pdo's configuration. */ |
448 Pdo's mapping. */ |
429 uint8_t entry_bit_length /**< Size of the Pdo entry in bit. */ |
449 uint8_t entry_bit_length /**< Size of the Pdo entry in bit. */ |
430 ); |
450 ); |
431 |
451 |
432 /** Specify the Pdo mapping and (optionally) the Pdo configuration. |
452 /** Clear the mapping of a given Pdo. |
433 * |
453 * |
434 * This function is a convenience function for the ecrt_slave_config_pdo() |
454 * This can be called before mapping Pdo entries via |
435 * and ecrt_slave_config_pdo_entry() functions, that are better suitable |
455 * ecrt_slave_config_pdo_mapping_add(), to clear the default mapping. |
436 * for automatic code generation. |
456 */ |
437 * |
457 void ecrt_slave_config_pdo_mapping_clear( |
438 * The following example shows, how to specify a complete Pdo mapping |
458 ec_slave_config_t *sc, /**< Slave configuration. */ |
439 * including the Pdo configuration. With this information, the master is able |
459 uint16_t pdo_index /**< Index of the Pdo. */ |
440 * to reserve the complete process data, even if the slave is not present |
460 ); |
441 * at configuration time: |
461 |
|
462 /** Specify the Pdo assignment and (optionally) the Pdo mappings. |
|
463 * |
|
464 * This function is a convenience wrapper for the functions |
|
465 * ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(), |
|
466 * ecrt_slave_config_pdo_mapping_clear() and |
|
467 * ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic |
|
468 * code generation. |
|
469 * |
|
470 * The following example shows, how to specify a complete Pdo assignment |
|
471 * including the Pdo mappings. With this information, the master is able to |
|
472 * reserve the complete process data, even if the slave is not present at |
|
473 * configuration time: |
442 * |
474 * |
443 * \code |
475 * \code |
444 * const ec_pdo_entry_info_t el3162_channel1[] = { |
476 * const ec_pdo_entry_info_t el3162_channel1[] = { |
445 * {0x3101, 1, 8}, // status |
477 * {0x3101, 1, 8}, // status |
446 * {0x3101, 2, 16} // value |
478 * {0x3101, 2, 16} // value |
449 * const ec_pdo_entry_info_t el3162_channel2[] = { |
481 * const ec_pdo_entry_info_t el3162_channel2[] = { |
450 * {0x3102, 1, 8}, // status |
482 * {0x3102, 1, 8}, // status |
451 * {0x3102, 2, 16} // value |
483 * {0x3102, 2, 16} // value |
452 * }; |
484 * }; |
453 * |
485 * |
454 * const ec_pdo_info_t el3162_mapping[] = { |
486 * const ec_pdo_info_t el3162_pdos[] = { |
455 * {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1}, |
487 * {EC_DIR_INPUT, 0x1A00, 2, el3162_channel1}, |
456 * {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2}, |
488 * {EC_DIR_INPUT, 0x1A01, 2, el3162_channel2}, |
457 * }; |
489 * }; |
458 * |
490 * |
459 * if (ecrt_slave_config_mapping(sc, 2, el3162_mapping)) |
491 * if (ecrt_slave_config_pdos(sc, 2, el3162_pdos)) |
460 * return -1; // error |
492 * return -1; // error |
461 * \endcode |
493 * \endcode |
462 * |
494 * |
463 * The next example shows, how to configure only the Pdo mapping. The entries |
495 * The next example shows, how to configure only the Pdo assignment. The |
464 * for each mapped Pdo are taken from the default Pdo configuration. Please |
496 * entries for each assigned Pdo are taken from the Pdo's default mapping. |
465 * note, that Pdo entry registration will fail, if the Pdo configuration is |
497 * Please note, that Pdo entry registration will fail, if the Pdo |
466 * left empty and the slave is offline. |
498 * configuration is left empty and the slave is offline. |
467 * |
499 * |
468 * \code |
500 * \code |
469 * const ec_pdo_info_t pdo_mapping[] = { |
501 * const ec_pdo_info_t pdos[] = { |
470 * {EC_DIR_INPUT, 0x1600}, // Channel 1 |
502 * {EC_DIR_INPUT, 0x1600}, // Channel 1 |
471 * {EC_DIR_INPUT, 0x1601} // Channel 2 |
503 * {EC_DIR_INPUT, 0x1601} // Channel 2 |
472 * }; |
504 * }; |
473 * |
505 * |
474 * if (ecrt_slave_config_mapping(slave_config_ana_in, 2, pdo_mapping)) |
506 * if (ecrt_slave_config_pdos(slave_config_ana_in, 2, pdos)) |
475 * return -1; // error |
507 * return -1; // error |
476 * \endcode |
508 * \endcode |
477 * |
509 * |
478 * Processing of \a pdo_infos will stop, if |
510 * Processing of \a pdo_infos will stop, if |
479 * - the number of processed items reaches \a n_infos, or |
511 * - the number of processed items reaches \a n_infos, or |
480 * - the \a dir member of an ec_pdo_info_t item is EC_MAP_END. In this case, |
512 * - the \a dir member of an ec_pdo_info_t item is EC_END. In this case, |
481 * \a n_infos should set to a number greater than the number of list items; |
513 * \a n_infos should set to a number greater than the number of list items; |
482 * using EC_MAP_END is recommended. |
514 * using EC_END is recommended. |
483 * |
515 * |
484 * \return zero on success, else non-zero |
516 * \return zero on success, else non-zero |
485 */ |
517 */ |
486 int ecrt_slave_config_mapping( |
518 int ecrt_slave_config_pdos( |
487 ec_slave_config_t *sc, /**< Slave configuration. */ |
519 ec_slave_config_t *sc, /**< Slave configuration. */ |
488 unsigned int n_infos, /**< Number of Pdo infos in \a pdo_infos. */ |
520 unsigned int n_infos, /**< Number of Pdo infos in \a pdo_infos. */ |
489 const ec_pdo_info_t pdo_infos[] /**< List with Pdo mapping. */ |
521 const ec_pdo_info_t pdo_infos[] /**< List with Pdos. */ |
490 ); |
522 ); |
491 |
523 |
492 /** Registers a Pdo entry for process data exchange in a domain. |
524 /** Registers a Pdo entry for process data exchange in a domain. |
493 * |
525 * |
494 * Searches the current mapping and Pdo configurations for the given Pdo |
526 * Searches the current Pdo assignment and Pdo mappings for the given Pdo |
495 * entry. An error is raised, if the given entry is not mapped. Otherwise, the |
527 * entry. An error is raised, if the given entry is not mapped. Otherwise, the |
496 * corresponding sync manager and FMMU configurations are provided for slave |
528 * corresponding sync manager and FMMU configurations are provided for slave |
497 * configuration and the respective sync manager's Pdos are appended to the |
529 * configuration and the respective sync manager's assigned Pdos are appended |
498 * given domain, if not already done. The offset of the requested Pdo entry's |
530 * to the given domain, if not already done. The offset of the requested Pdo |
499 * data inside the domain's process data is returned. |
531 * entry's data inside the domain's process data is returned. |
500 * |
532 * |
501 * \retval >=0 Success: Offset of the Pdo entry's process data. |
533 * \retval >=0 Success: Offset of the Pdo entry's process data. |
502 * \retval -1 Error: Pdo entry not found. |
534 * \retval -1 Error: Pdo entry not found. |
503 * \retval -2 Error: Failed to register Pdo entry. |
535 * \retval -2 Error: Failed to register Pdo entry. |
504 */ |
536 */ |