docs: Further split and update user guide

Signed-off-by: Artem Bityutskiy <artem.bityutskiy@linux.intel.com>

Author: dedekind

docs/guide-cstates.md

@@ -175,353 +175,19 @@ to collect and save emulation data from a real system. The emulation data should
 
 ## P-states
 
-The `pepc pstates` command groups operations related to CPU performance states (P-states). For
-example, it supports reading and changing CPU frequency limits.
-
-If you are new to Intel CPU P-states, the [Intel CPU Base Frequency
-Explained](misc-cpu-base-freq.md) article explains many concepts related to CPU performance scaling.
-
-### Examples
-
-**Get all P-states Information**
-
-Here is an example of running `pepc pstates info` on a 2-socket Granite Rapids system.
-
-```bash
-$ pepc pstates info
-Source: Linux sysfs file-system
- - Turbo: on
- - Min. CPU frequency: 800.00MHz for all CPUs
- - Max. CPU frequency: 3.90GHz for all CPUs
- - Min. supported CPU frequency: 800.00MHz for all CPUs
- - Max. supported CPU frequency: 3.90GHz for all CPUs
- - CPU base frequency: 2.00GHz for all CPUs
- - EPP: 'balance_performance' for all CPUs
- - EPB: 6 for all CPUs
- - CPU frequency driver: intel_pstate
- - Mode of 'intel_pstate' driver: active
- - CPU frequency governor: 'powersave' for all CPUs
- - Available CPU frequency governors: performance, powersave
- - ACPI CPPC lowest performance level: 5 for all CPUs
- - ACPI CPPC lowest nonlinear performance level: 8 for all CPUs
- - ACPI CPPC guaranteed performance level: 20 for all CPUs
- - ACPI CPPC nominal performance level: 20 for all CPUs
- - ACPI CPPC highest performance level: 39 for all CPUs
-Source: Model Specific Register (MSR)
- - Fixed CPU base frequency: 2.00GHz
- - Hardware power management: on
- - HWP lowest performance level: 5 for all CPUs
- - HWP most efficient performance level: 8 for all CPUs
- - HWP guaranteed performance level: 20 for all CPUs
- - HWP highest performance level: 39 for all CPUs
-Source: Hardware documentation
- - Bus clock speed: 100.00MHz
-```
-
-**Get CPU Base Frequency**
-
-Here are 2 commands for getting the fixed and sysfs CPU base frequency on a Raptor Lake system.
-
-```bash
-# Fixed CPU base frequency
-$ pepc pstates info --fixed-base-freq
-Fixed CPU base frequency: 2.20GHz
-# Sysfs CPU base frequency
-$ pepc pstates info --base-freq
-CPU base frequency: 1.90GHz for CPUs 0-7 (P-cores)
-CPU base frequency: 1.40GHz for CPUs 8-15 (E-cores)
-```
-
-**Set Min. and Max. CPU Frequency for E-cores**
-
-Here is how to limit CPU frequency range to [1.5GHz, 2GHz] for E-cores on a Raptor Lake system.
-
-First, find out what CPUs are E-cores using the `pepc topology info` command.
-
-```bash
-$ pepc topology info
-CPU    Core    Module    Node    Package    Hybrid
-  0       0         0       0          0    P-core
-  1       0         0       0          0    P-core
-  2       4         1       0          0    P-core
-  3       4         1       0          0    P-core
-  4       8         2       0          0    P-core
-  5       8         2       0          0    P-core
-  6      12         3       0          0    P-core
-  7      12         3       0          0    P-core
-  8      16         4       0          0    E-core
-  9      17         4       0          0    E-core
- 10      18         4       0          0    E-core
- 11      19         4       0          0    E-core
- 12      20         5       0          0    E-core
- 13      21         5       0          0    E-core
- 14      22         5       0          0    E-core
- 15      23         5       0          0    E-core
-```
-
-E-cores are CPUs 8-15. Now set the min. and max. CPU frequency for these CPUs.
-
-```bash
-$ pepc pstates config --min-freq 1.5GHz --max-freq 2GHz --cpus 8-15
-Min. CPU frequency: set to 1.50GHz for CPUs 8-15 (E-cores)
-Max. CPU frequency: set to 2.00GHz for CPUs 8-15 (E-cores)
-```
-
-Verify it.
-
-```bash
-$ pepc pstates info --min-freq --max-freq
-Min. CPU frequency: 400.00MHz for CPUs 0-7 (P-cores)
-Min. CPU frequency: 1.50GHz for CPUs 8-15 (E-cores)
-Max. CPU frequency: 4.60GHz for CPUs 0-7 (P-cores)
-Max. CPU frequency: 2.00GHz for CPUs 8-15 (E-cores)
-```
-
-**Lock CPU Frequency to Base Frequency**
-
-Lock CPU frequency to sysfs base frequency (HFM) for all CPUs in package 1 on a 2-socket Granite
-Rapids system.
-
-```bash
-$ pepc pstates config --min-freq base --max-freq base --packages 1
-Min. CPU frequency: set to 2.00GHz for CPUs 128-255,384-511 (package 1)
-Max. CPU frequency: set to 2.00GHz for CPUs 128-255,384-511 (package 1)
-```
-
-**Note:** You do not have to specify the exact base frequency value. You can simply use the 'base'
-keyword, and `pepc` will figure out the correct value itself.
-
-**Unlock CPU Frequency**
-
-Unlock CPU frequency for all CPUs on a Raptor Lake system by setting min. and max. CPU frequency to
-the supported minimum and maximum frequency.
-
-```bash
-$ pepc pstates config --min-freq min --max-freq max
-Min. CPU frequency: set to 1.2GHz for CPUs 0-87 (all CPUs)
-Max. CPU frequency: set to 3.6GHz for CPUs 0-87 (all CPUs)
-```
-
-**Change Linux CPU Frequency Governor**
-
-First, get the name of current governor and list of supported governors.
-
-```bash
-$ pepc pstates info --governor --governors
-CPU frequency governor: 'schedutil' for CPUs 0-87 (all CPUs)
-Available CPU frequency governors: conservative, ondemand, userspace, powersave, performance, schedutil
-```
-
-Switch to the 'performance' governor.
-
-```bash
-$ pepc pstates config --governor performance
-CPU frequency governor: set to 'performance' for CPUs 0-87 (all CPUs)
-```
-
-Verify it.
-
-```bash
-$ pepc pstates info --governor
-CPU frequency governor: 'performance' for CPUs 0-87 (all CPUs)
-```
+The `pepc pstates` command groups operations related to CPU performance states (P-states). This
+command is covered in a separate document: [Pepc User Guide: P-states](guide-pstates.md).
 
 ## C-states
 
