1.. SPDX-License-Identifier: GPL-2.0
2
3=======================================
4Configuring PCI Endpoint Using CONFIGFS
5=======================================
6
7:Author: Kishon Vijay Abraham I <kishon@ti.com>
8
9The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
10PCI endpoint function and to bind the endpoint function
11with the endpoint controller. (For introducing other mechanisms to
12configure the PCI Endpoint Function refer to [1]).
13
14Mounting configfs
15=================
16
17The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
18directory. configfs can be mounted using the following command::
19
20	mount -t configfs none /sys/kernel/config
21
22Directory Structure
23===================
24
25The pci_ep configfs has two directories at its root: controllers and
26functions. Every EPC device present in the system will have an entry in
27the *controllers* directory and every EPF driver present in the system
28will have an entry in the *functions* directory.
29::
30
31	/sys/kernel/config/pci_ep/
32		.. controllers/
33		.. functions/
34
35Creating EPF Device
36===================
37
38Every registered EPF driver will be listed in controllers directory. The
39entries corresponding to EPF driver will be created by the EPF core.
40::
41
42	/sys/kernel/config/pci_ep/functions/
43		.. <EPF Driver1>/
44			... <EPF Device 11>/
45			... <EPF Device 21>/
46		.. <EPF Driver2>/
47			... <EPF Device 12>/
48			... <EPF Device 22>/
49
50In order to create a <EPF device> of the type probed by <EPF Driver>, the
51user has to create a directory inside <EPF DriverN>.
52
53Every <EPF device> directory consists of the following entries that can be
54used to configure the standard configuration header of the endpoint function.
55(These entries are created by the framework when any new <EPF Device> is
56created)
57::
58
59		.. <EPF Driver1>/
60			... <EPF Device 11>/
61				... vendorid
62				... deviceid
63				... revid
64				... progif_code
65				... subclass_code
66				... baseclass_code
67				... cache_line_size
68				... subsys_vendor_id
69				... subsys_id
70				... interrupt_pin
71                                ... primary/
72			                ... <Symlink EPC Device1>/
73                                ... secondary/
74			                ... <Symlink EPC Device2>/
75
76If an EPF device has to be associated with 2 EPCs (like in the case of
77Non-transparent bridge), symlink of endpoint controller connected to primary
78interface should be added in 'primary' directory and symlink of endpoint
79controller connected to secondary interface should be added in 'secondary'
80directory.
81
82EPC Device
83==========
84
85Every registered EPC device will be listed in controllers directory. The
86entries corresponding to EPC device will be created by the EPC core.
87::
88
89	/sys/kernel/config/pci_ep/controllers/
90		.. <EPC Device1>/
91			... <Symlink EPF Device11>/
92			... <Symlink EPF Device12>/
93			... start
94		.. <EPC Device2>/
95			... <Symlink EPF Device21>/
96			... <Symlink EPF Device22>/
97			... start
98
99The <EPC Device> directory will have a list of symbolic links to
100<EPF Device>. These symbolic links should be created by the user to
101represent the functions present in the endpoint device.
102
103The <EPC Device> directory will also have a *start* field. Once
104"1" is written to this field, the endpoint device will be ready to
105establish the link with the host. This is usually done after
106all the EPF devices are created and linked with the EPC device.
107::
108
109			 | controllers/
110				| <Directory: EPC name>/
111					| <Symbolic Link: Function>
112					| start
113			 | functions/
114				| <Directory: EPF driver>/
115					| <Directory: EPF device>/
116						| vendorid
117						| deviceid
118						| revid
119						| progif_code
120						| subclass_code
121						| baseclass_code
122						| cache_line_size
123						| subsys_vendor_id
124						| subsys_id
125						| interrupt_pin
126						| function
127
128[1] Documentation/PCI/endpoint/pci-endpoint.rst
129