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) subsytem 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

- syscon-subsys:	phandle to syscon node of the switch
			subsystem registers.

- syscon-pcsr:		(10gbe only) phandle to syscon node of the
			switch PCSR registers.

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

		NetCP 1.4 ethss, here is the order
			index #0 - sgmii module 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 - sgmii module registers
			index #1 - switch module 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

----phys:	phandles to serdes PHY devices
		see Documentation/devicetree/bindings/phy/ti-phy.txt
		for Keystone SerDes device specificcations.

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.

 Properties related to cpts configurations.
	- cpts-rftclk-sel: selects one of up to 32 clocks for time sync
		reference.  Default = 0.
	- cpts_clock_mult/cpts_clock_shift:
		used for converting time counter cycles to ns as in

		ns = (cycles * clock_mult) >> _shift

		Defaults: clock_mult, clock_shift = calculated from
		CPTS refclk
	- cpts-ext-ts-inputs:
		The number of external time stamp channels.
		The different CPTS versions might support up 8
		external time stamp channels. if absent - unsupported.
	- cpts-ts-comp-length:
		Enable time stamp comparison event and TS_COMP signal output
		generation when CPTS counter reaches a value written to
		the TS_COMP_VAL register.
		The generated pulse width is 3 refclk cycles if this property
		has no value (empty) or, otherwise, it should specify desired
		pulse width in number of refclk periods - max value 2^16.
		TS_COMP functionality will be disabled if not present.
	- cpts-ts-comp-polarity-low:
		Set polarity of TS_COMP signal to low. Default is hight.

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-pools:	a multiple of quadruples, each quadruple configures one tx-pool
		which corresponds to one tx-pipe and hence one subqueue.
		Entries in a quadruple specifies the number of descriptors to
		be used, the region-id for creating the tx descriptor pool,
		the tx-threshold and rx-threshold.
- 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.
- local-mac-address:	the driver is designed to use the of_get_mac_address api
			only if efuse-mac is 0. When efuse-mac is 0, the MAC
			address is obtained from local-mac-address. If this
			attribute is not present, then the driver will use a
			random MAC address.
- "netcp-device label":	phandle to the device specification for each of NetCP
			sub-module attached to this interface.

Example binding:

gbe_subsys: subsys@2090000 {
	compatible = "syscon";
	reg = <0x02090000 0x100>;
};

gbe_serdes: phy@232a000 {
	status			= "ok";
	compatible		= "ti,keystone-serdes-gbe";
	reg			= <0x0232a000 0x2000>;
	link-rate-kbps		= <1250000>;
	num-lanes		= <4>;
	/*rx-force-enable;*/
	#address-cells = <1>;
	#size-cells = <0>;

	serdes_lane0: lane@0 {
		status		= "ok";
		/*loopback;*/
		#phy-cells	= <0>;
		reg		= <0>;
		control-rate	= <2>; /* quart */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <0 0 0 12 4>; /* c1 c2 cm att vreg */
	};
	serdes_lane1: lane@1 {
		status		= "ok";
		/*loopback;*/
		#phy-cells	= <0>;
		reg		= <1>;
		control-rate	= <2>; /* quart */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <0 0 0 12 4>; /* c1 c2 cm att vreg */
	};
	serdes_lane2: lane@2 {
		status		= "disabled";
		/*loopback;*/
		#phy-cells	= <0>;
		reg		= <2>;
		control-rate	= <2>; /* quart */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <0 0 0 12 4>; /* c1 c2 cm att vreg */
	};
	serdes_lane3: lane@3 {
		status		= "disabled";
		/*loopback;*/
		#phy-cells	= <0>;
		reg		= <3>;
		control-rate	= <2>; /* quart */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <0 0 0 12 4>; /* c1 c2 cm att vreg */
	};
};

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";
			syscon-subsys = <&gbe_subsys>;
			reg = <0x90100 0x200>, <0x90400 0x200>, <0x90800 0x700>;
			/* enable-ale; */
			tx-queue = <648>;
			tx-channel = <8>;

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

			secondary-slave-ports {
				port-2 {
					phys = <&serdes_lane2>;
					slave-port = <2>;
					link-interface	= <2>;
				};
				port-3 {
					phys = <&serdes_lane3>;
					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>;
		};
	};
};

Example bindings (10gbe):

xgbe_subsys: subsys@2f00000 {
	status		= "disabled";
	compatible	= "syscon";
	reg		= <0x02f00000 0x100>;
};

xgbe_pcsr: pcsr@2f00600 {
	status		= "disabled";
	compatible	= "syscon";
	reg		= <0x02f00600 0x100>;
};

