[GitHub/mt8127/android_kernel_alcatel_ttab.git] / Documentation / misc-devices / spear-pcie-gadget.txt

Spear PCIe Gadget Driver:

Author
=============
Pratyush Anand (pratyush.anand@st.com)

Location
============
driver/misc/spear13xx_pcie_gadget.c

Supported Chip:
===================
SPEAr1300
SPEAr1310

Menuconfig option:
==========================
Device Drivers
	Misc devices
		PCIe gadget support for SPEAr13XX platform
purpose
===========
This driver has several nodes which can be read/written by configfs interface.
Its main purpose is to configure selected dual mode PCIe controller as device
and then program its various registers to configure it as a particular device
type. This driver can be used to show spear's PCIe device capability.

Description of different nodes:
=================================

read behavior of nodes:
------------------------------
link 		:gives ltssm status.
int_type 	:type of supported interrupt
no_of_msi 	:zero if MSI is not enabled by host. A positive value is the
		number of MSI vector granted.
vendor_id	:returns programmed vendor id (hex)
device_id	:returns programmed device id(hex)
bar0_size:	:returns size of bar0 in hex.
bar0_address	:returns address of bar0 mapped area in hex.
bar0_rw_offset	:returns offset of bar0 for which bar0_data will return value.
bar0_data	:returns data at bar0_rw_offset.

write behavior of nodes:
------------------------------
link 		:write UP to enable ltsmm DOWN to disable
int_type	:write interrupt type to be configured and (int_type could be
		INTA, MSI or NO_INT). Select MSI only when you have programmed
		no_of_msi node.
no_of_msi	:number of MSI vector needed.
inta		:write 1 to assert INTA and 0 to de-assert.
send_msi	:write MSI vector to be sent.
vendor_id	:write vendor id(hex) to be programmed.
device_id	:write device id(hex) to be programmed.
bar0_size	:write size of bar0 in hex. default bar0 size is 1000 (hex)
		bytes.
