doc/driver-model/UDM-net.txt

   1 The U-Boot Driver Model Project
   2 ===============================
   3 Net system analysis
   4 ===================
   5 Marek Vasut <marek.vasut@gmail.com>
   6 2012-03-03
   7
   8 I) Overview
   9 -----------
  10
  11 The networking subsystem already supports multiple devices. Therefore the
  12 conversion shall not be very hard.
  13
  14 The network subsystem is operated from net/eth.c, which tracks all registered
  15 ethernet interfaces and calls their particular functions registered via
  16 eth_register().
  17
  18 The eth_register() is called from the network driver initialization function,
  19 which in turn is called most often either from "board_net_init()" or
  20 "cpu_net_init()". This function has one important argument, which is the
  21 "struct eth_device", defined at include/net.h:
  22
  23 struct eth_device {
  24   /* DRIVER: Name of the device */
  25   char name[NAMESIZE];
  26   /* DRIVER: MAC address */
  27   unsigned char enetaddr[6];
  28   /* DRIVER: Register base address */
  29   int iobase;
  30   /* CORE: state of the device */
  31   int state;
  32
  33   /* DRIVER: Device initialization function */
  34   int  (*init) (struct eth_device*, bd_t*);
  35   /* DRIVER: Function for sending packets */
  36   int  (*send) (struct eth_device*, volatile void* packet, int length);
  37   /* DRIVER: Function for receiving packets */
  38   int  (*recv) (struct eth_device*);
  39   /* DRIVER: Function to cease operation of the device */
  40   void (*halt) (struct eth_device*);
  41   /* DRIVER: Function to send multicast packet (OPTIONAL) */
  42   int (*mcast) (struct eth_device*, u32 ip, u8 set);
  43   /* DRIVER: Function to change ethernet MAC address */
  44   int  (*write_hwaddr) (struct eth_device*);
  45   /* CORE: Next device in the linked list of devices managed by net core */
  46   struct eth_device *next;
  47   /* CORE: Device index */
  48   int index;
  49   /* DRIVER: Driver's private data */
  50   void *priv;
  51 };
  52
  53 This structure defines the particular driver, though also contains elements that
  54 should not be exposed to the driver, like core state.
  55
  56 Small, but important part of the networking subsystem is the PHY management
  57 layer, whose drivers are contained in drivers/net/phy. These drivers register in
  58 a very similar manner to network drivers, by calling "phy_register()" with the
  59 argument of "struct phy_driver":
  60
  61 struct phy_driver {
  62   /* DRIVER: Name of the PHY driver */
  63   char *name;
  64   /* DRIVER: UID of the PHY driver */
  65   unsigned int uid;
  66   /* DRIVER: Mask for UID of the PHY driver */
  67   unsigned int mask;
  68   /* DRIVER: MMDS of the PHY driver */
  69   unsigned int mmds;
  70   /* DRIVER: Features the PHY driver supports */
  71   u32 features;
  72   /* DRIVER: Initialize the PHY hardware */
  73   int (*probe)(struct phy_device *phydev);
  74   /* DRIVER: Reconfigure the PHY hardware */
  75   int (*config)(struct phy_device *phydev);
  76   /* DRIVER: Turn on the PHY hardware, allow it to send/receive */
  77   int (*startup)(struct phy_device *phydev);
  78   /* DRIVER: Turn off the PHY hardware */
  79   int (*shutdown)(struct phy_device *phydev);
  80   /* CORE: Allows this driver to be part of list of drivers */
  81   struct list_head list;
  82 };
  83
  84 II) Approach
  85 ------------
  86
  87 To convert the elements of network subsystem to proper driver model method, the
  88 "struct eth_device" will have to be split into multiple components. The first
  89 will be a structure defining the driver operations:
  90
  91 struct eth_driver_ops {
  92   int  (*init)(struct instance*, bd_t*);
  93   int  (*send)(struct instance*, void *packet, int length);
  94   int  (*recv)(struct instance*);
  95   void (*halt)(struct instance*);
  96   int  (*mcast)(struct instance*, u32 ip, u8 set);
  97   int  (*write_hwaddr)(struct instance*);
  98 };
  99
 100 Next, there'll be platform data which will be per-driver and will replace the
 101 "priv" part of "struct eth_device". Last part will be the per-device core state.
 102
 103 With regards to the PHY part of the API, the "struct phy_driver" is almost ready
 104 to be used with the new driver model approach. The only change will be the
 105 replacement of per-driver initialization functions and removal of
 106 "phy_register()" function in favor or driver model approach.
 107
 108 III) Analysis of in-tree drivers
 109 --------------------------------
 110
 111   1) drivers/net/4xx_enet.c
 112   -------------------------
 113
 114   This driver uses the standard new networking API, therefore there should be no
 115   obstacles throughout the conversion process.
 116
 117   2) drivers/net/altera_tse.c
 118   ---------------------------
 119
 120   This driver uses the standard new networking API, therefore there should be no
 121   obstacles throughout the conversion process.
 122
 123   3) drivers/net/armada100_fec.c
 124   ------------------------------
 125
 126   This driver uses the standard new networking API, therefore there should be no
 127   obstacles throughout the conversion process.
 128
 129   4) drivers/net/at91_emac.c
 130   --------------------------
 131
 132   This driver uses the standard new networking API, therefore there should be no
 133   obstacles throughout the conversion process.
 134
 135   5) drivers/net/ax88180.c
 136   ------------------------
 137
 138   This driver uses the standard new networking API, therefore there should be no
 139   obstacles throughout the conversion process.
 140
 141   6) drivers/net/ax88796.c
 142   ------------------------
 143
 144   This file contains a components of the NE2000 driver, implementing only
 145   different parts on the NE2000 clone AX88796. This being no standalone driver,
 146   no conversion will be done here.
 147
 148   7) drivers/net/bfin_mac.c
 149   -------------------------
 150
 151   This driver uses the standard new networking API, therefore there should be no
 152   obstacles throughout the conversion process.
 153
 154   8) drivers/net/calxedaxgmac.c
 155   -----------------------------
 156
 157   This driver uses the standard new networking API, therefore there should be no
 158   obstacles throughout the conversion process.
 159
 160   9) drivers/net/cs8900.c
 161   -----------------------
 162
 163   This driver uses the standard new networking API, therefore there should be no
 164   obstacles throughout the conversion process.
 165
 166   10) drivers/net/davinci_emac.c
 167   ------------------------------
 168
 169   This driver uses the standard new networking API, therefore there should be no
 170   obstacles throughout the conversion process.
 171
 172   11) drivers/net/dc2114x.c
 173   -------------------------
 174
 175   This driver uses the standard new networking API, therefore there should be no
 176   obstacles throughout the conversion process.
 177
 178   12) drivers/net/designware.c
 179   ----------------------------
 180
 181   This driver uses the standard new networking API, therefore there should be no
 182   obstacles throughout the conversion process.
 183
 184   13) drivers/net/dm9000x.c
 185   -------------------------
 186
 187   This driver uses the standard new networking API, therefore there should be no
 188   obstacles throughout the conversion process.
 189
 190   14) drivers/net/dnet.c
 191   ----------------------
 192
 193   This driver uses the standard new networking API, therefore there should be no
 194   obstacles throughout the conversion process.
 195
 196   15) drivers/net/e1000.c
 197   -----------------------
 198
 199   This driver uses the standard new networking API, therefore there should be no
 200   obstacles throughout the conversion process.
 201
 202   16) drivers/net/e1000_spi.c
 203   ---------------------------
 204
 205   Driver for the SPI bus integrated on the Intel E1000. This is not part of the
 206   network stack.
 207
 208   17) drivers/net/eepro100.c
 209   --------------------------
 210
 211   This driver uses the standard new networking API, therefore there should be no
 212   obstacles throughout the conversion process.
 213
 214   18) drivers/net/enc28j60.c
 215   --------------------------
 216
 217   This driver uses the standard new networking API, therefore there should be no
 218   obstacles throughout the conversion process.
 219
 220   19) drivers/net/ep93xx_eth.c
 221   ----------------------------
 222
 223   This driver uses the standard new networking API, therefore there should be no
 224   obstacles throughout the conversion process.
 225
 226   20) drivers/net/ethoc.c
 227   -----------------------
 228
 229   This driver uses the standard new networking API, therefore there should be no
 230   obstacles throughout the conversion process.
 231
 232   21) drivers/net/fec_mxc.c
 233   -------------------------
 234
 235   This driver uses the standard new networking API, therefore there should be no
 236   obstacles throughout the conversion process.
 237
 238   22) drivers/net/fsl_mcdmafec.c
 239   ------------------------------
 240
 241   This driver uses the standard new networking API, therefore there should be no
 242   obstacles throughout the conversion process.
 243
 244   23) drivers/net/fsl_mdio.c
 245   --------------------------
 246
 247   This file contains driver for FSL MDIO interface, which is not part of the
 248   networking stack.
 249
 250   24) drivers/net/ftgmac100.c
 251   ---------------------------
 252
 253   This driver uses the standard new networking API, therefore there should be no
 254   obstacles throughout the conversion process.
 255
 256   25) drivers/net/ftmac100.c
 257   --------------------------
 258
 259   This driver uses the standard new networking API, therefore there should be no
 260   obstacles throughout the conversion process.
 261
 262   26) drivers/net/greth.c
 263   -----------------------
 264
 265   This driver uses the standard new networking API, therefore there should be no
 266   obstacles throughout the conversion process.
 267
 268   27) drivers/net/inca-ip_sw.c
 269   ----------------------------
 270
 271   This driver uses the standard new networking API, therefore there should be no
 272   obstacles throughout the conversion process.
 273
 274   28) drivers/net/ks8695eth.c
 275   ---------------------------
 276
 277   This driver uses the standard new networking API, therefore there should be no
 278   obstacles throughout the conversion process.
 279
 280   29) drivers/net/lan91c96.c
 281   --------------------------
 282
 283   This driver uses the standard new networking API, therefore there should be no
 284   obstacles throughout the conversion process.
 285
 286   30) drivers/net/macb.c
 287   ----------------------
 288
 289   This driver uses the standard new networking API, therefore there should be no
 290   obstacles throughout the conversion process.
 291
 292   31) drivers/net/mcffec.c
 293   ------------------------
 294
 295   This driver uses the standard new networking API, therefore there should be no
 296   obstacles throughout the conversion process.
 297
 298   32) drivers/net/mcfmii.c
 299   ------------------------
 300
 301   This file contains MII interface driver for MCF FEC.
 302
 303   33) drivers/net/mpc512x_fec.c
 304   -----------------------------
 305
 306   This driver uses the standard new networking API, therefore there should be no
 307   obstacles throughout the conversion process.
 308
 309   34) drivers/net/mpc5xxx_fec.c
 310   -----------------------------
 311
 312   This driver uses the standard new networking API, therefore there should be no
 313   obstacles throughout the conversion process.
 314
 315   35) drivers/net/mvgbe.c
 316   -----------------------
 317
 318   This driver uses the standard new networking API, therefore there should be no
 319   obstacles throughout the conversion process.
 320
 321   36) drivers/net/natsemi.c
 322   -------------------------
 323
 324   This driver uses the standard new networking API, therefore there should be no
 325   obstacles throughout the conversion process.
 326
 327   37) drivers/net/ne2000_base.c
 328   -----------------------------
 329
 330   This driver uses the standard new networking API, therefore there should be no
 331   obstacles throughout the conversion process. This driver contains the core
 332   implementation of NE2000, which needs a few external functions, implemented by
 333   AX88796, NE2000 etc.
 334
 335   38) drivers/net/ne2000.c
 336   ------------------------
 337
 338   This file implements external functions necessary for native NE2000 compatible
 339   networking card to work.
 340
 341   39) drivers/net/netarm_eth.c
 342   ----------------------------
 343
 344   This driver uses the old, legacy, network API and will either have to be
 345   converted or removed.
 346
 347   40) drivers/net/netconsole.c
 348   ----------------------------
 349
 350   This is actually an STDIO driver.
 351
 352   41) drivers/net/ns8382x.c
 353   -------------------------
 354
 355   This driver uses the standard new networking API, therefore there should be no
 356   obstacles throughout the conversion process.
 357
 358   42) drivers/net/pcnet.c
 359   -----------------------
 360
 361   This driver uses the standard new networking API, therefore there should be no
 362   obstacles throughout the conversion process.
 363
 364   43) drivers/net/plb2800_eth.c
 365   -----------------------------
 366
 367   This driver uses the standard new networking API, therefore there should be no
 368   obstacles throughout the conversion process.
 369
 370   44) drivers/net/rtl8139.c
 371   -------------------------
 372
 373   This driver uses the standard new networking API, therefore there should be no
 374   obstacles throughout the conversion process.
 375
 376   45) drivers/net/rtl8169.c
 377   -------------------------
 378
 379   This driver uses the standard new networking API, therefore there should be no
 380   obstacles throughout the conversion process.
 381
 382   46) drivers/net/sh_eth.c
 383   ------------------------
 384
 385   This driver uses the standard new networking API, therefore there should be no
 386   obstacles throughout the conversion process.
 387
 388   47) drivers/net/smc91111.c
 389   --------------------------
 390
 391   This driver uses the standard new networking API, therefore there should be no
 392   obstacles throughout the conversion process.
 393
 394   48) drivers/net/smc911x.c
 395   -------------------------
 396
 397   This driver uses the standard new networking API, therefore there should be no
 398   obstacles throughout the conversion process.
 399
 400   49) drivers/net/tsec.c
 401   ----------------------
 402
 403   This driver uses the standard new networking API, therefore there should be no
 404   obstacles throughout the conversion process.
 405
 406   50) drivers/net/tsi108_eth.c
 407   ----------------------------
 408
 409   This driver uses the standard new networking API, therefore there should be no
 410   obstacles throughout the conversion process.
 411
 412   51) drivers/net/uli526x.c
 413   -------------------------
 414
 415   This driver uses the standard new networking API, therefore there should be no
 416   obstacles throughout the conversion process.
 417
 418   52) drivers/net/vsc7385.c
 419   -------------------------
 420
 421   This is a driver that only uploads firmware to a switch. This is not subject
 422   of conversion.
 423
 424   53) drivers/net/xilinx_axi_emac.c
 425   ---------------------------------
 426
 427   This driver uses the standard new networking API, therefore there should be no
 428   obstacles throughout the conversion process.
 429
 430   54) drivers/net/xilinx_emaclite.c
 431   ---------------------------------
 432
 433   This driver uses the standard new networking API, therefore there should be no
 434   obstacles throughout the conversion process.