-The `pepc cstates` command groups operations related to CPU idle states (C-states). For
-example, it supports enabling or disabling requestable Linux C-states or toggling the CPU "C1
-demotion" feature.
-
-If you are new to Linux and Intel CPU C-states, the following articles available in the `pepc` repository
-may be helpful:
-- [Intel C-state namespaces](misc-cstate-namespaces.md) - explains C-state naming conventions.
-- [Xeon C6P and C6SP Idle States](misc-c6p-c6sp.md) - explains the C6P and C6SP idle states on
-  Intel Xeon platforms.
-
-### Examples
-
-**Get all C-states Information**
-
-```bash
-$ pepc cstates info
-Source: Linux sysfs file-system
- - POLL: 'on' for CPUs 0-87 (all CPUs)
-    - description: CPUIDLE CORE POLL IDLE
-    - expected latency: 0 us
-    - target residency: 0 us
- - C1: 'on' for CPUs 0-87 (all CPUs)
-    - description: MWAIT 0x00
-    - expected latency: 2 us
-    - target residency: 2 us
- - C1E: 'on' for CPUs 0-87 (all CPUs)
-    - description: MWAIT 0x01
-    - expected latency: 10 us
-    - target residency: 20 us
- - C3: 'off' for CPUs 0-87 (all CPUs)
-    - description: MWAIT 0x10
-    - expected latency: 40 us
-    - target residency: 100 us
- - C6: 'on' for CPUs 0-87 (all CPUs)
-    - description: MWAIT 0x20
-    - expected latency: 133 us
-    - target residency: 400 us
-Source: Model Specific Register (MSR)
- - Package C-state limit: 'PC6' for CPUs 0-87 (all CPUs)
- - Package C-state limit lock: 'on' for CPUs 0-87 (all CPUs)
- - Available package C-state limits: PC0, PC2, PC3, PC6, unlimited
- - C1 demotion: 'off' for CPUs 0-87 (all CPUs)
- - C1 undemotion: 'off' for CPUs 0-87 (all CPUs)
- - C1E autopromote: 'off' for CPUs 0-87 (all CPUs)
- - C-state prewake: 'on' for CPUs 0-87 (all CPUs)
-Source: Linux sysfs file-system
- - Idle driver: intel_idle
- - Idle governor: 'menu' for CPUs 0-87 (all CPUs)
- - Available idle governors: menu
-```
-
-**Get information about C1, C1E autopromote, and C1 demotion**
-
-```bash
-$ pepc cstates info --cstates C1 --c1e-autopromote --c1-demotion
-C1: 'on' for CPUs 0-87 (all CPUs)
- - description: MWAIT 0x00
- - expected latency: 2 us
- - target residency: 2 us
-C1E autopromote: 'off' for CPUs 0-87 (all CPUs)
-C1 demotion: 'off' for CPUs 0-87 (all CPUs)
-```
-
-**Toggle C-states**
-
-Disable all C-states except POLL on all CPUs.
-
-```bash
-$ pepc cstates config --disable all --enable POLL
-POLL: set to 'off' for CPUs 0-87 (all CPUs)
-C1: set to 'off' for CPUs 0-87 (all CPUs)
-C1E: set to 'off' for CPUs 0-87 (all CPUs)
-C3: set to 'off' for CPUs 0-87 (all CPUs)
-C6: set to 'off' for CPUs 0-87 (all CPUs)
-POLL: set to 'on' for CPUs 0-87 (all CPUs)
-```
-
-Re-enable all C-states on all CPUs.
-
-```bash
-$ pepc cstates config --enable all
-POLL: set to 'on' for CPUs 0-87 (all CPUs)
-C1: set to 'on' for CPUs 0-87 (all CPUs)
-C1E: set to 'on' for CPUs 0-87 (all CPUs)
-C3: set to 'on' for CPUs 0-87 (all CPUs)
-C6: set to 'on' for CPUs 0-87 (all CPUs)
-```
-
-Disable C1E and C6 on package 1.
-
-```bash
-$ pepc cstates config --disable C1E,C6 --packages 1
-C1E: set to 'off' for CPUs 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39,41,43,45,47,49,51,53,55,57,59,61,63,65,67,69,71,73,75,77,79,81,83,85,87 (package 1)
-C6: set to 'off' for CPUs 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,33,35,37,39,41,43,45,47,49,51,53,55,57,59,61,63,65,67,69,71,73,75,77,79,81,83,85,87 (package 1)
-```
-
-**Configure package C-state limit**
-
-Get package C-state limit information.
-
-```bash
-$ pepc cstates info --pkg-cstate-limit
-Package C-state limit: 'PC6' for CPUs 0-87 (all CPUs)
-Package C-state limit lock: 'off' for CPUs 0-87 (all CPUs)
-Available package C-state limits: PC0, PC2, PC3, PC6, unlimited
-```
-
-Since package C-state limit MSR is not locked, we can modify the limit. Set the deepest
-allowed package C-state to PC0 on all packages.
-
-```bash
-$ pepc cstates config --pkg-cstate-limit PC0 --packages all
-Package C-state limit set to 'PC0' for CPUs 0-87 (all CPUs)
-```
+The `pepc cstates` command groups operations related to CPU idle states (C-states). This command is
+covered in a separate document: [Pepc User Guide: C-states](guide-cstates.md).
 
 ## Uncore
 
 The `pepc uncore` command groups operations related to CPU uncore, for example reading or changing
