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