etherlabmaster: comparison include/ecrt.h

equal deleted inserted replaced

-:f98f89d0d778
+:c9308eb34c0e
 *   ecrt_slave_config_dc() to configure a slave for cyclic
 *   operation, and ecrt_master_application_time(),
 *   ecrt_master_sync_reference_clock() and  ecrt_master_sync_slave_clocks()
 *   for offset and drift compensation. The EC_TIMEVAL2NANO() macro can be
 *   used for epoch time conversion.
+* - Added ecrt_open_master() and ecrt_master_reserve() separation for
+*   userspace.
+* - Added ecrt_master() userspace interface, to get information about a
+*   master.
 * - Changed the meaning of the negative return values of
 *   ecrt_slave_config_reg_pdo_entry() and ecrt_slave_config_sdo*().
 * - Imlemented the Vendor-specific over EtherCAT mailbox protocol. See
 *   ecrt_slave_config_create_voe_handler().
 * - Renamed ec_sdo_request_state_t to ec_request_state_t, because it is also
 - 8: \a OP
 Note that each state is coded in a different
 bit! */
 } ec_slave_config_state_t;
+/*****************************************************************************/
+#ifndef __KERNEL__
+/** Master information.
+*
+* This is used as an output parameter of ecrt_master().
+*
+* \see ecrt_master().
+*/
+typedef struct {
+unsigned int slave_count; /**< Number of slaves in the bus. */
+unsigned int link_up : 1; /**< \a true, if the network link is up. */
+uint64_t app_time; /**< Application time. */
+} ec_master_info_t;
 /*****************************************************************************/
 /** Slave information.
 *
 uint8_t sync_count; /**< Number of sync managers. */
 uint16_t sdo_count; /**< Number of SDO's. */
 char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */
 } ec_slave_info_t;
+#endif // #ifndef __KERNEL__
 /*****************************************************************************/
 /** Domain working counter interpretation.
 *
 * This is used in ec_domain_state_t.
 /** Requests an EtherCAT master for realtime operation.
 *
 * Before an application can access an EtherCAT master, it has to reserve one
 * for exclusive use.
 *
+* In userspace, this is a convenience function for ecrt_open_master() and
+* ecrt_master_reserve().
+*
 * This function has to be the first function an application has to call to
 * use EtherCAT. The function takes the index of the master as its argument.
 * The first master has index 0, the n-th master has index n - 1. The number
 * of masters has to be specified when loading the master module.
 *
 */
 ec_master_t *ecrt_request_master(
 unsigned int master_index /**< Index of the master to request. */
 );
+#ifndef __KERNEL__
+/** Opens an EtherCAT master for userspace access.
+*
+* This function has to be the first function an application has to call to
+* use EtherCAT. The function takes the index of the master as its argument.
+* The first master has index 0, the n-th master has index n - 1. The number
+* of masters has to be specified when loading the master module.
+*
+* For convenience, the function ecrt_request_master() can be used.
+*
+* \return Pointer to the opened master, otherwise \a NULL.
+*/
+ec_master_t *ecrt_open_master(
+		unsigned int master_index /**< Index of the master to request. */
+		);
+#endif // #ifndef __KERNEL__
 /** Releases a requested EtherCAT master.
 *
 * After use, a master it has to be released to make it available for other
 * applications.
 */
 );
 /******************************************************************************
 * Master methods
 *****************************************************************************/
+#ifndef __KERNEL__
+/** Reserves an EtherCAT master for realtime operation.
+*
+* Before an application can use PDO/domain registration functions or SDO
+* request functions on the master, it has to reserve one for exclusive use.
+*
+* \return 0 in case of success, else < 0
+*
+*/
+int ecrt_master_reserve(
+		ec_master_t *master /**< EtherCAT master */
+		);
+#endif // #ifndef __KERNEL__
 #ifdef __KERNEL__
 /** Sets the locking callbacks.
 *
 uint32_t product_code /**< Expected product code. */
 );
 #ifndef __KERNEL__
+/** Obtains master information.
+*
+* No memory is allocated on the heap in
+* this function.
+*
+* \attention The pointer to this structure must point to a valid variable.
+*
+* \return 0 in case of success, else < 0
+*/
+int ecrt_master(
+		ec_master_t *master, /**< EtherCAT master */
+		ec_master_info_t *master_info /**< Structure that will output the
+									  information */
+		);
 /** Obtains slave information.
 *
 * Tries to find the slave with the given ring position. The obtained
 * information is stored in a structure. No memory is allocated on the heap in
 * this function.
 uint16_t position, /**< Slave position. */
 ec_slave_info_t *slave_info /**< Structure that will output the
 information */
 );
-#endif /* ifndef __KERNEL__ */
+#endif /* #ifndef __KERNEL__ */
 /** Finishes the configuration phase and prepares for cyclic operation.
 *
 * This function tells the master that the configuration phase is finished and
 * the realtime operation will begin. The function allocates internal memory
 size_t target_size, /**< Size of the target buffer. */
 size_t *result_size, /**< Uploaded data size. */
 uint32_t *abort_code /**< Abort code of the SDO upload. */
 );
-#endif /* ifndef __KERNEL__ */
+#endif /* #ifndef __KERNEL__ */
 /******************************************************************************
 * Slave configuration methods
 *****************************************************************************/

changeset 1497	c9308eb34c0e
parent 1495	88f242b722ce
child 1500	ed1a733efbc5