From 9ec10e32a4351d4ebabbb6094fdffb787dfbe38b Mon Sep 17 00:00:00 2001
From: Florian Pose <fp@igh-essen.com>
Date: Wed, 15 Oct 2008 10:01:54 +0000
Subject: [PATCH] Maintained code docs.
---
Doxyfile.in | 2 +-
Makefile.am | 1 +
master/cdev.c | 41 ++++++++++++++++++++++++++---------------
master/fsm_master.h | 2 +-
master/voe_handler.c | 16 ++++++++++++++--
5 files changed, 43 insertions(+), 19 deletions(-)
diff --git a/Doxyfile.in b/Doxyfile.in
index 585fef53..21a1230e 100644
--- a/Doxyfile.in
+++ b/Doxyfile.in
@@ -1056,7 +1056,7 @@ INCLUDE_FILE_PATTERNS =
# undefined via #undef or recursively expanded use the := operator
# instead of the = operator.
-PREDEFINED =
+PREDEFINED = __KERNEL__
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
diff --git a/Makefile.am b/Makefile.am
index 296ac1dd..4bb631d7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -62,6 +62,7 @@ EXTRA_DIST = \
README.EoE
BUILT_SOURCES = \
+ Doxyfile \
Kbuild
modules:
diff --git a/master/cdev.c b/master/cdev.c
index 771d5eae..bebb0fc1 100644
--- a/master/cdev.c
+++ b/master/cdev.c
@@ -50,18 +50,18 @@
/*****************************************************************************/
-/** \cond */
-
-int eccdev_open(struct inode *, struct file *);
-int eccdev_release(struct inode *, struct file *);
-long eccdev_ioctl(struct file *, unsigned int, unsigned long);
-int eccdev_mmap(struct file *, struct vm_area_struct *);
+static int eccdev_open(struct inode *, struct file *);
+static int eccdev_release(struct inode *, struct file *);
+static long eccdev_ioctl(struct file *, unsigned int, unsigned long);
+static int eccdev_mmap(struct file *, struct vm_area_struct *);
static struct page *eccdev_vma_nopage(
struct vm_area_struct *, unsigned long, int *);
/*****************************************************************************/
+/** File operation callbacks for the EtherCAT character device.
+ */
static struct file_operations eccdev_fops = {
.owner = THIS_MODULE,
.open = eccdev_open,
@@ -70,21 +70,21 @@ static struct file_operations eccdev_fops = {
.mmap = eccdev_mmap
};
+/** Callbacks for a virtual memory area retrieved with ecdevc_mmap().
+ */
struct vm_operations_struct eccdev_vm_ops = {
.nopage = eccdev_vma_nopage
};
-/** \endcond */
-
/*****************************************************************************/
/** Private data structure for file handles.
*/
typedef struct {
- ec_cdev_t *cdev;
- unsigned int requested;
- uint8_t *process_data;
- size_t process_data_size;
+ ec_cdev_t *cdev; /**< Character device. */
+ unsigned int requested; /**< Master wac requested via this file handle. */
+ uint8_t *process_data; /**< Total process data area. */
+ size_t process_data_size; /**< Size of the \a process_data. */
} ec_cdev_priv_t;
/*****************************************************************************/
@@ -2563,6 +2563,11 @@ long eccdev_ioctl(struct file *filp, unsigned int cmd, unsigned long arg)
/*****************************************************************************/
+/** Memory-map callback for the EtherCAT character device.
+ *
+ * The actual mapping will be done in the eccdev_vma_nopage() callback of the
+ * virtual memory area.
+ */
int eccdev_mmap(
struct file *filp,
struct vm_area_struct *vma
@@ -2582,10 +2587,16 @@ int eccdev_mmap(
/*****************************************************************************/
+/** Page fault callback for a virtual memory area.
+ *
+ * Called at the first access on a virtual-memory area retrieved with
+ * ecdev_mmap().
+ */
struct page *eccdev_vma_nopage(
- struct vm_area_struct *vma,
- unsigned long address,
- int *type
+ struct vm_area_struct *vma, /**< Virtual memory area initialized by
+ the kernel. */
+ unsigned long address, /**< Requested virtual address. */
+ int *type /**< Type output parameter. */
)
{
unsigned long offset;
diff --git a/master/fsm_master.h b/master/fsm_master.h
index 74bbdfbf..6ff8502d 100644
--- a/master/fsm_master.h
+++ b/master/fsm_master.h
@@ -71,7 +71,7 @@ typedef struct {
ec_direction_t dir; /**< Direction. */
uint16_t offset; /**< Physical memory offset. */
size_t length; /**< Number of bytes. */
- uint8_t *data;
+ uint8_t *data; /**< Data to write / memory for read data. */
ec_internal_request_state_t state; /**< State of the request. */
} ec_phy_request_t;
diff --git a/master/voe_handler.c b/master/voe_handler.c
index 7ff9e2b1..32fa1c53 100644
--- a/master/voe_handler.c
+++ b/master/voe_handler.c
@@ -58,8 +58,6 @@
/*****************************************************************************/
-void ec_voe_handler_clear_data(ec_voe_handler_t *);
-
void ec_voe_handler_state_write_start(ec_voe_handler_t *);
void ec_voe_handler_state_write_response(ec_voe_handler_t *);
@@ -199,6 +197,8 @@ ec_request_state_t ecrt_voe_handler_execute(ec_voe_handler_t *voe)
* State functions.
*****************************************************************************/
+/** Start writing VoE data.
+ */
void ec_voe_handler_state_write_start(ec_voe_handler_t *voe)
{
ec_slave_t *slave = voe->config->slave;
@@ -234,6 +234,8 @@ void ec_voe_handler_state_write_start(ec_voe_handler_t *voe)
/*****************************************************************************/
+/** Wait for the mailbox response.
+ */
void ec_voe_handler_state_write_response(ec_voe_handler_t *voe)
{
ec_datagram_t *datagram = &voe->datagram;
@@ -282,6 +284,8 @@ void ec_voe_handler_state_write_response(ec_voe_handler_t *voe)
/*****************************************************************************/
+/** Start reading VoE data.
+ */
void ec_voe_handler_state_read_start(ec_voe_handler_t *voe)
{
ec_datagram_t *datagram = &voe->datagram;
@@ -306,6 +310,8 @@ void ec_voe_handler_state_read_start(ec_voe_handler_t *voe)
/*****************************************************************************/
+/** Check for new data in the mailbox.
+ */
void ec_voe_handler_state_read_check(ec_voe_handler_t *voe)
{
ec_datagram_t *datagram = &voe->datagram;
@@ -356,6 +362,8 @@ void ec_voe_handler_state_read_check(ec_voe_handler_t *voe)
/*****************************************************************************/
+/** Read the pending mailbox data.
+ */
void ec_voe_handler_state_read_response(ec_voe_handler_t *voe)
{
ec_datagram_t *datagram = &voe->datagram;
@@ -419,12 +427,16 @@ void ec_voe_handler_state_read_response(ec_voe_handler_t *voe)
/*****************************************************************************/
+/** Successful termination state function.
+ */
void ec_voe_handler_state_end(ec_voe_handler_t *voe)
{
}
/*****************************************************************************/
+/** Failure termination state function.
+ */
void ec_voe_handler_state_error(ec_voe_handler_t *voe)
{
}
--
GitLab