diff mbox

[v2,04/22] Documentation: PCI: Guide to use pci endpoint configfs

Message ID 1487325042-28227-5-git-send-email-kishon@ti.com (mailing list archive)
State New, archived
Delegated to: Bjorn Helgaas
Headers show

Commit Message

Kishon Vijay Abraham I Feb. 17, 2017, 9:50 a.m. UTC 
Add Documentation to help users use pci endpoint to configure
pci endpoint function and to bind the endpoint function
with endpoint controller.

Signed-off-by: Kishon Vijay Abraham I <kishon@ti.com>
---
 Documentation/PCI/00-INDEX                      |    2 +
 Documentation/PCI/endpoint/pci-endpoint-cfs.txt |   84 +++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 Documentation/PCI/endpoint/pci-endpoint-cfs.txt

Comments

Joao Pinto Feb. 17, 2017, 1:05 p.m. UTC | #1 
Às 9:50 AM de 2/17/2017, Kishon Vijay Abraham I escreveu:
> Add Documentation to help users use pci endpoint to configure
> pci endpoint function and to bind the endpoint function
> with endpoint controller.
> 
> Signed-off-by: Kishon Vijay Abraham I <kishon@ti.com>
> ---
>  Documentation/PCI/00-INDEX                      |    2 +
>  Documentation/PCI/endpoint/pci-endpoint-cfs.txt |   84 +++++++++++++++++++++++
>  2 files changed, 86 insertions(+)
>  create mode 100644 Documentation/PCI/endpoint/pci-endpoint-cfs.txt
> 
> diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
> index ba950b2..f84a23c 100644
> --- a/Documentation/PCI/00-INDEX
> +++ b/Documentation/PCI/00-INDEX
> @@ -14,3 +14,5 @@ pcieaer-howto.txt
>  	- the PCI Express Advanced Error Reporting Driver Guide HOWTO
>  endpoint/pci-endpoint.txt
>  	- guide to add endpoint controller driver and endpoint function driver.
> +endpoint/pci-endpoint-cfs.txt
> +	- guide to use configfs to configure the pci endpoint function.
> diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
> new file mode 100644
> index 0000000..d9f8734
> --- /dev/null
> +++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
> @@ -0,0 +1,84 @@
> +                   CONFIGURING PCI ENDPOINT USING CONFIGFS
> +                    Kishon Vijay Abraham I <kishon@ti.com>
> +
> +The PCI Endpoint Core exposes configfs entry (pci_ep) in order to configure the
> +PCI endpoint function and in order to bind the endpoint function
> +with the endpoint controller. (For introducing other mechanisms to
> +configure the PCI Endpoint Function refer [1]).
> +
> +*) Mounting configfs
> +
> +The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
> +directory. configfs can be mounted using the following command.
> +
> +	mount -t configfs none /sys/kernel/config
> +
> +*) Directory Structure
> +
> +The pci_ep configfs directory structure has been created to reflect the
> +natural tree like structure of PCI devices. So every directory created
> +inside pci_ep represents a EPC device and every directory created inside
> +epf directory represents EPF device.
> +
> +/sys/kernel/config/pci_ep/
> +			 | <dir>/ --------------------------------------> [2]
> +				| epc
> +				| epf/
> +				     | <dir>/ --------------------------> [3]
> +					    | vendorid
> +					    | deviceid
> +					    | revid
> +					    | progif_code
> +					    | subclass_code
> +					    | baseclass_code
> +					    | cache_line_size
> +					    | subsys_vendor_id
> +					    | subsys_id
> +					    | interrupt_pin
> +					    | function
> +
> +*) Creating configfs entry for EPC
> +
> +Any directory created inside *pci_ep* represents an EPC device. In the above
> +directory structure [2] represents an EPC device. It consists of
> +
> +	*) epc: Use it to associate the configfs entry to an actual EPC device.
> +		The list of valid entries for this field can be obtained from
> +			ls /sys/class/pci_epc/
> +
> +	*) epf: Directory that contains all the endpoint functions. The name
> +		of the created directory determines the driver this particular
> +		epf device will be bound to. The name can be obtained either
> +		from the function binding documentation [4] or
> +			ls /sys/bus/pci-epf/drivers
> +
> +		If more than one endpoint function device has to be bound to
> +		the same driver, then the directory should be created using
> +		the following notation
> +			mkdir <name>.<num>
> +
> +*) Creating configfs entry for EPF
> +
> +Any directory created inside *epf* directory represents an EPF device. In the
> +above directory structure, [3] represents an EPF device. It consists of the
> +following entries that can be used to configure the standard configuration
> +header of the endpoint function. (These entries are created by the
> +framework when any new directory is created inside epf directory.)
> +
> +        | vendorid
> +        | deviceid
> +        | revid
> +        | progif_code
> +        | subclass_code
> +        | baseclass_code
> +        | cache_line_size
> +        | subsys_vendor_id
> +        | subsys_id
> +        | interrupt_pin
> +
> +The following entry identifies the function driver that is bound to the
> +function device
> +	| function
> +
> +[1] -> Documentation/PCI/endpoint/pci-endpoint.txt
> +[4] -> Documentation/PCI/endpoint/function/binding/
> 

