Merge tag 'pci-v5.3-changes' of git://git.kernel.org/pub/scm/linux/kernel/git/helgaas/pci (fb4da215) · Commits · jan.koester / Linux

Documentation/ABI/testing/sysfs-class-powercap

+1 −1

Original line number	Original line	Diff line number	Diff line
	@@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org
	Description:		Description:
	The powercap/ class sub directory belongs to the power cap		The powercap/ class sub directory belongs to the power cap
	subsystem. Refer to		subsystem. Refer to
	Documentation/power/powercap/powercap.txt for details.		Documentation/power/powercap/powercap.rst for details.

	What: /sys/class/powercap/<control type>		What: /sys/class/powercap/<control type>
	Date: September 2013		Date: September 2013

Documentation/PCI/acpi-info.txt→Documentation/PCI/acpi-info.rst

+7 −2

Original line number	Original line	Diff line number	Diff line
			.. SPDX-License-Identifier: GPL-2.0

			========================================
	ACPI considerations for PCI host bridges		ACPI considerations for PCI host bridges
			========================================

	The general rule is that the ACPI namespace should describe everything the		The general rule is that the ACPI namespace should describe everything the
	OS might use unless there's another way for the OS to find it [1, 2].		OS might use unless there's another way for the OS to find it [1, 2].
	@@ -135,8 +139,9 @@ address always corresponds to bus 0, even if the bus range below the bridge

	Extended Address Space Descriptor (.4)		Extended Address Space Descriptor (.4)
	General Flags: Bit [0] Consumer/Producer:		General Flags: Bit [0] Consumer/Producer:
	1–This device consumes this resource
	0–This device produces and consumes this resource		* 1 – This device consumes this resource
			* 0 – This device produces and consumes this resource

	[5] ACPI 6.2, sec 19.6.43:		[5] ACPI 6.2, sec 19.6.43:
	ResourceUsage specifies whether the Memory range is consumed by		ResourceUsage specifies whether the Memory range is consumed by

Documentation/PCI/endpoint/index.rst

0 → 100644

+13 −0

Original line number	Original line	Diff line number	Diff line
			.. SPDX-License-Identifier: GPL-2.0

			======================
			PCI Endpoint Framework
			======================

			.. toctree::
			:maxdepth: 2

			pci-endpoint
			pci-endpoint-cfs
			pci-test-function
			pci-test-howto

Documentation/PCI/endpoint/pci-endpoint-cfs.txt→Documentation/PCI/endpoint/pci-endpoint-cfs.rst

+22 −9

Original line number	Original line	Diff line number	Diff line
	CONFIGURING PCI ENDPOINT USING CONFIGFS		.. SPDX-License-Identifier: GPL-2.0
	Kishon Vijay Abraham I <kishon@ti.com>
			=======================================
			Configuring PCI Endpoint Using CONFIGFS
			=======================================

			:Author: Kishon Vijay Abraham I <kishon@ti.com>

	The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the		The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
	PCI endpoint function and to bind the endpoint function		PCI endpoint function and to bind the endpoint function
	with the endpoint controller. (For introducing other mechanisms to		with the endpoint controller. (For introducing other mechanisms to
	configure the PCI Endpoint Function refer to [1]).		configure the PCI Endpoint Function refer to [1]).

	*) Mounting configfs		Mounting configfs
			=================

	The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs		The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
	directory. configfs can be mounted using the following command.		directory. configfs can be mounted using the following command::

	mount -t configfs none /sys/kernel/config		mount -t configfs none /sys/kernel/config

	*) Directory Structure		Directory Structure
			===================

	The pci_ep configfs has two directories at its root: controllers and		The pci_ep configfs has two directories at its root: controllers and
	functions. Every EPC device present in the system will have an entry in		functions. Every EPC device present in the system will have an entry in
	the controllers directory and and every EPF driver present in the system		the controllers directory and and every EPF driver present in the system
	will have an entry in the functions directory.		will have an entry in the functions directory.
			::

	/sys/kernel/config/pci_ep/		/sys/kernel/config/pci_ep/
	.. controllers/		.. controllers/
	.. functions/		.. functions/

	*) Creating EPF Device		Creating EPF Device
			===================

	Every registered EPF driver will be listed in controllers directory. The		Every registered EPF driver will be listed in controllers directory. The
	entries corresponding to EPF driver will be created by the EPF core.		entries corresponding to EPF driver will be created by the EPF core.
			::

	/sys/kernel/config/pci_ep/functions/		/sys/kernel/config/pci_ep/functions/
	.. <EPF Driver1>/		.. <EPF Driver1>/
	@@ -44,6 +54,7 @@ Every <EPF device> directory consists of the following entries that can be
	used to configure the standard configuration header of the endpoint function.		used to configure the standard configuration header of the endpoint function.
	(These entries are created by the framework when any new <EPF Device> is		(These entries are created by the framework when any new <EPF Device> is
	created)		created)
			::

	.. <EPF Driver1>/		.. <EPF Driver1>/
	... <EPF Device 11>/		... <EPF Device 11>/
	@@ -58,10 +69,12 @@ created)
	... subsys_id		... subsys_id
	... interrupt_pin		... interrupt_pin

	*) EPC Device		EPC Device
			==========

	Every registered EPC device will be listed in controllers directory. The		Every registered EPC device will be listed in controllers directory. The
	entries corresponding to EPC device will be created by the EPC core.		entries corresponding to EPC device will be created by the EPC core.
			::

	/sys/kernel/config/pci_ep/controllers/		/sys/kernel/config/pci_ep/controllers/
	.. <EPC Device1>/		.. <EPC Device1>/
	@@ -81,7 +94,7 @@ The <EPC Device> directory will also have a start field. Once
	"1" is written to this field, the endpoint device will be ready to		"1" is written to this field, the endpoint device will be ready to
	establish the link with the host. This is usually done after		establish the link with the host. This is usually done after
	all the EPF devices are created and linked with the EPC device.		all the EPF devices are created and linked with the EPC device.
			::

	\| controllers/		\| controllers/
	\| <Directory: EPC name>/		\| <Directory: EPC name>/
	@@ -102,4 +115,4 @@ all the EPF devices are created and linked with the EPC device.
	\| interrupt_pin		\| interrupt_pin
	\| function		\| function

	[1] -> Documentation/PCI/endpoint/pci-endpoint.txt		[1] :doc:`pci-endpoint`

