xref: /freebsd/sys/contrib/device-tree/Bindings/net/keystone-netcp.txt (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)

This document describes the device tree bindings associated with the
keystone network coprocessor(NetCP) driver support.

The network coprocessor (NetCP) is a hardware accelerator that processes
Ethernet packets. NetCP has a gigabit Ethernet (GbE) subsystem with a ethernet
switch sub-module to send and receive packets. NetCP also includes a packet
accelerator (PA) module to perform packet classification operations such as
header matching, and packet modification operations such as checksum
generation. NetCP can also optionally include a Security Accelerator (SA)
capable of performing IPSec operations on ingress/egress packets.

Keystone II SoC's also have a 10 Gigabit Ethernet Subsystem (XGbE) which
includes a 3-port Ethernet switch sub-module capable of 10Gb/s and 1Gb/s rates
per Ethernet port.

Keystone NetCP driver has a plug-in module architecture where each of the NetCP
sub-modules exist as a loadable kernel module which plug in to the netcp core.
These sub-modules are represented as "netcp-devices" in the dts bindings. It is
mandatory to have the ethernet switch sub-module for the ethernet interface to
be operational. Any other sub-module like the PA is optional.

NetCP Ethernet SubSystem Layout:

-----------------------------
  NetCP subsystem(10G or 1G)
-----------------------------
	|
	|-> NetCP Devices ->	|
	|			|-> GBE/XGBE Switch
	|			|
	|			|-> Packet Accelerator
	|			|
	|			|-> Security Accelerator
	|
	|
	|
	|-> NetCP Interfaces ->	|
				|-> Ethernet Port 0
				|
				|-> Ethernet Port 1
				|
				|-> Ethernet Port 2
				|
				|-> Ethernet Port 3


NetCP subsystem properties:
Required properties:
- compatible:	Should be "ti,netcp-1.0"
- clocks:	phandle to the reference clocks for the subsystem.
- dma-id:	Navigator packet dma instance id.
- ranges:	address range of NetCP (includes, Ethernet SS, PA and SA)

Optional properties:
- reg:		register location and the size for the following register
		regions in the specified order.
		- Efuse MAC address register
- dma-coherent:	Present if dma operations are coherent
- big-endian:	Keystone devices can be operated in a mode where the DSP is in
		the big endian mode. In such cases enable this option. This
		option should also be enabled if the ARM is operated in
		big endian mode with the DSP in little endian.

NetCP device properties: Device specification for NetCP sub-modules.
1Gb/10Gb (gbe/xgbe) ethernet switch sub-module specifications.
Required properties:
- label:	Must be "netcp-gbe" for 1Gb & "netcp-xgbe" for 10Gb.
- compatible:	Must be one of below:-
		"ti,netcp-gbe" for 1GbE on NetCP 1.4
		"ti,netcp-gbe-5" for 1GbE N NetCP 1.5 (N=5)
		"ti,netcp-gbe-9" for 1GbE N NetCP 1.5 (N=9)
		"ti,netcp-gbe-2" for 1GbE N NetCP 1.5 (N=2)
		"ti,netcp-xgbe" for 10 GbE

- reg:		register location and the size for the following register
		regions in the specified order.
		- switch subsystem registers
		- sgmii port3/4 module registers (only for NetCP 1.4)
		- switch module registers
		- serdes registers (only for 10G)

		NetCP 1.4 ethss, here is the order
			index #0 - switch subsystem registers
			index #1 - sgmii port3/4 module registers
			index #2 - switch module registers

		NetCP 1.5 ethss 9 port, 5 port and 2 port
			index #0 - switch subsystem registers
			index #1 - switch module registers
			index #2 - serdes registers

- tx-channel:	the navigator packet dma channel name for tx.
- tx-queue:	the navigator queue number associated with the tx dma channel.
- interfaces:	specification for each of the switch port to be registered as a
		network interface in the stack.
-- slave-port:	Switch port number, 0 based numbering.
-- link-interface:	type of link interface, supported options are
			- mac<->mac auto negotiate mode: 0
			- mac<->phy mode: 1
			- mac<->mac forced mode: 2
			- mac<->fiber mode: 3
			- mac<->phy mode with no mdio: 4
			- 10Gb mac<->phy mode : 10
			- 10Gb mac<->mac forced mode : 11
----phy-handle:	phandle to PHY device

- cpts:		sub-node time synchronization (CPTS) submodule configuration
-- clocks:	CPTS reference clock. Should point on cpts-refclk-mux clock.
-- clock-names: should be "cpts"
-- cpts-refclk-mux: multiplexer clock definition sub-node for CPTS reference (RFTCLK) clock
--- #clock-cells: should be 0
--- clocks:	list of CPTS reference (RFTCLK) clock's parents as defined in Data manual
--- ti,mux-tbl: array of multiplexer indexes as defined in Data manual
--- assigned-clocks: should point on cpts-refclk-mux clock
--- assigned-clock-parents: should point on required RFTCLK clock parent to be selected
-- cpts_clock_mult: (optional) Numerator to convert input clock ticks
		into nanoseconds
