Merge branch 'pci/host-designware' into next

	- info on the PCI subsystem for device driver authors

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.

endpoint/pci-test-function.txt

	- specification of *PCI test* function device.

endpoint/pci-test-howto.txt

	- userguide for PCI endpoint test function.

endpoint/function/binding/

	- binding documentation for PCI endpoint function

PCI TEST ENDPOINT FUNCTION

name: Should be "pci_epf_test" to bind to the pci_epf_test driver.

Configurable Fields:

vendorid	 : should be 0x104c

deviceid	 : should be 0xb500 for DRA74x and 0xb501 for DRA72x

revid		 : don't care

progif_code	 : don't care

subclass_code	 : don't care

baseclass_code	 : should be 0xff

cache_line_size	 : don't care

subsys_vendor_id : don't care

subsys_id	 : don't care

interrupt_pin	 : Should be 1 - INTA, 2 - INTB, 3 - INTC, 4 -INTD

msi_interrupts	 : Should be 1 to 32 depending on the number of MSI interrupts

		   to test

                   CONFIGURING PCI ENDPOINT USING CONFIGFS

                    Kishon Vijay Abraham I <kishon@ti.com>

The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the

PCI endpoint function and to bind the endpoint function

with the endpoint controller. (For introducing other mechanisms to

configure the PCI Endpoint Function refer to [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 has two directories at its root: controllers and

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

will have an entry in the *functions* directory.

/sys/kernel/config/pci_ep/

	.. controllers/

	.. functions/

*) Creating EPF Device

Every registered EPF driver will be listed in controllers directory. The

entries corresponding to EPF driver will be created by the EPF core.

/sys/kernel/config/pci_ep/functions/

	.. <EPF Driver1>/

		... <EPF Device 11>/

		... <EPF Device 21>/

	.. <EPF Driver2>/

		... <EPF Device 12>/

		... <EPF Device 22>/

In order to create a <EPF device> of the type probed by <EPF Driver>, the

user has to create a directory inside <EPF DriverN>.

Every <EPF device> directory 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 <EPF Device> is

created)

	.. <EPF Driver1>/

		... <EPF Device 11>/

			... vendorid

			... deviceid

			... revid

			... progif_code

			... subclass_code

			... baseclass_code

			... cache_line_size

			... subsys_vendor_id

			... subsys_id

			... interrupt_pin

*) EPC Device

Every registered EPC device will be listed in controllers directory. The

entries corresponding to EPC device will be created by the EPC core.

/sys/kernel/config/pci_ep/controllers/

	.. <EPC Device1>/

		... <Symlink EPF Device11>/

		... <Symlink EPF Device12>/

		... start

	.. <EPC Device2>/

		... <Symlink EPF Device21>/

		... <Symlink EPF Device22>/

		... start

The <EPC Device> directory will have a list of symbolic links to

<EPF Device>. These symbolic links should be created by the user to

represent the functions present in the endpoint device.

The <EPC Device> directory will also have a *start* field. Once

"1" is written to this field, the endpoint device will be ready to

establish the link with the host. This is usually done after

all the EPF devices are created and linked with the EPC device.

			 | controllers/

				| <Directory: EPC name>/

					| <Symbolic Link: Function>

					| start

			 | functions/

				| <Directory: EPF driver>/

					| <Directory: EPF device>/

						| vendorid

						| deviceid

						| revid

						| progif_code

						| subclass_code

						| baseclass_code

						| cache_line_size

						| subsys_vendor_id

						| subsys_id

						| interrupt_pin

						| function

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

			    PCI ENDPOINT FRAMEWORK

		    Kishon Vijay Abraham I <kishon@ti.com>

This document is a guide to use the PCI Endpoint Framework in order to create

endpoint controller driver, endpoint function driver, and using configfs

interface to bind the function driver to the controller driver.

1. Introduction

Linux has a comprehensive PCI subsystem to support PCI controllers that

operates in Root Complex mode. The subsystem has capability to scan PCI bus,

assign memory resources and IRQ resources, load PCI driver (based on

vendor ID, device ID), support other services like hot-plug, power management,

advanced error reporting and virtual channels.

However the PCI controller IP integrated in some SoCs is capable of operating

either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will

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

validation, co-processor accelerator, etc.

2. PCI Endpoint Core

The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller

library, the Endpoint Function library, and the configfs layer to bind the

endpoint function with the endpoint controller.

2.1 PCI Endpoint Controller(EPC) Library

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 order to implement a particular endpoint function.

2.1.1 APIs for the PCI controller Driver

This section lists the APIs that the PCI Endpoint core provides to be used

by the PCI controller driver.

*) devm_pci_epc_create()/pci_epc_create()

   The PCI controller driver should implement the following ops:

	 * write_header: ops to populate configuration space header

	 * set_bar: ops to configure the BAR

	 * clear_bar: ops to reset the BAR

	 * alloc_addr_space: ops to allocate in PCI controller address space

	 * free_addr_space: ops to free the allocated address space

	 * raise_irq: ops to raise a legacy or MSI interrupt

	 * start: ops to start the PCI link

	 * stop: ops to stop the PCI link

   The PCI controller driver can then create a new EPC device by invoking

   devm_pci_epc_create()/pci_epc_create().

*) devm_pci_epc_destroy()/pci_epc_destroy()

   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

   pci_epc_destroy().

*) pci_epc_linkup()

   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

   driver should invoke pci_epc_linkup().

*) pci_epc_mem_init()

   Initialize the pci_epc_mem structure used for allocating EPC addr space.

*) pci_epc_mem_exit()

   Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().

2.1.2 APIs for the PCI Endpoint Function Driver

