Documentation: PM: Assorted updates
cover Documentation: PM: Assorted updates
Hi All,
There patches make some changes in the PM documentation:
- Add "references" sections to cpufreq-related documents (patch [1/4]).
- Add SPDX license tags to multiple PM-related documents (patch [2/4]).
- Unify copyright notices in PM-related documents (patch [3/4]).
- Add an SPDX license tag and a copyright notice to the new intel_epb doc (in linux-next only ATM).
Thanks,
Rafael
PATCH 1/4 cpufreq: intel_pstate: Documentation: Add references sections
From: Rafael J. Wysocki <[email protected]>
Add separate refereces sections to the cpufreq.rst and intel_pstate.rst documents under admin-quide/pm and list the references to external documentation in there.
Update the ACPI specification URL while at it.
--- Documentation/admin-guide/pm/cpufreq.rst | 10 +++++++--- Documentation/admin-guide/pm/intel_pstate.rst | 25 ++++++++++++++++--------- 2 files changed, 23 insertions(+), 12 deletions(-)
Documentation/admin-guide/pm/intel_pstate.rst +16 -9
@@ -20,11 +20,10 @@ you have not done that yet.] For the processors supported by ``intel_pstate``, the P-state concept is broader than just an operating frequency or an operating performance point (see the -`LinuxCon Europe 2015 presentation by Kristen Accardi <LCEU2015_>`_ for more +LinuxCon Europe 2015 presentation by Kristen Accardi [1]_ for more information about that). For this reason, the representation of P-states used by ``intel_pstate`` internally follows the hardware specification (for details -refer to `Intel® 64 and IA-32 Architectures Software Developer’s Manual -Volume 3: System Programming Guide <SDM_>`_). However, the ``CPUFreq`` core +refer to Intel Software Developer’s Manual [2]_). However, the ``CPUFreq`` core uses frequencies for identifying operating performance points of CPUs and frequencies are involved in the user space interface exposed by it, so ``intel_pstate`` maps its internal representation of P-states to frequencies too
@@ -561,9 +560,9 @@ or to pin every task potentially sensiti On the majority of systems supported by ``intel_pstate``, the ACPI tables provided by the platform firmware contain ``_PSS`` objects returning information -that can be used for CPU performance scaling (refer to the `ACPI specification`_ -for details on the ``_PSS`` objects and the format of the information returned -by them). +that can be used for CPU performance scaling (refer to the ACPI specification +[3]_ for details on the ``_PSS`` objects and the format of the information +returned by them). The information returned by the ACPI ``_PSS`` objects is used by the ``acpi-cpufreq`` scaling driver. On systems supported by ``intel_pstate``
@@ -728,6 +727,14 @@ P-state is called, the ``ftrace`` filter <idle>-0 [000] ..s. 2537.654843: intel_pstate_set_pstate <-intel_pstate_timer_func -.. _LCEU2015: http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf -.. _SDM: http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html -.. _ACPI specification: http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf +References +========== + +.. [1] Kristen Accardi, *Balancing Power and Performance in the Linux Kernel*, + http://events.linuxfoundation.org/sites/events/files/slides/LinuxConEurope_2015.pdf + +.. [2] *Intel® 64 and IA-32 Architectures Software Developer’s Manual Volume 3: System Programming Guide*, + http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-software-developer-system-programming-manual-325384.html + +.. [3] *Advanced Configuration and Power Interface Specification*, + https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf
Documentation/admin-guide/pm/cpufreq.rst +7 -3
@@ -396,8 +396,8 @@ RT or deadline scheduling classes, the g the allowed maximum (that is, the ``scaling_max_freq`` policy limit). In turn, if it is invoked by the CFS scheduling class, the governor will use the Per-Entity Load Tracking (PELT) metric for the root control group of the -given CPU as the CPU utilization estimate (see the `Per-entity load tracking`_ -LWN.net article for a description of the PELT mechanism). Then, the new +given CPU as the CPU utilization estimate (see the *Per-entity load tracking* +LWN.net article [1]_ for a description of the PELT mechanism). Then, the new CPU frequency to apply is computed in accordance with the formula f = 1.25 * ``f_0`` * ``util`` / ``max``
@@ -698,4 +698,8 @@ hardware feature (e.g. all Intel ones), :c:macro:`CONFIG_X86_ACPI_CPUFREQ_CPB` configuration option is set. -.. _Per-entity load tracking: https://lwn.net/Articles/531853/ +References +========== + +.. [1] Jonathan Corbet, *Per-entity load tracking*, + https://lwn.net/Articles/531853/
PATCH 2/4 Documentation: PM: Add SPDX license tags to multiple files
In reply to Rafael J. WysockiFrom: Rafael J. Wysocki <[email protected]>
Add SPDX license tags to .rst files under Documentation/driver-api/pm and Documentation/admin-quide/pm.
--- Documentation/admin-guide/pm/cpufreq.rst | 2 ++ Documentation/admin-guide/pm/cpuidle.rst | 2 ++ Documentation/admin-guide/pm/index.rst | 2 ++ Documentation/admin-guide/pm/intel_pstate.rst | 2 ++ Documentation/admin-guide/pm/sleep-states.rst | 2 ++ Documentation/admin-guide/pm/strategies.rst | 2 ++ Documentation/admin-guide/pm/system-wide.rst | 2 ++ Documentation/admin-guide/pm/working-state.rst | 2 ++ Documentation/driver-api/pm/cpuidle.rst | 2 ++ Documentation/driver-api/pm/devices.rst | 2 ++ Documentation/driver-api/pm/index.rst | 2 ++ Documentation/driver-api/pm/notifiers.rst | 2 ++ Documentation/driver-api/pm/types.rst | 2 ++ 13 files changed, 26 insertions(+)
Documentation/admin-guide/pm/cpufreq.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>` .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`
Documentation/admin-guide/pm/cpuidle.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` .. |cpufreq| replace:: :doc:`CPU Performance Scaling <cpufreq>`
Documentation/admin-guide/pm/index.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ Power Management ================
Documentation/admin-guide/pm/intel_pstate.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =============================================== ``intel_pstate`` CPU Performance Scaling Driver ===============================================
Documentation/admin-guide/pm/sleep-states.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =================== System Sleep States ===================
Documentation/admin-guide/pm/strategies.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =========================== Power Management Strategies ===========================
Documentation/admin-guide/pm/system-wide.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ============================ System-Wide Power Management ============================
Documentation/admin-guide/pm/working-state.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ============================== Working-State Power Management ==============================
Documentation/driver-api/pm/cpuidle.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` .. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>` .. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>`
Documentation/driver-api/pm/devices.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` .. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` .. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>`
Documentation/driver-api/pm/index.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =============================== CPU and Device Power Management ===============================
Documentation/driver-api/pm/notifiers.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ============================= Suspend/Hibernation Notifiers =============================
Documentation/driver-api/pm/types.rst +2 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================================== Device Power Management Data Types ==================================
PATCH 3/4 Documentation: PM: Unify copyright notices
In reply to Rafael J. WysockiFrom: Rafael J. Wysocki <[email protected]>
Unify copyright notices in the .rst files under Documentation/driver-api/pm and Documentation/admin-quide/pm.
--- Documentation/admin-guide/pm/cpufreq.rst | 6 ++++-- Documentation/admin-guide/pm/cpuidle.rst | 6 ++++-- Documentation/admin-guide/pm/intel_pstate.rst | 5 +++-- Documentation/admin-guide/pm/sleep-states.rst | 6 ++++-- Documentation/admin-guide/pm/strategies.rst | 6 ++++-- Documentation/driver-api/pm/cpuidle.rst | 5 +++-- Documentation/driver-api/pm/devices.rst | 10 ++++++---- Documentation/driver-api/pm/notifiers.rst | 6 ++++-- 8 files changed, 32 insertions(+), 18 deletions(-)
Documentation/admin-guide/pm/cpufreq.rst +4 -2
@@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> .. |struct cpufreq_policy| replace:: :c:type:`struct cpufreq_policy <cpufreq_policy>` .. |intel_pstate| replace:: :doc:`intel_pstate <intel_pstate>`
@@ -7,9 +8,10 @@ CPU Performance Scaling ======================= -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]> The Concept of CPU Performance Scaling ======================================
Documentation/admin-guide/pm/cpuidle.rst +4 -2
@@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> .. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` .. |cpufreq| replace:: :doc:`CPU Performance Scaling <cpufreq>`
@@ -7,9 +8,10 @@ CPU Idle Time Management ======================== -:: +:Copyright: |copy| 2018 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2018 Intel Corp., Rafael J. Wysocki <[email protected]> Concepts ========
Documentation/admin-guide/pm/intel_pstate.rst +3 -2
@@ -1,12 +1,13 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> =============================================== ``intel_pstate`` CPU Performance Scaling Driver =============================================== -:: +:Copyright: |copy| 2017 Intel Corporation - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]> +:Author: Rafael J. Wysocki <[email protected]> General Information
Documentation/admin-guide/pm/strategies.rst +4 -2
@@ -1,12 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> =========================== Power Management Strategies =========================== -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]> The Linux kernel supports two major high-level power management strategies.
Documentation/driver-api/pm/cpuidle.rst +3 -2
@@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> .. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` .. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>`
@@ -9,9 +10,9 @@ CPU Idle Time Management ======================== -:: +:Copyright: |copy| 2019 Intel Corporation - Copyright (c) 2019 Intel Corp., Rafael J. Wysocki <[email protected]> +:Author: Rafael J. Wysocki <[email protected]> CPU Idle Time Management Subsystem
Documentation/driver-api/pm/devices.rst +6 -4
@@ -1,4 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> .. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` .. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
@@ -14,11 +15,12 @@ Device Power Management Basics ============================== -:: +:Copyright: |copy| 2010-2011 Rafael J. Wysocki <[email protected]>, Novell Inc. +:Copyright: |copy| 2010 Alan Stern <[email protected]> +:Copyright: |copy| 2016 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2010-2011 Rafael J. Wysocki <[email protected]>, Novell Inc. - Copyright (c) 2010 Alan Stern <[email protected]> - Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <[email protected]> Most of the code in Linux is device drivers, so most of the Linux power management (PM) code is also driver-specific. Most drivers will do very
Documentation/driver-api/pm/notifiers.rst +4 -2
@@ -1,12 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> ============================= Suspend/Hibernation Notifiers ============================= -:: +:Copyright: |copy| 2016 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <[email protected]> There are some operations that subsystems or drivers may want to carry out before hibernation/suspend or after restore/resume, but they require the system
Documentation/admin-guide/pm/sleep-states.rst +4 -2
@@ -1,12 +1,14 @@ .. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> =================== System Sleep States =================== -:: +:Copyright: |copy| 2017 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> - Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]> Sleep states are global low-power states of the entire system in which user space code cannot be executed and the overall system activity is significantly
PATCH 4/4 admin-guide: pm: intel_epb: Add SPDX license tag and copyright notice
In reply to Rafael J. WysockiFrom: Rafael J. Wysocki <[email protected]>
Add an SPDX license tag and a copyright notice to the intel_epb.rst file under Documentation/admin-quide/pm.
--- Documentation/admin-guide/pm/intel_epb.rst | 8 ++++++++ 1 file changed, 8 insertions(+)
Documentation/admin-guide/pm/intel_epb.rst +8 -0
@@ -1,7 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + ====================================== Intel Performance and Energy Bias Hint ====================================== +:Copyright: |copy| 2019 Intel Corporation + +:Author: Rafael J. Wysocki <[email protected]> + + .. kernel-doc:: arch/x86/kernel/cpu/intel_epb.c :doc: overview
Quoted 9 lines · Rafael J. Wysocki
Hi All,
There patches make some changes in the PM documentation:
- Add "references" sections to cpufreq-related documents (patch [1/4]).
- Add SPDX license tags to multiple PM-related documents (patch [2/4]).
- Unify copyright notices in PM-related documents (patch [3/4]).
- Add an SPDX license tag and a copyright notice to the newintel_epbdoc (in linux-next only ATM).
Signature · 1 line
viresh