-uncore frequency limits.
-
-"Uncore" is an informal term referring to the Intel CPU north complex blocks excluding the cores. For
-example, it typically includes components like the last level cache (LLC), memory controller, and
-north complex interconnects (e.g., between cores).
-
-Some concepts related to uncore frequency scaling and the ELC (Efficiency Latency Control) feature
-are explained in [Uncore ELC and Frequency Scaling](misc-uncore-elc.md).
-
-### Uncore Frequency and Dies
-
-In pepc, a "die" is considered to be a unit of uncore frequency scaling. In other words, uncore
-frequency is per-die.
-
-Dies that include CPU cores are referred to as compute dies. Some Intel CPUs enumerate compute dies
-via the `CPUID` instruction, and Linux exposes this information via sysfs (e.g.,
-'/sys/devices/system/cpu/cpu179/topology/die_cpus_list'). Some Intel CPUs do not enumerate
-compute dies via `CPUID`, so Linux does not expose any die-related information in sysfs. In such
-cases, `pepc` uses platform-specific methods to figure out the die topology. For example, on
-Granite Rapids Xeon, `pepc` uses MSR 0x54 (`MSR_PM_LOGICAL_ID`) to figure out which CPUs belong to
-which compute die.
-
-Some dies do not include CPUs, but still have uncore frequency scaling capability. For example,
-on Granite Rapids Xeon there are "I/O dies" that include uncore blocks related to PCIe and
-CXL. Such dies cannot be discovered via `CPUID` or sysfs, so `pepc` uses the TPMI mechanism to
-enumerate non-compute dies and assign them unique die IDs.
-
-Typically client CPUs (e.g., Raptor Lake, Alder Lake) have a single compute die and no non-compute
-dies. Many server CPUs (e.g., Ice Lake Xeon, Sapphire Rapids Xeon) have only a single compute die
-and no non-compute dies as well. Some server CPUs (e.g., Cascade Lake-AP) have multiple compute dies
-and no non-compute dies. Finally, newer server CPUs (e.g., Granite Rapids Xeon and Sierra Forest
-Xeon) may have multiple compute dies and multiple non-compute dies.
-
-Use `pepc topology info` to discover die topology on your system. Refer to the
-[CPU Topology](#cpu-topology) section for examples, including how to discover non-compute dies.
-
-### Examples
-
-**Get All Uncore Information**
-
-Here is an example of running `pepc uncore info` on a Granite Rapids system.
-
-```bash
-$ pepc uncore info
-Source: Linux sysfs file-system
- - Min. uncore frequency: 800.00MHz for all dies in all packages
- - Max. uncore frequency: 2.20GHz for dies 0-2 in package 0, dies 0-2 in package 1
- - Max. uncore frequency: 2.50GHz for dies 3,4 in package 0, dies 3,4 in package 1
- - Min. supported uncore frequency: 800.00MHz for all dies in all packages
- - Max. supported uncore frequency: 2.20GHz for dies 0-2 in package 0, dies 0-2 in package 1
- - Max. supported uncore frequency: 2.50GHz for dies 3,4 in package 0, dies 3,4 in package 1
- - ELC low zone min. uncore frequency: 1.20GHz for dies 0-2 in package 0, dies 0-2 in package 1
- - ELC low zone min. uncore frequency: 800.00MHz for dies 3,4 in package 0, dies 3,4 in package 1
- - ELC low threshold: 11% for all dies in all packages
- - ELC high threshold: 95% for all dies in all packages
- - ELC high threshold status: 'on' for all dies in all packages
-```
-
-Notice that compute dies (0-2) and I/O dies (3,4) have different maximum uncore frequencies.
-
-The Raptor Lake client system has only one compute die and no non-compute dies, and it does not
-support ELC.
-
-```bash
-$ pepc uncore info
-Source: Linux sysfs file-system
- - Min. uncore frequency: 400.00MHz for all CPUs
- - Max. uncore frequency: 4.00GHz for all CPUs
- - Min. supported uncore frequency: 400.00MHz for all CPUs
- - Max. supported uncore frequency: 4.00GHz for all CPUs
-```
-
-**Additional Examples**
-
-For more examples related to uncore frequency scaling and ELC configuration, refer to
-the [Uncore ELC and Frequency Scaling](misc-uncore-elc.md) article.
+uncore performance scaling settings. This command is covered in a separate document:
+[Pepc User Guide: Uncore](guide-uncore.md).
 
 ## CPU Hotplug