Added missing documentation.
authorFlorian Pose <fp@igh-essen.com>
Mon, 26 Jun 2006 16:05:30 +0000
changeset 286 f3352378b4d4
parent 285 d6145fc87a74
child 287 529c27d9d4d7
Added missing documentation.
devices/ecdev.h
include/ecrt.h
master/canopen.c
master/ethernet.c
master/ethernet.h
master/fsm.c
master/fsm.h
master/master.h
master/module.c
master/types.h
--- a/devices/ecdev.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/devices/ecdev.h	Mon Jun 26 16:05:30 2006 +0000
@@ -55,7 +55,11 @@
 /*****************************************************************************/
 
 struct ec_device;
-typedef struct ec_device ec_device_t;
+typedef struct ec_device ec_device_t; /**< \see ec_device */
+
+/**
+   Interrupt-Service-Routine Type
+*/
 
 typedef irqreturn_t (*ec_isr_t)(int, void *, struct pt_regs *);
 
--- a/include/ecrt.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/include/ecrt.h	Mon Jun 26 16:05:30 2006 +0000
@@ -60,13 +60,13 @@
 /*****************************************************************************/
 
 struct ec_master;
-typedef struct ec_master ec_master_t;
+typedef struct ec_master ec_master_t; /**< \see ec_master */
 
 struct ec_domain;
-typedef struct ec_domain ec_domain_t;
+typedef struct ec_domain ec_domain_t; /**< \see ec_domain */
 
 struct ec_slave;
-typedef struct ec_slave ec_slave_t;
+typedef struct ec_slave ec_slave_t; /**< \see ec_slave */
 
 /**
    Initialization type for field registrations.
--- a/master/canopen.c	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/canopen.c	Mon Jun 26 16:05:30 2006 +0000
@@ -54,10 +54,6 @@
 
 /*****************************************************************************/
 
-const ec_code_msg_t sdo_abort_messages[];
-
-/*****************************************************************************/
-
 /**
    Reads 32 bit of a CANopen SDO in expedited mode.
    \return 0 in case of success, else < 0
@@ -529,25 +525,11 @@
 /*****************************************************************************/
 
 /**
-   Outputs an SDO abort message.
-*/
-
-void ec_canopen_abort_msg(uint32_t abort_code)
-{
-    const ec_code_msg_t *abort_msg;
-
-    for (abort_msg = sdo_abort_messages; abort_msg->code; abort_msg++) {
-        if (abort_msg->code == abort_code) {
-            EC_ERR("SDO abort message 0x%08X: \"%s\".\n",
-                   abort_msg->code, abort_msg->message);
-            return;
-        }
-    }
-
-    EC_ERR("Unknown SDO abort code 0x%08X.\n", abort_code);
-}
-
-/*****************************************************************************/
+   SDO abort messages.
+   The "abort SDO transfer request" supplies an abort code,
+   which can be translated to clear text. This table does
+   the mapping of the codes and messages.
+*/
 
 const ec_code_msg_t sdo_abort_messages[] = {
     {0x05030000, "Toggle bit not changed"},
@@ -586,6 +568,27 @@
     {}
 };
 
+/*****************************************************************************/
+
+/**
+   Outputs an SDO abort message.
+*/
+
+void ec_canopen_abort_msg(uint32_t abort_code)
+{
+    const ec_code_msg_t *abort_msg;
+
+    for (abort_msg = sdo_abort_messages; abort_msg->code; abort_msg++) {
+        if (abort_msg->code == abort_code) {
+            EC_ERR("SDO abort message 0x%08X: \"%s\".\n",
+                   abort_msg->code, abort_msg->message);
+            return;
+        }
+    }
+
+    EC_ERR("Unknown SDO abort code 0x%08X.\n", abort_code);
+}
+
 /******************************************************************************
  *  Realtime interface
  *****************************************************************************/
--- a/master/ethernet.c	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/ethernet.c	Mon Jun 26 16:05:30 2006 +0000
@@ -47,6 +47,14 @@
 #include "mailbox.h"
 #include "ethernet.h"
 
+/**
+   Defines the debug level of EoE processing
+
+   0 = No debug messages.
+   1 = Output actions.
+   2 = Output actions and frame data.
+*/
+
 #define EOE_DEBUG_LEVEL 0
 
 /*****************************************************************************/
--- a/master/ethernet.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/ethernet.h	Mon Jun 26 16:05:30 2006 +0000
@@ -61,7 +61,7 @@
 
 /*****************************************************************************/
 
-typedef struct ec_eoe ec_eoe_t;
+typedef struct ec_eoe ec_eoe_t; /**< \see ec_eoe */
 
 /**
    Ethernet-over-EtherCAT (EoE) handler.
--- a/master/fsm.c	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/fsm.c	Mon Jun 26 16:05:30 2006 +0000
@@ -44,10 +44,6 @@
 
 /*****************************************************************************/
 
