include/driver.h

   1 /*
   2  * (C) 2007 Pengutronix, Sascha Hauer <s.hauer@pengutronix.de>
   3  *
   4  * See file CREDITS for list of people who contributed to this
   5  * project.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of
  10  * the License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  20  * MA 02111-1307 USA
  21  */
  22
  23 #ifndef DRIVER_H
  24 #define DRIVER_H
  25
  26 #include <linux/list.h>
  27
  28 #define MAX_DRIVER_NAME 32
  29
  30 #include <param.h>
  31
  32 /**
  33  * @file
  34  * @brief Main description of the device/driver model
  35  */
  36
  37 /** @page driver_model Main description of the device/driver model
  38  *
  39  * We follow a rather simplistic driver model here. There is a
  40  * @code struct device_d @endcode
  41  * which describes a particular device present in the system.
  42  *
  43  * On the other side a
  44  * @code struct driver_d @endcode
  45  * represents a driver present in the system.
  46  *
  47  * Both structs find together via the members 'type' (int) and 'name' (char *).
  48  * If both members match, the driver's probe function is called with the
  49  * struct device_d as argument.
  50  *
  51  * People familiar with the Linux platform bus will recognize this behaviour
  52  * and in fact many things were stolen from there. Some selected members of the
  53  * structs will be described in this document.
  54  */
  55
  56 /*@{*/  /* do not delete, doxygen relevant */
  57
  58 struct filep;
  59 struct bus_type;
  60
  61 /** @brief Describes a particular device present in the system */
  62 struct device_d {
  63         /*! This member (and 'type' described below) is used to match with a
  64          * driver. This is a descriptive name and could be MPC5XXX_ether or
  65          * imx_serial. */
  66         char name[MAX_DRIVER_NAME];
  67         /*! The id is used to uniquely identify a device in the system. The id
  68          * will show up under /dev/ as the device's name. Usually this is
  69          * something like eth0 or nor0. */
  70         int id;
  71
  72         resource_size_t size;
  73
  74         /*! For devices which are directly mapped into memory, i.e. NOR
  75          * Flash or SDRAM. */
  76         resource_size_t map_base;
  77
  78         void *platform_data; /*! board specific information about this device */
  79
  80         /*! Devices of a particular class normaly need to store more
  81          * information than struct device holds.
  82          */
  83         void *priv;
  84         void *type_data;     /*! In case this device is a specific device, this pointer
  85                               * points to the type specific device, i.e. eth_device
  86                               */
  87         struct driver_d *driver; /*! The driver for this device */
  88
  89         struct list_head list;     /* The list of all devices */
  90         struct list_head children; /* our children            */
  91         struct list_head sibling;
  92         struct list_head active;   /* The list of all devices which have a driver */
  93
  94         struct device_d *parent;   /* our parent, NULL if not present */
  95
  96         struct bus_type *bus;
  97
  98         /*! The parameters for this device. This is used to carry information
  99          * of board specific data from the board code to the device driver. */
 100         struct list_head parameters;
 101
 102         struct list_head cdevs;
 103 };
 104
 105 /** @brief Describes a driver present in the system */
 106 struct driver_d {
 107         /*! The name of this driver. Used to match to
 108          * the corresponding device. */
 109         char name[MAX_DRIVER_NAME];
 110
 111         struct list_head list;
 112
 113         /*! Called if an instance of a device is found */
 114         int     (*probe) (struct device_d *);
 115
 116         /*! Called if an instance of a device is gone. */
 117         void     (*remove)(struct device_d *);
 118
 119         void    (*info) (struct device_d *);
 120         void    (*shortinfo) (struct device_d *);
 121
 122         unsigned long type;
 123         struct bus_type *bus;
 124
 125         /*! This is somewhat redundant with the type data in struct device.
 126          * Currently the filesystem implementation uses this field while
 127          * ethernet drivers use the same field in struct device. Probably
 128          * one of both should be removed. */
 129         void *type_data;
 130 };
 131
 132 /*@}*/  /* do not delete, doxygen relevant */
 133
 134 #define RW_SIZE(x)      (x)
 135 #define RW_SIZE_MASK    0x7
 136
 137 /* Register devices and drivers.
 138  */
 139 int register_driver(struct driver_d *);
 140 int register_device(struct device_d *);
 141
 142 /* Unregister a device. This function can fail, e.g. when the device
 143  * has children.
 144  */
 145 int unregister_device(struct device_d *);
 146
 147 /* Organize devices in a tree. These functions do _not_ register or
 148  * unregister a device. Only registered devices are allowed here.
 149  */
 150 int dev_add_child(struct device_d *dev, struct device_d *child);
 151
 152 /* Iterate over a devices children
 153  */
 154 #define device_for_each_child(dev, child) \
 155         list_for_each_entry(child, &dev->children, sibling)
 156
 157 /* Iterate over a devices children - Safe against removal version
 158  */
 159 #define device_for_each_child_safe(dev, tmpdev, child) \
 160         list_for_each_entry_safe(child, tmpdev, &dev->children, sibling)
 161
 162 /* Iterate through the devices of a given type. if last is NULL, the
 163  * first device of this type is returned. Put this pointer in as
 164  * 'last' to get the next device. This functions returns NULL if no
 165  * more devices are found.
 166  */
 167 struct device_d *get_device_by_type(ulong type, struct device_d *last);
 168 struct device_d *get_device_by_id(const char *id);
 169 struct device_d *get_device_by_name(const char *name);
 170
 171 /* Find a free device id from the given template. This is archieved by
 172  * appending a number to the template. Dynamically created devices should
 173  * use this function rather than filling the id field themselves.
 174  */
 175 int get_free_deviceid(const char *name_template);
 176
 177 char *deviceid_from_spec_str(const char *str, char **endp);
 178
 179 static inline const char *dev_name(const struct device_d *dev)
 180 {
 181         return dev->name;
 182 }
 183
 184 /* linear list over all available devices
 185  */
 186 extern struct list_head device_list;
 187
 188 /* linear list over all available drivers
 189  */
 190 extern struct list_head driver_list;
 191
 192 /* Iterate over all devices
 193  */
 194 #define for_each_device(dev) list_for_each_entry(dev, &device_list, list)
 195
 196 /* Iterate over all drivers
 197  */
 198 #define for_each_driver(drv) list_for_each_entry(drv, &driver_list, list)
 199
 200 /* Find a driver with the given name. Currently the filesystem implementation
 201  * uses this to get the driver from the name the user specifies with the
 202  * mount command
 203  */
 204 struct driver_d *get_driver_by_name(const char *name);
 205
 206 struct cdev;
 207
 208 int     dev_protect(struct device_d *dev, size_t count, unsigned long offset, int prot);
 209
 210 /* These are used by drivers which work with direct memory accesses */
 211 ssize_t mem_read(struct cdev *cdev, void *buf, size_t count, ulong offset, ulong flags);
 212 ssize_t mem_write(struct cdev *cdev, const void *buf, size_t count, ulong offset, ulong flags);
 213 int mem_memmap(struct cdev *cdev, void **map, int flags);
 214
 215 /* Use this if you have nothing to do in your drivers probe function */
 216 int dummy_probe(struct device_d *);
 217
 218 /* Iterate over all activated devices (i.e. the ones with drivers and shut
 219  * them down.
 220  */
 221 void devices_shutdown(void);
 222
 223 int generic_memmap_ro(struct cdev *dev, void **map, int flags);
 224 int generic_memmap_rw(struct cdev *dev, void **map, int flags);
 225
 226 static inline off_t dev_lseek_default(struct cdev *cdev, off_t ofs)
 227 {
 228         return ofs;
 229 }
 230
 231 static inline int dev_open_default(struct device_d *dev, struct filep *f)
 232 {
 233         return 0;
 234 }
 235
 236 static inline int dev_close_default(struct device_d *dev, struct filep *f)
 237 {
 238         return 0;
 239 }
 240
 241 /* debugging and troubleshooting/diagnostic helpers. */
 242 extern const char *dev_id(const struct device_d *dev);
 243
 244 #define dev_printf(dev, format, arg...) \
 245         printf("%s@%s: " format , dev_name(dev) , \
 246                dev_id(dev) , ## arg)
 247
 248 #define dev_emerg(dev, format, arg...)          \
 249         dev_printf((dev) , format , ## arg)
 250 #define dev_alert(dev, format, arg...)          \
 251         dev_printf((dev) , format , ## arg)
 252 #define dev_crit(dev, format, arg...)           \
 253         dev_printf((dev) , format , ## arg)
 254 #define dev_err(dev, format, arg...)            \
 255         dev_printf(dev , format , ## arg)
 256 #define dev_warn(dev, format, arg...)           \
 257         dev_printf((dev) , format , ## arg)
 258 #define dev_notice(dev, format, arg...)         \
 259         dev_printf((dev) , format , ## arg)
 260 #define dev_info(dev, format, arg...)           \
 261         dev_printf((dev) , format , ## arg)
 262
 263 #if defined(DEBUG)
 264 #define dev_dbg(dev, format, arg...)            \
 265         dev_printf((dev) , format , ## arg)
 266 #else
 267 #define dev_dbg(dev, format, arg...)            \
 268         ({ if (0) dev_printf((dev), format, ##arg); 0; })
 269 #endif
 270
 271 struct bus_type {
 272         char *name;
 273         int (*match)(struct device_d *dev, struct driver_d *drv);
 274         int (*probe)(struct device_d *dev);
 275         void (*remove)(struct device_d *dev);
 276
 277         struct list_head list;
 278 };
 279
 280 extern struct bus_type platform_bus;
 281
 282 struct file_operations {
 283         /*! Called in response of reading from this device. Required */
 284         ssize_t (*read)(struct cdev*, void* buf, size_t count, ulong offset, ulong flags);
 285
 286         /*! Called in response of write to this device. Required */
 287         ssize_t (*write)(struct cdev*, const void* buf, size_t count, ulong offset, ulong flags);
 288
 289         int (*ioctl)(struct cdev*, int, void *);
 290         off_t (*lseek)(struct cdev*, off_t);
 291         int (*open)(struct cdev*, struct filep*);
 292         int (*close)(struct cdev*, struct filep*);
 293         int (*erase)(struct cdev*, size_t count, unsigned long offset);
 294         int (*protect)(struct cdev*, size_t count, unsigned long offset, int prot);
 295         int (*memmap)(struct cdev*, void **map, int flags);
 296 };
 297
 298 struct cdev {
 299         struct file_operations *ops;
 300         void *priv;
 301         struct device_d *dev;
 302         struct list_head list;
 303         struct list_head devices_list;
 304         char *name;
 305         unsigned long offset;
 306         size_t size;
 307         unsigned int flags;
 308         int open;
 309         struct mtd_info *mtd;
 310 };
 311
 312 int devfs_create(struct cdev *);
 313 int devfs_remove(struct cdev *);
 314 struct cdev *cdev_by_name(const char *filename);
 315 ssize_t cdev_read(struct cdev *cdev, void *buf, size_t count, ulong offset, ulong flags);
 316 ssize_t cdev_write(struct cdev *cdev, const void *buf, size_t count, ulong offset, ulong flags);
 317
 318 #define DEVFS_PARTITION_FIXED           (1 << 0)
 319 #define DEVFS_PARTITION_READONLY        (1 << 1)
 320 #define DEVFS_IS_PARTITION              (1 << 2)
 321 #define DEVFS_RDWR                      (1 << 3)
 322
 323 int devfs_add_partition(const char *devname, unsigned long offset, size_t size,
 324                 int flags, const char *name);
 325 int devfs_del_partition(const char *name);
 326
 327 struct memory_platform_data {
 328         char *name;
 329         unsigned int flags;
 330 };
 331
 332 #endif /* DRIVER_H */
 333