bar0_address	:write	address of bar0 mapped area in hex. (default mapping of
		bar0 is SYSRAM1(E0800000). Always program bar size before bar
		address. Kernel might modify bar size and address for alignment, so
		read back bar size and address after writing to cross check.
bar0_rw_offset	:write offset of bar0 for which	bar0_data will write value.
bar0_data	:write data to be written at bar0_rw_offset.

Node programming example
===========================
Program all PCIe registers in such a way that when this device is connected
to the PCIe host, then host sees this device as 1MB RAM.
#mount -t configfs none /Config
For nth PCIe Device Controller
# cd /config/pcie_gadget.n/
Now you have all the nodes in this directory.
program vendor id as 0x104a
# echo 104A >> vendor_id

program device id as 0xCD80
# echo CD80 >> device_id

program BAR0 size as 1MB
# echo 100000 >> bar0_size

check for programmed bar0 size
# cat bar0_size

Program BAR0 Address as DDR (0x2100000). This is the physical address of
memory, which is to be made visible to PCIe host. Similarly any other peripheral
can also be made visible to PCIe host. E.g., if you program base address of UART
as BAR0 address then when this device will be connected to a host, it will be
visible as UART.
# echo 2100000 >> bar0_address

program interrupt type : INTA
# echo INTA >> int_type

go for link up now.
# echo UP >> link

It will have to be insured that, once link up is done on gadget, then only host
is initialized and start to search PCIe devices on its port.

/*wait till link is up*/
# cat link
wait till it returns UP.

To assert INTA
# echo 1 >> inta

To de-assert INTA
# echo 0 >> inta

if MSI is to be used as interrupt, program no of msi vector needed (say4)
# echo 4 >> no_of_msi

select MSI as interrupt type
# echo MSI >> int_type

go for link up now
# echo UP >> link

wait till link is up
# cat link
An application can repetitively read this node till link is found UP. It can
sleep between two read.

wait till msi is enabled
# cat no_of_msi
Should return 4 (number of requested MSI vector)

to send msi vector 2
# echo 2 >> send_msi
#cd -
Commit	Line	Data
b9500546 PA	1	Spear PCIe Gadget Driver:
	2
	3	Author
	4	=============
	5	Pratyush Anand (pratyush.anand@st.com)
	6
	7	Location
	8	============
	9	driver/misc/spear13xx_pcie_gadget.c
	10
	11	Supported Chip:
	12	===================
	13	SPEAr1300
	14	SPEAr1310
	15
	16	Menuconfig option:
	17	==========================
	18	Device Drivers
	19	Misc devices
	20	PCIe gadget support for SPEAr13XX platform
	21	purpose
	22	===========
	23	This driver has several nodes which can be read/written by configfs interface.
	24	Its main purpose is to configure selected dual mode PCIe controller as device
	25	and then program its various registers to configure it as a particular device
	26	type. This driver can be used to show spear's PCIe device capability.
	27
	28	Description of different nodes:
	29	=================================
	30
	31	read behavior of nodes:
	32	------------------------------
	33	link :gives ltssm status.
	34	int_type :type of supported interrupt
	35	no_of_msi :zero if MSI is not enabled by host. A positive value is the
	36	number of MSI vector granted.
	37	vendor_id :returns programmed vendor id (hex)
	38	device_id :returns programmed device id(hex)
	39	bar0_size: :returns size of bar0 in hex.
	40	bar0_address :returns address of bar0 mapped area in hex.
	41	bar0_rw_offset :returns offset of bar0 for which bar0_data will return value.
	42	bar0_data :returns data at bar0_rw_offset.
	43
	44	write behavior of nodes:
	45	------------------------------
	46	link :write UP to enable ltsmm DOWN to disable
	47	int_type :write interrupt type to be configured and (int_type could be
	48	INTA, MSI or NO_INT). Select MSI only when you have programmed
	49	no_of_msi node.
	50	no_of_msi :number of MSI vector needed.
	51	inta :write 1 to assert INTA and 0 to de-assert.
	52	send_msi :write MSI vector to be sent.
	53	vendor_id :write vendor id(hex) to be programmed.
	54	device_id :write device id(hex) to be programmed.
	55	bar0_size :write size of bar0 in hex. default bar0 size is 1000 (hex)
	56	bytes.
	57	bar0_address :write address of bar0 mapped area in hex. (default mapping of
	58	bar0 is SYSRAM1(E0800000). Always program bar size before bar
	59	address. Kernel might modify bar size and address for alignment, so
	60	read back bar size and address after writing to cross check.
	61	bar0_rw_offset :write offset of bar0 for which bar0_data will write value.
	62	bar0_data :write data to be written at bar0_rw_offset.
	63
	64	Node programming example
65	===========================
66	Program all PCIe registers in such a way that when this device is connected
67	to the PCIe host, then host sees this device as 1MB RAM.
68	#mount -t configfs none /Config
69	For nth PCIe Device Controller
70	# cd /config/pcie_gadget.n/
71	Now you have all the nodes in this directory.
72	program vendor id as 0x104a
73	# echo 104A >> vendor_id
74
75	program device id as 0xCD80
76	# echo CD80 >> device_id
77
78	program BAR0 size as 1MB
79	# echo 100000 >> bar0_size
80
81	check for programmed bar0 size
82	# cat bar0_size
83
84	Program BAR0 Address as DDR (0x2100000). This is the physical address of
85	memory, which is to be made visible to PCIe host. Similarly any other peripheral
86	can also be made visible to PCIe host. E.g., if you program base address of UART
87	as BAR0 address then when this device will be connected to a host, it will be
88	visible as UART.
89	# echo 2100000 >> bar0_address
90
91	program interrupt type : INTA
92	# echo INTA >> int_type
93
94	go for link up now.
95	# echo UP >> link
96
97	It will have to be insured that, once link up is done on gadget, then only host
98	is initialized and start to search PCIe devices on its port.
99
100	/wait till link is up/
101	# cat link
102	wait till it returns UP.
103
104	To assert INTA
105	# echo 1 >> inta
106
107	To de-assert INTA
108	# echo 0 >> inta
109
110	if MSI is to be used as interrupt, program no of msi vector needed (say4)
111	# echo 4 >> no_of_msi
112
113	select MSI as interrupt type
114	# echo MSI >> int_type
115
116	go for link up now
117	# echo UP >> link
118
119	wait till link is up
120	# cat link
121	An application can repetitively read this node till link is found UP. It can
122	sleep between two read.
123
124	wait till msi is enabled
125	# cat no_of_msi
126	Should return 4 (number of requested MSI vector)
127
128	to send msi vector 2
129	# echo 2 >> send_msi
130	#cd -