[PATCH v1] doc/guides: update monitor PMD mode description

[PATCH v1] doc/guides: update monitor PMD mode description

[Chris MacNamara]

A recent CPU change requires an extra enabling step for
the umonitor instruction on Intel CPUs.
This is now detailed in the l3 fwd power manager doc.

Signed-off-by: Chris MacNamara <chris.macnamara@intel.com>
---
 .mailmap                                          | 1 +
 doc/guides/sample_app_ug/l3_forward_power_man.rst | 5 +++++
 2 files changed, 6 insertions(+)

diff --git a/.mailmap b/.mailmap
index a03d3cfb59..c4bc38752f 100644
--- a/.mailmap
+++ b/.mailmap
@@ -263,6 +263,7 @@ Christopher Reder <christopher.reder@broadcom.com>
 Christoph Gysin <christoph.gysin@gmail.com>
 Christos Ricudis <ricudis@niometrics.com>
 Chris Wright <chrisw@redhat.com>
+Chris MacNamara <chris.macnamara@intel.com>
 Chuanshe Zhang <zhangchuanshe@icloudshield.com>
 Chuanyu Xue <chuanyu.xue@uconn.edu>
 Chuhong Yao <ych@panath.cn>
diff --git a/doc/guides/sample_app_ug/l3_forward_power_man.rst b/doc/guides/sample_app_ug/l3_forward_power_man.rst
index 3271bc2154..d0af28e0ec 100644
--- a/doc/guides/sample_app_ug/l3_forward_power_man.rst
+++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst
@@ -293,6 +293,11 @@ and has three available power management schemes:
 ``monitor``
   This will use ``rte_power_monitor()`` function to enter
   a power-optimized state (subject to platform support).
+  On recent Gen 4 Xeon Scalable Processors the umonitor instruction
+  is disabled by default.
+  An additional step is required to enable the umonitor instruction.
+  Writing 0 to bit 6 of register 0x123 will enable umonitor.
+  `More details are available via Monitor and Umonitor Performance Guidance <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/monitor-umonitor-performance-guidance.html>`_
 
 ``pause``
   This will use ``rte_power_pause()`` or ``rte_pause()``
-- 
2.43.0

--------------------------------------------------------------
Intel Research and Development Ireland Limited
Registered in Ireland
Registered Office: Collinstown Industrial Park, Leixlip, County Kildare
Registered Number: 308263


This e-mail and any attachments may contain confidential material for the sole
use of the intended recipient(s). Any review or distribution by others is
strictly prohibited. If you are not the intended recipient, please contact the
sender and delete all copies.

Re: [PATCH v1] doc/guides: update monitor PMD mode description

[Bruce Richardson]

On Fri, Feb 21, 2025 at 04:54:40PM +0000, Chris MacNamara wrote:
> A recent CPU change requires an extra enabling step for
> the umonitor instruction on Intel CPUs.
> This is now detailed in the l3 fwd power manager doc.
> 
> Signed-off-by: Chris MacNamara <chris.macnamara@intel.com>
> ---
>  .mailmap                                          | 1 +
>  doc/guides/sample_app_ug/l3_forward_power_man.rst | 5 +++++
>  2 files changed, 6 insertions(+)
> 
> diff --git a/.mailmap b/.mailmap
> index a03d3cfb59..c4bc38752f 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -263,6 +263,7 @@ Christopher Reder <christopher.reder@broadcom.com>
>  Christoph Gysin <christoph.gysin@gmail.com>
>  Christos Ricudis <ricudis@niometrics.com>
>  Chris Wright <chrisw@redhat.com>
> +Chris MacNamara <chris.macnamara@intel.com>

Minor nit, this is kept in alphabetical order, so your name should go just
above Chris Wright's one.

>  Chuanshe Zhang <zhangchuanshe@icloudshield.com>
>  Chuanyu Xue <chuanyu.xue@uconn.edu>
>  Chuhong Yao <ych@panath.cn>
> diff --git a/doc/guides/sample_app_ug/l3_forward_power_man.rst b/doc/guides/sample_app_ug/l3_forward_power_man.rst
> index 3271bc2154..d0af28e0ec 100644
> --- a/doc/guides/sample_app_ug/l3_forward_power_man.rst
> +++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst
> @@ -293,6 +293,11 @@ and has three available power management schemes:
>  ``monitor``
>    This will use ``rte_power_monitor()`` function to enter
>    a power-optimized state (subject to platform support).
> +  On recent Gen 4 Xeon Scalable Processors the umonitor instruction
> +  is disabled by default.
> +  An additional step is required to enable the umonitor instruction.
> +  Writing 0 to bit 6 of register 0x123 will enable umonitor.
> +  `More details are available via Monitor and Umonitor Performance Guidance <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/monitor-umonitor-performance-guidance.html>`_
>  
>  ``pause``
>    This will use ``rte_power_pause()`` or ``rte_pause()``
> -- 

I'd suggest this extra info be added as a note, rather than inline in the
text, since it's not applicable to all systems. I'd also suggest that an
equivalent note needs to be added to the programmer's guide doc, in [1].
The info is relevant for those using the library, as well as those just
using the sample app.

/Bruce

[1] https://doc.dpdk.org/guides/prog_guide/power_man.html#ethernet-pmd-power-management-api

Re: [PATCH v1] doc/guides: update monitor PMD mode description

[Stephen Hemminger]

On Fri, 21 Feb 2025 16:54:40 +0000
Chris MacNamara <chris.macnamara@intel.com> wrote:

> A recent CPU change requires an extra enabling step for
> the umonitor instruction on Intel CPUs.
> This is now detailed in the l3 fwd power manager doc.
> 
> Signed-off-by: Chris MacNamara <chris.macnamara@intel.com>
> ---
>  .mailmap                                          | 1 +
>  doc/guides/sample_app_ug/l3_forward_power_man.rst | 5 +++++
>  2 files changed, 6 insertions(+)
> 
> diff --git a/.mailmap b/.mailmap
> index a03d3cfb59..c4bc38752f 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -263,6 +263,7 @@ Christopher Reder <christopher.reder@broadcom.com>
>  Christoph Gysin <christoph.gysin@gmail.com>
>  Christos Ricudis <ricudis@niometrics.com>
>  Chris Wright <chrisw@redhat.com>
> +Chris MacNamara <chris.macnamara@intel.com>
>  Chuanshe Zhang <zhangchuanshe@icloudshield.com>
>  Chuanyu Xue <chuanyu.xue@uconn.edu>
>  Chuhong Yao <ych@panath.cn>
> diff --git a/doc/guides/sample_app_ug/l3_forward_power_man.rst b/doc/guides/sample_app_ug/l3_forward_power_man.rst
> index 3271bc2154..d0af28e0ec 100644
> --- a/doc/guides/sample_app_ug/l3_forward_power_man.rst
> +++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst
> @@ -293,6 +293,11 @@ and has three available power management schemes:
>  ``monitor``
>    This will use ``rte_power_monitor()`` function to enter
>    a power-optimized state (subject to platform support).
> +  On recent Gen 4 Xeon Scalable Processors the umonitor instruction
> +  is disabled by default.
> +  An additional step is required to enable the umonitor instruction.
> +  Writing 0 to bit 6 of register 0x123 will enable umonitor.
> +  `More details are available via Monitor and Umonitor Performance Guidance <https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/monitor-umonitor-performance-guidance.html>`_
>  

This should be done by the power library, what is the point of having a power API
if we require applications to test for CPU type and go tweak some CPU register bits.
And it may be restricted by OS permissions etc.