Improved source code doc.
authorFlorian Pose <fp@igh-essen.com>
Fri, 04 Jul 2008 12:06:10 +0000
changeset 1092 69393cf60399
parent 1091 363205c2ebaf
child 1093 f34cc6fa4a73
Improved source code doc.
include/ecrt.h
master/cdev.c
master/domain.c
master/fsm_coe.c
master/master.c
master/pdo.c
master/pdo_list.c
master/sdo_entry.h
master/slave.h
master/slave_config.c
--- 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(
--- 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;
--- 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;
     }
--- 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 */
--- 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) {
--- 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. */
--- 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. */
--- 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. */
 
 /*****************************************************************************/
 
--- 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. */
--- 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. */
         )