[PATCH v1 3/3] doc/power: remove empty poll documentation

[David Hunt <david.hunt@intel.com>]

Remove the documentation for the removed experimental empty poll
API, as it is no longer needed.

This API is no longer needed as it is superceded by the
monitor/pause/scale callback mechanism.

Signed-off-by: David Hunt <david.hunt@intel.com>
---
 doc/guides/prog_guide/power_man.rst           | 94 -------------------
 doc/guides/rel_notes/release_23_03.rst        |  4 +
 .../sample_app_ug/l3_forward_power_man.rst    | 70 --------------
 3 files changed, 4 insertions(+), 164 deletions(-)

diff --git a/doc/guides/prog_guide/power_man.rst b/doc/guides/prog_guide/power_man.rst
index 68db59bd49..f6674efe2d 100644
--- a/doc/guides/prog_guide/power_man.rst
+++ b/doc/guides/prog_guide/power_man.rst
@@ -107,100 +107,6 @@ User Cases
 The power management mechanism is used to save power when performing L3 forwarding.
 
 
-Empty Poll API
---------------
-
-Removal Warning
-~~~~~~~~~~~~~~~
-
-The experimental empty poll API will be removed from the library
-in a future DPDK release.
-The empty poll mechanism is superseded by the power PMD modes
-i.e. monitor, pause and scale.
-
-
-Abstract
-~~~~~~~~
-
-For packet processing workloads such as DPDK polling is continuous.
-This means CPU cores always show 100% busy independent of how much work
-those cores are doing. It is critical to accurately determine how busy
-a core is hugely important for the following reasons:
-
-        * No indication of overload conditions
-        * User does not know how much real load is on a system, resulting
-          in wasted energy as no power management is utilized
-
-Compared to the original l3fwd-power design, instead of going to sleep
-after detecting an empty poll, the new mechanism just lowers the core frequency.
-As a result, the application does not stop polling the device, which leads
-to improved handling of bursts of traffic.
-
-When the system become busy, the empty poll mechanism can also increase the core
-frequency (including turbo) to do best effort for intensive traffic. This gives
-us more flexible and balanced traffic awareness over the standard l3fwd-power
-application.
-
-
-Proposed Solution
-~~~~~~~~~~~~~~~~~
-The proposed solution focuses on how many times empty polls are executed.
-The less the number of empty polls, means current core is busy with processing
-workload, therefore, the higher frequency is needed. The high empty poll number
-indicates the current core not doing any real work therefore, we can lower the
-frequency to safe power.
-
-In the current implementation, each core has 1 empty-poll counter which assume
-1 core is dedicated to 1 queue. This will need to be expanded in the future to
-support multiple queues per core.
-
-Power state definition:
-^^^^^^^^^^^^^^^^^^^^^^^
-
-* LOW:  Not currently used, reserved for future use.
-
-* MED:  the frequency is used to process modest traffic workload.
-
-* HIGH: the frequency is used to process busy traffic workload.
-
-There are two phases to establish the power management system:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Training phase. This phase is used to measure the optimal frequency
-  change thresholds for a given system. The thresholds will differ from
-  system to system due to differences in processor micro-architecture,
-  cache and device configurations.
-  In this phase, the user must ensure that no traffic can enter the
-  system so that counts can be measured for empty polls at low, medium
-  and high frequencies. Each frequency is measured for two seconds.
-  Once the training phase is complete, the threshold numbers are
-  displayed, and normal mode resumes, and traffic can be allowed into
-  the system. These threshold number can be used on the command line
-  when starting the application in normal mode to avoid re-training
-  every time.
-
-* Normal phase. Every 10ms the run-time counters are compared
-  to the supplied threshold values, and the decision will be made
-  whether to move to a different power state (by adjusting the
-  frequency).
-
-API Overview for Empty Poll Power Management
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* **State Init**: initialize the power management system.
-
-* **State Free**: free the resource hold by power management system.
-
-* **Update Empty Poll Counter**: update the empty poll counter.
-
-* **Update Valid Poll Counter**: update the valid poll counter.
-
-* **Set the Frequency Index**: update the power state/frequency mapping.
-
-* **Detect empty poll state change**: empty poll state change detection algorithm then take action.
-
-User Cases
-----------
-The mechanism can applied to any device which is based on polling. e.g. NIC, FPGA.
-
 Ethernet PMD Power Management API
 ---------------------------------
 
