From c616179204072ba3dcf1e31aa2029fa6c2de3efe Mon Sep 17 00:00:00 2001 From: Juergen Beisert Date: Fri, 19 Oct 2007 11:58:22 +0200 Subject: doc added only --- include/driver.h | 108 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 92 insertions(+), 16 deletions(-) (limited to 'include') diff --git a/include/driver.h b/include/driver.h index 018bbacee5..c1ebe8aefc 100644 --- a/include/driver.h +++ b/include/driver.h @@ -1,3 +1,25 @@ +/* + * (C) 2007 Pengutronix, Sascha Hauer + * + * 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 +/** + * @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 -- cgit v1.2.3