This section lists the APIs that the PCI Endpoint core provides to be used

by the PCI endpoint function driver.

*) pci_epc_write_header()

   The PCI endpoint function driver should use pci_epc_write_header() to

   write the standard configuration header to the endpoint controller.

*) pci_epc_set_bar()

   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.

   Register space of the function driver is usually configured

   using this API.

*) pci_epc_clear_bar()

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

   the BAR.

*) pci_epc_raise_irq()

   The PCI endpoint function driver should use pci_epc_raise_irq() to raise

   Legacy Interrupt or MSI Interrupt.

*) pci_epc_mem_alloc_addr()

   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

   RC's buffer

*) pci_epc_mem_free_addr()

   The PCI endpoint function driver should use pci_epc_mem_free_addr() to

   free the memory space allocated using pci_epc_mem_alloc_addr().

2.1.3 Other APIs

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

using these APIs.

*) pci_epc_get()

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

   the controller.

*) pci_epc_put()

   Release the reference to the PCI endpoint controller obtained using

   pci_epc_get()

*) pci_epc_add_epf()

   Add a PCI endpoint function to a PCI endpoint controller. A PCIe device

   can have up to 8 functions according to the specification.

*) pci_epc_remove_epf()

   Remove the PCI endpoint function from PCI endpoint controller.

*) pci_epc_start()

   The PCI endpoint function driver should invoke pci_epc_start() once it

   has configured the endpoint function and wants to start the PCI link.

*) pci_epc_stop()

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

   the PCI LINK.

2.2 PCI Endpoint Function(EPF) Library

The EPF library provides APIs to be used by the function driver and the EPC

library to provide endpoint mode functionality.

2.2.1 APIs for the PCI Endpoint Function Driver

This section lists the APIs that the PCI Endpoint core provides to be used

by the PCI endpoint function driver.

*) pci_epf_register_driver()

   The PCI Endpoint Function driver should implement the following ops:

	 * bind: ops to perform when a EPC device has been bound to EPF device

	 * unbind: ops to perform when a binding has been lost between a EPC

	   device and EPF device

	 * linkup: ops to perform when the EPC device has established a

	   connection with a host system

  The PCI Function driver can then register the PCI EPF driver by using

  pci_epf_register_driver().

*) pci_epf_unregister_driver()

  The PCI Function driver can unregister the PCI EPF driver by using

  pci_epf_unregister_driver().

*) pci_epf_alloc_space()

  The PCI Function driver can allocate space for a particular BAR using

  pci_epf_alloc_space().

*) pci_epf_free_space()

  The PCI Function driver can free the allocated space

  (using pci_epf_alloc_space) by invoking pci_epf_free_space().

2.2.2 APIs for the PCI Endpoint Controller Library

This section lists the APIs that the PCI Endpoint core provides to be used

by the PCI endpoint controller library.

*) pci_epf_linkup()

   The PCI endpoint controller library invokes pci_epf_linkup() when the

   EPC device has established the connection to the host.

2.2.2 Other APIs

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.

pci-ep-cfs.c can be used as reference for using these APIs.

*) pci_epf_create()

   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.

*) pci_epf_destroy()

   Destroy the created PCI EPF device.

*) pci_epf_bind()

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

   a EPC device.

*) pci_epf_unbind()

   pci_epf_unbind() should be invoked when the binding between EPC device

   and EPF device is lost.

				PCI TEST

		    Kishon Vijay Abraham I <kishon@ti.com>

Traditionally PCI RC has always been validated by using standard

PCI cards like ethernet PCI cards or USB PCI cards or SATA PCI cards.

However with the addition of EP-core in linux kernel, it is possible

to configure a PCI controller that can operate in EP mode to work as

a test device.

The PCI endpoint test device is a virtual device (defined in software)

used to test the endpoint functionality and serve as a sample driver

for other PCI endpoint devices (to use the EP framework).

The PCI endpoint test device has the following registers:

	1) PCI_ENDPOINT_TEST_MAGIC

	2) PCI_ENDPOINT_TEST_COMMAND

	3) PCI_ENDPOINT_TEST_STATUS

	4) PCI_ENDPOINT_TEST_SRC_ADDR

	5) PCI_ENDPOINT_TEST_DST_ADDR

	6) PCI_ENDPOINT_TEST_SIZE

	7) PCI_ENDPOINT_TEST_CHECKSUM

*) PCI_ENDPOINT_TEST_MAGIC

This register will be used to test BAR0. A known pattern will be written

and read back from MAGIC register to verify BAR0.

*) PCI_ENDPOINT_TEST_COMMAND:

This register will be used by the host driver to indicate the function

that the endpoint device must perform.

Bitfield Description:

  Bit 0		: raise legacy IRQ

  Bit 1		: raise MSI IRQ

  Bit 2 - 7	: MSI interrupt number

  Bit 8		: read command (read data from RC buffer)

  Bit 9		: write command (write data to RC buffer)

  Bit 10	: copy command (copy data from one RC buffer to another

		  RC buffer)

*) PCI_ENDPOINT_TEST_STATUS

This register reflects the status of the PCI endpoint device.

Bitfield Description:

  Bit 0		: read success

  Bit 1		: read fail

  Bit 2		: write success

  Bit 3		: write fail

  Bit 4		: copy success

  Bit 5		: copy fail

  Bit 6		: IRQ raised

  Bit 7		: source address is invalid

  Bit 8		: destination address is invalid

*) PCI_ENDPOINT_TEST_SRC_ADDR

This register contains the source address (RC buffer address) for the

COPY/READ command.

*) PCI_ENDPOINT_TEST_DST_ADDR

This register contains the destination address (RC buffer address) for

the COPY/WRITE command.