diff --git a/doc/guides/rel_notes/release_23_03.rst b/doc/guides/rel_notes/release_23_03.rst
index b8c5b68d6c..bc3395d1ca 100644
--- a/doc/guides/rel_notes/release_23_03.rst
+++ b/doc/guides/rel_notes/release_23_03.rst
@@ -68,6 +68,10 @@ Removed Items
    Also, make sure to start the actual text at the margin.
    =======================================================
 
+   * Removed the experimental empty poll API from the power library
+     The empty poll mechanism is superseded by the power PMD modes
+     i.e. monitor, pause and scale.
+
 
 API Changes
 -----------
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 fa3ef67c08..4a6f33bf4f 100644
--- a/doc/guides/sample_app_ug/l3_forward_power_man.rst
+++ b/doc/guides/sample_app_ug/l3_forward_power_man.rst
@@ -109,8 +109,6 @@ where,
 
 *   --no-numa: optional, disables numa awareness
 
-*   --empty-poll: Traffic Aware power management. See below for details
-
 *   --telemetry:  Telemetry mode.
 
 *   --pmd-mgmt: PMD power management mode.
@@ -238,74 +236,6 @@ If a thread polls multiple Rx queues and different queue returns different sleep
 the algorithm controls the sleep time in a conservative manner by sleeping for the least possible time
 in order to avoid a potential performance impact.
 
-Empty Poll Mode
--------------------------
-Additionally, there is a traffic aware mode of operation called "Empty
-Poll" where the number of empty polls can be monitored to keep track
-of how busy the application is. Empty poll mode can be enabled by the
-command line option --empty-poll.
-
-See :doc:`Power Management<../prog_guide/power_man>` chapter in the DPDK Programmer's Guide for empty poll mode details.
-
-.. code-block:: console
-
-    ./<build_dir>/examples/dpdk-l3fwd-power -l xxx -n 4 -a 0000:xx:00.0 -a 0000:xx:00.1 \
-    	-- -p 0x3 -P --config="(0,0,xx),(1,0,xx)" --empty-poll="0,0,0" -l 14 -m 9 -h 1
-
-Where,
-
---empty-poll: Enable the empty poll mode instead of original algorithm
-
---empty-poll="training_flag, med_threshold, high_threshold"
-
-* ``training_flag`` : optional, enable/disable training mode. Default value is 0. If the training_flag is set as 1(true), then the application will start in training mode and print out the trained threshold values. If the training_flag is set as 0(false), the application will start in normal mode, and will use either the default thresholds or those supplied on the command line. The trained threshold values are specific to the user’s system, may give a better power profile when compared to the default threshold values.
-
-* ``med_threshold`` : optional, sets the empty poll threshold of a modestly busy system state. If this is not supplied, the application will apply the default value of 350000.
-
-* ``high_threshold`` : optional, sets the empty poll threshold of a busy system state. If this is not supplied, the application will apply the default value of 580000.
-
-* -l : optional, set up the LOW power state frequency index
-
-* -m : optional, set up the MED power state frequency index
-
-* -h : optional, set up the HIGH power state frequency index
-
-Empty Poll Mode Example Usage
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To initially obtain the ideal thresholds for the system, the training
-mode should be run first. This is achieved by running the l3fwd-power
-app with the training flag set to “1”, and the other parameters set to
-0.
-
-.. code-block:: console
-
-        ./<build_dir>/examples/dpdk-l3fwd-power -l 1-3 -- -p 0x0f --config="(0,0,2),(0,1,3)" --empty-poll "1,0,0" –P
-
-This will run the training algorithm for x seconds on each core (cores 2
-and 3), and then print out the recommended threshold values for those
-cores. The thresholds should be very similar for each core.
-
-.. code-block:: console
-
-        POWER: Bring up the Timer
-        POWER: set the power freq to MED
-        POWER: Low threshold is 230277
-        POWER: MED threshold is 335071
-        POWER: HIGH threshold is 523769
-        POWER: Training is Complete for 2
-        POWER: set the power freq to MED
-        POWER: Low threshold is 236814
-        POWER: MED threshold is 344567
-        POWER: HIGH threshold is 538580
-        POWER: Training is Complete for 3
-
-Once the values have been measured for a particular system, the app can
-then be started without the training mode so traffic can start immediately.
-
-.. code-block:: console
-
-        ./<build_dir>/examples/dpdk-l3fwd-power -l 1-3 -- -p 0x0f --config="(0,0,2),(0,1,3)" --empty-poll "0,340000,540000" –P
-
 Telemetry Mode
 --------------
 
-- 
2.17.1