src/include/dev.h

   1 #ifndef DEV_H
   2 #define DEV_H
   3
   4 #include "stdint.h"
   5 #include "string.h"
   6 #include "dhcp.h" /* for dhcp_dev_id */
   7
   8 /*
   9  * Forward declarations
  10  *
  11  */
  12 struct type_dev;
  13 struct type_driver;
  14 struct bus_driver;
  15 struct bus_dev;
  16 struct device_driver;
  17
  18 /*
  19  * When looking at the following data structures, mentally substitute
  20  * "<bus>_" in place of "bus_" and everything will become clear.
  21  * "struct bus_location" becomes "struct <bus>_location", which means
  22  * "the location of a device on a <bus> bus", where <bus> is a
  23  * particular type of bus such as "pci" or "isapnp".
  24  *
  25  */
  26
  27 /*
  28  * A physical device location on a bus.
  29  *
  30  */
  31 #define BUS_LOC_SIZE 8
  32 struct bus_loc {
  33         char bytes[BUS_LOC_SIZE];
  34 };
  35
  36 /*
  37  * A structure fully describing a physical device on a bus.
  38  *
  39  */
  40 #define BUS_DEV_SIZE 32
  41 struct bus_dev {
  42         char bytes[BUS_DEV_SIZE];
  43 };
  44
  45 /*
  46  * Individual buses will have different sizes for their <bus>_location
  47  * and <bus>_device structures.  We need to be able to allocate static
  48  * storage that's large enough to contain these structures for any
  49  * bus type that's being used in the current binary.
  50  *
  51  * We can't just create a union of all the various types, because some
  52  * may be architecture-dependent (and some are even embedded in
  53  * specific drivers, e.g. 3c509), so this would quickly get messy.
  54  *
  55  * We could use the magic of common symbols.  Each bus could declare a
  56  * common symbol with the name "_bus_dev" of the correct size; this
  57  * is easily done using code like
  58  *      struct pci_device _bus_dev;
  59  * The linker would then use the largest size of the "_bus_dev" symbol
  60  * in any included object, thus giving us a single _bus_dev symbol of
  61  * *exactly* the required size.  However, there's no way to extract
  62  * the size of this symbol, either directly as a linker symbol
  63  * ("_bus_dev_size = SIZEOF(_bus_dev)"; the linker language just
  64  * doesn't provide this construct) or via any linker trickery I can
  65  * think of (such as creating a special common symbol section just for
  66  * this symbol then using SIZE(section) to read the size of the
  67  * section; ld recognises only a single common symbol section called
  68  * "COMMON").
  69  *
  70  * Since there's no way to get the size of the symbol, this
  71  * effectively limits us to just one instance of the symbol.  This is
  72  * all very well for the simple case of "just boot from any single
  73  * device you can", but becomes limiting when you want to do things
  74  * like introducing PCMCIA buses (which must instantiate other devices
  75  * such as PCMCIA controllers).
  76  *
  77  * So, we declare the maximum sizes of these constructions to be
  78  * compile-time constants.  Each individual bus driver should define
  79  * its own struct <bus>_location and struct <bus>_device however it
  80  * likes, and can freely cast pointers from struct bus_loc to
  81  * struct <bus>_location (and similarly for bus_dev).  To guard
  82  * against bounding errors, each bus driver *MUST* use the macros
  83  * BUS_LOC_CHECK() and BUS_DEV_CHECK(), as in:
  84  *
  85  *   BUS_LOC_CHECK ( struct pci_location );
  86  *   BUS_DEV_CHECK ( struct pci_device );
  87  *
  88  * These macros will generate a link-time error if the size of the
  89  * <bus> structure exceeds the declared maximum size.
  90  *
  91  * The macros will generate no binary object code, but must be placed
  92  * inside a function (in order to generate syntactically valid C).
  93  * The easiest wy to do this is to place them in the
  94  * <bus>_next_location() function.
  95  *
  96  * If anyone can think of a better way of doing this that avoids *ALL*
  97  * of the problems described above, please implement it!
  98  *
  99  */
 100
 101 #define LINKER_ASSERT(test,error_symbol)                \
 102         if ( ! (test) ) {                               \
 103                 extern void error_symbol ( void );      \
 104                 error_symbol();                         \
 105         }
 106
 107 #define BUS_LOC_CHECK(datatype)                                       \
 108         LINKER_ASSERT( ( sizeof (datatype) <= sizeof (struct bus_loc) ),  \
 109                        __BUS_LOC_SIZE_is_too_small__see_dev_h )
 110 #define BUS_DEV_CHECK(datatype)                                       \
 111         LINKER_ASSERT( ( sizeof (datatype) <= sizeof (struct bus_dev) ),    \
 112                        __BUS_DEV_SIZE_is_too_small__see_dev_h )
 113
 114 /*
 115  * Bus-level operations.
 116  *
 117  * int next_location ( struct bus_loc * bus_loc )
 118  *
 119  *      Increment bus_loc to point to the next possible device on
 120  *      the bus (e.g. the next PCI busdevfn, or the next ISAPnP CSN).
 121  *      If there are no more valid locations, return 0 and leave
 122  *      struct bus_loc zeroed, otherwise return true.
 123  *
 124  * int fill_device ( struct bus_dev *bus_dev,
 125  *                   struct bus_loc *bus_loc )
 126  *
 127  *      Fill out a bus_dev structure with the parameters for the
 128  *      device at bus_loc.  (For example, fill in the PCI vendor
 129  *      and device IDs).  Return true if there is a device physically
 130  *      present at this location, otherwise 0.
 131  *
 132  * int check_driver ( struct bus_dev *bus_dev,
 133  *                    struct device_driver *device_driver )
 134  *
 135  *      Test whether or not the specified driver is capable of driving
 136  *      the specified device by, for example, comparing the device's
 137  *      PCI IDs against the list of PCI IDs claimed by the driver.
 138  *
 139  * char * describe ( struct bus_dev *bus_dev )
 140  *
 141  *      Return a text string describing the bus device bus_dev
 142  *      (e.g. "PCI 00:01.2")
 143  *
 144  * char * name ( struct bus_dev *bus_dev )
 145  *
 146  *      Return a text string describing the bus device bus_dev
 147  *      (e.g. "dfe538")
 148  *
 149  */
 150 struct bus_driver {
 151         const char *name;
 152         int ( *next_location ) ( struct bus_loc *bus_loc );
 153         int ( *fill_device ) ( struct bus_dev *bus_dev,
 154                                struct bus_loc *bus_loc );
 155         int ( *check_driver ) ( struct bus_dev *bus_dev,
 156                                 struct device_driver *device_driver );
 157         char * ( *describe_device ) ( struct bus_dev *bus_dev );
 158         const char * ( *name_device ) ( struct bus_dev *bus_dev );
 159 };
 160
 161 #define __bus_driver __attribute__ (( used, __section__ ( ".drivers.bus" ) ))
 162
 163 /*
 164  * A structure fully describing the bus-independent parts of a
 165  * particular type (e.g. nic or disk) of device.
 166  *
 167  * Unlike struct bus_dev, e can limit ourselves to having no more than
 168  * one instance of this data structure.  We therefore place an
 169  * instance in each type driver file (e.g. nic.c), and simply use a
 170  * pointer to the struct type_dev in the struct dev.
 171  *
 172  */
 173 struct type_dev;
 174
 175 /*
 176  * A type driver (e.g. nic, disk)
 177  *
 178  */
 179 struct type_driver {
 180         char *name;
 181         struct type_dev *type_dev; /* single instance */
 182         char * ( * describe_device ) ( struct type_dev *type_dev );
 183         int ( * configure ) ( struct type_dev *type_dev );
 184         int ( * load ) ( struct type_dev *type_dev,
 185                          int ( * process ) ( unsigned char *data,
 186                                              unsigned int blocknum,
 187                                              unsigned int len, int eof ) );
 188 };
 189
 190 #define __type_driver __attribute__ (( used, __section__ ( ".drivers.type" ) ))
 191
 192 /*
 193  * A driver for a device.
 194  *
 195  */
 196 struct device_driver {
 197         const char *name;
 198         struct type_driver *type_driver;
 199         struct bus_driver *bus_driver;
 200         struct bus_driver_info *bus_driver_info;
 201         int ( * probe ) ( struct type_dev *type_dev,
 202                           struct bus_dev *bus_dev );
 203         void ( * disable ) ( struct type_dev *type_dev,
 204                              struct bus_dev *bus_dev );
 205 };
 206
 207 #define __device_driver \
 208         __attribute__ (( used, __section__ ( ".drivers.device" ) ))
 209
 210 #define DRIVER(_name,_type_driver,_bus_driver,_bus_info,                      \
 211                _probe,_disable)                                               \
 212         static struct device_driver device_ ## _bus_info __device_driver = {  \
 213                 .name = _name,                                                \
 214                 .type_driver = &_type_driver,                                 \
 215                 .bus_driver = &_bus_driver,                                   \
 216                 .bus_driver_info = ( struct bus_driver_info * ) &_bus_info,   \
 217                 .probe = ( int (*) () ) _probe,                               \
 218                 .disable = ( void (*) () ) _disable,                          \
 219         };
 220
 221 /*
 222  * A bootable device, comprising a physical device on a bus, a driver
 223  * for that device, and a type device
 224  *
 225  */
 226 struct dev {
 227         struct bus_driver       *bus_driver;
 228         struct bus_loc          bus_loc;
 229         struct bus_dev          bus_dev;
 230         struct device_driver    *device_driver;
 231         struct type_driver      *type_driver;
 232         struct type_dev         *type_dev;
 233 };
 234
 235 /* The current boot device */
 236 extern struct dev dev;
 237
 238 /*
 239  * Functions in dev.c
 240  *
 241  */
 242 extern void print_drivers ( void );
 243 extern int find_any ( struct bus_driver **bus_driver, struct bus_loc *bus_loc,
 244                       struct bus_dev *bus_dev, signed int skip );
 245 extern int find_by_device ( struct device_driver **device_driver,
 246                             struct bus_driver *bus_driver,
 247                             struct bus_dev *bus_dev,
 248                             signed int skip );
 249 extern int find_by_driver ( struct bus_loc *bus_loc, struct bus_dev *bus_dev,
 250                             struct device_driver *device_driver,
 251                             signed int skip );
 252 extern int find_any_with_driver ( struct dev *dev, signed int skip );
 253
 254 /*
 255  * Functions inlined to save space
 256  *
 257  */
 258
 259 /* Probe a device */
 260 static inline int probe ( struct dev *dev ) {
 261         return dev->device_driver->probe ( dev->type_dev, &dev->bus_dev );
 262 }
 263 /* Disable a device */
 264 static inline void disable ( struct dev *dev ) {
 265         dev->device_driver->disable ( dev->type_dev, &dev->bus_dev );
 266 }
 267 /* Set the default boot device */
 268 static inline void select_device ( struct dev *dev,
 269                                    struct bus_driver *bus_driver,
 270                                    struct bus_loc *bus_loc ) {
 271         dev->bus_driver = bus_driver;
 272         memcpy ( &dev->bus_loc, bus_loc, sizeof ( dev->bus_loc ) );
 273 }
 274 /* Configure a device */
 275 static inline int configure ( struct dev *dev ) {
 276         return dev->type_driver->configure ( dev->type_dev );
 277 }
 278 /* Boot from a device */
 279 static inline int load ( struct dev *dev,
 280                          int ( * process ) ( unsigned char *data,
 281                                              unsigned int blocknum,
 282                                              unsigned int len, int eof ) ) {
 283         return dev->type_driver->load ( dev->type_dev, process );
 284 }
 285
 286 /* Linker symbols for the various tables */
 287 extern struct bus_driver bus_drivers[];
 288 extern struct bus_driver bus_drivers_end[];
 289 extern struct type_driver type_drivers[];
 290 extern struct type_driver type_drivers_end[];
 291 extern struct device_driver device_drivers[];
 292 extern struct device_driver device_drivers_end[];
 293
 294 #endif /* DEV_H */