doc/driver-model/UDM-net.txt

The U-Boot Driver Model Project
===============================
Net system analysis
===================
Marek Vasut <marek.vasut@gmail.com>
2012-03-03

I) Overview
-----------

The networking subsystem already supports multiple devices. Therefore the
conversion shall not be very hard.

The network subsystem is operated from net/eth.c, which tracks all registered
ethernet interfaces and calls their particular functions registered via
eth_register().

The eth_register() is called from the network driver initialization function,
which in turn is called most often either from "board_net_init()" or
"cpu_net_init()". This function has one important argument, which is the
"struct eth_device", defined at include/net.h:

struct eth_device {
  /* DRIVER: Name of the device */
  char name[NAMESIZE];
  /* DRIVER: MAC address */
  unsigned char enetaddr[6];
  /* DRIVER: Register base address */
  int iobase;
  /* CORE: state of the device */
  int state;

  /* DRIVER: Device initialization function */
  int  (*init) (struct eth_device*, bd_t*);
  /* DRIVER: Function for sending packets */
  int  (*send) (struct eth_device*, volatile void* packet, int length);
  /* DRIVER: Function for receiving packets */
  int  (*recv) (struct eth_device*);
  /* DRIVER: Function to cease operation of the device */
  void (*halt) (struct eth_device*);
  /* DRIVER: Function to send multicast packet (OPTIONAL) */
  int (*mcast) (struct eth_device*, u32 ip, u8 set);
  /* DRIVER: Function to change ethernet MAC address */
  int  (*write_hwaddr) (struct eth_device*);
  /* CORE: Next device in the linked list of devices managed by net core */
  struct eth_device *next;
  /* CORE: Device index */
  int index;
  /* DRIVER: Driver's private data */
  void *priv;
};

This structure defines the particular driver, though also contains elements that
should not be exposed to the driver, like core state.

Small, but important part of the networking subsystem is the PHY management
layer, whose drivers are contained in drivers/net/phy. These drivers register in
a very similar manner to network drivers, by calling "phy_register()" with the
argument of "struct phy_driver":

struct phy_driver {
  /* DRIVER: Name of the PHY driver */
  char *name;
  /* DRIVER: UID of the PHY driver */
  unsigned int uid;
  /* DRIVER: Mask for UID of the PHY driver */
  unsigned int mask;
  /* DRIVER: MMDS of the PHY driver */
  unsigned int mmds;
  /* DRIVER: Features the PHY driver supports */
  u32 features;
  /* DRIVER: Initialize the PHY hardware */
  int (*probe)(struct phy_device *phydev);
  /* DRIVER: Reconfigure the PHY hardware */
  int (*config)(struct phy_device *phydev);
  /* DRIVER: Turn on the PHY hardware, allow it to send/receive */
  int (*startup)(struct phy_device *phydev);
  /* DRIVER: Turn off the PHY hardware */
  int (*shutdown)(struct phy_device *phydev);
  /* CORE: Allows this driver to be part of list of drivers */
  struct list_head list;
};

II) Approach
------------

To convert the elements of network subsystem to proper driver model method, the
"struct eth_device" will have to be split into multiple components. The first
will be a structure defining the driver operations:

struct eth_driver_ops {
  int  (*init)(struct instance*, bd_t*);
  int  (*send)(struct instance*, void *packet, int length);
  int  (*recv)(struct instance*);
  void (*halt)(struct instance*);
  int  (*mcast)(struct instance*, u32 ip, u8 set);
  int  (*write_hwaddr)(struct instance*);
};

Next, there'll be platform data which will be per-driver and will replace the
"priv" part of "struct eth_device". Last part will be the per-device core state.

With regards to the PHY part of the API, the "struct phy_driver" is almost ready
to be used with the new driver model approach. The only change will be the
replacement of per-driver initialization functions and removal of
"phy_register()" function in favor or driver model approach.

III) Analysis of in-tree drivers
--------------------------------

  drivers/net/4xx_enet.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/altera_tse.c
  ------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/armada100_fec.c
  ---------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/at91_emac.c
  -----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ax88180.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ax88796.c
  ---------------------

  This file contains a components of the NE2000 driver, implementing only
  different parts on the NE2000 clone AX88796. This being no standalone driver,
  no conversion will be done here.

  drivers/net/bfin_mac.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/calxedaxgmac.c
  --------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/cs8900.c
  --------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/davinci_emac.c
  --------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/dc2114x.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/designware.c
  ------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/dm9000x.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/dnet.c
  ------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/e1000.c
  -------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/e1000_spi.c
  -----------------------

  Driver for the SPI bus integrated on the Intel E1000. This is not part of the
  network stack.

  drivers/net/eepro100.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/enc28j60.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ep93xx_eth.c
  ------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ethoc.c
  -------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/fec_mxc.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/fsl_mcdmafec.c
  --------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/fsl_mdio.c
  ----------------------

  This file contains driver for FSL MDIO interface, which is not part of the
  networking stack.

  drivers/net/ftgmac100.c
  -----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ftmac100.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/greth.c
  -------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/inca-ip_sw.c
  ------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ks8695eth.c
  -----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/lan91c96.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/macb.c
  ------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/mcffec.c
  --------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/mcfmii.c
  --------------------

  This file contains MII interface driver for MCF FEC.

  drivers/net/mpc512x_fec.c
  -------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/mpc5xxx_fec.c
  -------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/mvgbe.c
  -------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/natsemi.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/ne2000_base.c
  -------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process. This driver contains the core
  implementation of NE2000, which needs a few external functions, implemented by
  AX88796, NE2000 etc.

  drivers/net/ne2000.c
  --------------------

  This file implements external functions necessary for native NE2000 compatible
  networking card to work.

  drivers/net/netconsole.c
  ------------------------

  This is actually an STDIO driver.

  drivers/net/ns8382x.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/pcnet.c
  -------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/plb2800_eth.c
  -------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/rtl8139.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/rtl8169.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/sh_eth.c
  --------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/smc91111.c
  ----------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/smc911x.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/tsec.c
  ------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/tsi108_eth.c
  ------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/uli526x.c
  ---------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/vsc7385.c
  ---------------------

  This is a driver that only uploads firmware to a switch. This is not subject
  of conversion.

  drivers/net/xilinx_axi_emac.c
  -----------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.

  drivers/net/xilinx_emaclite.c
  -----------------------------

  This driver uses the standard new networking API, therefore there should be no
  obstacles throughout the conversion process.