-const ec_code_msg_t al_status_messages[];
-
-/*****************************************************************************/
-
 void ec_fsm_master_start(ec_fsm_t *);
 void ec_fsm_master_broadcast(ec_fsm_t *);
 void ec_fsm_master_proc_states(ec_fsm_t *);
@@ -1675,123 +1671,6 @@
 /*****************************************************************************/
 
 /**
-   Change state: CODE.
-*/
-
-void ec_fsm_change_code(ec_fsm_t *fsm /**< finite state machine */)
-{
-    ec_command_t *command = &fsm->command;
-    ec_slave_t *slave = fsm->slave;
-    uint32_t code;
-    const ec_code_msg_t *al_msg;
-
-    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
-        EC_ERR("Reception of AL status code command failed.\n");
-        slave->state_error = 1;
-        fsm->change_state = ec_fsm_change_error;
-        return;
-    }
-
-    if ((code = EC_READ_U16(command->data))) {
-        for (al_msg = al_status_messages; al_msg->code; al_msg++) {
-            if (al_msg->code != code) continue;
-            EC_ERR("AL status message 0x%04X: \"%s\".\n",
-                   al_msg->code, al_msg->message);
-            break;
-        }
-        if (!al_msg->code)
-            EC_ERR("Unknown AL status code 0x%04X.\n", code);
-    }
-
-    // acknowledge "old" slave state
-    ec_command_npwr(command, slave->station_address, 0x0120, 2);
-    EC_WRITE_U16(command->data, slave->current_state);
-    ec_master_queue_command(fsm->master, command);
-    fsm->change_state = ec_fsm_change_ack;
-}
-
-/*****************************************************************************/
-
-/**
-   Change state: ACK.
-*/
-
-void ec_fsm_change_ack(ec_fsm_t *fsm /**< finite state machine */)
-{
-    ec_command_t *command = &fsm->command;
-    ec_slave_t *slave = fsm->slave;
-
-    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
-        EC_ERR("Reception of state ack command failed.\n");
-        slave->state_error = 1;
-        fsm->change_state = ec_fsm_change_error;
-        return;
-    }
-
-    // read new AL status
-    ec_command_nprd(command, slave->station_address, 0x0130, 2);
-    ec_master_queue_command(fsm->master, command);
-    fsm->change_state = ec_fsm_change_ack2;
-}
-
-/*****************************************************************************/
-
-/**
-   Change state: ACK.
-   Acknowledge 2.
-*/
-
-void ec_fsm_change_ack2(ec_fsm_t *fsm /**< finite state machine */)
-{
-    ec_command_t *command = &fsm->command;
-    ec_slave_t *slave = fsm->slave;
-
-    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
-        EC_ERR("Reception of state ack check command failed.\n");
-        slave->state_error = 1;
-        fsm->change_state = ec_fsm_change_error;
-        return;
-    }
-
-    slave->current_state = EC_READ_U8(command->data);
-
-    if (slave->current_state == fsm->change_new) {
-        EC_INFO("Acknowleged state 0x%02X on slave %i.\n",
-                slave->current_state, slave->ring_position);
-        slave->state_error = 1;
-        fsm->change_state = ec_fsm_change_error;
-        return;
-    }
-
-    EC_WARN("Failed to acknowledge state 0x%02X on slave %i"
-            " - Timeout!\n", fsm->change_new, slave->ring_position);
-    slave->state_error = 1;
-    fsm->change_state = ec_fsm_change_error;
-}
-
-/*****************************************************************************/
-
-/**
-   Change state: END.
-*/
-
-void ec_fsm_change_end(ec_fsm_t *fsm /**< finite state machine */)
-{
-}
-
-/*****************************************************************************/
-
-/**
-   Change state: ERROR.
-*/
-
-void ec_fsm_change_error(ec_fsm_t *fsm /**< finite state machine */)
-{
-}
-
-/*****************************************************************************/
-
-/**
    Application layer status messages.
 */
 
@@ -1816,3 +1695,120 @@
 };
 
 /*****************************************************************************/
