Pull documentation updates from Jonathan Corbet:
"A slightly calmer cycle for docs this time around, though there is
still a fair amount going on, including:
- Some signs of life on the long-moribund Japanese translation
- Documentation on policies around the use of generative tools for
patch submissions, and a separate document intended for consumption
by generative tools
- The completion of the move of the documentation tools to
tools/docs. For now we're leaving a /scripts/kernel-doc symlink
behind to avoid breaking scripts
- Ongoing build-system work includes the incorporation of
documentation in Python code, better support for documenting
variables, and lots of improvements and fixes
- Automatic linking of man-page references -- cat(1), for example --
to the online pages in the HTML build
...and the usual array of typo fixes and such"
* tag 'docs-7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (107 commits)
doc: development-process: add notice on testing
tools: sphinx-build-wrapper: improve its help message
docs: sphinx-build-wrapper: allow -v override -q
docs: kdoc: Fix pdfdocs build for tools
docs: ja_JP: process: translate 'Obtain a current source tree'
docs: fix 're-use' -> 'reuse' in documentation
docs: ioctl-number: fix a typo in ioctl-number.rst
docs: filesystems: ensure proc pid substitutable is complete
docs: automarkup.py: Skip common English words as C identifiers
Documentation: use a source-read extension for the index link boilerplate
docs: parse_features: make documentation more consistent
docs: add parse_features module documentation
docs: jobserver: do some documentation improvements
docs: add jobserver module documentation
docs: kabi: helpers: add documentation for each "enum" value
docs: kabi: helpers: add helper for debug bits 7 and 8
docs: kabi: system_symbols: end docstring phrases with a dot
docs: python: abi_regex: do some improvements at documentation
docs: python: abi_parser: do some improvements at documentation
docs: add kabi modules documentation
...
Merge power capping updates, OPP (operating performance points) updates
and energy model management documentation updates for 6.20-rc1/7.0-rc1:
- Add PL4 support for Ice Lake to the Intel RAPL power capping
driver (Daniel Tang)
- Replace sprintf() with sysfs_emit() in power capping sysfs show
functions (Sumeet Pawnikar)
- Make dev_pm_opp_get_level() return value match the documentation
after a previous update of the latter (Aleks Todorov)
- Use scoped for each OF child loop in the OPP code (Krzysztof
Kozlowski)
- Fix a bug in an example code snippet and correct typos in the energy
model management documentation (Patrick Little)
* pm-powercap:
powercap: intel_rapl: Add PL4 support for Ice Lake
powercap: Replace sprintf() with sysfs_emit() in sysfs show functions
* pm-opp:
OPP: Return correct value in dev_pm_opp_get_level
OPP: of: Simplify with scoped for each OF child loop
* pm-em:
PM: EM: Documentation: Fix bug in example code snippet
Documentation: Fix typos in energy model documentation
The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.
For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.
This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.
Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.
For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
Till now, the runtime PM workqueue has been flagged as freezable, so it
does not process work items during system-wide PM transitions like
system suspend and resume. The original reason to do that was to
reduce the likelihood of runtime PM getting in the way of system-wide
PM processing, but now it is mostly an optimization because (1) runtime
suspend of devices is prevented by bumping up their runtime PM usage
counters in device_prepare() and (2) device drivers are expected to
disable runtime PM for the devices handled by them before they embark
on system-wide PM activities that may change the state of the hardware
or otherwise interfere with runtime PM. However, it prevents
asynchronous runtime resume of devices from working during system-wide
PM transitions, which is confusing because synchronous runtime resume
is not prevented at the same time, and it also sometimes turns out to
be problematic.
For example, it has been reported that blk_queue_enter() may deadlock
during a system suspend transition because of the pm_request_resume()
usage in it [1]. It may also deadlock during a system resume transition
in a similar way. That happens because the asynchronous runtime resume
of the given device is not processed due to the freezing of the runtime
PM workqueue. While it may be better to address this particular issue
in the block layer, the very presence of it means that similar problems
may be expected to occur elsewhere.
For this reason, remove the WQ_FREEZABLE flag from the runtime PM
workqueue and make device_suspend_late() use the generic variant of
pm_runtime_disable() that will carry out runtime PM of the device
synchronously if there is pending resume work for it.
Also update the comment before the pm_runtime_disable() call in
device_suspend_late(), to document the fact that the runtime PM
should not be expected to work for the device until the end of
device_resume_early(), and update the related documentation.
This change may, even though it is not expected to, uncover some
latent issues related to queuing up asynchronous runtime resume
work items during system suspend or hibernation. However, they
should be limited to the interference between runtime resume and
system-wide PM callbacks in the cases when device drivers start
to handle system-wide PM before disabling runtime PM as described
above.
Link: https://lore.kernel.org/linux-pm/20251126101636.205505-2-yang.yang@vivo.com/
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: Ulf Hansson <ulf.hansson@linaro.org>
Link: https://patch.msgid.link/12794222.O9o76ZdvQC@rafael.j.wysocki
Pull more power management updates from Rafael Wysocki:
"Fix a runtime PM unit test added during the 6.18 development cycle and
change the pm_runtime_barrier() return type to void (Brian Norris)"
* tag 'pm-6.19-rc1-2' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm:
coccinelle: Drop pm_runtime_barrier() error code checks
PM: runtime: Make pm_runtime_barrier() return void
PM: runtime: Stop checking pm_runtime_barrier() return code
Merge PM QoS updates and a cpupower utility update for 6.19-rc1:
- Introduce and document a QoS limit on CPU exit latency during wakeup
from suspend-to-idle (Ulf Hansson)
- Add support for building libcpupower statically (Zuo An)
* pm-qos:
Documentation: power/cpuidle: Document the CPU system wakeup latency QoS
cpuidle: Respect the CPU system wakeup QoS limit for cpuidle
sched: idle: Respect the CPU system wakeup QoS limit for s2idle
pmdomain: Respect the CPU system wakeup QoS limit for cpuidle
pmdomain: Respect the CPU system wakeup QoS limit for s2idle
PM: QoS: Introduce a CPU system wakeup QoS limit
* pm-tools:
tools/power/cpupower: Support building libcpupower statically
Merge updates related to system suspend and hibernation for 6.19-rc1:
- Replace snprintf() with scnprintf() in show_trace_dev_match()
(Kaushlendra Kumar)
- Fix memory allocation error handling in pm_vt_switch_required()
(Malaya Kumar Rout)
- Introduce CALL_PM_OP() macro and use it to simplify code in
generic PM operations (Kaushlendra Kumar)
- Add module param to backtrace all CPUs in the device power management
watchdog (Sergey Senozhatsky)
- Rework message printing in swsusp_save() (Rafael Wysocki)
- Make it possible to change the number of hibernation compression
threads (Xueqin Luo)
- Clarify that only cgroup1 freezer uses PM freezer (Tejun Heo)
- Add document on debugging shutdown hangs to PM documentation and
correct a mistaken configuration option in it (Mario Limonciello)
- Shut down wakeup source timer before removing the wakeup source from
the list (Kaushlendra Kumar, Rafael Wysocki)
- Introduce new PMSG_POWEROFF event for system shutdown handling with
the help of PM device callbacks (Mario Limonciello)
- Make pm_test delay interruptible by wakeup events (Riwen Lu)
- Clean up kernel-doc comment style usage in the core hibernation
code and remove unuseful comments from it (Sunday Adelodun, Rafael
Wysocki)
- Add support for handling wakeup events and aborting the suspend
process while it is syncing file systems (Samuel Wu, Rafael Wysocki)
* pm-sleep: (21 commits)
PM: hibernate: Extra cleanup of comments in swap handling code
PM: sleep: Call pm_sleep_fs_sync() instead of ksys_sync_helper()
PM: sleep: Add support for wakeup during filesystem sync
PM: hibernate: Clean up kernel-doc comment style usage
PM: suspend: Make pm_test delay interruptible by wakeup events
usb: sl811-hcd: Add PM_EVENT_POWEROFF into suspend callbacks
scsi: Add PM_EVENT_POWEROFF into suspend callbacks
PM: Introduce new PMSG_POWEROFF event
PM: wakeup: Update after recent wakeup source removal ordering change
PM: wakeup: Delete timer before removing wakeup source from list
Documentation: power: Correct a mistaken configuration option
Documentation: power: Add document on debugging shutdown hangs
freezer: Clarify that only cgroup1 freezer uses PM freezer
PM: hibernate: add sysfs interface for hibernate_compression_threads
PM: hibernate: make compression threads configurable
PM: hibernate: dynamically allocate crc->unc_len/unc for configurable threads
PM: hibernate: Rework message printing in swsusp_save()
PM: dpm_watchdog: add module param to backtrace all CPUs
PM: sleep: Introduce CALL_PM_OP() macro to simplify code
PM: console: Fix memory allocation error handling in pm_vt_switch_required()
...
Pull documentation updates from Jonathan Corbet:
"It has been a relatively busy cycle in docsland, with changes all
over:
- Bring the kernel memory-model docs into the Sphinx build in the
"literal include" mode.
- Lots of build-infrastructure work, further cleaning up long-term
kernel-doc technical debt. The sphinx-pre-install tool has been
converted to Python and updated for current systems.
- A new tool to detect when documents have been moved and generate
HTML redirects; this can be used on kernel.org (or any other site
hosting the rendered docs) to avoid breaking links.
- Automated processing of the YAML files describing the netlink
protocol.
- A significant update of the maintainer's PGP guide.
... and a seemingly endless series of typo fixes, build-problem fixes,
etc"
* tag 'docs-6.18' of git://git.lwn.net/linux: (193 commits)
Documentation/features: Update feature lists for 6.17-rc7
docs: remove cdomain.py
Documentation/process: submitting-patches: fix typo in "were do"
docs: dev-tools/lkmm: Fix typo of missing file extension
Documentation: trace: histogram: Convert ftrace docs cross-reference
Documentation: trace: histogram-design: Wrap introductory note in note:: directive
Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram
Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text
Documentation: trace: histogram: Fix histogram trigger subsection number order
docs: driver-api: fix spelling of "buses".
Documentation: fbcon: Use admonition directives
Documentation: fbcon: Reindent 8th step of attach/detach/unload
Documentation: fbcon: Add boot options and attach/detach/unload section headings
docs: filesystems: sysfs: add remaining top level sysfs directory descriptions
docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions
docs: filesystems: sysfs: remove top level sysfs net directory
docs: maintainer: Fix ambiguous subheading formatting
docs: kdoc: a few more dump_typedef() tweaks
docs: kdoc: remove redundant comment stripping in dump_typedef()
docs: kdoc: remove some dead code in dump_typedef()
...
The current consumer documentation does not include bulk operations,
providing an example of how to acquire multiple regulators by calling
regulator_get() multiple times. That solution is valid and slightly
simpler for a small amount of regulators, but it does not scale well.
Document the bulk operations to get, enable and disable regulators.
Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
Link: https://patch.msgid.link/20250819-reg_consumer_doc-v1-1-b631fc0d35a3@gmail.com
Signed-off-by: Mark Brown <broonie@kernel.org>
Merge runtime PM updates and power capping updates for 6.17-rc1:
- Document return values of suspend-related API functions in the
runtime PM framework (Sakari Ailus)
- Mark last busy stamp in multiple autosuspend-related functions in the
runtime PM framework and update its documentation (Sakari Ailus)
- Take active children into account in pm_runtime_get_if_in_use() for
consistency (Rafael Wysocki)
- Fix NULL pointer dereference in get_pd_power_uw() in the dtpm_cpu
power capping driver (Sivan Zohar-Kotzer)
- Add support for the Bartlett Lake platform to the Intel RAPL power
capping driver (Qiao Wei)
- Add PL4 support for Panther Lake to the intel_rapl_msr power capping
driver (Zhang Rui)
* pm-runtime:
PM: runtime: Take active children into account in pm_runtime_get_if_in_use()
Documentation: PM: *_autosuspend() functions update last busy time
PM: runtime: Mark last busy stamp in pm_request_autosuspend()
PM: runtime: Mark last busy stamp in pm_runtime_autosuspend()
PM: runtime: Mark last busy stamp in pm_runtime_put_sync_autosuspend()
PM: runtime: Mark last busy stamp in pm_runtime_put_autosuspend()
PM: runtime: Document return values of suspend-related API functions
* pm-powercap:
powercap: dtpm_cpu: Fix NULL pointer dereference in get_pd_power_uw()
powercap: intel_rapl: Add support for Bartlett Lake platform
powercap: intel_rapl_msr: Add PL4 support for Panther Lake
Pull documentation fixes from Jonathan Corbet:
"Two fixes for footnote-related warnings that appeared with Sphinx 8.x.
We want to encourage use of newer Sphinx - they fixed a performance
problem and the docs build takes less than half the time it used to"
* tag 'docs-6.14-2' of git://git.lwn.net/linux:
docs: power: Fix footnote reference for Toshiba Satellite P10-554
Documentation: ublk: Drop Stefan Hajnoczi's message footnote
platform_pci_wakeup_init() was removed by d2e5f0c16a ("ACPI / PCI: Rework
the setup and cleanup of device wakeup") but was still mentioned in the
documentation.
Update the doc to refer to pci_acpi_setup(), which does the equivalent
work.
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Dhruva Gole <d-gole@ti.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Merge Enery Model changes for 6.9-rc1:
- Allow the Energy Model to be updated dynamically (Lukasz Luba).
* pm-em: (24 commits)
PM: EM: Fix nr_states warnings in static checks
Documentation: EM: Update with runtime modification design
PM: EM: Add em_dev_compute_costs()
PM: EM: Remove old table
PM: EM: Change debugfs configuration to use runtime EM table data
drivers/thermal/devfreq_cooling: Use new Energy Model interface
drivers/thermal/cpufreq_cooling: Use new Energy Model interface
powercap/dtpm_devfreq: Use new Energy Model interface to get table
powercap/dtpm_cpu: Use new Energy Model interface to get table
PM: EM: Optimize em_cpu_energy() and remove division
PM: EM: Support late CPUs booting and capacity adjustment
PM: EM: Add performance field to struct em_perf_state and optimize
PM: EM: Add em_perf_state_from_pd() to get performance states table
PM: EM: Introduce em_dev_update_perf_domain() for EM updates
PM: EM: Add functions for memory allocations for new EM tables
PM: EM: Use runtime modified EM for CPUs energy estimation in EAS
PM: EM: Introduce runtime modifiable table
PM: EM: Split the allocation and initialization of the EM table
PM: EM: Check if the get_cost() callback is present in em_compute_costs()
PM: EM: Introduce em_compute_costs()
...
Merge cpufreq changes for 6.9-rc1:
- Enable preferred core support in the amd-pstate cpufreq driver (Meng
Li).
- Fix min_perf assignment in amd_pstate_adjust_perf() and make the
min/max limit perf values in amd-pstate always stay within the
(highest perf, lowest perf) range (Tor Vic, Meng Li).
- Change default transition delay in cpufreq to 2ms (Qais Yousef).
- Drop long-unused cpudata::prev_cummulative_iowait from the
intel_pstate cpufreq driver (Jiri Slaby).
- Allow intel_pstate to assign model-specific values to strings used in
the EPP sysfs interface and make it do so on Meteor Lake (Srinivas
Pandruvada).
- Remove references to 10ms minimum sampling rate from comments in the
cpufreq code (Pierre Gondois).
- Prevent scaling_cur_freq from exceeding scaling_max_freq when the
latter is an inefficient frequency (Shivnandan Kumar).
- Honour transition_latency over transition_delay_us in cpufreq (Qais
Yousef).
- Stop unregistering cpufreq cooling on CPU hot-remove (Viresh Kumar).
- General enhancements / cleanups to ARM cpufreq drivers (tianyu2,
Nícolas F. R. A. Prado, Erick Archer, Arnd Bergmann, Anastasia
Belova).
- Update cpufreq-dt-platdev to block/approve devices (Richard Acayan).
- Make the SCMI cpufreq driver get a transition delay value from
firmware (Pierre Gondois).
* pm-cpufreq: (28 commits)
cpufreq: scmi: Set transition_delay_us
firmware: arm_scmi: Populate fast channel rate_limit
firmware: arm_scmi: Populate perf commands rate_limit
cpufreq: Don't unregister cpufreq cooling on CPU hotplug
cpufreq: Honour transition_latency over transition_delay_us
cpufreq: Limit resolving a frequency to policy min/max
cpufreq: amd-pstate: adjust min/max limit perf
cpufreq: Remove references to 10ms min sampling rate
cpufreq: intel_pstate: Update default EPPs for Meteor Lake
cpufreq: intel_pstate: Allow model specific EPPs
cpufreq: qcom-hw: add CONFIG_COMMON_CLK dependency
cpufreq: dt-platdev: block SDM670 in cpufreq-dt-platdev
cpufreq: intel_pstate: remove cpudata::prev_cummulative_iowait
cpufreq: Change default transition delay to 2ms
cpufreq: amd-pstate: Fix min_perf assignment in amd_pstate_adjust_perf()
Documentation: PM: amd-pstate: Fix section title underline
Documentation: introduce amd-pstate preferrd core mode kernel command line options
Documentation: amd-pstate: introduce amd-pstate preferred core
cpufreq: amd-pstate: Update amd-pstate preferred core ranking dynamically
ACPI: cpufreq: Add highest perf change notification
...
Merge changes related to the runtime power management of devices for
6.9-rc1:
- Simplify pm_runtime_get_if_active() usage and add a replacement for
pm_runtime_put_autosuspend() (Sakari Ailus).
- Add a tracepoint for runtime_status changes tracking (Vilas Bhat).
- Fix section title markdown in the runtime PM documentation (Yiwei
Lin).
* pm-runtime:
Documentation: PM: Fix runtime_pm.rst markdown syntax
PM: runtime: add tracepoint for runtime_status changes
PM: runtime: Add pm_runtime_put_autosuspend() replacement
PM: runtime: Simplify pm_runtime_get_if_active() usage
The '7. Generic subsystem callbacks' should be a section title, but
the markdown syntax is not adequate now.
Fix it so the chapter can be linked at docs.kernel.org correctly.
Signed-off-by: Yiwei Lin <s921975628@gmail.com>
[ rjw: Changelog edits ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
According to the context, 'pci_pm_suspend_noirq' is the right
word for the changed sentence.
Signed-off-by: Yiwei Lin <s921975628@gmail.com>
[ rjw: Subject edits ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Add __pm_runtime_put_autosuspend() that replaces
pm_runtime_put_autosuspend() for new users. The intent is to later
re-purpose pm_runtime_put_autosuspend() to also mark the device's last
busy stamp---which is what the vast majority of users actually need.
This is also described in pm_runtime_put_autosuspend() documentation.
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
There are two ways to opportunistically increment a device's runtime PM
usage count, calling either pm_runtime_get_if_active() or
pm_runtime_get_if_in_use(). The former has an argument to tell whether to
ignore the usage count or not, and the latter simply calls the former with
ign_usage_count set to false. The other users that want to ignore the
usage_count will have to explicitly set that argument to true which is a
bit cumbersome.
To make this function more practical to use, remove the ign_usage_count
argument from the function. The main implementation is in a static
function called pm_runtime_get_conditional() and implementations of
pm_runtime_get_if_active() and pm_runtime_get_if_in_use() are moved to
runtime.c.
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Reviewed-by: Alex Elder <elder@linaro.org>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: Takashi Iwai <tiwai@suse.de> # sound/
Reviewed-by: Jacek Lawrynowicz <jacek.lawrynowicz@linux.intel.com> # drivers/accel/ivpu/
Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com> # drivers/gpu/drm/i915/
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Acked-by: Bjorn Helgaas <bhelgaas@google.com> # drivers/pci/
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Add a new description which covers the information about runtime EM.
It contains the design decisions, describes models and how they
reflect the reality. Remove description of the default EM. Add example
driver code which modifies EM. Add API documentation for the new feature
which allows to modify the EM in runtime.
Reviewed-by: Dietmar Eggemann <dietmar.eggemann@arm.com>
Tested-by: Dietmar Eggemann <dietmar.eggemann@arm.com>
Signed-off-by: Lukasz Luba <lukasz.luba@arm.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
As noted in the "Deprecated Interfaces, Language Features, Attributes,
and Conventions" documentation [1], size calculations (especially
multiplication) should not be performed in memory allocator (or similar)
function arguments due to the risk of them overflowing. This could lead
to values wrapping around and a smaller allocation being made than the
caller was expecting. Using those allocations could lead to linear
overflows of heap memory and other misbehaviors.
So, in the example code use the purpose specific kcalloc() function
instead of the argument size * count in the kzalloc() function.
At the same time, modify the translations accordingly.
Signed-off-by: Erick Archer <erick.archer@gmx.com>
Reviewed-by: Hu Haowen <2023002089@link.tyut.edu.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Hu Haowen <2023002089@link.tyut.edu.cn>
Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
The core freezer logic has been modified by commit f5d39b0208
("freezer,sched: Rewrite core freezer logic"), so adjust the
documentation to reflect the new code. The main changes include:
- Drop references to PF_FROZEN and PF_FREEZER_SKIP
- Describe TASK_FROZEN, TASK_FREEZABLE and __TASK_FREEZABLE_UNSAFE
- Replace system_freezing_cnt with freezer_active
- Use a different example for the loop of a freezable kernel thread,
since the old code is gone gone
Signed-off-by: Kevin Hao <haokexin@gmail.com>
[ rjw: Subject and changelog edits, doc text adjustments ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
