Configfs PCI endpoint 구성

Configfs interface

저자는 Kishon Vijay Abraham I입니다. PCI Endpoint Core는 endpoint function을 설정하고 endpoint controller와 bind하는 configfs entry `pci_ep`를 제공합니다. 다른 구성 mechanism을 도입하는 방법은 [1]을 참조합니다.

.. SPDX-License-Identifier: GPL-2.0

=======================================
Configuring PCI Endpoint Using CONFIGFS
=======================================

:Author: Kishon Vijay Abraham I <[email protected]>

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]).

Configfs mount

PCI Endpoint Core layer는 mount된 configfs에 `pci_ep` directory를 만듭니다. Configfs는 다음과 같이 mount합니다.

mount -t configfs none /sys/kernel/config

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

Root directory 구조

`pci_ep` root에는 `controllers`와 `functions` directory가 있습니다. System의 각 EPC device는 `controllers` 아래에, 각 EPF driver는 `functions` 아래에 entry를 가집니다.

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 every EPF driver present in the system
will have an entry in the *functions* directory.
::

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

EPF device 생성과 표준 header

등록된 각 EPF driver는 `functions` directory에 나열되고 EPF core가 driver entry를 만듭니다. 특정 EPF driver type의 device를 만들려면 해당 driver directory 안에 새 directory를 만듭니다.

Framework는 새 EPF device directory에 endpoint function의 표준 configuration header를 설정하는 entry를 만듭니다.

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 Device 31>/
                .. <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
                                ... <Symlink EPF Device 31>/
                                ... primary/
                                        ... <Symlink EPC Device1>/
                                ... secondary/
                                        ... <Symlink EPC Device2>/

Dual EPC와 PF/VF link

Non-transparent bridge처럼 EPF device 하나를 EPC 두 개와 연결해야 한다면 primary interface의 endpoint controller symlink는 `primary` directory에, secondary interface symlink는 `secondary` directory에 추가합니다.

EPF device directory는 다른 EPF device를 가리키는 symbolic link 목록을 가질 수 있습니다. 사용자가 physical function에 bind된 virtual function 관계를 나타내도록 이 link를 만듭니다.

원문 예에서 `EPF Device 11`은 physical function이고 `EPF Device 31`은 virtual function입니다. 한 EPF device가 다른 EPF device에 link되면 EPC device에는 link할 수 없습니다.

If an EPF device has to be associated with 2 EPCs (like in the case of
Non-transparent bridge), symlink of endpoint controller connected to primary
interface should be added in 'primary' directory and symlink of endpoint
controller connected to secondary interface should be added in 'secondary'
directory.

The <EPF Device> directory can have a list of symbolic links
(<Symlink EPF Device 31>) to other <EPF Device>. These symbolic links should
be created by the user to represent the virtual functions that are bound to
the physical function. In the above directory structure <EPF Device 11> is a
physical function and <EPF Device 31> is a virtual function. An EPF device once
it's linked to another EPF device, cannot be linked to an EPC device.

EPC device와 endpoint 시작

등록된 EPC device는 `controllers` directory에 나열되고 EPC core가 entry를 만듭니다. EPC directory에는 endpoint device의 function을 나타내는 EPF device symlink를 사용자가 만듭니다.

EPC device에는 physical function을 나타내는 EPF device만 link할 수 있습니다.

EPC directory의 `start` field에 `1`을 쓰면 endpoint device가 host와 link를 맺을 준비를 합니다. 일반적으로 모든 EPF device를 만들고 EPC에 link한 뒤 시작합니다.

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. Only <EPF Device>
that represents a physical function can be linked to an EPC 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.
::

전체 configfs 관계와 참고문서

전체 구조에서 `controllers/<EPC name>/`에는 function symlink와 `start`가 있고, `functions/<EPF driver>/<EPF device>/`에는 표준 PCI field와 function-specific entry가 있습니다.

다른 PCI Endpoint Function 구성 mechanism을 도입하는 방법은 [1] `Documentation/PCI/endpoint/pci-endpoint.rst`를 참조합니다.

                         | 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.rst