1.. SPDX-License-Identifier: GPL-2.0
2
3=====================
4DM9000 Network driver
5=====================
6
7Copyright 2008 Simtec Electronics,
8
9	  Ben Dooks <ben@simtec.co.uk> <ben-linux@fluff.org>
10
11
12Introduction
13------------
14
15This file describes how to use the DM9000 platform-device based network driver
16that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h.
17
18The driver supports three DM9000 variants, the DM9000E which is the first chip
19supported as well as the newer DM9000A and DM9000B devices. It is currently
20maintained and tested by Ben Dooks, who should be CC: to any patches for this
21driver.
22
23
24Defining the platform device
25----------------------------
26
27The 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
33These resources should be specified in that order, as the ordering of the
34two address regions is important (the driver expects these to be address
35and then data).
36
37An 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
64Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags,
65as this will generate a warning if it is not present. The trigger from
66the flags field will be passed to request_irq() when registering the IRQ
67handler to ensure that the IRQ is setup correctly.
68
69This shows a typical platform device, without the optional configuration
70platform data supplied. The next example uses the same resources, but adds
71the 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
87The platform data is defined in include/linux/dm9000.h and described below.
88
89
90Platform data
91-------------
92
93Extra platform data for the DM9000 can describe the IO bus width to the
94device, whether or not an external PHY is attached to the device and
95the availability of an external configuration EEPROM.
96
97The flags for the platform data .flags field are as follows:
98
99DM9000_PLATF_8BITONLY
100
101	The IO should be done with 8bit operations.
102
103DM9000_PLATF_16BITONLY
104
105	The IO should be done with 16bit operations.
106
107DM9000_PLATF_32BITONLY
108
109	The IO should be done with 32bit operations.
110
111DM9000_PLATF_EXT_PHY
112
113	The chip is connected to an external PHY.
114
115DM9000_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
120DM9000_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
132PHY Link state polling
133----------------------
134
135The driver keeps track of the link state and informs the network core
136about link (carrier) availability. This is managed by several methods
137depending on the version of the chip and on which PHY is being used.
138
139For the internal PHY, the original (and currently default) method is
140to read the MII state, either when the status changes if we have the
141necessary interrupt support in the chip or every two seconds via a
142periodic timer.
143
144To reduce the overhead for the internal PHY, there is now the option
145of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY
146platform data option to read the summary information without the
147expensive MII accesses. This method is faster, but does not print
148as much information.
149
150When using an external PHY, the driver currently has to poll the MII
151link status as there is no method for getting an interrupt on link change.
152
153
154DM9000A / DM9000B
155-----------------
156
157These chips are functionally similar to the DM9000E and are supported easily
158by 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
167ethtool
168-------
169
170The driver supports the ethtool interface for access to the driver
171state information, the PHY state and the EEPROM.
172