+
+/**
+   Change state: CODE.
+*/
+
+void ec_fsm_change_code(ec_fsm_t *fsm /**< finite state machine */)
+{
+    ec_command_t *command = &fsm->command;
+    ec_slave_t *slave = fsm->slave;
+    uint32_t code;
+    const ec_code_msg_t *al_msg;
+
+    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
+        EC_ERR("Reception of AL status code command failed.\n");
+        slave->state_error = 1;
+        fsm->change_state = ec_fsm_change_error;
+        return;
+    }
+
+    if ((code = EC_READ_U16(command->data))) {
+        for (al_msg = al_status_messages; al_msg->code; al_msg++) {
+            if (al_msg->code != code) continue;
+            EC_ERR("AL status message 0x%04X: \"%s\".\n",
+                   al_msg->code, al_msg->message);
+            break;
+        }
+        if (!al_msg->code)
+            EC_ERR("Unknown AL status code 0x%04X.\n", code);
+    }
+
+    // acknowledge "old" slave state
+    ec_command_npwr(command, slave->station_address, 0x0120, 2);
+    EC_WRITE_U16(command->data, slave->current_state);
+    ec_master_queue_command(fsm->master, command);
+    fsm->change_state = ec_fsm_change_ack;
+}
+
+/*****************************************************************************/
+
+/**
+   Change state: ACK.
+*/
+
+void ec_fsm_change_ack(ec_fsm_t *fsm /**< finite state machine */)
+{
+    ec_command_t *command = &fsm->command;
+    ec_slave_t *slave = fsm->slave;
+
+    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
+        EC_ERR("Reception of state ack command failed.\n");
+        slave->state_error = 1;
+        fsm->change_state = ec_fsm_change_error;
+        return;
+    }
+
+    // read new AL status
+    ec_command_nprd(command, slave->station_address, 0x0130, 2);
+    ec_master_queue_command(fsm->master, command);
+    fsm->change_state = ec_fsm_change_ack2;
+}
+
+/*****************************************************************************/
+
+/**
+   Change state: ACK.
+   Acknowledge 2.
+*/
+
+void ec_fsm_change_ack2(ec_fsm_t *fsm /**< finite state machine */)
+{
+    ec_command_t *command = &fsm->command;
+    ec_slave_t *slave = fsm->slave;
+
+    if (command->state != EC_CMD_RECEIVED || command->working_counter != 1) {
+        EC_ERR("Reception of state ack check command failed.\n");
+        slave->state_error = 1;
+        fsm->change_state = ec_fsm_change_error;
+        return;
+    }
+
+    slave->current_state = EC_READ_U8(command->data);
+
+    if (slave->current_state == fsm->change_new) {
+        EC_INFO("Acknowleged state 0x%02X on slave %i.\n",
+                slave->current_state, slave->ring_position);
+        slave->state_error = 1;
+        fsm->change_state = ec_fsm_change_error;
+        return;
+    }
+
+    EC_WARN("Failed to acknowledge state 0x%02X on slave %i"
+            " - Timeout!\n", fsm->change_new, slave->ring_position);
+    slave->state_error = 1;
+    fsm->change_state = ec_fsm_change_error;
+}
+
+/*****************************************************************************/
+
+/**
+   Change state: END.
+*/
+
+void ec_fsm_change_end(ec_fsm_t *fsm /**< finite state machine */)
+{
+}
+
+/*****************************************************************************/
+
+/**
+   Change state: ERROR.
+*/
+
+void ec_fsm_change_error(ec_fsm_t *fsm /**< finite state machine */)
+{
+}
+
+/*****************************************************************************/
--- a/master/fsm.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/fsm.h	Mon Jun 26 16:05:30 2006 +0000
@@ -47,9 +47,7 @@
 
 /*****************************************************************************/
 
-typedef struct ec_fsm ec_fsm_t;
-
-/*****************************************************************************/
+typedef struct ec_fsm ec_fsm_t; /**< \see ec_fsm */
 
 /**
    Finite state machine of an EtherCAT master.
--- a/master/master.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/master.h	Mon Jun 26 16:05:30 2006 +0000
@@ -115,7 +115,7 @@
     ec_fsm_t fsm; /**< master state machine */
     ec_master_mode_t mode; /**< master mode */
 
-    struct timer_list eoe_timer; /** EoE timer object */
+    struct timer_list eoe_timer; /**< EoE timer object */
     unsigned int eoe_running; /**< non-zero, if EoE processing is active. */
     struct list_head eoe_handlers; /**< Ethernet-over-EtherCAT handlers */
     spinlock_t internal_lock; /**< spinlock used in freerun mode */
--- a/master/module.c	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/module.c	Mon Jun 26 16:05:30 2006 +0000
@@ -66,9 +66,9 @@
 
 /*****************************************************************************/
 
-static int ec_master_count = 1;
-static int ec_eoe_devices = 0;
-static struct list_head ec_masters;
+static int ec_master_count = 1; /**< parameter value, number of masters */
+static int ec_eoe_devices = 0; /**< parameter value, number of EoE interf. */
+static struct list_head ec_masters; /**< list of masters */
 
 /*****************************************************************************/
 
--- a/master/types.h	Mon Jun 26 15:33:18 2006 +0000
+++ b/master/types.h	Mon Jun 26 16:05:30 2006 +0000
@@ -47,8 +47,8 @@
 
 /*****************************************************************************/
 
-#define EC_MAX_FIELDS 10
-#define EC_MAX_SYNC   16
+#define EC_MAX_FIELDS 10 /**< maximal number of data fields per sync manager */
+#define EC_MAX_SYNC   16 /**< maximal number of sync managers per type */
 
 /*****************************************************************************/