[dpdk-dev] [PATCH] docs: add statistics read frequency to fm10k guide

[dpdk-dev] [PATCH] docs: add statistics read frequency to fm10k guide

[Harry van Haaren]

This patch documents that the statistics of fm10k based NICs must be
read regularly in order to avoid an undetected 32 bit integer-overflow.

Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
---
 doc/guides/nics/fm10k.rst            | 16 ++++++++++++++++
 doc/guides/rel_notes/release_2_3.rst |  4 ++++
 2 files changed, 20 insertions(+)

diff --git a/doc/guides/nics/fm10k.rst b/doc/guides/nics/fm10k.rst
index 4206b7f..4250c9e 100644
--- a/doc/guides/nics/fm10k.rst
+++ b/doc/guides/nics/fm10k.rst
@@ -65,3 +65,19 @@ The FM10000 family of NICS support a maximum of a 15K jumbo frame. The value
 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 member of ``struct rte_eth_conf`` is set to a value lower than 15364, frames
 up to 15364 bytes can still reach the host interface.
+
+Statistic Polling Frequency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FM10000 NICs expose a set of statistics via the PCI BARs. These statistics
+are read from the hardware registers when ``rte_eth_stats_get()`` or
+``rte_eth_xstats_get()`` is called. The packet counting registers are 32 bits
+while the byte counting registers are 48 bits. As a result, the statistics must
+be polled regularly in order to ensure the consistency of the returned reads.
+
+Given the PCIe Gen3 x8, about 50Gbps of traffic can occur. With 64 byte packets
+this gives almost 100 million packets/second, causing 32 bit integer overflow
+after approx 40 seconds. To ensure these overflows are detected and accounted
+for in the statistics, it is necessary to read statistic regularly. It is
+suggested to read stats every 20 seconds, which will gaurantee the statistics
+are accurate.
diff --git a/doc/guides/rel_notes/release_2_3.rst b/doc/guides/rel_notes/release_2_3.rst
index 99de186..f966940 100644
--- a/doc/guides/rel_notes/release_2_3.rst
+++ b/doc/guides/rel_notes/release_2_3.rst
@@ -15,6 +15,10 @@ EAL
 Drivers
 ~~~~~~~
 
+* **FM10K: Statistics Polling Frequency**
+
+  A section has been added to the NIC guide for fm10k about the time
+  between reading statistics and 32 bit packet counter overflows.
 
 Libraries
 ~~~~~~~~~
-- 
2.5.0

Re: [dpdk-dev] [PATCH] docs: add statistics read frequency to fm10k guide

[Thomas Monjalon]

2016-02-08 15:42, Harry van Haaren:
> This patch documents that the statistics of fm10k based NICs must be
> read regularly in order to avoid an undetected 32 bit integer-overflow.
> 
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> ---
>  doc/guides/nics/fm10k.rst            | 16 ++++++++++++++++
>  doc/guides/rel_notes/release_2_3.rst |  4 ++++

Thanks for improving the doc.
I think we should not add it to the release notes. Other opinions?

Re: [dpdk-dev] [PATCH] docs: add statistics read frequency to fm10k guide

[Van Haaren, Harry]

> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> 2016-02-08 15:42, Harry van Haaren:
> > This patch documents that the statistics of fm10k based NICs must be
> > read regularly in order to avoid an undetected 32 bit integer-overflow.
> >
> > Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> > ---
> >  doc/guides/nics/fm10k.rst            | 16 ++++++++++++++++
> >  doc/guides/rel_notes/release_2_3.rst |  4 ++++
> 
> Thanks for improving the doc.
> I think we should not add it to the release notes. Other opinions?

I was unsure on including it, and have no problem with it not being included. V2?

Re: [dpdk-dev] [PATCH] docs: add statistics read frequency to fm10k guide

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Thomas Monjalon
> Sent: Monday, February 8, 2016 4:01 PM
> To: Van Haaren, Harry <harry.van.haaren@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH] docs: add statistics read frequency to
> fm10k guide
> 
> 2016-02-08 15:42, Harry van Haaren:
> > This patch documents that the statistics of fm10k based NICs must be
> > read regularly in order to avoid an undetected 32 bit integer-overflow.
> >
> > Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> > ---
> >  doc/guides/nics/fm10k.rst            | 16 ++++++++++++++++
> >  doc/guides/rel_notes/release_2_3.rst |  4 ++++
> 
> Thanks for improving the doc.
> I think we should not add it to the release notes. Other opinions?


