doc added only

include/driver.h

@@ -1,3 +1,25 @@
+/*
+ * (C) 2007 Pengutronix, Sascha Hauer <s.hauer@pengutronix.de>
+ *
+ * See file CREDITS for list of people who contributed to this
+ * project.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ * MA 02111-1307 USA
+ */
+
 #ifndef DRIVER_H
 #define DRIVER_H
 
@@ -16,44 +38,93 @@
 
 #include <param.h>
 
+/**
+ * @file
+ * @brief Main description of the device/driver model
+ */
+/** @defgroup driver_model Main description of the device/driver model
+ *
+ * We follow a rather simplistic driver model here. There is a
+ * @code struct device_d @endcode
+ * which describes a particular device present in the system. A
+ * @code struct driver_d @endcode
+ * represents a driver present in the system.
+ *
+ * Both structs find together via the members 'type' (int) and 'name' (char *).
+ * If both members match, the driver's probe function is called with the
+ * struct device_d as argument.
+ *
+ * People familiar with the Linux platform bus will recognize this behaviour
+ * and in fact many things were stolen from there. Some selected members of the
+ * structs will be described in this document.
+ */
+
+/*@{*/	/* do not delete, doxygen relevant */
+
+/** @brief Describes a particular device present in the system */
 struct device_d {
-	char name[MAX_DRIVER_NAME]; /* The name of this device. Used to match
-				     * to the corresponding driver.
-				     */
+	/*! This member (and 'type' described below) is used to match with a
+	 * driver. This is a descriptive name and could be MPC5XXX_ether or
+	 * imx_serial. */
+	char name[MAX_DRIVER_NAME];
+	/*! The id is used to uniquely identify a device in the system. The id
+	 * will show up under /dev/ as the device's name. Usually this is
+	 * something like eth0 or nor0. */
 	char id[MAX_DRIVER_NAME];
 
+	/*! FIXME */
 	unsigned long size;
 
-	/* For devices which are directly mapped into memory, i.e. NOR Flash or
-	 * SDRAM.
-	 */
+	/*! For devices which are directly mapped into memory, i.e. NOR
+	 * Flash or SDRAM. */
 	unsigned long map_base;
 
-	void *platform_data; /* board specific information about this device */
-	void *priv;          /* data private to the driver */
-	void *type_data;     /* In case this device is a specific device, this pointer
+	void *platform_data; /*! board specific information about this device */
+
+	/*! Devices of a particular class normaly need to store more
+	 * information than struct device holds. This entry holds a pointer to
+	 * the type specific struct, so a a device of type DEVICE_TYPE_ETHER
+	 * sets this to a struct eth_device. */
+	void *priv;
+	void *type_data;     /*! In case this device is a specific device, this pointer
 			      * points to the type specific device, i.e. eth_device
 			      */
 
-	struct driver_d *driver; /* The driver for this device */
+	struct driver_d *driver; /*! The driver for this device */
 
 	struct list_head list;
 
+	/*! This describes the type (or class) of this device. Have a look at
+	 * include/driver.h to see a list of known device types. Currently this
+	 * includes DEVICE_TYPE_ETHER, DEVICE_TYPE_CONSOLE and others. */
 	unsigned long type;
 
+	/*! The parameters for this device. This is used to carry information
+	 * of board specific data from the board code to the device driver. */
 	struct param_d *param;
 };
 
+/** @brief Describes a driver present in the system */
 struct driver_d {
-	char name[MAX_DRIVER_NAME]; /* The name of this driver. Used to match to
-				     * the corresponding device.
-				     */
+	/*! The name of this driver. Used to match to
+	 * the corresponding device. */
+	char name[MAX_DRIVER_NAME];
+
 	struct list_head list;
 
+	/*! Called if an instance of a device is found */
 	int     (*probe) (struct device_d *);
+
+	/*! Called if an instance of a device is gone. */
 	int     (*remove)(struct device_d *);
+
+	/*! Called in response of reading from this device. Required */
 	ssize_t (*read)  (struct device_d*, void* buf, size_t count, ulong offset, ulong flags);
+
+	/*! Called in response of write to this device. Required */
 	ssize_t (*write) (struct device_d*, const void* buf, size_t count, ulong offset, ulong flags);
+
+
 	int     (*erase) (struct device_d*, size_t count, unsigned long offset);
 	int     (*protect)(struct device_d*, size_t count, unsigned long offset, int prot);
 	int     (*memmap)(struct device_d*, void **map, int flags);
@@ -62,11 +133,16 @@ struct driver_d {
 	void    (*shortinfo) (struct device_d *);
 
 	unsigned long type;
-	void *type_data; /* In case this driver is of a specific type, i.e. a filesystem
-			  * driver, this pointer points to the corresponding data struct
-			  */
+
+	/*! This is somewhat redundant with the type data in struct device.
+	 * Currently the filesystem implementation uses this field while
+	 * ethernet drivers use the same field in struct device. Probably
+	 * one of both should be removed. */
+	void *type_data;
 };
 
+/*@}*/	/* do not delete, doxygen relevant */
+
 #define RW_SIZE(x)      (x)
 #define RW_SIZE_MASK    0x7