Documentation/PCI/endpoint/pci-endpoint.rst

Source file repositories/reference/linux-study-clean/Documentation/PCI/endpoint/pci-endpoint.rst

File Facts

System
Linux kernel
Corpus path
Documentation/PCI/endpoint/pci-endpoint.rst
Extension
.rst
Size
9991 bytes
Lines
284
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

:Author: 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.

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.

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.

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.

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, MSI or MSI-X 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().

* pci_epc_destroy()

   The PCI controller driver can destroy the EPC device created by
   pci_epc_create() using 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().

Annotation

Implementation Notes