netdev - Re: [PATCH V2 7/9] PCI/TPH: Add TPH documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date: Fri, 7 Jun 2024 18:43:31 +0100
From: Jonathan Cameron <Jonathan.Cameron@...wei.com>
To: Wei Huang <wei.huang2@....com>
CC: <linux-pci@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
	<linux-doc@...r.kernel.org>, <netdev@...r.kernel.org>, <bhelgaas@...gle.com>,
	<corbet@....net>, <davem@...emloft.net>, <edumazet@...gle.com>,
	<kuba@...nel.org>, <pabeni@...hat.com>, <alex.williamson@...hat.com>,
	<gospo@...adcom.com>, <michael.chan@...adcom.com>,
	<ajit.khaparde@...adcom.com>, <somnath.kotur@...adcom.com>,
	<andrew.gospodarek@...adcom.com>, <manoj.panicker2@....com>,
	<Eric.VanTassell@....com>, <vadim.fedorenko@...ux.dev>, <horms@...nel.org>,
	<bagasdotme@...il.com>
Subject: Re: [PATCH V2 7/9] PCI/TPH: Add TPH documentation

On Fri, 31 May 2024 16:38:39 -0500
Wei Huang <wei.huang2@....com> wrote:

> Provide a document for TPH feature, including the description of
> kernel options and driver API interface.
> 
> Co-developed-by: Eric Van Tassell <Eric.VanTassell@....com>
> Signed-off-by: Eric Van Tassell <Eric.VanTassell@....com>
> Signed-off-by: Wei Huang <wei.huang2@....com>
> Reviewed-by: Ajit Khaparde <ajit.khaparde@...adcom.com>
> Reviewed-by: Somnath Kotur <somnath.kotur@...adcom.com> 
> Reviewed-by: Andy Gospodarek <andrew.gospodarek@...adcom.com>
Sort and sweet.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@...wei.com>

> ---
>  Documentation/PCI/index.rst          |  1 +
>  Documentation/PCI/tph.rst            | 57 ++++++++++++++++++++++++++++
>  Documentation/driver-api/pci/pci.rst |  3 ++
>  3 files changed, 61 insertions(+)
>  create mode 100644 Documentation/PCI/tph.rst
> 
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index e73f84aebde3..5e7c4e6e726b 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -18,3 +18,4 @@ PCI Bus Subsystem
>     pcieaer-howto
>     endpoint/index
>     boot-interrupts
> +   tph
> diff --git a/Documentation/PCI/tph.rst b/Documentation/PCI/tph.rst
> new file mode 100644
> index 000000000000..ea9c8313f3e4
> --- /dev/null
> +++ b/Documentation/PCI/tph.rst
> @@ -0,0 +1,57 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========
> +TPH Support
> +===========
> +
> +
> +:Copyright: 2024 Advanced Micro Devices, Inc.
> +:Authors: - Eric van Tassell <eric.vantassell@....com>
> +          - Wei Huang <wei.huang2@....com>
> +
> +Overview
> +========
> +TPH (TLP Processing Hints) is a PCIe feature that allows endpoint devices
> +to provide optimization hints, such as desired caching behavior, for
> +requests that target memory space. These hints, in a format called steering
> +tags, are provided in the requester's TLP headers and can empower the system
> +hardware, including the Root Complex, to optimize the utilization of platform
> +resources for the requests.
> +
> +User Guide
> +==========
> +
> +Kernel Options
> +--------------
> +There are two kernel command line options available to control TPH feature
> +
> +   * "notph": TPH will be disabled for all endpoint devices.
> +   * "nostmode": TPH will be enabled but the ST Mode will be forced to "No ST Mode".
> +
> +Device Driver API
> +-----------------
> +In brief, an endpoint device driver using the TPH interface to configure
> +Interrupt Vector Mode will call pcie_tph_set_st() when setting up MSI-X
> +interrupts as shown below:
> +
> +.. code-block:: c
> +
> +    for (i = 0, j = 0; i < nr_rings; i++) {
> +        ...
> +        rc = request_irq(irq->vector, irq->handler, flags, irq->name, NULL);
> +        ...
> +        if (!pcie_tph_set_st(pdev, i, cpumask_first(irq->cpu_mask),
> +                             TPH_MEM_TYPE_VM, PCI_TPH_REQ_TPH_ONLY))
> +               pr_err("Error in configuring steering tag\n");
> +        ...
> +    }
> +
> +If a device only supports TPH vendor specific mode, its driver can call
> +pcie_tph_get_st() to retrieve the steering tag for a specific CPU and uses
> +the tag to control TPH behavior.
> +
> +.. kernel-doc:: drivers/pci/pcie/tph.c
> +   :export:
> +
> +.. kernel-doc:: drivers/pci/pcie/tph.c
> +   :identifiers: pcie_tph_set_st
> diff --git a/Documentation/driver-api/pci/pci.rst b/Documentation/driver-api/pci/pci.rst
> index aa40b1cc243b..3d896b2cf16e 100644
> --- a/Documentation/driver-api/pci/pci.rst
> +++ b/Documentation/driver-api/pci/pci.rst
> @@ -46,6 +46,9 @@ PCI Support Library
>  .. kernel-doc:: drivers/pci/pci-sysfs.c
>     :internal:
>  
> +.. kernel-doc:: drivers/pci/pcie/tph.c
> +   :export:
> +
>  PCI Hotplug Support Library
>  ---------------------------
>