In general it shouldn't be required to add a note about doc changes to the release note.

In this case the note part may make more sense in the "Known Issues" section of the release note.

John.
-- 

[dpdk-dev] [PATCH v2] docs: add statistics read frequency to fm10k guide

[Harry van Haaren]

This patch documents that the statistics of fm10k based NICs must be
read regularly in order to avoid an undetected 32 bit integer-overflow.

Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
---

v2:
-Moved notes to Known Issues section of Release Notes.

 doc/guides/nics/fm10k.rst            | 16 ++++++++++++++++
 doc/guides/rel_notes/release_2_3.rst |  4 ++++
 2 files changed, 20 insertions(+)

diff --git a/doc/guides/nics/fm10k.rst b/doc/guides/nics/fm10k.rst
index 4206b7f..4250c9e 100644
--- a/doc/guides/nics/fm10k.rst
+++ b/doc/guides/nics/fm10k.rst
@@ -65,3 +65,19 @@ The FM10000 family of NICS support a maximum of a 15K jumbo frame. The value
 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 member of ``struct rte_eth_conf`` is set to a value lower than 15364, frames
 up to 15364 bytes can still reach the host interface.
+
+Statistic Polling Frequency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FM10000 NICs expose a set of statistics via the PCI BARs. These statistics
+are read from the hardware registers when ``rte_eth_stats_get()`` or
+``rte_eth_xstats_get()`` is called. The packet counting registers are 32 bits
+while the byte counting registers are 48 bits. As a result, the statistics must
+be polled regularly in order to ensure the consistency of the returned reads.
+
+Given the PCIe Gen3 x8, about 50Gbps of traffic can occur. With 64 byte packets
+this gives almost 100 million packets/second, causing 32 bit integer overflow
+after approx 40 seconds. To ensure these overflows are detected and accounted
+for in the statistics, it is necessary to read statistic regularly. It is
+suggested to read stats every 20 seconds, which will gaurantee the statistics
+are accurate.
diff --git a/doc/guides/rel_notes/release_2_3.rst b/doc/guides/rel_notes/release_2_3.rst
index 99de186..6748b89 100644
--- a/doc/guides/rel_notes/release_2_3.rst
+++ b/doc/guides/rel_notes/release_2_3.rst
@@ -31,6 +31,10 @@ Other
 Known Issues
 ------------
 
+* **FM10K: Statistics Polling Frequency**
+
+  A section has been added to the NIC guide for fm10k about the maximum
+  time between reading statistics and 32 bit packet counter overflows.
 
 API Changes
 -----------
-- 
2.5.0

Re: [dpdk-dev] [PATCH v2] docs: add statistics read frequency to fm10k guide

[Mcnamara, John]

> -----Original Message-----
> From: Van Haaren, Harry
> Sent: Tuesday, February 9, 2016 3:20 PM
> To: Chen, Jing D <jing.d.chen@intel.com>
> Cc: Mcnamara, John <john.mcnamara@intel.com>; dev@dpdk.org; Van Haaren,
> Harry <harry.van.haaren@intel.com>
> Subject: [PATCH v2] docs: add statistics read frequency to fm10k guide
> 
> This patch documents that the statistics of fm10k based NICs must be read
> regularly in order to avoid an undetected 32 bit integer-overflow.
> 
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>

Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [dpdk-dev] [PATCH v2] docs: add statistics read frequency to fm10k guide

[Mcnamara, John]

>  Known Issues
>  ------------
> 
> +* **FM10K: Statistics Polling Frequency**
> +
> +  A section has been added to the NIC guide for fm10k about the maximum
> + time between reading statistics and 32 bit packet counter overflows.

Hi Thomas,

We should probably call this section "New Known Issues" and then copy them to the legacy "Known Issues" doc after 1 release.

    http://dpdk.org/doc/guides/rel_notes/release_2_2.html#known-issues
    http://dpdk.org/doc/guides/rel_notes/known_issues.html

Or any other suggestion?

John

Re: [dpdk-dev] [PATCH v2] docs: add statistics read frequency to fm10k guide

[Thomas Monjalon]

2016-02-22 17:18, Mcnamara, John:
> >  Known Issues
> >  ------------
> > 
> > +* **FM10K: Statistics Polling Frequency**
> > +
> > +  A section has been added to the NIC guide for fm10k about the maximum
> > + time between reading statistics and 32 bit packet counter overflows.
> 
> Hi Thomas,
> 
> We should probably call this section "New Known Issues" and then copy them to the legacy "Known Issues" doc after 1 release.
> 
>     http://dpdk.org/doc/guides/rel_notes/release_2_2.html#known-issues
>     http://dpdk.org/doc/guides/rel_notes/known_issues.html
> 
> Or any other suggestion?

Yes it is an option.
Or we can simply maintain known issues in one place and remove the
per-release section.

Re: [dpdk-dev] [PATCH v2] docs: add statistics read frequency to fm10k guide

[Thomas Monjalon]

2016-02-09 15:19, Harry van Haaren:
> +suggested to read stats every 20 seconds, which will gaurantee the statistics

typo: gaurantee

> --- a/doc/guides/rel_notes/release_2_3.rst
> +++ b/doc/guides/rel_notes/release_2_3.rst
> @@ -31,6 +31,10 @@ Other
>  Known Issues
>  ------------
>  
> +* **FM10K: Statistics Polling Frequency**
> +
> +  A section has been added to the NIC guide for fm10k about the maximum
> +  time between reading statistics and 32 bit packet counter overflows.

I don't think it is an issue. It is common to every counter registers.
It is good to give some explanations in the doc but I don't think it must be
registered as an issue.

[dpdk-dev] [PATCH v3] docs: add statistics read frequency to fm10k guide

[Harry van Haaren]

This patch documents that the statistics of fm10k based NICs must be
read regularly in order to avoid an undetected 32 bit integer-overflow.

Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
---

v3:
-Removed paragraph from "Known Issues" based on feedback

v2:
-Moved notes to Known Issues section of Release Notes.

 doc/guides/nics/fm10k.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/guides/nics/fm10k.rst b/doc/guides/nics/fm10k.rst
index 4206b7f..63b495d 100644
--- a/doc/guides/nics/fm10k.rst
+++ b/doc/guides/nics/fm10k.rst
@@ -65,3 +65,19 @@ The FM10000 family of NICS support a maximum of a 15K jumbo frame. The value
 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
 member of ``struct rte_eth_conf`` is set to a value lower than 15364, frames
 up to 15364 bytes can still reach the host interface.
+
+Statistic Polling Frequency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FM10000 NICs expose a set of statistics via the PCI BARs. These statistics
+are read from the hardware registers when ``rte_eth_stats_get()`` or
+``rte_eth_xstats_get()`` is called. The packet counting registers are 32 bits
+while the byte counting registers are 48 bits. As a result, the statistics must
+be polled regularly in order to ensure the consistency of the returned reads.
+
+Given the PCIe Gen3 x8, about 50Gbps of traffic can occur. With 64 byte packets
+this gives almost 100 million packets/second, causing 32 bit integer overflow
+after approx 40 seconds. To ensure these overflows are detected and accounted
+for in the statistics, it is necessary to read statistic regularly. It is
+suggested to read stats every 20 seconds, which will ensure the statistics
+are accurate.
-- 
2.5.0

Re: [dpdk-dev] [PATCH v3] docs: add statistics read frequency to fm10k guide

[Thomas Monjalon]

2016-03-08 17:16, Harry van Haaren:
> This patch documents that the statistics of fm10k based NICs must be
> read regularly in order to avoid an undetected 32 bit integer-overflow.
> 
> Signed-off-by: Harry van Haaren <harry.van.haaren@intel.com>
> Acked-by: John McNamara <john.mcnamara@intel.com>

Applied, thanks