# HG changeset patch # User Florian Pose # Date 1215173170 0 # Node ID 69393cf60399a71d23981a73d80ceff1b34d9b1e # Parent 363205c2ebafbc737de988056ffe793526c2326e Improved source code doc. diff -r 363205c2ebaf -r 69393cf60399 include/ecrt.h --- a/include/ecrt.h Fri Jul 04 12:05:21 2008 +0000 +++ b/include/ecrt.h Fri Jul 04 12:06:10 2008 +0000 @@ -297,10 +297,10 @@ uint8_t subindex; /**< Pdo entry subindex. */ unsigned int *offset; /**< Pointer to a variable to store the Pdo entry's (byte-)offset in the process data. */ - unsigned int *bit_position; /** Pointer to a variable to store a bit - position (0-7) within the \a offset. Can be - NULL, in which case an error is raised if the - Pdo entry does not byte-align. */ + unsigned int *bit_position; /**< Pointer to a variable to store a bit + position (0-7) within the \a offset. Can be + NULL, in which case an error is raised if the + Pdo entry does not byte-align. */ } ec_pdo_entry_reg_t; /*****************************************************************************/ @@ -328,13 +328,24 @@ /** Requests an EtherCAT master for realtime operation. * - * \return pointer to reserved master, or NULL on error + * Before an application can access an EtherCAT master, it has to reserve one + * for exclusive use. + * + * 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. + * + * \return Pointer to reserved master, or \a NULL on error. */ ec_master_t *ecrt_request_master( unsigned int master_index /**< Index of the master to request. */ ); /** Releases a requested EtherCAT master. + * + * After use, a master it has to be released to make it available for other + * applications. */ void ecrt_release_master( ec_master_t *master /**< EtherCAT master */ @@ -346,9 +357,15 @@ /** Sets the locking callbacks. * + * For concurrent master access, the application has to provide a locking + * mechanism (see section FIXME in the docs). The method takes two function + * pointers and a data value as its parameters. The arbitrary \a cb_data value + * will be passed as argument on every callback. Asynchronous master access + * (like EoE processing) is only possible if the callbacks have been set. + * * The request_cb function must return zero, to allow another instance - * (the EoE process for example) to access the master. Non-zero means, - * that access is forbidden at this time. + * (an EoE process for example) to access the master. Non-zero means, + * that access is currently forbidden. */ void ecrt_master_callbacks( ec_master_t *master, /**< EtherCAT master */ @@ -357,7 +374,12 @@ void *cb_data /**< Arbitrary user data. */ ); -/** Creates a new domain. +/** Creates a new process data domain. + * + * For process data exchange, at least one process data domain is needed. + * This method creates a new process data domain and returns a pointer to the + * new domain object. This object can be used for registering Pdos and + * exchanging them in cyclic operation. * * \return Pointer to the new domain on success, else NULL. */ @@ -422,8 +444,11 @@ /** Sends all datagrams in the queue. * - * This has to be called cyclically by the realtime application after - * ecrt_master_activate() has returned. + * This method takes all datagrams, that have been queued for transmission, + * puts them into frames, and passes them to the Ethernet device for sending. + * + * Has to be called cyclically by the application after ecrt_master_activate() + * has returned. */ void ecrt_master_send( ec_master_t *master /**< EtherCAT master. */ @@ -431,7 +456,12 @@ /** Fetches received frames from the hardware and processes the datagrams. * - * This has to be called cyclically by the realtime application after + * Queries the network device for received frames by calling the interrupt + * service routine. Extracts received datagrams and dispatches the results to + * the datagram objects in the queue. Received datagrams, and the ones that + * timed out, will be marked, and dequeued. + * + * Has to be called cyclically by the realtime application after * ecrt_master_activate() has returned. */ void ecrt_master_receive( diff -r 363205c2ebaf -r 69393cf60399 master/cdev.c --- a/master/cdev.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/cdev.c Fri Jul 04 12:06:10 2008 +0000 @@ -1195,6 +1195,8 @@ * File operations *****************************************************************************/ +/** Called when the cdev is opened. + */ int eccdev_open(struct inode *inode, struct file *filp) { ec_cdev_t *cdev = container_of(inode->i_cdev, ec_cdev_t, cdev); @@ -1208,6 +1210,8 @@ /*****************************************************************************/ +/** Called when the cdev is closed. + */ int eccdev_release(struct inode *inode, struct file *filp) { ec_cdev_t *cdev = (ec_cdev_t *) filp->private_data; @@ -1220,6 +1224,8 @@ /*****************************************************************************/ +/** Called when an ioctl() command is issued. + */ long eccdev_ioctl(struct file *filp, unsigned int cmd, unsigned long arg) { ec_cdev_t *cdev = (ec_cdev_t *) filp->private_data; diff -r 363205c2ebaf -r 69393cf60399 master/domain.c --- a/master/domain.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/domain.c Fri Jul 04 12:06:10 2008 +0000 @@ -277,6 +277,8 @@ /*****************************************************************************/ +/** Get the number of FMMU configurations of the domain. + */ unsigned int ec_domain_fmmu_count(const ec_domain_t *domain) { const ec_fmmu_config_t *fmmu; @@ -291,15 +293,17 @@ /*****************************************************************************/ +/** Get a certain FMMU configuration via its position in the list. + */ const ec_fmmu_config_t *ec_domain_find_fmmu( - const ec_domain_t *domain, - unsigned int index + const ec_domain_t *domain, /**< EtherCAT domain. */ + unsigned int pos /**< List position. */ ) { const ec_fmmu_config_t *fmmu; list_for_each_entry(fmmu, &domain->fmmu_configs, list) { - if (index--) + if (pos--) continue; return fmmu; } diff -r 363205c2ebaf -r 69393cf60399 master/fsm_coe.c --- a/master/fsm_coe.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/fsm_coe.c Fri Jul 04 12:06:10 2008 +0000 @@ -231,7 +231,11 @@ /*****************************************************************************/ -/** +/** Check if the received data are a CoE emergency request. + * + * If the check is positive, the emergency request is output. + * + * \return The data were an emergency request. */ int ec_fsm_coe_check_emergency( ec_fsm_coe_t *fsm, /**< Finite state machine */ diff -r 363205c2ebaf -r 69393cf60399 master/master.c --- a/master/master.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/master.c Fri Jul 04 12:06:10 2008 +0000 @@ -1072,6 +1072,10 @@ /*****************************************************************************/ +/** Get the number of slave configurations provided by the application. + * + * \return Number of configurations. + */ unsigned int ec_master_config_count( const ec_master_t *master /**< EtherCAT master. */ ) @@ -1088,15 +1092,21 @@ /*****************************************************************************/ +/** Get a slave configuration via its position in the list. + * + * Const version. + * + * \return Slave configuration or \a NULL. + */ const ec_slave_config_t *ec_master_get_config_const( const ec_master_t *master, /**< EtherCAT master. */ - unsigned int index /**< List position. */ + unsigned int pos /**< List position. */ ) { const ec_slave_config_t *sc; list_for_each_entry(sc, &master->configs, list) { - if (index--) + if (pos--) continue; return sc; } @@ -1106,6 +1116,10 @@ /*****************************************************************************/ +/** Get the number of domains. + * + * \return Number of domains. + */ unsigned int ec_master_domain_count( const ec_master_t *master /**< EtherCAT master. */ ) @@ -1136,6 +1150,10 @@ return NULL; \ } while (0) +/** Get a domain via its position in the list. + * + * \return Domain pointer, or \a NULL if not found. + */ ec_domain_t *ec_master_find_domain( ec_master_t *master, /**< EtherCAT master. */ unsigned int index /**< Domain index. */ @@ -1145,6 +1163,12 @@ EC_FIND_DOMAIN; } +/** Get a domain via its position in the list. + * + * Const version. + * + * \return Domain pointer, or \a NULL if not found. + */ const ec_domain_t *ec_master_find_domain_const( const ec_master_t *master, /**< EtherCAT master. */ unsigned int index /**< Domain index. */ @@ -1156,9 +1180,14 @@ /*****************************************************************************/ +/** Set the debug level. + * + * \retval 0 Success. + * \retval -1 Invalid debug level. + */ int ec_master_debug_level( - ec_master_t *master, - int level + ec_master_t *master, /**< EtherCAT master. */ + int level /**< Debug level. May be 0, 1 or 2. */ ) { if (level < 0 || level > 2) { diff -r 363205c2ebaf -r 69393cf60399 master/pdo.c --- a/master/pdo.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/pdo.c Fri Jul 04 12:06:10 2008 +0000 @@ -227,7 +227,9 @@ /*****************************************************************************/ -/** +/** Get the number of Pdo entries. + * + * \return Number of Pdo entries. */ unsigned int ec_pdo_entry_count( const ec_pdo_t *pdo /**< Pdo. */ diff -r 363205c2ebaf -r 69393cf60399 master/pdo_list.c --- a/master/pdo_list.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/pdo_list.c Fri Jul 04 12:06:10 2008 +0000 @@ -299,7 +299,9 @@ /*****************************************************************************/ -/** +/** Get the number of Pdos in the list. + * + * \return Number of Pdos. */ unsigned int ec_pdo_list_count( const ec_pdo_list_t *pl /**< Pdo list. */ diff -r 363205c2ebaf -r 69393cf60399 master/sdo_entry.h --- a/master/sdo_entry.h Fri Jul 04 12:05:21 2008 +0000 +++ b/master/sdo_entry.h Fri Jul 04 12:06:10 2008 +0000 @@ -49,7 +49,7 @@ /*****************************************************************************/ struct ec_sdo; -typedef struct ec_sdo ec_sdo_t; +typedef struct ec_sdo ec_sdo_t; /**< \see ec_sdo. */ /*****************************************************************************/ diff -r 363205c2ebaf -r 69393cf60399 master/slave.h --- a/master/slave.h Fri Jul 04 12:05:21 2008 +0000 +++ b/master/slave.h Fri Jul 04 12:06:10 2008 +0000 @@ -128,7 +128,7 @@ uint16_t base_fmmu_count; /**< Number of supported FMMUs. */ // data link status - ec_slave_port_t ports[EC_MAX_PORTS]; + ec_slave_port_t ports[EC_MAX_PORTS]; /**< Port link status. */ // SII uint16_t *sii_words; /**< Complete SII image. */ diff -r 363205c2ebaf -r 69393cf60399 master/slave_config.c --- a/master/slave_config.c Fri Jul 04 12:05:21 2008 +0000 +++ b/master/slave_config.c Fri Jul 04 12:06:10 2008 +0000 @@ -312,6 +312,10 @@ /*****************************************************************************/ +/** Get the number of Sdo configurations. + * + * \return Number of Sdo configurations. + */ unsigned int ec_slave_config_sdo_count( const ec_slave_config_t *sc /**< Slave configuration. */ )