include/ecrt.h
changeset 1092 69393cf60399
parent 1083 1322dc34cb37
child 1096 a32a102a30db
equal deleted inserted replaced
1091:363205c2ebaf 1092:69393cf60399
   295     uint32_t product_code; /**< Slave product code. */
   295     uint32_t product_code; /**< Slave product code. */
   296     uint16_t index; /**< Pdo entry index. */
   296     uint16_t index; /**< Pdo entry index. */
   297     uint8_t subindex; /**< Pdo entry subindex. */
   297     uint8_t subindex; /**< Pdo entry subindex. */
   298     unsigned int *offset; /**< Pointer to a variable to store the Pdo entry's
   298     unsigned int *offset; /**< Pointer to a variable to store the Pdo entry's
   299                        (byte-)offset in the process data. */
   299                        (byte-)offset in the process data. */
   300     unsigned int *bit_position; /** Pointer to a variable to store a bit 
   300     unsigned int *bit_position; /**< Pointer to a variable to store a bit 
   301                                  position (0-7) within the \a offset. Can be
   301                                   position (0-7) within the \a offset. Can be
   302                                  NULL, in which case an error is raised if the
   302                                   NULL, in which case an error is raised if the
   303                                  Pdo entry does not byte-align. */
   303                                   Pdo entry does not byte-align. */
   304 } ec_pdo_entry_reg_t;
   304 } ec_pdo_entry_reg_t;
   305 
   305 
   306 /*****************************************************************************/
   306 /*****************************************************************************/
   307 
   307 
   308 /** Sdo request state.
   308 /** Sdo request state.
   326  */
   326  */
   327 unsigned int ecrt_version_magic(void);
   327 unsigned int ecrt_version_magic(void);
   328 
   328 
   329 /** Requests an EtherCAT master for realtime operation.
   329 /** Requests an EtherCAT master for realtime operation.
   330  * 
   330  * 
   331  * \return pointer to reserved master, or NULL on error
   331  * Before an application can access an EtherCAT master, it has to reserve one
       
   332  * for exclusive use.
       
   333  *
       
   334  * This function has to be the first function an application has to call to
       
   335  * use EtherCAT. The function takes the index of the master as its argument.
       
   336  * The first master has index 0, the n-th master has index n - 1. The number
       
   337  * of masters has to be specified when loading the master module.
       
   338  *
       
   339  * \return Pointer to reserved master, or \a NULL on error.
   332  */
   340  */
   333 ec_master_t *ecrt_request_master(
   341 ec_master_t *ecrt_request_master(
   334         unsigned int master_index /**< Index of the master to request. */
   342         unsigned int master_index /**< Index of the master to request. */
   335         );
   343         );
   336 
   344 
   337 /** Releases a requested EtherCAT master.
   345 /** Releases a requested EtherCAT master.
       
   346  *
       
   347  * After use, a master it has to be released to make it available for other
       
   348  * applications.
   338  */
   349  */
   339 void ecrt_release_master(
   350 void ecrt_release_master(
   340         ec_master_t *master /**< EtherCAT master */
   351         ec_master_t *master /**< EtherCAT master */
   341         );
   352         );
   342 
   353 
   344  * Master methods
   355  * Master methods
   345  *****************************************************************************/
   356  *****************************************************************************/
   346 
   357 
   347 /** Sets the locking callbacks.
   358 /** Sets the locking callbacks.
   348  *
   359  *
       
   360  * For concurrent master access, the application has to provide a locking
       
   361  * mechanism (see section FIXME in the docs). The method takes two function
       
   362  * pointers and a data value as its parameters. The arbitrary \a cb_data value
       
   363  * will be passed as argument on every callback. Asynchronous master access
       
   364  * (like EoE processing) is only possible if the callbacks have been set.
       
   365  *
   349  * The request_cb function must return zero, to allow another instance
   366  * The request_cb function must return zero, to allow another instance
   350  * (the EoE process for example) to access the master. Non-zero means,
   367  * (an EoE process for example) to access the master. Non-zero means,
   351  * that access is forbidden at this time.
   368  * that access is currently forbidden.
   352  */
   369  */
   353 void ecrt_master_callbacks(
   370 void ecrt_master_callbacks(
   354         ec_master_t *master, /**< EtherCAT master */
   371         ec_master_t *master, /**< EtherCAT master */
   355         int (*request_cb)(void *), /**< Lock request function. */
   372         int (*request_cb)(void *), /**< Lock request function. */
   356         void (*release_cb)(void *), /**< Lock release function. */
   373         void (*release_cb)(void *), /**< Lock release function. */
   357         void *cb_data /**< Arbitrary user data. */
   374         void *cb_data /**< Arbitrary user data. */
   358         );
   375         );
   359 
   376 
   360 /** Creates a new domain.
   377 /** Creates a new process data domain.
       
   378  *
       
   379  * For process data exchange, at least one process data domain is needed.
       
   380  * This method creates a new process data domain and returns a pointer to the
       
   381  * new domain object. This object can be used for registering Pdos and
       
   382  * exchanging them in cyclic operation.
   361  *
   383  *
   362  * \return Pointer to the new domain on success, else NULL.
   384  * \return Pointer to the new domain on success, else NULL.
   363  */
   385  */
   364 ec_domain_t *ecrt_master_create_domain(
   386 ec_domain_t *ecrt_master_create_domain(
   365         ec_master_t *master /**< EtherCAT master. */
   387         ec_master_t *master /**< EtherCAT master. */
   420         ec_master_t *master /**< EtherCAT master. */
   442         ec_master_t *master /**< EtherCAT master. */
   421         );
   443         );
   422 
   444 
   423 /** Sends all datagrams in the queue.
   445 /** Sends all datagrams in the queue.
   424  *
   446  *
   425  * This has to be called cyclically by the realtime application after
   447  * This method takes all datagrams, that have been queued for transmission,
   426  * ecrt_master_activate() has returned.
   448  * puts them into frames, and passes them to the Ethernet device for sending.
       
   449  *
       
   450  * Has to be called cyclically by the application after ecrt_master_activate()
       
   451  * has returned.
   427  */
   452  */
   428 void ecrt_master_send(
   453 void ecrt_master_send(
   429         ec_master_t *master /**< EtherCAT master. */
   454         ec_master_t *master /**< EtherCAT master. */
   430         );
   455         );
   431 
   456 
   432 /** Fetches received frames from the hardware and processes the datagrams.
   457 /** Fetches received frames from the hardware and processes the datagrams.
   433  *
   458  *
   434  * This has to be called cyclically by the realtime application after
   459  * Queries the network device for received frames by calling the interrupt
       
   460  * service routine. Extracts received datagrams and dispatches the results to
       
   461  * the datagram objects in the queue. Received datagrams, and the ones that
       
   462  * timed out, will be marked, and dequeued.
       
   463  *
       
   464  * Has to be called cyclically by the realtime application after
   435  * ecrt_master_activate() has returned.
   465  * ecrt_master_activate() has returned.
   436  */
   466  */
   437 void ecrt_master_receive(
   467 void ecrt_master_receive(
   438         ec_master_t *master /**< EtherCAT master. */
   468         ec_master_t *master /**< EtherCAT master. */
   439         );
   469         );