Good content.

Acked-By: Joao Pinto <jpinto@synopsys.com>
Christoph Hellwig Feb. 17, 2017, 5:15 p.m. UTC | #2 
I'm commenting on the configfs layout here instead of the patch with the
code as the issues are easier to explain that way.  I think the layout
is a bit confusing and could be cleaner by making use of pre-created
entries and symlinks.  Here is my suggestion:

/sys/kernel/config/pci_ep/functions/		
    .. test/					# a directory for each function driver
       ... user-specified-name1/
       ... user-specified-name2
    .. nvme/
       ... user-specified-name42/		

Each directory under /sys/kernel/config/pci_ep/functions/ is owned
by a function drivers.  Under that function driver's directory you
can create a directory for each instance of a function driver.  The
configfs layout is controlled by the function driver.  E.g. your current
EPF fields would move into the test function driver, while the nvme
function would expose totally different fields.


/sys/kernel/config/pci_ep/controllers/
	... dwc-0/
	    ... function
	... dwc-1/
	    ... function
	... vhost-0/
	    ... function

	Here you have a directory for each controller that can be bound
	to a function.  The directories are pre-created for each
	controller port that is EP capable.
	Function is a symlink to the function instance above.
	Additional parameters might also be present depending on the
	EPC driver.
Kishon Vijay Abraham I March 6, 2017, 10:16 a.m. UTC | #3 
Hi,

On Friday 17 February 2017 10:45 PM, Christoph Hellwig wrote:
> I'm commenting on the configfs layout here instead of the patch with the
> code as the issues are easier to explain that way.  I think the layout
> is a bit confusing and could be cleaner by making use of pre-created
> entries and symlinks.  Here is my suggestion:
> 
> /sys/kernel/config/pci_ep/functions/		
>     .. test/					# a directory for each function driver
>        ... user-specified-name1/
>        ... user-specified-name2
>     .. nvme/
>        ... user-specified-name42/		
> 
> Each directory under /sys/kernel/config/pci_ep/functions/ is owned
> by a function drivers.  Under that function driver's directory you
> can create a directory for each instance of a function driver.  The
> configfs layout is controlled by the function driver.  E.g. your current
> EPF fields would move into the test function driver, while the nvme
> function would expose totally different fields.
> 
> 
> /sys/kernel/config/pci_ep/controllers/
> 	... dwc-0/
> 	    ... function
> 	... dwc-1/
> 	    ... function
> 	... vhost-0/
> 	    ... function
> 
> 	Here you have a directory for each controller that can be bound
> 	to a function.  The directories are pre-created for each
> 	controller port that is EP capable.
> 	Function is a symlink to the function instance above.
> 	Additional parameters might also be present depending on the
> 	EPC driver.

