tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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>
authored by
Ben Dooks
and committed by
Jeff Garzik
2bdf06c0
6ff4ff06
+167
+167
Documentation/networking/dm9000.txt
+167
Documentation/networking/dm9000.txt
···
1
+
DM9000 Network driver
2
+
=====================
3
+
4
+
Copyright 2008 Simtec Electronics,
5
+
Ben Dooks <ben@simtec.co.uk> <ben-linux@fluff.org>
6
+
7
+
8
+
Introduction
9
+
------------
10
+
11
+
This file describes how to use the DM9000 platform-device based network driver
12
+
that is contained in the files drivers/net/dm9000.c and drivers/net/dm9000.h.
13
+
14
+
The driver supports three DM9000 variants, the DM9000E which is the first chip
15
+
supported as well as the newer DM9000A and DM9000B devices. It is currently
16
+
maintained and tested by Ben Dooks, who should be CC: to any patches for this
17
+
driver.
18
+
19
+
20
+
Defining the platform device
21
+
----------------------------
22
+
23
+
The 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
+
29
+
These resources should be specified in that order, as the ordering of the
30
+
two address regions is important (the driver expects these to be address
31
+
and then data).
32
+
33
+
An example from arch/arm/mach-s3c2410/mach-bast.c is:
34
+
35
+
static 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
+
53
+
static 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
+
60
+
Note the setting of the IRQ trigger flag in bast_dm9k_resource[2].flags,
61
+
as this will generate a warning if it is not present. The trigger from
62
+
the flags field will be passed to request_irq() when registering the IRQ
63
+
handler to ensure that the IRQ is setup correctly.
64
+
65
+
This shows a typical platform device, without the optional configuration
66
+
platform data supplied. The next example uses the same resources, but adds
67
+
the optional platform data to pass extra configuration data:
68
+
69
+
static struct dm9000_plat_data bast_dm9k_platdata = {
70
+
.flags = DM9000_PLATF_16BITONLY,
71
+
};
72
+
73
+
static 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
+
83
+
The platform data is defined in include/linux/dm9000.h and described below.
84
+
85
+
86
+
Platform data
87
+
-------------
88
+
89
+
Extra platform data for the DM9000 can describe the IO bus width to the
90
+
device, whether or not an external PHY is attached to the device and
91
+
the availability of an external configuration EEPROM.
92
+
93
+
The flags for the platform data .flags field are as follows:
94
+
95
+
DM9000_PLATF_8BITONLY
96
+
97
+
The IO should be done with 8bit operations.
98
+
99
+
DM9000_PLATF_16BITONLY
100
+
101
+
The IO should be done with 16bit operations.
102
+
103
+
DM9000_PLATF_32BITONLY
104
+
105
+
The IO should be done with 32bit operations.
106
+
107
+
DM9000_PLATF_EXT_PHY
108
+
109
+
The chip is connected to an external PHY.
110
+
111
+
DM9000_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
+
116
+
DM9000_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
+
128
+
PHY Link state polling
129
+
----------------------
130
+
131
+
The driver keeps track of the link state and informs the network core
132
+
about link (carrier) availablilty. This is managed by several methods
133
+
depending on the version of the chip and on which PHY is being used.
134
+
135
+
For the internal PHY, the original (and currently default) method is
136
+
to read the MII state, either when the status changes if we have the
137
+
necessary interrupt support in the chip or every two seconds via a
138
+
periodic timer.
139
+
140
+
To reduce the overhead for the internal PHY, there is now the option
141
+
of using the DM9000_FORCE_SIMPLE_PHY_POLL config, or DM9000_PLATF_SIMPLE_PHY
142
+
platform data option to read the summary information without the
143
+
expensive MII accesses. This method is faster, but does not print
144
+
as much information.
145
+
146
+
When using an external PHY, the driver currently has to poll the MII
147
+
link status as there is no method for getting an interrupt on link change.
148
+
149
+
150
+
DM9000A / DM9000B
151
+
-----------------
152
+
153
+
These chips are functionally similar to the DM9000E and are supported easily
154
+
by 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
+
163
+
ethtool
164
+
-------
165
+
166
+
The driver supports the ethtool interface for access to the driver
167
+
state information, the PHY state and the EEPROM.