-- cpts_clock_shift: (optional) Denominator to convert input clock ticks into
		nanoseconds.
		Mult and shift will be calculated basing on CPTS
		rftclk frequency if both cpts_clock_shift and
		cpts_clock_mult properties are not provided.

Optional properties:
- enable-ale:	NetCP driver keeps the address learning feature in the ethernet
		switch module disabled. This attribute is to enable the address
		learning.
- secondary-slave-ports:	specification for each of the switch port not be
				registered as a network interface. NetCP driver
				will only initialize these ports and attach PHY
				driver to them if needed.

NetCP interface properties: Interface specification for NetCP sub-modules.
Required properties:
- rx-channel:	the navigator packet dma channel name for rx.
- rx-queue:	the navigator queue number associated with rx dma channel.
- rx-pool:	specifies the number of descriptors to be used & the region-id
		for creating the rx descriptor pool.
- tx-pool:	specifies the number of descriptors to be used & the region-id
		for creating the tx descriptor pool.
- rx-queue-depth:	number of descriptors in each of the free descriptor
			queue (FDQ) for the pktdma Rx flow. There can be at
			present a maximum of 4 queues per Rx flow.
- rx-buffer-size:	the buffer size for each of the Rx flow FDQ.
- tx-completion-queue:	the navigator queue number where the descriptors are
			recycled after Tx DMA completion.

Optional properties:
- efuse-mac:	If this is 1, then the MAC address for the interface is
		obtained from the device efuse mac address register.
		If this is 2, the two DWORDs occupied by the MAC address
		are swapped.  The netcp driver will swap the two DWORDs
		back to the proper order when this property is set to 2
		when it obtains the mac address from efuse.
- "netcp-device label":	phandle to the device specification for each of NetCP
			sub-module attached to this interface.

The MAC address will be determined using the optional properties defined in
ethernet.txt and only if efuse-mac is set to 0. If all of the optional MAC
address properties are not present, then the driver will use a random MAC
address.

Example binding:

netcp: netcp@2000000 {
	reg = <0x2620110 0x8>;
	reg-names = "efuse";
	compatible = "ti,netcp-1.0";
	#address-cells = <1>;
	#size-cells = <1>;
	ranges  = <0 0x2000000 0xfffff>;
	clocks = <&papllclk>, <&clkcpgmac>, <&chipclk12>;
	dma-coherent;
	/* big-endian; */
	dma-id = <0>;

	netcp-devices {
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;
		gbe@90000 {
			label = "netcp-gbe";
			reg = <0x90000 0x300>, <0x90400 0x400>, <0x90800 0x700>;
			/* enable-ale; */
			tx-queue = <648>;
			tx-channel = <8>;

			cpts {
				clocks = <&cpts_refclk_mux>;
				clock-names = "cpts";

				cpts_refclk_mux: cpts-refclk-mux {
					#clock-cells = <0>;
					clocks = <&chipclk12>, <&chipclk13>,
						 <&timi0>, <&timi1>,
						 <&tsipclka>, <&tsrefclk>,
						 <&tsipclkb>;
					ti,mux-tbl = <0x0>, <0x1>, <0x2>,
						<0x3>, <0x4>, <0x8>, <0xC>;
					assigned-clocks = <&cpts_refclk_mux>;
					assigned-clock-parents = <&chipclk12>;
				};
			};

			interfaces {
				gbe0: interface-0 {
					slave-port = <0>;
					link-interface	= <4>;
				};
				gbe1: interface-1 {
					slave-port = <1>;
					link-interface	= <4>;
				};
			};

			secondary-slave-ports {
				port-2 {
					slave-port = <2>;
					link-interface	= <2>;
				};
				port-3 {
					slave-port = <3>;
					link-interface	= <2>;
				};
			};
		};
	};

	netcp-interfaces {
		interface-0 {
			rx-channel = <22>;
			rx-pool = <1024 12>;
			tx-pool = <1024 12>;
			rx-queue-depth = <128 128 0 0>;
			rx-buffer-size = <1518 4096 0 0>;
			rx-queue = <8704>;
			tx-completion-queue = <8706>;
			efuse-mac = <1>;
			netcp-gbe = <&gbe0>;

		};
		interface-1 {
			rx-channel = <23>;
			rx-pool = <1024 12>;
			tx-pool = <1024 12>;
			rx-queue-depth = <128 128 0 0>;
			rx-buffer-size = <1518 4096 0 0>;
			rx-queue = <8705>;
			tx-completion-queue = <8707>;
			efuse-mac = <0>;
			local-mac-address = [02 18 31 7e 3e 6f];
			netcp-gbe = <&gbe1>;
		};
	};
};

CPTS board configuration - select external CPTS RFTCLK:

&tsrefclk{
	clock-frequency = <500000000>;
};

&cpts_refclk_mux {
	assigned-clock-parents = <&tsrefclk>;
};