I've changed the configfs entry according to your suggestion. However I've
considered only the generic test function and a standard EP controller and
implemented the configfs in a single file pci-ep-cfs.c. But I think this will
get more complex as we add custom parameters for individual EPC, new functions
etc..

Thanks
Kishon
diff mbox

Patch

diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX
index ba950b2..f84a23c 100644
--- a/Documentation/PCI/00-INDEX
+++ b/Documentation/PCI/00-INDEX
@@ -14,3 +14,5 @@  pcieaer-howto.txt
 	- the PCI Express Advanced Error Reporting Driver Guide HOWTO
 endpoint/pci-endpoint.txt
 	- guide to add endpoint controller driver and endpoint function driver.
+endpoint/pci-endpoint-cfs.txt
+	- guide to use configfs to configure the pci endpoint function.
diff --git a/Documentation/PCI/endpoint/pci-endpoint-cfs.txt b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
new file mode 100644
index 0000000..d9f8734
--- /dev/null
+++ b/Documentation/PCI/endpoint/pci-endpoint-cfs.txt
@@ -0,0 +1,84 @@ 
+                   CONFIGURING PCI ENDPOINT USING CONFIGFS
+                    Kishon Vijay Abraham I <kishon@ti.com>
+
+The PCI Endpoint Core exposes configfs entry (pci_ep) in order to configure the
+PCI endpoint function and in order to bind the endpoint function
+with the endpoint controller. (For introducing other mechanisms to
+configure the PCI Endpoint Function refer [1]).
+
+*) Mounting configfs
+
+The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
+directory. configfs can be mounted using the following command.
+
+	mount -t configfs none /sys/kernel/config
+
+*) Directory Structure
+
+The pci_ep configfs directory structure has been created to reflect the
+natural tree like structure of PCI devices. So every directory created
+inside pci_ep represents a EPC device and every directory created inside
+epf directory represents EPF device.
+
+/sys/kernel/config/pci_ep/
+			 | <dir>/ --------------------------------------> [2]
+				| epc
+				| epf/
+				     | <dir>/ --------------------------> [3]
+					    | vendorid
+					    | deviceid
+					    | revid
+					    | progif_code
+					    | subclass_code
+					    | baseclass_code
+					    | cache_line_size
+					    | subsys_vendor_id
+					    | subsys_id
+					    | interrupt_pin
+					    | function
+
+*) Creating configfs entry for EPC
+
+Any directory created inside *pci_ep* represents an EPC device. In the above
+directory structure [2] represents an EPC device. It consists of
+
+	*) epc: Use it to associate the configfs entry to an actual EPC device.
+		The list of valid entries for this field can be obtained from
+			ls /sys/class/pci_epc/
+
+	*) epf: Directory that contains all the endpoint functions. The name
+		of the created directory determines the driver this particular
+		epf device will be bound to. The name can be obtained either
+		from the function binding documentation [4] or
+			ls /sys/bus/pci-epf/drivers
+
+		If more than one endpoint function device has to be bound to
+		the same driver, then the directory should be created using
+		the following notation
+			mkdir <name>.<num>
+
+*) Creating configfs entry for EPF
+
+Any directory created inside *epf* directory represents an EPF device. In the
+above directory structure, [3] represents an EPF device. It consists of the
+following entries that can be used to configure the standard configuration
+header of the endpoint function. (These entries are created by the
+framework when any new directory is created inside epf directory.)
+
+        | vendorid
+        | deviceid
+        | revid
+        | progif_code
+        | subclass_code
+        | baseclass_code
+        | cache_line_size
+        | subsys_vendor_id
+        | subsys_id
+        | interrupt_pin
+
+The following entry identifies the function driver that is bound to the
+function device
+	| function
+
+[1] -> Documentation/PCI/endpoint/pci-endpoint.txt
+[4] -> Documentation/PCI/endpoint/function/binding/