Re: [PATCH v9 7/8] docs: trace: Add HiSilicon PTT device driver documentation
On Thu, Jul 07, 2022 at 07:43:21PM +0800, Yicong Yang wrote:
> On 2022/7/7 1:57, Mathieu Poirier wrote:
> > Hi,
> >
> > I have started looking at this set.
>
> Thanks!
>
> >
> > On Mon, Jun 06, 2022 at 07:55:54PM +0800, Yicong Yang wrote:
> >> Document the introduction and usage of HiSilicon PTT device driver.
> >>
> >> Signed-off-by: Yicong Yang
> >> Reviewed-by: Jonathan Cameron
> >> ---
> >> Documentation/trace/hisi-ptt.rst | 307 +++
> >> Documentation/trace/index.rst| 1 +
> >
> > The "get_maintainer" script clearly indicates that Jonathan Corbet
> > maintains the
> > Documentation directory and yet he is not CC'ed on this patch, nor is the
> > linux-doc mainling list. As such, it would not be possible to merge this
> > patchset.
> >
>
> sorry for missing. +cc'ed.
>
> >> 2 files changed, 308 insertions(+)
> >> create mode 100644 Documentation/trace/hisi-ptt.rst
> >>
> >> diff --git a/Documentation/trace/hisi-ptt.rst
> >> b/Documentation/trace/hisi-ptt.rst
> >> new file mode 100644
> >> index ..0a3112244d40
> >> --- /dev/null
> >> +++ b/Documentation/trace/hisi-ptt.rst
> >> @@ -0,0 +1,307 @@
> >> +.. SPDX-License-Identifier: GPL-2.0
> >> +
> >> +==
> >> +HiSilicon PCIe Tune and Trace device
> >> +==
> >> +
> >> +Introduction
> >> +
> >> +
> >> +HiSilicon PCIe tune and trace device (PTT) is a PCIe Root Complex
> >> +integrated Endpoint (RCiEP) device, providing the capability
> >> +to dynamically monitor and tune the PCIe link's events (tune),
> >> +and trace the TLP headers (trace). The two functions are independent,
> >> +but is recommended to use them together to analyze and enhance the
> >> +PCIe link's performance.
> >> +
> >> +On Kunpeng 930 SoC, the PCIe Root Complex is composed of several
> >> +PCIe cores. Each PCIe core includes several Root Ports and a PTT
> >> +RCiEP, like below. The PTT device is capable of tuning and
> >> +tracing the links of the PCIe core.
> >> +::
> >> +
> >> + +--Core 0---+
> >> + | | [ PTT ] |
> >> + | | [Root Port]---[Endpoint]
> >> + | | [Root Port]---[Endpoint]
> >> + | | [Root Port]---[Endpoint]
> >> +Root Complex |--Core 1---+
> >> + | | [ PTT ] |
> >> + | | [Root Port]---[ Switch ]---[Endpoint]
> >> + | | [Root Port]---[Endpoint] `-[Endpoint]
> >> + | | [Root Port]---[Endpoint]
> >> + +---+
> >> +
> >> +The PTT device driver registers one PMU device for each PTT device.
> >> +The name of each PTT device is composed of 'hisi_ptt' prefix with
> >> +the id of the SICL and the Core where it locates. The Kunpeng 930
> >> +SoC encapsulates multiple CPU dies (SCCL, Super CPU Cluster) and
> >> +IO dies (SICL, Super I/O Cluster), where there's one PCIe Root
> >> +Complex for each SICL.
> >> +::
> >> +
> >> +/sys/devices/hisi_ptt_
> >
> > All entries added to sysfs should have corresponding documentation. See
> > [1] and
> > [2] for details and [3] for an example.
> >
> > [1]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/README
> > [2].
> > https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing
> > [3].
> > https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
> >
>
> ok. I'll add a patch for ABI description. Thanks for the reference.
>
> >> +
> >> +Tune
> >> +
> >> +
> >> +PTT tune is designed for monitoring and adjusting PCIe link parameters
> >> (events).
> >> +Currently we support events in 4 classes. The scope of the events
> >> +covers the PCIe core to which the PTT device belongs.
> >> +
> >> +Each event is presented as a file under $(PTT PMU dir)/tune, and
> >> +a simple open/read/write/close cycle will be used to tune the event.
> >> +::
> >> +
> >> +$ cd /sys/devices/hisi_ptt_/tune
> >> +$ ls
> >> +qos_tx_cplqos_tx_npqos_tx_p
> >> +tx_path_rx_req_alloc_buf_level
> >> +tx_path_tx_req_alloc_buf_level
> >
> > These look overly long... How about watermark_rx and watermark_tx?
> >
>
> These are gotten from the hardware manual and abbreviated. These events are
> highly connected
> to the hardware desgin so I think it's better to keep consistence. The
> watermark_{rx, tx} will
> become ambigious when we add more events for Rx path or other Tx path events.
>
> The event code is composed of two parts. First part (tx_path) describes which
> path it belongs to
> and second part describes the function ({rx,tx}_req_alloc_buf_level). We
> called the link path
> between CPU and PCIe RC as Rx path and the path between PCIe RC to the PCIe
> link as Tx path.
> So we need to have tx_path prefix for the Tx path and {rx,
> tx}_req_alloc_buf_level for the
Re: [PATCH v9 7/8] docs: trace: Add HiSilicon PTT device driver documentation
On 2022/7/7 1:57, Mathieu Poirier wrote:
> Hi,
>
> I have started looking at this set.
Thanks!
>
> On Mon, Jun 06, 2022 at 07:55:54PM +0800, Yicong Yang wrote:
>> Document the introduction and usage of HiSilicon PTT device driver.
>>
>> Signed-off-by: Yicong Yang
>> Reviewed-by: Jonathan Cameron
>> ---
>> Documentation/trace/hisi-ptt.rst | 307 +++
>> Documentation/trace/index.rst| 1 +
>
> The "get_maintainer" script clearly indicates that Jonathan Corbet maintains
> the
> Documentation directory and yet he is not CC'ed on this patch, nor is the
> linux-doc mainling list. As such, it would not be possible to merge this
> patchset.
>
sorry for missing. +cc'ed.
>> 2 files changed, 308 insertions(+)
>> create mode 100644 Documentation/trace/hisi-ptt.rst
>>
>> diff --git a/Documentation/trace/hisi-ptt.rst
>> b/Documentation/trace/hisi-ptt.rst
>> new file mode 100644
>> index ..0a3112244d40
>> --- /dev/null
>> +++ b/Documentation/trace/hisi-ptt.rst
>> @@ -0,0 +1,307 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +==
>> +HiSilicon PCIe Tune and Trace device
>> +==
>> +
>> +Introduction
>> +
>> +
>> +HiSilicon PCIe tune and trace device (PTT) is a PCIe Root Complex
>> +integrated Endpoint (RCiEP) device, providing the capability
>> +to dynamically monitor and tune the PCIe link's events (tune),
>> +and trace the TLP headers (trace). The two functions are independent,
>> +but is recommended to use them together to analyze and enhance the
>> +PCIe link's performance.
>> +
>> +On Kunpeng 930 SoC, the PCIe Root Complex is composed of several
>> +PCIe cores. Each PCIe core includes several Root Ports and a PTT
>> +RCiEP, like below. The PTT device is capable of tuning and
>> +tracing the links of the PCIe core.
>> +::
>> +
>> + +--Core 0---+
>> + | | [ PTT ] |
>> + | | [Root Port]---[Endpoint]
>> + | | [Root Port]---[Endpoint]
>> + | | [Root Port]---[Endpoint]
>> +Root Complex |--Core 1---+
>> + | | [ PTT ] |
>> + | | [Root Port]---[ Switch ]---[Endpoint]
>> + | | [Root Port]---[Endpoint] `-[Endpoint]
>> + | | [Root Port]---[Endpoint]
>> + +---+
>> +
>> +The PTT device driver registers one PMU device for each PTT device.
>> +The name of each PTT device is composed of 'hisi_ptt' prefix with
>> +the id of the SICL and the Core where it locates. The Kunpeng 930
>> +SoC encapsulates multiple CPU dies (SCCL, Super CPU Cluster) and
>> +IO dies (SICL, Super I/O Cluster), where there's one PCIe Root
>> +Complex for each SICL.
>> +::
>> +
>> +/sys/devices/hisi_ptt_
>
> All entries added to sysfs should have corresponding documentation. See [1]
> and
> [2] for details and [3] for an example.
>
> [1]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/README
> [2]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing
> [3].
> https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
>
ok. I'll add a patch for ABI description. Thanks for the reference.
>> +
>> +Tune
>> +
>> +
>> +PTT tune is designed for monitoring and adjusting PCIe link parameters
>> (events).
>> +Currently we support events in 4 classes. The scope of the events
>> +covers the PCIe core to which the PTT device belongs.
>> +
>> +Each event is presented as a file under $(PTT PMU dir)/tune, and
>> +a simple open/read/write/close cycle will be used to tune the event.
>> +::
>> +
>> +$ cd /sys/devices/hisi_ptt_/tune
>> +$ ls
>> +qos_tx_cplqos_tx_npqos_tx_p
>> +tx_path_rx_req_alloc_buf_level
>> +tx_path_tx_req_alloc_buf_level
>
> These look overly long... How about watermark_rx and watermark_tx?
>
These are gotten from the hardware manual and abbreviated. These events are
highly connected
to the hardware desgin so I think it's better to keep consistence. The
watermark_{rx, tx} will
become ambigious when we add more events for Rx path or other Tx path events.
The event code is composed of two parts. First part (tx_path) describes which
path it belongs to
and second part describes the function ({rx,tx}_req_alloc_buf_level). We called
the link path
between CPU and PCIe RC as Rx path and the path between PCIe RC to the PCIe
link as Tx path.
So we need to have tx_path prefix for the Tx path and {rx,
tx}_req_alloc_buf_level for the
requested watermark of {inbound, outbound} buffer allocation. Indeed we have
other Tx path
buffer events which are not exported in this series.
>> +$ cat qos_tx_dp
>> +1
>> +$ echo 2 > qos_tx_dp
>> +$ cat qos_tx_dp
>> +2
>> +
>> +Current value (numerical value) of the event can be simply read
>>
Re: [PATCH v9 7/8] docs: trace: Add HiSilicon PTT device driver documentation
Hi, I have started looking at this set. On Mon, Jun 06, 2022 at 07:55:54PM +0800, Yicong Yang wrote: > Document the introduction and usage of HiSilicon PTT device driver. > > Signed-off-by: Yicong Yang > Reviewed-by: Jonathan Cameron > --- > Documentation/trace/hisi-ptt.rst | 307 +++ > Documentation/trace/index.rst| 1 + The "get_maintainer" script clearly indicates that Jonathan Corbet maintains the Documentation directory and yet he is not CC'ed on this patch, nor is the linux-doc mainling list. As such, it would not be possible to merge this patchset. > 2 files changed, 308 insertions(+) > create mode 100644 Documentation/trace/hisi-ptt.rst > > diff --git a/Documentation/trace/hisi-ptt.rst > b/Documentation/trace/hisi-ptt.rst > new file mode 100644 > index ..0a3112244d40 > --- /dev/null > +++ b/Documentation/trace/hisi-ptt.rst > @@ -0,0 +1,307 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +== > +HiSilicon PCIe Tune and Trace device > +== > + > +Introduction > + > + > +HiSilicon PCIe tune and trace device (PTT) is a PCIe Root Complex > +integrated Endpoint (RCiEP) device, providing the capability > +to dynamically monitor and tune the PCIe link's events (tune), > +and trace the TLP headers (trace). The two functions are independent, > +but is recommended to use them together to analyze and enhance the > +PCIe link's performance. > + > +On Kunpeng 930 SoC, the PCIe Root Complex is composed of several > +PCIe cores. Each PCIe core includes several Root Ports and a PTT > +RCiEP, like below. The PTT device is capable of tuning and > +tracing the links of the PCIe core. > +:: > + > + +--Core 0---+ > + | | [ PTT ] | > + | | [Root Port]---[Endpoint] > + | | [Root Port]---[Endpoint] > + | | [Root Port]---[Endpoint] > +Root Complex |--Core 1---+ > + | | [ PTT ] | > + | | [Root Port]---[ Switch ]---[Endpoint] > + | | [Root Port]---[Endpoint] `-[Endpoint] > + | | [Root Port]---[Endpoint] > + +---+ > + > +The PTT device driver registers one PMU device for each PTT device. > +The name of each PTT device is composed of 'hisi_ptt' prefix with > +the id of the SICL and the Core where it locates. The Kunpeng 930 > +SoC encapsulates multiple CPU dies (SCCL, Super CPU Cluster) and > +IO dies (SICL, Super I/O Cluster), where there's one PCIe Root > +Complex for each SICL. > +:: > + > +/sys/devices/hisi_ptt_ All entries added to sysfs should have corresponding documentation. See [1] and [2] for details and [3] for an example. [1]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/README [2]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing [3]. https://elixir.bootlin.com/linux/latest/source/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x > + > +Tune > + > + > +PTT tune is designed for monitoring and adjusting PCIe link parameters > (events). > +Currently we support events in 4 classes. The scope of the events > +covers the PCIe core to which the PTT device belongs. > + > +Each event is presented as a file under $(PTT PMU dir)/tune, and > +a simple open/read/write/close cycle will be used to tune the event. > +:: > + > +$ cd /sys/devices/hisi_ptt_/tune > +$ ls > +qos_tx_cplqos_tx_npqos_tx_p > +tx_path_rx_req_alloc_buf_level > +tx_path_tx_req_alloc_buf_level These look overly long... How about watermark_rx and watermark_tx? > +$ cat qos_tx_dp > +1 > +$ echo 2 > qos_tx_dp > +$ cat qos_tx_dp > +2 > + > +Current value (numerical value) of the event can be simply read > +from the file, and the desired value written to the file to tune. > + > +1. Tx path QoS control > + > + > +The following files are provided to tune the QoS of the tx path of > +the PCIe core. > + > +- qos_tx_cpl: weight of Tx completion TLPs > +- qos_tx_np: weight of Tx non-posted TLPs > +- qos_tx_p: weight of Tx posted TLPs > + > +The weight influences the proportion of certain packets on the PCIe link. > +For example, for the storage scenario, increase the proportion > +of the completion packets on the link to enhance the performance as > +more completions are consumed. > + > +The available tune data of these events is [0, 1, 2]. > +Writing a negative value will return an error, and out of range > +values will be converted to 2. Note that the event value just > +indicates a probable level, but is not precise. > + > +2. Tx path buffer control > +- > + > +Following files are provided to tune the buffer of tx path of the PCIe core. > + > +- tx_path_rx_req_alloc_buf_level: watermark of Rx requested > +-
