NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
drv/src/net/ether/dec21x4x/dec21x4x.h - hardware related constants drv/src/net/ether/dec21x4x/dec21x4x.c - driver code drv/src/net/ether/dec21x4x/dec21x4xProp.h - driver specific properties
DRV
Device Driver for dec21x4x Ethernet controllers
The dec21x4x Ethernet driver implements the ether device driver interface.
The driver works on dec 21040, 21041, 21140 and 21143 Ethernet controllers.
The driver uses the pci bus driver interface provided by a parent bus driver. Thus, the driver may be applied to any pci bus interface.
The dec21x4x driver does not provide the drv_probe routine. In other words, the dec21x4x driver does not enumerate the pci bus, nor does it detect a dec21x4x device or create an associated device node. When the dec21x4x driver is used, associated device nodes should be created either statically by a boot program or dynamically by a separate pci bus enumerator driver.
The dec21x4x driver provides the drv_bind() routine. This routine examines the device node properties and thus, identifies a dec21x4x compatible device. The routine checks for the pci vendor and device identifiers matching a dec21x4x compatible device. If the check is positive, the drv_bind() routine binds the driver to the device node, attaching a PROP_DRIVER property to the device node. The property value specifies the dec21x4x driver name. The parent bus driver uses such a property to determine the name of drivers servicing the device. Via the PROP_DRIVER property, the driver gives its name to the parent bus driver, asking it to invoke the drv_int() routine on that device. Note that the drv_bind() routine does nothing if the PROP_DRIVER property is already present in the device node, as the drv_bind() routine will not override existing driver-to-driver binding.
The driver provides the drv_unload() entry and supports the driver component unloading. This allows the driver component to be unloaded if it is no longer being used and if it has been dynamically loaded at run time.
The driver supports all bus events specified by the pci bus driver interface. As a consequence, the driver may be used with a hot-pluggable pci bus (for example, CompactPCI).
The table below summarizes the characteristics of the dec21x4x Ethernet driver:
driver name: | "sun:pci-dec21x4x-ether" |
---|---|
hardware: | dec 21040/21041/21140/21143 |
exported interface: | "ether" (ETHER_CLASS) |
exported interface version: | 0 (ETHER_VERSION_INITIAL) |
imported parent interface: | "pci" (PCI_CLASS) |
minimal parent interface version: | 0 (PCI_VERSION_INITIAL) |
device probing (auto-detection): | not supported |
driver unloading: | supported |
system (emergency) shut-down: | supported |
normal device shut-down: | supported |
hot-plug (surprise) device removal: | supported |
The table below lists device node properties used by the dec21x4x driver. Note that the column "m/o" specifies whether a given property is mandatory or optional. For optional properties, the column "default value" shows a default value which is used by the driver when a given property is not specified.
Name | Alias | Type | m/o | Default value |
---|---|---|---|---|
"vend-id" | PCI_PROP_VEND_ID | PciPropVendId | m | |
"dev-id" | PCI_PROP_DEV_ID | PciPropDevId | m | |
"dev-num" | PCI_PROP_DEV_NUM | PciPropDevNum | m | |
"func-num" | PCI_PROP_FUNC_NUM | PciPropFuncNum | m | |
"intr" | PCI_PROP_INTR | PciPropIntr | m | |
"ether-addr" | ETHER_PROP_ADDR | EtherPropAddr | o | SROM content |
"srom" | DEC21_PROP_SROM | uint8_f[] | o | see text below |
"media" | DEC21_PROP_MEDIA | Dec21PropMedia | o | MEDIA_TP |
"tx-desc-nb" | DEC21_PROP_TX_DESC_NB | Dec21PropTxDescNb | o | 8 |
"rx-desc-nb" | DEC21_PROP_RX_DESC_NB | Dec21PropRxDescNb | o | 8 |
"tx-buf-size" | DEC21_PROP_TX_BUF_SIZE | Dec21PropTxBufSize | o | 1514 bytes |
"rx-buf-size" | DEC21_PROP_RX_BUF_SIZE | Dec21PropRxBufSize | o | 1514 bytes |
The PCI_PROP_VEND_ID property specifies the dec pci vendor identifier (must be 0x1011).
The PCI_PROP_DEV_ID property identifies the type of controller within the dec21x4x family:
must be 0x0002 for dec21040
must be 0x0014 for dec21041
must be 0x0009 for dec21140
must be 0x0019 for dec21143
The PCI_PROP_DEV_NUM, and PCI_PROP_FUNC_NUM properties specify the configuration space address of the device.
The PCI_PROP_INTR property specifies the pci interrupt used by the device.
The PCI_PROP_IO_REGS property specifies the controller I/O registers range.
The ETHER_PROP_ADDR property specifies the controller Ethernet address. If the property is not present, the driver reads the Ethernet address from the controller SROM, and creates the property in the device node.
The DEC21_PROP_SROM property specifies the SROM data. This property is optional. If the property is not present, the driver does not access the controller SROM but, instead, uses the property value as the SROM image. The property value must be a byte stream in the 21x4 Serial ROM format.
The DEC21_PROP_MEDIA property specifies the default media type. The controller is configured for the default media in case the driver is not able to detect the media type automatically. This property is optional. If the property is not present, the default media type is the Twister Pair 10MB link (MEDIA_TP) .
The DEC21_PROP_TX_DESC_NB property specifies the number of descriptors to be allocated in the transmit ring. By default, 8 descriptors are used.
The DEC21_PROP_RX_DESC_NB property specifies the number of descriptors to be allocated in the receive ring. By default, 8 descriptors are used.
The DEC21_PROP_TX_BUF_SIZE property specifies the size of the DMA buffers to be allocated and bound to each descriptor in the transmit ring. By default, each buffer has a size of 1514 bytes, which is the maximum size of an Ethernet frame.
The DEC21_PROP_RX_BUF_SIZE property specifies the size of the DMA buffers to be allocated and bound to each descriptor in the receive ring. By default, each buffer has a size of 1514 bytes, which is the maximum size of an Ethernet frame.
Thus, the total size of DMA memory allocated by the driver will be:
dec21_PROP_TX_DESC_NB * dec21_PROP_TX_BUF_SIZE for transmission
dec21_PROP_RX_DESC_NB * dec21_PROP_RX_BUF_SIZE for reception.
Note that the driver is able to send and receive an Ethernet frame using multiple descriptors in a ring. It is not able to share the memory buffer bound to one descriptor between multiple Ethernet frames. In other words, configuring buffer sizes with big values will lead to poor memory usage, for small Ethernet frames.
The table below lists device node properties added by the dec21x4x driver, which may be used by the driver clients:
Name | Alias | Type |
"link-throughput" | ETHER_PROP_THROUGHPUT | EtherPropThroughput |
"ether-addr" | ETHER_PROP_ADDR | EtherPropAddr |
The ETHER_PROP_THROUGHPUT property specifies the throughput of the Ethernet link.
The ETHER_PROP_ADDR property specifies the controller Ethernet address. Note that the driver adds this property to the device node only if it does not already exist.
The media speed (10/100Mb) and mode (half and full-duplex) is detected automatically by the driver in one of the following ways:
when an external PHY is present on the board, the auto-negotiation capabilities of the transceiver are used to configure the controller in the best mode possible (as detected by the transceiver)
when an external PHY is present on the board, the auto-negotiation capabilities of the transceiver are used to configure the controller in the best mode possible (as detected by the transceiver)
The default media type (obtained through the DEC21_PROP_MEDIA property) is used if either of the following cases occur:
the auto-negotiation (using PHY) fails
the manual detection (using the test frame) fails
The DEC21_PROP_NO_AUTO_DETECT property diables link auto-detection.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO