[v9,10/10] doc: update programmer's guide for power library
diff mbox series

Message ID 1603494392-7181-11-git-send-email-liang.j.ma@intel.com
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series
  • Add PMD power mgmt
Related show

Checks

Context Check Description
ci/iol-mellanox-Performance success Performance Testing PASS
ci/travis-robot success Travis build: passed
ci/iol-intel-Functional success Functional Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-testing success Testing PASS
ci/Intel-compilation success Compilation OK
ci/iol-broadcom-Functional success Functional Testing PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/checkpatch success coding style OK

Commit Message

Liang, Ma Oct. 23, 2020, 11:06 p.m. UTC
Update programmer's guide to document PMD power management usage.

Signed-off-by: Liang Ma <liang.j.ma@intel.com>
Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
Acked-by: David Hunt <david.hunt@intel.com>
---
 doc/guides/prog_guide/power_man.rst | 42 +++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

Comments

Thomas Monjalon Oct. 24, 2020, 8:49 p.m. UTC | #1
24/10/2020 01:06, Liang Ma:
> Update programmer's guide to document PMD power management usage.
> 
> Signed-off-by: Liang Ma <liang.j.ma@intel.com>
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> Acked-by: David Hunt <david.hunt@intel.com>
> ---
>  doc/guides/prog_guide/power_man.rst | 42 +++++++++++++++++++++++++++++
>  1 file changed, 42 insertions(+)

Why don't you update this doc in the patch 5
adding the code in the power library?


> --- a/doc/guides/prog_guide/power_man.rst
> +++ b/doc/guides/prog_guide/power_man.rst
> @@ -192,6 +192,45 @@ User Cases
>  ----------
>  The mechanism can applied to any device which is based on polling. e.g. NIC, FPGA.
>  
> +PMD Power Management API
> +------------------------
> +

Blank line missing below:

> +Abstract
> +~~~~~~~~
> +Existing power management mechanisms require developers to change application
> +design or change code to make use of it. The PMD power management API provides a
> +convenient alternative by utilizing Ethernet PMD RX callbacks, and triggering
> +power saving whenever empty poll count reaches a certain number.
> +

Here you start a list of schemes, without introducing it.

> +  * UMWAIT/UMONITOR
> +
> +   This power saving scheme will put the CPU into optimized power state and use
> +   the UMWAIT/UMONITOR instructions to monitor the Ethernet PMD RX descriptor
> +   address, and wake the CPU up whenever there's new traffic.
> +
> +  * Pause
> +
> +   This power saving scheme will use the `rte_pause` function to avoid busy
> +   polling.
> +
> +  * Frequency scaling
> +
> +   This power saving scheme will use existing power library functionality to
> +   scale the core frequency up/down depending on traffic volume.
> +
> +
> +.. note::
> +
> +   Currently, this power management API is limited to mandatory mapping of 1
> +   queue to 1 core (multiple queues are supported, but they must be polled from
> +   different cores).
> +
> +API Overview for PMD Power Management
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Underlining is long enough...
... but a blank line is missing after the title.

> +* **Queue Enable**: Enable specific power scheme for certain queue/port/core
> +
> +* **Queue Disable**: Disable power scheme for certain queue/port/core
Liang, Ma Oct. 27, 2020, 11:04 a.m. UTC | #2
Hi Thomas, 
   all is fixed in v10.
Regards
Liang
On 24 Oct 22:49, Thomas Monjalon wrote:
> 24/10/2020 01:06, Liang Ma:
> > Update programmer's guide to document PMD power management usage.
> > 
> > Signed-off-by: Liang Ma <liang.j.ma@intel.com>
> > Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> > Acked-by: David Hunt <david.hunt@intel.com>
> > ---
> >  doc/guides/prog_guide/power_man.rst | 42 +++++++++++++++++++++++++++++
> >  1 file changed, 42 insertions(+)
> 
> Why don't you update this doc in the patch 5
> adding the code in the power library?
> 
> 
> > --- a/doc/guides/prog_guide/power_man.rst
> > +++ b/doc/guides/prog_guide/power_man.rst
> > @@ -192,6 +192,45 @@ User Cases
> >  ----------
> >  The mechanism can applied to any device which is based on polling. e.g. NIC, FPGA.
> >  
> > +PMD Power Management API
> > +------------------------
> > +
> 
> Blank line missing below:
> 
> > +Abstract
> > +~~~~~~~~
> > +Existing power management mechanisms require developers to change application
> > +design or change code to make use of it. The PMD power management API provides a
> > +convenient alternative by utilizing Ethernet PMD RX callbacks, and triggering
> > +power saving whenever empty poll count reaches a certain number.
> > +
> 
> Here you start a list of schemes, without introducing it.
> 
> > +  * UMWAIT/UMONITOR
> > +
> > +   This power saving scheme will put the CPU into optimized power state and use
> > +   the UMWAIT/UMONITOR instructions to monitor the Ethernet PMD RX descriptor
> > +   address, and wake the CPU up whenever there's new traffic.
> > +
> > +  * Pause
> > +
> > +   This power saving scheme will use the `rte_pause` function to avoid busy
> > +   polling.
> > +
> > +  * Frequency scaling
> > +
> > +   This power saving scheme will use existing power library functionality to
> > +   scale the core frequency up/down depending on traffic volume.
> > +
> > +
> > +.. note::
> > +
> > +   Currently, this power management API is limited to mandatory mapping of 1
> > +   queue to 1 core (multiple queues are supported, but they must be polled from
> > +   different cores).
> > +
> > +API Overview for PMD Power Management
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> Underlining is long enough...
> ... but a blank line is missing after the title.
> 
> > +* **Queue Enable**: Enable specific power scheme for certain queue/port/core
> > +
> > +* **Queue Disable**: Disable power scheme for certain queue/port/core
> 
> 
>

Patch
diff mbox series

diff --git a/doc/guides/prog_guide/power_man.rst b/doc/guides/prog_guide/power_man.rst
index 0a3755a901..38c64d31e4 100644
--- a/doc/guides/prog_guide/power_man.rst
+++ b/doc/guides/prog_guide/power_man.rst
@@ -192,6 +192,45 @@  User Cases
 ----------
 The mechanism can applied to any device which is based on polling. e.g. NIC, FPGA.
 
+PMD Power Management API
+------------------------
+
+Abstract
+~~~~~~~~
+Existing power management mechanisms require developers to change application
+design or change code to make use of it. The PMD power management API provides a
+convenient alternative by utilizing Ethernet PMD RX callbacks, and triggering
+power saving whenever empty poll count reaches a certain number.
+
+  * UMWAIT/UMONITOR
+
+   This power saving scheme will put the CPU into optimized power state and use
+   the UMWAIT/UMONITOR instructions to monitor the Ethernet PMD RX descriptor
+   address, and wake the CPU up whenever there's new traffic.
+
+  * Pause
+
+   This power saving scheme will use the `rte_pause` function to avoid busy
+   polling.
+
+  * Frequency scaling
+
+   This power saving scheme will use existing power library functionality to
+   scale the core frequency up/down depending on traffic volume.
+
+
+.. note::
+
+   Currently, this power management API is limited to mandatory mapping of 1
+   queue to 1 core (multiple queues are supported, but they must be polled from
+   different cores).
+
+API Overview for PMD Power Management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* **Queue Enable**: Enable specific power scheme for certain queue/port/core
+
+* **Queue Disable**: Disable power scheme for certain queue/port/core
+
 References
 ----------
 
@@ -200,3 +239,6 @@  References
 
 *   The :doc:`../sample_app_ug/vm_power_management`
     chapter in the :doc:`../sample_app_ug/index` section.
+
+*   The :doc:`../sample_app_ug/rxtx_callbacks`
+    chapter in the :doc:`../sample_app_ug/index` section.