xgbe_serdes: phy@231e000 {
	status			= "disabled";
	compatible		= "ti,keystone-serdes-xgbe";
	reg			= <0x0231e000 0x2000>;
	link-rate-kbps		= <10312500>;
	num-lanes		= <2>;
	syscon-peripheral	= <&xgbe_subsys>;
	syscon-link		= <&xgbe_pcsr>;
	/*rx-force-enable;*/
	#address-cells  = <1>;
	#size-cells     = <0>;

	xserdes_lane0: lane@0 {
		status		= "ok";
		#phy-cells	= <0>;
		reg		= <0>;
		control-rate	= <0>; /* full */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <2 0 0 12 4>; /* c1 c2 cm att vreg */
	};
	xserdes_lane1: lane@1 {
		status		= "ok";
		#phy-cells	= <0>;
		reg		= <1>;
		control-rate	= <0>; /* full */
		rx-start	= <7 5>;
		rx-force	= <1 1>;
		tx-coeff	= <2 0 0 12 4>; /* c1 c2 cm att vreg */
	};
};

netcpx: netcpx@2f00000 {
	status		= "disabled";
	compatible	= "ti,netcp-1.0";
	#address-cells	= <1>;
	#size-cells	= <1>;
	ranges;

	clocks		= <&clkxge>;
	clock-names	= "clk_xge";
	dma-coherent;
	/* big-endian; */

	ti,navigator-dmas = <&dma_xgbe 0>,
			<&dma_xgbe 8>,
			<&dma_xgbe 0>;
	ti,navigator-dma-names = "xnetrx0", "xnetrx1", "xnettx";

	netcp-devices {
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;
		xgbe@2f00000 {
			label = "netcp-xgbe";
			compatible = "ti,netcp-xgbe";
			syscon-subsys = <&xgbe_subsys>;
			syscon-pcsr = <&xgbe_pcsr>;
			reg = <0x02f00100 0x200>, <0x02f01000 0xb00>;
			/* enable-ale; */
			tx-queue = <692>;
			tx-channel = "xnettx";

			interfaces {
				xgbe0: interface-0 {
					phys = <&xserdes_lane0>;
					slave-port = <0>;
					link-interface	= <11>; /* MAC_MAC */
				};
				xgbe1: interface-1 {
					phys = <&xserdes_lane1>;
					slave-port = <1>;
					link-interface	= <11>;
				};
			};
		};
	};

	netcp-interfaces {
		interface-0 {
			rx-channel = "xnetrx0";
			rx-pool = <2048 12>; /* num_desc region-id */
			/* 7 tx pools, hence 7 subqueues
			 *   <#desc rgn-id tx-thresh rx-thresh>
			 */
			tx-pools = <1024 12 17 17
				    64 12 17 17
				    64 12 17 17
				    64 12 17 17
				    64 12 17 17
				    64 12 17 17
				    64 12 17 17>;
			rx-queue-depth = <1024 1024 0 0>;
			rx-buffer-size = <1536 4096 0 0>;
			rx-queue = <532>;
			tx-completion-queue = <534>;
			efuse-mac = <0>;
			netcp-xgbe = <&xgbe0>;

		};
		interface-1 {
			rx-channel = "xnetrx1";
			rx-pool = <2048 12>; /* num_desc region-id */
			tx-pool = <1024 12>; /* num_desc region-id */
			rx-queue-depth = <1024 1024 0 0>;
			rx-buffer-size = <1536 4096 0 0>;
			rx-queue = <533>;
			tx-completion-queue = <535>;
			efuse-mac = <0>;
			netcp-xgbe = <&xgbe1>;
		};
	};
};

Packet Accelarator sub-module specifications.
=============================================

Note: The bindings are experimental and may change while feature development
is in progress. However attempt will be made to make changes backward
compatible if possible.

Required properties:
- label:	Must be "netcp-pa" for PA on K2H/K SoC
		Must be "netcp-pa2" for PA2 on K2L/E SoCs

- compatible:	Must be one of below:-
		"ti,netcp-pa" for PA
		"ti,netcp-pa2" for PA2

- reg:		register location and the size for the following register
		regions in the specified order.

		Packet Accelarator (PA)
		- Mailbox
		- Packet ID
		- LUT2
		- streaming switch
		- Control
		- Timers
		- Statistics
		- IRAM
		- SRAM

		Packet Accelarator 2 (PA2)
		- Mailbox
		- RA bridge
		- Thread mapper
		- RA
		- Statistics regs
		- Statistics block
		- cluster memory

- clusters:	Contain cluster specific configuration
		reg:		 cluster ID
		tx-queue:	 Queue for sending commands/data to a cluster
		tx-channel:	 knav Tx channel associated with the queue

- tx-cmd-pool:	specifies the number of descriptors to be used & the region-id
		for creating the tx descriptor pool for tx channnels.