Documentation/PCI/endpoint/pci-endpoint.txt→Documentation/PCI/endpoint/pci-endpoint.rst

+54 −38

Original line number	Original line	Diff line number	Diff line
	PCI ENDPOINT FRAMEWORK		.. SPDX-License-Identifier: GPL-2.0
	Kishon Vijay Abraham I <kishon@ti.com>
			:Author: Kishon Vijay Abraham I <kishon@ti.com>

	This document is a guide to use the PCI Endpoint Framework in order to create		This document is a guide to use the PCI Endpoint Framework in order to create
	endpoint controller driver, endpoint function driver, and using configfs		endpoint controller driver, endpoint function driver, and using configfs
	interface to bind the function driver to the controller driver.		interface to bind the function driver to the controller driver.

	1. Introduction		Introduction
			============

	Linux has a comprehensive PCI subsystem to support PCI controllers that		Linux has a comprehensive PCI subsystem to support PCI controllers that
	operates in Root Complex mode. The subsystem has capability to scan PCI bus,		operates in Root Complex mode. The subsystem has capability to scan PCI bus,
	@@ -19,26 +21,30 @@ add endpoint mode support in Linux. This will help to run Linux in an
	EP system which can have a wide variety of use cases from testing or		EP system which can have a wide variety of use cases from testing or
	validation, co-processor accelerator, etc.		validation, co-processor accelerator, etc.

	2. PCI Endpoint Core		PCI Endpoint Core
			=================

	The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller		The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
	library, the Endpoint Function library, and the configfs layer to bind the		library, the Endpoint Function library, and the configfs layer to bind the
	endpoint function with the endpoint controller.		endpoint function with the endpoint controller.

	2.1 PCI Endpoint Controller(EPC) Library		PCI Endpoint Controller(EPC) Library
			------------------------------------

	The EPC library provides APIs to be used by the controller that can operate		The EPC library provides APIs to be used by the controller that can operate
	in endpoint mode. It also provides APIs to be used by function driver/library		in endpoint mode. It also provides APIs to be used by function driver/library
	in order to implement a particular endpoint function.		in order to implement a particular endpoint function.

	2.1.1 APIs for the PCI controller Driver		APIs for the PCI controller Driver
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This section lists the APIs that the PCI Endpoint core provides to be used		This section lists the APIs that the PCI Endpoint core provides to be used
	by the PCI controller driver.		by the PCI controller driver.

	*) devm_pci_epc_create()/pci_epc_create()		* devm_pci_epc_create()/pci_epc_create()

	The PCI controller driver should implement the following ops:		The PCI controller driver should implement the following ops:

	* write_header: ops to populate configuration space header		* write_header: ops to populate configuration space header
	* set_bar: ops to configure the BAR		* set_bar: ops to configure the BAR
	* clear_bar: ops to reset the BAR		* clear_bar: ops to reset the BAR
	@@ -51,110 +57,116 @@ by the PCI controller driver.
	The PCI controller driver can then create a new EPC device by invoking		The PCI controller driver can then create a new EPC device by invoking
	devm_pci_epc_create()/pci_epc_create().		devm_pci_epc_create()/pci_epc_create().

	*) devm_pci_epc_destroy()/pci_epc_destroy()		* devm_pci_epc_destroy()/pci_epc_destroy()

	The PCI controller driver can destroy the EPC device created by either		The PCI controller driver can destroy the EPC device created by either
	devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or		devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
	pci_epc_destroy().		pci_epc_destroy().

	*) pci_epc_linkup()		* pci_epc_linkup()

	In order to notify all the function devices that the EPC device to which		In order to notify all the function devices that the EPC device to which
	they are linked has established a link with the host, the PCI controller		they are linked has established a link with the host, the PCI controller
	driver should invoke pci_epc_linkup().		driver should invoke pci_epc_linkup().

	*) pci_epc_mem_init()		* pci_epc_mem_init()

	Initialize the pci_epc_mem structure used for allocating EPC addr space.		Initialize the pci_epc_mem structure used for allocating EPC addr space.

	*) pci_epc_mem_exit()		* pci_epc_mem_exit()

	Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().		Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().

	2.1.2 APIs for the PCI Endpoint Function Driver
			APIs for the PCI Endpoint Function Driver
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This section lists the APIs that the PCI Endpoint core provides to be used		This section lists the APIs that the PCI Endpoint core provides to be used
	by the PCI endpoint function driver.		by the PCI endpoint function driver.

	*) pci_epc_write_header()		* pci_epc_write_header()

	The PCI endpoint function driver should use pci_epc_write_header() to		The PCI endpoint function driver should use pci_epc_write_header() to
	write the standard configuration header to the endpoint controller.		write the standard configuration header to the endpoint controller.

	*) pci_epc_set_bar()		* pci_epc_set_bar()

	The PCI endpoint function driver should use pci_epc_set_bar() to configure		The PCI endpoint function driver should use pci_epc_set_bar() to configure
	the Base Address Register in order for the host to assign PCI addr space.		the Base Address Register in order for the host to assign PCI addr space.
	Register space of the function driver is usually configured		Register space of the function driver is usually configured
	using this API.		using this API.

	*) pci_epc_clear_bar()		* pci_epc_clear_bar()

	The PCI endpoint function driver should use pci_epc_clear_bar() to reset		The PCI endpoint function driver should use pci_epc_clear_bar() to reset
	the BAR.		the BAR.

	*) pci_epc_raise_irq()		* pci_epc_raise_irq()

	The PCI endpoint function driver should use pci_epc_raise_irq() to raise		The PCI endpoint function driver should use pci_epc_raise_irq() to raise
	Legacy Interrupt, MSI or MSI-X Interrupt.		Legacy Interrupt, MSI or MSI-X Interrupt.

	*) pci_epc_mem_alloc_addr()		* pci_epc_mem_alloc_addr()

	The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to		The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
	allocate memory address from EPC addr space which is required to access		allocate memory address from EPC addr space which is required to access
	RC's buffer		RC's buffer

	*) pci_epc_mem_free_addr()		* pci_epc_mem_free_addr()

	The PCI endpoint function driver should use pci_epc_mem_free_addr() to		The PCI endpoint function driver should use pci_epc_mem_free_addr() to
	free the memory space allocated using pci_epc_mem_alloc_addr().		free the memory space allocated using pci_epc_mem_alloc_addr().

	2.1.3 Other APIs		Other APIs
			~~~~~~~~~~

	There are other APIs provided by the EPC library. These are used for binding		There are other APIs provided by the EPC library. These are used for binding
	the EPF device with EPC device. pci-ep-cfs.c can be used as reference for		the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
	using these APIs.		using these APIs.

	*) pci_epc_get()		* pci_epc_get()

	Get a reference to the PCI endpoint controller based on the device name of		Get a reference to the PCI endpoint controller based on the device name of
	the controller.		the controller.

	*) pci_epc_put()		* pci_epc_put()

	Release the reference to the PCI endpoint controller obtained using		Release the reference to the PCI endpoint controller obtained using
	pci_epc_get()		pci_epc_get()

	*) pci_epc_add_epf()		* pci_epc_add_epf()

	Add a PCI endpoint function to a PCI endpoint controller. A PCIe device		Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
	can have up to 8 functions according to the specification.		can have up to 8 functions according to the specification.

	*) pci_epc_remove_epf()		* pci_epc_remove_epf()

	Remove the PCI endpoint function from PCI endpoint controller.		Remove the PCI endpoint function from PCI endpoint controller.

	*) pci_epc_start()		* pci_epc_start()

	The PCI endpoint function driver should invoke pci_epc_start() once it		The PCI endpoint function driver should invoke pci_epc_start() once it
	has configured the endpoint function and wants to start the PCI link.		has configured the endpoint function and wants to start the PCI link.

	*) pci_epc_stop()		* pci_epc_stop()

	The PCI endpoint function driver should invoke pci_epc_stop() to stop		The PCI endpoint function driver should invoke pci_epc_stop() to stop
	the PCI LINK.		the PCI LINK.

	2.2 PCI Endpoint Function(EPF) Library
			PCI Endpoint Function(EPF) Library
			----------------------------------

	The EPF library provides APIs to be used by the function driver and the EPC		The EPF library provides APIs to be used by the function driver and the EPC
	library to provide endpoint mode functionality.		library to provide endpoint mode functionality.

	2.2.1 APIs for the PCI Endpoint Function Driver		APIs for the PCI Endpoint Function Driver
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This section lists the APIs that the PCI Endpoint core provides to be used		This section lists the APIs that the PCI Endpoint core provides to be used
	by the PCI endpoint function driver.		by the PCI endpoint function driver.

	*) pci_epf_register_driver()		* pci_epf_register_driver()

	The PCI Endpoint Function driver should implement the following ops:		The PCI Endpoint Function driver should implement the following ops:
	* bind: ops to perform when a EPC device has been bound to EPF device		* bind: ops to perform when a EPC device has been bound to EPF device
	@@ -166,50 +178,54 @@ by the PCI endpoint function driver.
	The PCI Function driver can then register the PCI EPF driver by using		The PCI Function driver can then register the PCI EPF driver by using
	pci_epf_register_driver().		pci_epf_register_driver().

	*) pci_epf_unregister_driver()		* pci_epf_unregister_driver()

	The PCI Function driver can unregister the PCI EPF driver by using		The PCI Function driver can unregister the PCI EPF driver by using
	pci_epf_unregister_driver().		pci_epf_unregister_driver().

	*) pci_epf_alloc_space()		* pci_epf_alloc_space()

	The PCI Function driver can allocate space for a particular BAR using		The PCI Function driver can allocate space for a particular BAR using
	pci_epf_alloc_space().		pci_epf_alloc_space().

	*) pci_epf_free_space()		* pci_epf_free_space()

	The PCI Function driver can free the allocated space		The PCI Function driver can free the allocated space
	(using pci_epf_alloc_space) by invoking pci_epf_free_space().		(using pci_epf_alloc_space) by invoking pci_epf_free_space().

	2.2.2 APIs for the PCI Endpoint Controller Library		APIs for the PCI Endpoint Controller Library
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This section lists the APIs that the PCI Endpoint core provides to be used		This section lists the APIs that the PCI Endpoint core provides to be used
	by the PCI endpoint controller library.		by the PCI endpoint controller library.

	*) pci_epf_linkup()		* pci_epf_linkup()

	The PCI endpoint controller library invokes pci_epf_linkup() when the		The PCI endpoint controller library invokes pci_epf_linkup() when the
	EPC device has established the connection to the host.		EPC device has established the connection to the host.

	2.2.2 Other APIs		Other APIs
			~~~~~~~~~~

	There are other APIs provided by the EPF library. These are used to notify		There are other APIs provided by the EPF library. These are used to notify
	the function driver when the EPF device is bound to the EPC device.		the function driver when the EPF device is bound to the EPC device.
	pci-ep-cfs.c can be used as reference for using these APIs.		pci-ep-cfs.c can be used as reference for using these APIs.

	*) pci_epf_create()		* pci_epf_create()

	Create a new PCI EPF device by passing the name of the PCI EPF device.		Create a new PCI EPF device by passing the name of the PCI EPF device.
	This name will be used to bind the the EPF device to a EPF driver.		This name will be used to bind the the EPF device to a EPF driver.

	*) pci_epf_destroy()		* pci_epf_destroy()

	Destroy the created PCI EPF device.		Destroy the created PCI EPF device.

	*) pci_epf_bind()		* pci_epf_bind()

	pci_epf_bind() should be invoked when the EPF device has been bound to		pci_epf_bind() should be invoked when the EPF device has been bound to
	a EPC device.		a EPC device.

	*) pci_epf_unbind()		* pci_epf_unbind()

	pci_epf_unbind() should be invoked when the binding between EPC device		pci_epf_unbind() should be invoked when the binding between EPC device
	and EPF device is lost.		and EPF device is lost.