| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
===================== |
| 4 |
DM9000 Network driver |
| 5 |
===================== |
| 6 |
|
| 7 |
Copyright 2008 Simtec Electronics, |
| 8 |
|
| 9 |
Ben Dooks <[email protected]> <[email protected]> |
| 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. |