:orphan:
.. raw:: html
.. dtcompatible:: snps,dwcxgmac
.. _dtbinding_snps_dwcxgmac:
snps,dwcxgmac
#############
Vendor: :ref:`Synopsys, Inc. `
.. note::
An implementation of a driver matching this compatible is available in
:zephyr_file:`drivers/ethernet/dwc_xgmac/eth_dwc_xgmac.c`.
Description
***********
.. code-block:: none
Synopsys DesignWareCore XGMAC
Properties
**********
.. tabs::
.. group-tab:: Node specific properties
Properties not inherited from the base binding file.
.. list-table::
:widths: 1 1 4
:header-rows: 1
* - Name
- Type
- Details
* - ``max-frame-size``
- ``int``
- .. code-block:: none
Maximum ethernet frame size. The current ethernet frame sizes
supported by hardware are standard and jumbo (up to 16KB) frames. This
means that normally xgmac will reject any frame above max-frame-size
value. The default value is 1518, which represents an usual
IEEE 802.3 ethernet frame:
Ethernet Frame [ 14 MAC HEADER | 1500 MTU | 4 FCS ] = 1518 bytes
Default value: ``1518``
* - ``max-speed``
- ``int``
- .. code-block:: none
This specifies maximum speed in Mbit/s supported by the device. The
xgmac driver supports 10Mbit/s, 100Mbit/s, 1000Mbit/s, and 2500Mbit/s. Using 1000,
as default value, enables driver to configure 10 and 100Mbit/s speeds.
2500Mbit/s speed can be used only with Soft PCS. When selected driver assumes
soft PCS is connected to XGMAC through GMII. make sure the phy-connection-type is
selected as gmii when 2500Mbit/s speed is selected.
Default value: ``1000``
Legal values: ``10``, ``100``, ``1000``, ``2500``
* - ``tx-fifo-size``
- ``int``
- .. code-block:: none
Specifies the size of the MTL Transmit FIFO
Default value: ``32768``
Legal values: ``1024``, ``2048``, ``4096``, ``8192``, ``16384``, ``32768``, ``65536``, ``131072``, ``262144``
* - ``rx-fifo-size``
- ``int``
- .. code-block:: none
Specifies the size of the MTL Receive FIFO
Default value: ``32768``
Legal values: ``1024``, ``2048``, ``4096``, ``8192``, ``16384``, ``32768``, ``65536``, ``131072``, ``262144``
* - ``num-dma-ch``
- ``int``
- .. code-block:: none
Number of dma channels range: 1 to 8.
This property is **required**.
* - ``num-tx-queues``
- ``int``
- .. code-block:: none
Number of hardware TX queues range: 1 to 8.
This property is **required**.
* - ``num-rx-queues``
- ``int``
- .. code-block:: none
Number of hardware RX queues range: 1 to 8.
This property is **required**.
* - ``num-tc``
- ``int``
- .. code-block:: none
Number of traffic classes range: 1 to 7.
Default value: ``1``
* - ``full-duplex-mode-en``
- ``boolean``
- .. code-block:: none
MAC communication mode to full duplex mode.
This property is **required**.
* - ``wr-osr-lmt``
- ``int``
- .. code-block:: none
AXI Maximum Write Outstanding Request Limit.This value
limits the maximum outstanding request on the AXI write
interface. Maximum outstanding requests = WR_OSR_LMT + 1
Default value: ``31``
* - ``rd-osr-lmt``
- ``int``
- .. code-block:: none
AXI Maximum Read Outstanding Request Limit.This value
limits the maximum outstanding request on the AXI read
interface. Maximum outstanding requests = WR_OSR_LMT + 1
Default value: ``31``
* - ``pbl``
- ``int``
- .. code-block:: none
Programmable burst length range: 4,5,16,32,64,128,256
Default value: ``32``
* - ``edma-tdps``
- ``int``
- .. code-block:: none
Tx Descriptor Pre-fetch threshold Size.
This field controls the threshold in the Descriptor cache after
which the DMA starts pre-fetching the TxDMA descriptors. The
DMA engine for all TxDMA channels initiate requests for the
descriptor fetches as soon as the number of descriptors in the
cache memory for that DMA channel, falls below or equal to
the programmed threshold (each descriptor is 16 bytes)
Range: 0,1,2,3,4,5
Default value: ``1``
* - ``edma-rdps``
- ``int``
- .. code-block:: none
Rx Descriptor Pre-fetch threshold Size.
This field controls the threshold in the Descriptor cache after
which the DMA starts pre-fetching the RxDMA descriptors. The
DMA engine for all RxDMA channels initiate requests for the
descriptor fetches as soon as the number of descriptors in the
cache memory for that DMA channel, falls below or equal to
the programmed threshold (each descriptor is 16 bytes)
Range: 0,1,2,3,4,5
Default value: ``1``
* - ``pblx8``
- ``boolean``
- .. code-block:: none
8xPBL mode.
When this is set to true, the PBL value is multiplied eight times.
Therefore, the DMA transfers the data in 8, 16, 32, 64, 128, and 256
beats depending on the PBL value.
* - ``ubl``
- ``boolean``
- .. code-block:: none
AXI Undefined Burst Length.
1: The AXI master can perform burst transfers that are equal to or less
than the maximum allowed burst length enabled.
0: The AXI master performs one of the following burst transfers: Burst
transfers of fixed burst lengths as indicated by the BLEN256, BLEN128,
BLEN64, BLEN32, BLEN16, BLEN8, or BLEN4 field.
* - ``blen4``
- ``boolean``
- .. code-block:: none
AXI Burst Length 4.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 4 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen8``
- ``boolean``
- .. code-block:: none
AXI Burst Length 8.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 8 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen16``
- ``boolean``
- .. code-block:: none
AXI Burst Length 16.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 16 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen32``
- ``boolean``
- .. code-block:: none
AXI Burst Length 32.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 32 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen64``
- ``boolean``
- .. code-block:: none
AXI Burst Length 64.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 64 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen128``
- ``boolean``
- .. code-block:: none
AXI Burst Length 128.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 128 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``blen256``
- ``boolean``
- .. code-block:: none
AXI Burst Length 256.
When this enabled and the mixed_burst is disabled, the AXI master
can select a burst length of 256 on the AXI interface.
When the mixed_burst enabled, enabling this field has no effect.
* - ``aal``
- ``boolean``
- .. code-block:: none
Address-Aligned Beats.
When this is enabled, the AXI master performs address-aligned
burst transfers on Read and Write channels.
* - ``eame``
- ``boolean``
- .. code-block:: none
Enhanced Address Mode Enable.
DMA master enables the enhanced address mode (40-bit or 48-bit addressing mode).
In this mode, the DMA engine uses either the 40-bit or 48-bit address, depending
on the configuration.
* - ``dma-ch-mss``
- ``int``
- .. code-block:: none
Maximum Segment Size.
This field specifies the maximum segment size that must be
used while segmenting the Transmit packet. This field is valid
only if the TSE enabled.
Default value: ``4096``
* - ``dma-ch-tdrl``
- ``int``
- .. code-block:: none
Transmit Descriptor Ring Length.
This field sets the maximum number of Tx descriptors in the
circular descriptor ring. The maximum number of descriptors is
limited to 16384 descriptors.
Default value: ``512``
* - ``dma-ch-rdrl``
- ``int``
- .. code-block:: none
Receive Descriptor Ring Length.
This field sets the maximum number of Rx descriptors in the
circular descriptor ring. The maximum number of descriptors is
limited to 16384 descriptors.
Default value: ``512``
* - ``dma-ch-rbsz``
- ``int``
- .. code-block:: none
Receive Buffer size.
This field indicates the size of the Rx buffers specified in bytes
allocated by the software to store the packets the Rx DMA
transfers to the host memory. The maximum buffer size is
limited to 16K bytes. The buffer size is applicable to payload
buffers when split headers are enabled.
Default value: ``16383``
* - ``dma-ch-arbs``
- ``int``
- .. code-block:: none
Alternate Receive Buffer Size
Indicates size in bytes for Buffer 1 when ARBS is set
to a non-zero value (when split header(SPH) feature is not enabled).
When split header feature is enabled, ARBS indicates the
buffer size for header data. The maximum alternate buffer is
limited to 1016 or 1008-bytes depending on the data bus
widths (64-bit or 128-bit respectively). When ARBS=0, Rx
Buffer1 and Rx Buffer2 sizes are based on RBSZ field. Width of
ARBS field is 7 or 6-bits depending on the data bus widths
(64-bit or 128-bit respectively).
* - ``dma-ch-rxpbl``
- ``int``
- .. code-block:: none
Receive Programmable Burst Length.
These field indicate the maximum number of beats to be
transferred in one DMA data transfer.
Default value: ``32``
* - ``dma-ch-txpbl``
- ``int``
- .. code-block:: none
Transmit Programmable Burst Length.
These field indicate the maximum number of beats to be
transferred in one DMA data transfer.
Default value: ``32``
* - ``dma-ch-sph``
- ``boolean``
- .. code-block:: none
Header-Payload Split.
When this field is set, the DMA splits the header and payload in
the Receive path. The DMA writes the header to the Buffer
Address1. The DMA writes the payload to the buffer to which
the Buffer Address2 is pointing.
The software must ensure that the header fits into the Receive
buffers. If the header length exceeds the receive buffer size,
the DMA does not split the header and payload.
* - ``dma-ch-edse``
- ``boolean``
- .. code-block:: none
Enhanced Descriptor Enable.
When this field is set, the corresponding channel uses
enhanced Descriptors.
* - ``dma-ch-tse``
- ``boolean``
- .. code-block:: none
TCP Segmentation Enabled.
When this field is set, the DMA performs the TCP segmentation
for packets in Channel. The TCP segmentation is done only
for those packets for which the TSE is set in the Tx Normal
descriptor.
* - ``dma-ch-osp``
- ``boolean``
- .. code-block:: none
Operate on Second Packet.
When this field is set, it instructs the DMA to process the second
packet of the Transmit data even before closing the descriptor
of the first packet.
* - ``mtl-raa``
- ``boolean``
- .. code-block:: none
Receive Arbitration Algorithm.
This field is used to select the arbitration algorithm for the Rx
side. 0: Strict Priority (SP), 1: Weighted Strict Priority (WSP)
* - ``mtl-etsalg``
- ``int``
- .. code-block:: none
ETS Algorithm.
This field selects the type of ETS algorithm to be applied for
traffic classes whose transmission selection algorithm (TSA) is
set to ETS:
0: WRR algorithm
1: WFQ algorithm
2: DWRR algorithm
* - ``rxq-dyn-dma-en``
- ``int``
- .. code-block:: none
Receive Queue Enabled for Dynamic DMA Channel Selection.
Each bit position of this field maps to a queue. there are total 8 queues
Default value: ``1``
* - ``rxq-dma-ch-sel``
- ``uint8-array``
- .. code-block:: none
Receive Queue Mapped to DMA Channel. this field does not have
effect when rxQ-DynDma-En is enabled.
range 0 - 7
Default value: ``[0, 1, 2, 3, 4, 5, 6, 7]``
* - ``txq-size``
- ``uint8-array``
- .. code-block:: none
This field indicates the size of the allocated Transmit queues
in blocks of 256 bytes. = (txQ-size + 1) x 256
range: 0 - 7
Default value: ``[127]``
* - ``map-queue-tc``
- ``uint8-array``
- .. code-block:: none
Queue to Traffic Class Mapping. range 0 - 7
Default value: ``[0]``
* - ``tx-threshold-ctrl``
- ``uint8-array``
- .. code-block:: none
Transmit Threshold Control.
These field control the threshold level of the MTL Tx Queue.
Transmission starts when the packet size within the MTL Tx
Queue is larger than the threshold. In addition, full packets
with length less than the threshold are also transmitted. This
field us used only when Transmit Store and Forward is disabled.
range 0 - 7
0: 64
1: reserved
2: 96
3: 128
4: 192
5: 256
6: 384
7: 512
Default value: ``[0]``
* - ``rx-threshold-ctrl``
- ``uint8-array``
- .. code-block:: none
The received packet is transferred to the application or DMA
when the packet size within the MTL Rx queue is larger than
the threshold. In addition, full packets with length less than the
threshold are automatically transferred. The value of 11 is not
applicable if the size of the configured Rx Queue is 128 bytes.
This field is valid only when the RSF bit is zero. This field is
ignored when the RSF field is set to 1.
range 0 - 3
0: 64
1: reserved
2: 96
3: 128
Default value: ``[0]``
* - ``rxq-size``
- ``uint8-array``
- .. code-block:: none
Receive Queue Size. This field indicates the size of the allocated
Receive queues in blocks 256 bytes. = (rxQ-size + 1) x 256
Range: 0 - 127 ,
Default value: ``[127]``
* - ``tx-store-fwrd-en``
- ``int``
- .. code-block:: none
Transmit Store and Forward. When this field is set, the transmission
starts when a full packet resides in the MTL Tx Queue.
Each bit position of this field maps to a queue. there are total 8 queues
Default value: ``255``
* - ``hfc-en``
- ``int``
- .. code-block:: none
Enable Hardware Flow Control. When this field is set, the flow control
signal operation, based on the fill-level of Rx queue, is enabled.
Each bit position of this field maps to a queue. there are total 8 queues
* - ``cs-error-pkt-drop-dis``
- ``int``
- .. code-block:: none
Disable Dropping of TCP/IP Checksum Error Packets
Each bit position of this field maps to a queue. there are total 8 queues
* - ``rx-store-fwrd-en``
- ``int``
- .. code-block:: none
Receive Store and Forward. When this field is set, DWC_xgmac reads a
packet from the Rx queue only after the complete packet has been written to it.
Each bit position of this field maps to a queue. there are total 8 queues
Default value: ``255``
* - ``fep-en``
- ``int``
- .. code-block:: none
Forward Error Packets. When this bit is set, all packets except the runt error
packets are forwarded to the application or DMA.
Each bit position of this field maps to a queue. there are total 8 queues
* - ``fup-en``
- ``int``
- .. code-block:: none
Forward Undersized Good Packets. When this field is set, the Rx queue forwards
the undersized good packets.
Each bit position of this field maps to a queue. there are total 8 queues
* - ``priorities-map-tc``
- ``array``
- .. code-block:: none
Priorities Mapped to Traffic Class. This field determines if the transmit
queues associated with the traffic class should be blocked from transmitting
for the specified pause time when a PFC packet is received with priorities
matching the priorities programmed in this field.
range: 0 - 7 and max array size is 8
ex: <0,1,2,3,4,5,6,7>
Default value: ``[0]``
* - ``tx-sel-algorithm``
- ``uint8-array``
- .. code-block:: none
Transmission Selection Algorithm. This field is used to assign a transmission
selection algorithm for this traffic class.
range: 0 -strict priority
1 - Credit based shaper
2 - Enhanced Transmission Selection
Default value: ``[0]``
* - ``jumbo-pkt-en``
- ``boolean``
- .. code-block:: none
Jumbo Packet Enable.
When this bit is set, the MAC allows jumbo packets of 9018
bytes (9022 bytes for VLAN tagged packets) without reporting
a giant packet error in the Rx packet status
* - ``gaint-pkt-size-limit``
- ``int``
- .. code-block:: none
Giant Packet Size Limit.
If the received packet size is greater than the value
programmed in this field in units of bytes, the MAC declares
the received packet as Giant packet. The value programmed in
this field must be greater than or equal to 1518 bytes. Any
other programmed value is considered as 1518 bytes.
Default value: ``9018``
* - ``resets``
- ``phandle-array``
- .. code-block:: none
Reset information
* - ``reset-names``
- ``string-array``
- .. code-block:: none
Name of each reset
* - ``local-mac-address``
- ``uint8-array``
- .. code-block:: none
Specifies the MAC address that was assigned to the network device
* - ``zephyr,random-mac-address``
- ``boolean``
- .. code-block:: none
Use a random MAC address generated when the driver is initialized.
Note that using this choice and rebooting a board may leave stale
MAC address in peers' ARP caches and lead to issues and delays in
communication. (Use "ip neigh flush all" on Linux peers to clear
ARP cache.)
It is driver specific how the OUI octets are handled.
If set we ignore any setting of the local-mac-address property.
* - ``phy-handle``
- ``phandle``
- .. code-block:: none
Specifies a reference to a node representing a PHY device.
* - ``phy-connection-type``
- ``string``
- .. code-block:: none
Specifies the interface connection type between ethernet MAC and PHY.
Legal values: ``'mii'``, ``'rmii'``, ``'gmii'``, ``'rgmii'``, ``'internal'``
.. group-tab:: Deprecated node specific properties
Deprecated properties not inherited from the base binding file.
(None)
.. group-tab:: Base properties
Properties inherited from the base binding file, which defines
common properties that may be set on many nodes. Not all of these
may apply to the "snps,dwcxgmac" compatible.
.. list-table::
:widths: 1 1 4
:header-rows: 1
* - Name
- Type
- Details
* - ``reg``
- ``array``
- .. code-block:: none
Information used to address the device. The value is specific to
the device (i.e. is different depending on the compatible
property).
The "reg" property is typically a sequence of (address, length) pairs.
Each pair is called a "register block". Values are
conventionally written in hex.
For details, see "2.3.6 reg" in Devicetree Specification v0.4.
This property is **required**.
See :ref:`zephyr:dt-important-props` for more information.
* - ``interrupts``
- ``array``
- .. code-block:: none
Information about interrupts generated by the device, encoded as an array
of one or more interrupt specifiers. The format of the data in this property
varies by where the device appears in the interrupt tree. Devices with the same
"interrupt-parent" will use the same format in their interrupts properties.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
This property is **required**.
See :ref:`zephyr:dt-important-props` for more information.
* - ``status``
- ``string``
- .. code-block:: none
Indicates the operational status of the hardware or other
resource that the node represents. In particular:
- "okay" means the resource is operational and, for example,
can be used by device drivers
- "disabled" means the resource is not operational and the system
should treat it as if it is not present
For details, see "2.3.4 status" in Devicetree Specification v0.4.
Legal values: ``'ok'``, ``'okay'``, ``'disabled'``, ``'reserved'``, ``'fail'``, ``'fail-sss'``
See :ref:`zephyr:dt-important-props` for more information.
* - ``compatible``
- ``string-array``
- .. code-block:: none
This property is a list of strings that essentially define what
type of hardware or other resource this devicetree node
represents. Each device driver checks for specific compatible
property values to find the devicetree nodes that represent
resources that the driver should manage.
The recommended format is "vendor,device", The "vendor" part is
an abbreviated name of the vendor. The "device" is usually from
the datasheet.
The compatible property can have multiple values, ordered from
most- to least-specific. Having additional values is useful when the
device is a specific instance of a more general family, to allow the
system to match the most specific driver available.
For details, see "2.3.1 compatible" in Devicetree Specification v0.4.
This property is **required**.
See :ref:`zephyr:dt-important-props` for more information.
* - ``reg-names``
- ``string-array``
- .. code-block:: none
Optional names given to each register block in the "reg" property.
For example:
/ {
soc {
#address-cells = <1>;
#size-cells = <1>;
uart@1000 {
reg = <0x1000 0x2000>, <0x3000 0x4000>;
reg-names = "foo", "bar";
};
};
};
The uart@1000 node has two register blocks:
- one with base address 0x1000, size 0x2000, and name "foo"
- another with base address 0x3000, size 0x4000, and name "bar"
* - ``interrupts-extended``
- ``compound``
- .. code-block:: none
Extended interrupt specifier for device, used as an alternative to
the "interrupts" property.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``interrupt-names``
- ``string-array``
- .. code-block:: none
Optional names given to each interrupt generated by a device.
The interrupts themselves are defined in either "interrupts" or
"interrupts-extended" properties.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``interrupt-parent``
- ``phandle``
- .. code-block:: none
If present, this refers to the node which handles interrupts generated
by this device.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``label``
- ``string``
- .. code-block:: none
Human readable string describing the device. Use of this property is
deprecated except as needed on a case-by-case basis.
For details, see "4.1.2 Miscellaneous Properties" in Devicetree
Specification v0.4.
See :ref:`zephyr:dt-important-props` for more information.
* - ``clocks``
- ``phandle-array``
- .. code-block:: none
Information about the device's clock providers. In general, this property
should follow conventions established in the dt-schema binding:
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml
* - ``clock-names``
- ``string-array``
- .. code-block:: none
Optional names given to each clock provider in the "clocks" property.
* - ``#address-cells``
- ``int``
- .. code-block:: none
This property encodes the number of cells used by address fields
in "reg" properties in this node's children.
For details, see "2.3.5 #address-cells and #size-cells" in Devicetree
Specification v0.4.
* - ``#size-cells``
- ``int``
- .. code-block:: none
This property encodes the number of cells used by size fields in
"reg" properties in this node's children.
For details, see "2.3.5 #address-cells and #size-cells" in Devicetree
Specification v0.4.
* - ``dmas``
- ``phandle-array``
- .. code-block:: none
DMA channel specifiers relevant to the device.
* - ``dma-names``
- ``string-array``
- .. code-block:: none
Optional names given to the DMA channel specifiers in the "dmas" property.
* - ``io-channels``
- ``phandle-array``
- .. code-block:: none
IO channel specifiers relevant to the device.
* - ``io-channel-names``
- ``string-array``
- .. code-block:: none
Optional names given to the IO channel specifiers in the "io-channels" property.
* - ``mboxes``
- ``phandle-array``
- .. code-block:: none
Mailbox / IPM channel specifiers relevant to the device.
* - ``mbox-names``
- ``string-array``
- .. code-block:: none
Optional names given to the mbox specifiers in the "mboxes" property.
* - ``power-domains``
- ``phandle-array``
- .. code-block:: none
Power domain specifiers relevant to the device.
* - ``power-domain-names``
- ``string-array``
- .. code-block:: none
Optional names given to the power domain specifiers in the "power-domains" property.
* - ``#power-domain-cells``
- ``int``
- .. code-block:: none
Number of cells in power-domains property
* - ``zephyr,deferred-init``
- ``boolean``
- .. code-block:: none
Do not initialize device automatically on boot. Device should be manually
initialized using device_init().
* - ``wakeup-source``
- ``boolean``
- .. code-block:: none
Property to identify that a device can be used as wake up source.
When this property is provided a specific flag is set into the
device that tells the system that the device is capable of
wake up the system.
Wake up capable devices are disabled (interruptions will not wake up
the system) by default but they can be enabled at runtime if necessary.
* - ``zephyr,pm-device-runtime-auto``
- ``boolean``
- .. code-block:: none
Automatically configure the device for runtime power management after the
init function runs.
* - ``zephyr,disabling-power-states``
- ``phandles``
- .. code-block:: none
List of power states that will disable this device power.