- rx-cmd-rsp-chan:		rx channel name for receiving responses from
				PDSPs
- rx-cmd-rsp-pool:		specifies the number of descriptors to be used
				& the region-id for creating the rx descriptor
				pool for rx rsp channel.
- rx-cmd-rsp-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-cmd-rsp-buffer-size:	Size of the buffers allocated for the desc
				in each rx response FDQs.
- mac-lut-ranges:		LUT range of index used by PA device for MAC
				rules. LUT is shared across different software
				components in the system and this range is
				reserved for PA device.
- rx-route:			Rx Queue / Flow base used by PA. They should
				match with rx-channel queue / flow for netcp
				ethernet interface when PA is in the rx path.
- netcp-interfaces:		interface specific configuration for PA.
	slave-port		cpsw slave port number for the interface
Optional properties:-

- ip-lut-ranges:		LUT range of index reserved for PA device.
				Used for rx checksum handling.
- netcp-interfaces:		interface specific configuration for PA.
		rx-channel:	rx channel name for ethernet interface when PA
				is in the rx path for data. Uses a different
				flow id when PA is added to the rx path.
- disable-hw-timestamp:		Disable hw timestamp feature.
- disable-pre-classify:		By default, PA firmware does pre-classify
				Broadcast and multicast packet at ingress
				and route them to Linux network interface
				rx-queue. To disable this feature in PA
				firmware, add this DT property. In this case,
				explicit BC & MC rules will be added to
				LUT1-0 to achieve the same.

Example:

PA is a netcp device and appears under netcp-devices node. Example bindings for
PA device is provided below.

	netcp-devices {

		<other netcp devices>

		pa@0 {
			#address-cells = <1>;
			#size-cells = <1>;
			label = "netcp-pa";
			compatible = "ti,netcp-pa";

			reg = <0 0x60>,			/* Mailbox */
				<0x400 0x10>,		/* Packet ID */
				<0x500 0x40>,		/* LUT2 */
				<0x604 0x4>,		/* streaming switch */
				<0x1000 0x600>,		/* Control */
				<0x3000 0x600>,		/* Timers */
				<0x6000 0x100>,		/* Statistics */
				<0x10000 0x30000>,	/* Iram */
				<0x40000 0x8000>;	/* Sram */

			mac-lut-ranges		= <0 43 56 63>;
			/* Static reservation in LUT-1 (outer IP)
			 * used by driver to add IP rules for Rx checksum
			 * offload.
			 */
			ip-lut-ranges		= <61 63>;
			/* base queue, base flow. Should match with that
			 * for netrx0
			 */
			rx-route		= <8704 22>;
			tx-cmd-pool		= <256 12>;
			/* rx command pool */
			rx-cmd-rsp-pool		= <256 12>;
			/* rx channel name for command response */
			rx-cmd-rsp-chan		= "pa-cmd-rsp";
			rx-cmd-rsp-queue-depth	= <128 32 0 0>;
			rx-cmd-rsp-buffer-size	= <128 512 0 0>;

			/* PA clusters that does packet processing */
			clusters {
				#address-cells = <1>;
				#size-cells = <0>;
				cluster@0 {
					reg = <0>;
					tx-queue = <640>;
					tx-channel = "pa-cl0";
				};

				cluster@1 {
					reg = <1>;
					tx-queue = <641>;
					tx-channel = "pa-cl1";
				};

				cluster@5 {
					reg = <5>;
					tx-queue = <645>;
					tx-channel = "pa-cl5";
				};
			};
		};
	};

NETCP Quality of Service (QoS) sub-module specifications
========================================================

Note: The bindings are experimental and may change while feature development
is in progress. However attempt will be made to make changes backward
compatible if possible.

Required properties:
- label:	Must be "netcp-qos"

- compatible:	Must be "ti,netcp-qos"

- interfaces:	interface specific configuration for QoS
	-- tx-channel:	the navigator packet dma channel name for tx.
			this is the channel to which a packet will be
			dropped into when it comes out from a qostree.

	-- tx-queues:	the subqueues to the QMSS QoS drop scheduler.

NETCP QoS is a netcp device which appears under netcp-devices node.
Example bindings for NETCP QoS device is as follows:

	netcp-devices {

		<other netcp devices>

		qos@0 {
			label = "netcp-qos";
			compatible = "ti,netcp-qos";
			tx-channel = "nettx";

			interfaces {
				qos0: interface-0 {
					tx-queues = <645 8072 8073 8074
						     8075 8076 8077>;
				};
				qos1: interface-1 {
					tx-queues = <645 6472 6473 6474
							6475 6476 6477>;
				};
			};
		};
	};