Doug / smarc-fsl-linux-kernel | Embedian Git Server

Commit 2bdf06c047d0bf7baa629b9074086e5338bd2b60

Authored by Ben Dooks 2008-06-25 05:16:08 +0800

Committed by Jeff Garzik 2008-06-25 10:58:39 +0800

Exists in master and in 7 other branches

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>

Showing 1 changed file with 167 additions and 0 deletions Side-by-side Diff

Documentation/networking/dm9000.txt

Documentation/networking/dm9000.txt

Diff comments View file @ 2bdf06c

	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.