diff --git a/TODO b/TODO
index 251624e9debb1bf3f335a5a1a3fe0be98c4da83a..0e03bac0283f6e6582e91ab9e127a555d9254e6d 100644
--- a/TODO
+++ b/TODO
@@ -45,6 +45,7 @@ Version 1.5.0:
the SDO handlers.
* Apply watchdog patches from J. Mohre.
* Move device driver files in subdirectories.
+* Document ec_fsm_foe members.
Future issues:
diff --git a/master/cdev.c b/master/cdev.c
index cf9ec7eec595651b2a3fa57cb2dec299193fa326..b798d3f7eead1b50e28f1c72ae31606568a1050b 100644
--- a/master/cdev.c
+++ b/master/cdev.c
@@ -44,6 +44,8 @@
#include "voe_handler.h"
#include "ioctl.h"
+/** Set to 1 to enable ioctl() command debugging.
+ */
#define DEBUG_IOCTL 0
/*****************************************************************************/
diff --git a/master/foe_request.c b/master/foe_request.c
index 4cce67a7e10c04886750bb68242c680b2e79d38a..dd2ca18f95820fe3dc09557dfceb24eced75ac9a 100644
--- a/master/foe_request.c
+++ b/master/foe_request.c
@@ -149,7 +149,9 @@ int ec_foe_request_copy_data(
*
* \return non-zero if the timeout was exceeded, else zero.
*/
-int ec_foe_request_timed_out(const ec_foe_request_t *req /**< FoE request. */)
+int ec_foe_request_timed_out(
+ const ec_foe_request_t *req /**< FoE request. */
+ )
{
return req->issue_timeout
&& jiffies - req->jiffies_start > HZ * req->issue_timeout / 1000;
@@ -157,28 +159,49 @@ int ec_foe_request_timed_out(const ec_foe_request_t *req /**< FoE request. */)
/*****************************************************************************/
-void ec_foe_request_timeout(ec_foe_request_t *req, uint32_t timeout)
+/** Set the request timeout.
+ */
+void ec_foe_request_timeout(
+ ec_foe_request_t *req, /**< FoE request. */
+ uint32_t timeout /**< Timeout in ms. */
+ )
{
req->issue_timeout = timeout;
}
/*****************************************************************************/
-uint8_t *ec_foe_request_data(ec_foe_request_t *req)
+/** Returns a pointer to the request's data.
+ *
+ * \return Data pointer.
+ */
+uint8_t *ec_foe_request_data(
+ ec_foe_request_t *req /**< FoE request. */
+ )
{
return req->buffer;
}
/*****************************************************************************/
-size_t ec_foe_request_data_size(const ec_foe_request_t *req)
+/** Returns the data size.
+ *
+ * \return Data size.
+ */
+size_t ec_foe_request_data_size(
+ const ec_foe_request_t *req /**< FoE request. */
+ )
{
return req->data_size;
}
/*****************************************************************************/
-void ec_foe_request_read(ec_foe_request_t *req)
+/** Prepares a read request (slave to master).
+ */
+void ec_foe_request_read(
+ ec_foe_request_t *req /**< FoE request. */
+ )
{
req->dir = EC_DIR_INPUT;
req->state = EC_INT_REQUEST_QUEUED;
@@ -188,7 +211,11 @@ void ec_foe_request_read(ec_foe_request_t *req)
/*****************************************************************************/
-void ec_foe_request_write(ec_foe_request_t *req)
+/** Prepares a write request (master to slave).
+ */
+void ec_foe_request_write(
+ ec_foe_request_t *req /**< FoE request. */
+ )
{
req->dir = EC_DIR_OUTPUT;
req->state = EC_INT_REQUEST_QUEUED;
diff --git a/master/fsm_foe.c b/master/fsm_foe.c
index e746c6879fafc1e623f57e8c3ef2f0407a30892e..6bae96177af6dd431c824fc5e0298170496541b9 100644
--- a/master/fsm_foe.c
+++ b/master/fsm_foe.c
@@ -46,8 +46,12 @@
*/
#define EC_FSM_FOE_TIMEOUT 3000
+/** Mailbox type FoE.
+ */
#define EC_MBOX_TYPE_FILEACCESS 0x04
+/** Size of the FoE header.
+ */
#define EC_FOE_HEADER_SIZE 6
// uint8_t OpCode
// uint8_t reserved
@@ -152,6 +156,8 @@ int ec_fsm_foe_success(ec_fsm_foe_t *fsm /**< Finite state machine */)
/*****************************************************************************/
+/** Prepares an FoE transfer.
+ */
void ec_fsm_foe_transfer(
ec_fsm_foe_t *fsm, /**< State machine. */
ec_slave_t *slave, /**< EtherCAT slave. */
@@ -263,7 +269,11 @@ int ec_foe_prepare_wrq_send(ec_fsm_foe_t *fsm)
/*****************************************************************************/
-void ec_fsm_foe_write(ec_fsm_foe_t *fsm /**< finite state machine */)
+/** Start a write operation.
+ */
+void ec_fsm_foe_write(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
fsm->tx_buffer = fsm->request->buffer;
fsm->tx_buffer_size = fsm->request->data_size;
@@ -276,10 +286,9 @@ void ec_fsm_foe_write(ec_fsm_foe_t *fsm /**< finite state machine */)
}
/*****************************************************************************/
-/**
- Initializes the SII write state machine.
-*/
+/** Initializes the FoE write state machine.
+ */
void ec_fsm_foe_write_start(ec_fsm_foe_t *fsm /**< finite state machine */)
{
ec_slave_t *slave = fsm->slave;
@@ -309,7 +318,11 @@ void ec_fsm_foe_write_start(ec_fsm_foe_t *fsm /**< finite state machine */)
/*****************************************************************************/
-void ec_fsm_foe_state_ack_check(ec_fsm_foe_t *fsm)
+/** Check for acknowledge.
+ */
+void ec_fsm_foe_state_ack_check(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -359,9 +372,12 @@ void ec_fsm_foe_state_ack_check(ec_fsm_foe_t *fsm)
/*****************************************************************************/
-void ec_fsm_foe_state_ack_read(ec_fsm_foe_t *fsm)
+/** Acknowledge a read operation.
+ */
+void ec_fsm_foe_state_ack_read(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
-
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
uint8_t *data, mbox_prot;
@@ -433,13 +449,15 @@ void ec_fsm_foe_state_ack_read(ec_fsm_foe_t *fsm)
}
/*****************************************************************************/
-/**
- State: WRQ SENT.
- Checks is the previous transmit datagram succeded and sends the next
- fragment, if necessary.
-*/
-void ec_fsm_foe_state_wrq_sent(ec_fsm_foe_t *fsm)
+/** State: WRQ SENT.
+ *
+ * Checks is the previous transmit datagram succeded and sends the next
+ * fragment, if necessary.
+ */
+void ec_fsm_foe_state_wrq_sent(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -474,13 +492,15 @@ void ec_fsm_foe_state_wrq_sent(ec_fsm_foe_t *fsm)
}
/*****************************************************************************/
-/**
- State: WRQ SENT.
- Checks is the previous transmit datagram succeded and sends the next
- fragment, if necessary.
-*/
-void ec_fsm_foe_state_data_sent(ec_fsm_foe_t *fsm)
+/** State: WRQ SENT.
+ *
+ * Checks is the previous transmit datagram succeded and sends the next
+ * fragment, if necessary.
+ */
+void ec_fsm_foe_state_data_sent(
+ ec_fsm_foe_t *fsm /**< Foe statemachine. */
+ )
{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -543,7 +563,11 @@ int ec_foe_prepare_rrq_send(ec_fsm_foe_t *fsm)
/*****************************************************************************/
-int ec_foe_prepare_send_ack(ec_fsm_foe_t *foe)
+/** Prepare to send an acknowledge.
+ */
+int ec_foe_prepare_send_ack(
+ ec_fsm_foe_t *foe /**< FoE statemachine. */
+ )
{
uint8_t *data;
@@ -559,13 +583,16 @@ int ec_foe_prepare_send_ack(ec_fsm_foe_t *foe)
}
/*****************************************************************************/
-/**
- State: RRQ SENT.
- Checks is the previous transmit datagram succeded and sends the next
- fragment, if necessary.
-*/
-void ec_fsm_foe_state_rrq_sent( ec_fsm_foe_t *fsm ) {
+/** State: RRQ SENT.
+ *
+ * Checks is the previous transmit datagram succeded and sends the next
+ * fragment, if necessary.
+ */
+void ec_fsm_foe_state_rrq_sent(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
+{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -600,7 +627,11 @@ void ec_fsm_foe_state_rrq_sent( ec_fsm_foe_t *fsm ) {
/*****************************************************************************/
-void ec_fsm_foe_read(ec_fsm_foe_t *fsm /**< finite state machine */)
+/** Start a read operation.
+ */
+void ec_fsm_foe_read(
+ ec_fsm_foe_t *fsm /**< FoE state machine. */
+ )
{
fsm->state = ec_fsm_foe_read_start;
fsm->rx_filename = fsm->request->file_name;
@@ -612,7 +643,11 @@ void ec_fsm_foe_read(ec_fsm_foe_t *fsm /**< finite state machine */)
/*****************************************************************************/
-void ec_fsm_foe_read_start(ec_fsm_foe_t *fsm /**< finite state machine */)
+/** Starting state for read operations.
+ */
+void ec_fsm_foe_read_start(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
size_t current_size;
ec_slave_t *slave = fsm->slave;
@@ -645,7 +680,12 @@ void ec_fsm_foe_read_start(ec_fsm_foe_t *fsm /**< finite state machine */)
/*****************************************************************************/
-void ec_fsm_foe_state_data_check ( ec_fsm_foe_t *fsm ) {
+/** Check for data.
+ */
+void ec_fsm_foe_state_data_check(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
+{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -694,7 +734,11 @@ void ec_fsm_foe_state_data_check ( ec_fsm_foe_t *fsm ) {
/*****************************************************************************/
-void ec_fsm_foe_state_data_read(ec_fsm_foe_t *fsm)
+/** Start reading data.
+ */
+void ec_fsm_foe_state_data_read(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
{
size_t rec_size;
uint8_t *data, opCode, packet_no, mbox_prot;
@@ -815,8 +859,12 @@ void ec_fsm_foe_state_data_read(ec_fsm_foe_t *fsm)
/*****************************************************************************/
-void ec_fsm_foe_state_sent_ack( ec_fsm_foe_t *fsm ) {
-
+/** Sent an acknowledge.
+ */
+void ec_fsm_foe_state_sent_ack(
+ ec_fsm_foe_t *fsm /**< FoE statemachine. */
+ )
+{
ec_datagram_t *datagram = fsm->datagram;
ec_slave_t *slave = fsm->slave;
@@ -859,7 +907,12 @@ void ec_fsm_foe_state_sent_ack( ec_fsm_foe_t *fsm ) {
/*****************************************************************************/
-void ec_foe_set_tx_error(ec_fsm_foe_t *fsm, uint32_t errorcode)
+/** Set an error code and go to the send error state.
+ */
+void ec_foe_set_tx_error(
+ ec_fsm_foe_t *fsm, /**< FoE statemachine. */
+ uint32_t errorcode /**< FoE error code. */
+ )
{
fsm->tx_errors++;
fsm->request->result = errorcode;
@@ -868,7 +921,12 @@ void ec_foe_set_tx_error(ec_fsm_foe_t *fsm, uint32_t errorcode)
/*****************************************************************************/
-void ec_foe_set_rx_error(ec_fsm_foe_t *fsm, uint32_t errorcode)
+/** Set an error code and go to the receive error state.
+ */
+void ec_foe_set_rx_error(
+ ec_fsm_foe_t *fsm, /**< FoE statemachine. */
+ uint32_t errorcode /**< FoE error code. */
+ )
{
fsm->rx_errors++;
fsm->request->result = errorcode;
diff --git a/master/fsm_foe.h b/master/fsm_foe.h
index 62362256dff6bf73136445583b7cfaa9d172cf44..2940b2d806a2adba9f986847ce5d4c3f74986a02 100644
--- a/master/fsm_foe.h
+++ b/master/fsm_foe.h
@@ -60,6 +60,8 @@ struct ec_fsm_foe {
ec_foe_request_t *request; /**< FoE request */
uint8_t toggle; /**< toggle bit for segment commands */
+ /** \cond */
+
uint32_t tx_errors;
uint8_t *tx_buffer;
uint32_t tx_buffer_size;
@@ -81,6 +83,8 @@ struct ec_fsm_foe {
uint32_t rx_last_packet;
uint8_t *rx_filename;
uint32_t rx_filename_len;
+
+ /** \endcond */
};
/*****************************************************************************/
diff --git a/master/slave.h b/master/slave.h
index aa7fb707d15cc24e1a1051b7d8fe09bc9d18e7dc..ffe9cd4d579d7c373890846f3f8236bf3a31a24c 100644
--- a/master/slave.h
+++ b/master/slave.h
@@ -124,10 +124,13 @@ struct ec_slave
ec_slave_state_t current_state; /**< Current application state. */
unsigned int error_flag; /**< Stop processing after an error. */
unsigned int force_config; /**< Force (re-)configuration. */
- uint16_t configured_rx_mailbox_offset;
- uint16_t configured_rx_mailbox_size;
- uint16_t configured_tx_mailbox_offset;
- uint16_t configured_tx_mailbox_size;
+ uint16_t configured_rx_mailbox_offset; /**< Configured receive mailbox
+ offset. */
+ uint16_t configured_rx_mailbox_size; /**< Configured receive mailbox size.
+ */
+ uint16_t configured_tx_mailbox_offset; /**< Configured send mailbox
+ offset. */
+ uint16_t configured_tx_mailbox_size; /**< Configured send mailbox size. */
// base data
uint8_t base_type; /**< Slave type. */