Documentation/networking/device_drivers/ethernet/davicom/dm9000.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =====================
   4 DM9000 Network driver
   5 =====================
   6
   7 Copyright 2008 Simtec Electronics,
   8
   9           Ben Dooks <ben@simtec.co.uk> <ben-linux@fluff.org>
  10
  11
  12 Introduction
  13 ------------
  14
  15 This file describes how to use the DM9000 platform-device based network driver
  16 that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h.
  17
  18 The driver supports three DM9000 variants, the DM9000E which is the first chip
  19 supported as well as the newer DM9000A and DM9000B devices. It is currently
  20 maintained and tested by Ben Dooks, who should be CC: to any patches for this
  21 driver.
  22
  23
  24 Defining the platform device
  25 ----------------------------
  26
  27 The minimum set of resources attached to the platform device are as follows:
  28
  29     1) The physical address of the address register
  30     2) The physical address of the data register
  31     3) The IRQ line the device's interrupt pin is connected to.
  32
  33 These resources should be specified in that order, as the ordering of the
  34 two address regions is important (the driver expects these to be address
  35 and then data).
  36
  37 An example from arch/arm/mach-s3c/mach-bast.c is::
  38
  39   static struct resource bast_dm9k_resource[] = {
  40         [0] = {
  41                 .start = S3C2410_CS5 + BAST_PA_DM9000,
  42                 .end   = S3C2410_CS5 + BAST_PA_DM9000 + 3,
  43                 .flags = IORESOURCE_MEM,
  44         },
  45         [1] = {
  46                 .start = S3C2410_CS5 + BAST_PA_DM9000 + 0x40,
  47                 .end   = S3C2410_CS5 + BAST_PA_DM9000 + 0x40 + 0x3f,
  48                 .flags = IORESOURCE_MEM,
  49         },
  50         [2] = {
  51                 .start = IRQ_DM9000,
  52                 .end   = IRQ_DM9000,
  53                 .flags = IORESOURCE_IRQ | IORESOURCE_IRQ_HIGHLEVEL,
  54         }
  55   };
  56
  57   static struct platform_device bast_device_dm9k = {
  58         .name           = "dm9000",
  59         .id             = 0,
  60         .num_resources  = ARRAY_SIZE(bast_dm9k_resource),
  61         .resource       = bast_dm9k_resource,
  62   };
  63
  64 Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags,
  65 as this will generate a warning if it is not present. The trigger from
  66 the flags field will be passed to request_irq() when registering the IRQ
  67 handler to ensure that the IRQ is setup correctly.
  68
  69 This shows a typical platform device, without the optional configuration
  70 platform data supplied. The next example uses the same resources, but adds
  71 the optional platform data to pass extra configuration data::
  72
  73   static struct dm9000_plat_data bast_dm9k_platdata = {
  74         .flags          = DM9000_PLATF_16BITONLY,
  75   };
  76
  77   static struct platform_device bast_device_dm9k = {
  78         .name           = "dm9000",
  79         .id             = 0,
  80         .num_resources  = ARRAY_SIZE(bast_dm9k_resource),
  81         .resource       = bast_dm9k_resource,
  82         .dev            = {
  83                 .platform_data = &bast_dm9k_platdata,
  84         }
  85   };
  86
  87 The platform data is defined in include/linux/dm9000.h and described below.
  88
  89
  90 Platform data
  91 -------------
  92
  93 Extra platform data for the DM9000 can describe the IO bus width to the
  94 device, whether or not an external PHY is attached to the device and
  95 the availability of an external configuration EEPROM.
  96
  97 The flags for the platform data .flags field are as follows:
  98
  99 DM9000_PLATF_8BITONLY
 100
 101         The IO should be done with 8bit operations.
 102
 103 DM9000_PLATF_16BITONLY
 104
 105         The IO should be done with 16bit operations.
 106
 107 DM9000_PLATF_32BITONLY
 108
 109         The IO should be done with 32bit operations.
 110
 111 DM9000_PLATF_EXT_PHY
 112
 113         The chip is connected to an external PHY.
 114
 115 DM9000_PLATF_NO_EEPROM
 116
 117         This can be used to signify that the board does not have an
 118         EEPROM, or that the EEPROM should be hidden from the user.
 119
 120 DM9000_PLATF_SIMPLE_PHY
 121
 122         Switch to using the simpler PHY polling method which does not
 123         try and read the MII PHY state regularly. This is only available
 124         when using the internal PHY. See the section on link state polling
 125         for more information.
 126
 127         The config symbol DM9000_FORCE_SIMPLE_PHY_POLL, Kconfig entry
 128         "Force simple NSR based PHY polling" allows this flag to be
 129         forced on at build time.
 130
 131
 132 PHY Link state polling
 133 ----------------------
 134
 135 The driver keeps track of the link state and informs the network core
 136 about link (carrier) availability. This is managed by several methods
 137 depending on the version of the chip and on which PHY is being used.
 138
 139 For the internal PHY, the original (and currently default) method is
 140 to read the MII state, either when the status changes if we have the
 141 necessary interrupt support in the chip or every two seconds via a
 142 periodic timer.
 143
 144 To reduce the overhead for the internal PHY, there is now the option
 145 of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY
 146 platform data option to read the summary information without the
 147 expensive MII accesses. This method is faster, but does not print
 148 as much information.
 149
 150 When using an external PHY, the driver currently has to poll the MII
 151 link status as there is no method for getting an interrupt on link change.
 152
 153
 154 DM9000A / DM9000B
 155 -----------------
 156
 157 These chips are functionally similar to the DM9000E and are supported easily
 158 by the same driver. The features are:
 159
 160    1) Interrupt on internal PHY state change. This means that the periodic
 161       polling of the PHY status may be disabled on these devices when using
 162       the internal PHY.
 163
 164    2) TCP/UDP checksum offloading, which the driver does not currently support.
 165
 166
 167 ethtool
 168 -------
 169
 170 The driver supports the ethtool interface for access to the driver
 171 state information, the PHY state and the EEPROM.