Unverified Commit 9f6bdb0a authored by Mark Brown's avatar Mark Brown
Browse files

ASoC: doc: dapm: various improvements 



Merge series from Luca Ceresoli <luca.ceresoli@bootlin.com>:

This series applies various improvements to the DAPM documentation: a
rewrite of a few sections for clarity, style improvements and typo fixes.

Signed-off-by: default avatarLuca Ceresoli <luca.ceresoli@bootlin.com>
---
Changes in v2:
- avoid wrapping in patch 3 as suggested by Alex
- Link to v1: https://lore.kernel.org/r/20240416-dapm-docs-v1-0-a818d2819bf6@bootlin.com

---
Luca Ceresoli (12):
      ASoC: doc: dapm: fix typos
      ASoC: doc: dapm: fix struct name
      ASoC: doc: dapm: minor rewording
      ASoC: doc: dapm: remove dash after colon
      ASoC: doc: dapm: clarify it's an internal API
      ASoC: doc: dapm: replace "map" with "graph"
      ASoC: doc: dapm: extend initial descrption
      ASoC: doc: dapm: describe how widgets and routes are registered
      ASoC: doc: dapm: fix and improve section "Registering DAPM controls"
      ASoC: doc: dapm: improve section "Codec/DSP Widget Interconnections"
      ASoC: doc: dapm: update section "DAPM Widget Events"
      ASoC: doc: dapm: update event types

 Documentation/sound/soc/dapm-graph.svg | 375 +++++++++++++++++++++++++++++++++
 Documentation/sound/soc/dapm.rst       | 174 ++++++++++-----
 2 files changed, 492 insertions(+), 57 deletions(-)
---
base-commit: c942a0cd
change-id: 20240315-dapm-docs-79bd51f267db

Best regards,
--
Luca Ceresoli <luca.ceresoli@bootlin.com>
parents 395f23e9 4155a82f

.mailmap

+15 −1
Original line number Diff line number Diff line
@@ -38,6 +38,16 @@ Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com> 
Alexei Starovoitov <ast@kernel.org> <ast@fb.com>

Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>

Alexey Makhalov <alexey.amakhalov@broadcom.com> <amakhalov@vmware.com>

Alex Elder <elder@kernel.org>

Alex Elder <elder@kernel.org> <aelder@sgi.com>

Alex Elder <elder@kernel.org> <alex.elder@linaro.org>

Alex Elder <elder@kernel.org> <alex.elder@linary.org>

Alex Elder <elder@kernel.org> <elder@dreamhost.com>

Alex Elder <elder@kernel.org> <elder@dreawmhost.com>

Alex Elder <elder@kernel.org> <elder@ieee.org>

Alex Elder <elder@kernel.org> <elder@inktank.com>

Alex Elder <elder@kernel.org> <elder@linaro.org>

Alex Elder <elder@kernel.org> <elder@newdream.net>

Alex Hung <alexhung@gmail.com> <alex.hung@canonical.com>

Alex Shi <alexs@kernel.org> <alex.shi@intel.com>

Alex Shi <alexs@kernel.org> <alex.shi@linaro.org>
@@ -98,6 +108,8 @@ Ben Widawsky <bwidawsk@kernel.org> <ben@bwidawsk.net> 
Ben Widawsky <bwidawsk@kernel.org> <ben.widawsky@intel.com>

Ben Widawsky <bwidawsk@kernel.org> <benjamin.widawsky@intel.com>

Benjamin Poirier <benjamin.poirier@gmail.com> <bpoirier@suse.de>

Benjamin Tissoires <bentiss@kernel.org> <benjamin.tissoires@gmail.com>

Benjamin Tissoires <bentiss@kernel.org> <benjamin.tissoires@redhat.com>

Bjorn Andersson <andersson@kernel.org> <bjorn@kryo.se>

Bjorn Andersson <andersson@kernel.org> <bjorn.andersson@linaro.org>

Bjorn Andersson <andersson@kernel.org> <bjorn.andersson@sonymobile.com>
@@ -446,7 +458,8 @@ Mythri P K <mythripk@ti.com> 
Nadav Amit <nadav.amit@gmail.com> <namit@vmware.com>

Nadav Amit <nadav.amit@gmail.com> <namit@cs.technion.ac.il>

Nadia Yvette Chambers <nyc@holomorphy.com> William Lee Irwin III <wli@holomorphy.com>

Naoya Horiguchi <naoya.horiguchi@nec.com> <n-horiguchi@ah.jp.nec.com>

Naoya Horiguchi <nao.horiguchi@gmail.com> <n-horiguchi@ah.jp.nec.com>

Naoya Horiguchi <nao.horiguchi@gmail.com> <naoya.horiguchi@nec.com>

Nathan Chancellor <nathan@kernel.org> <natechancellor@gmail.com>

Neeraj Upadhyay <quic_neeraju@quicinc.com> <neeraju@codeaurora.org>

Neil Armstrong <neil.armstrong@linaro.org> <narmstrong@baylibre.com>
@@ -524,6 +537,7 @@ Rémi Denis-Courmont <rdenis@simphalempin.com> 
Ricardo Ribalda <ribalda@kernel.org> <ricardo@ribalda.com>

Ricardo Ribalda <ribalda@kernel.org> Ricardo Ribalda Delgado <ribalda@kernel.org>

Ricardo Ribalda <ribalda@kernel.org> <ricardo.ribalda@gmail.com>

Richard Genoud <richard.genoud@bootlin.com> <richard.genoud@gmail.com>

Richard Leitner <richard.leitner@linux.dev> <dev@g0hl1n.net>

Richard Leitner <richard.leitner@linux.dev> <me@g0hl1n.net>

Richard Leitner <richard.leitner@linux.dev> <richard.leitner@skidata.com>

CREDITS

+4 −0
Original line number Diff line number Diff line
@@ -3146,6 +3146,10 @@ S: Triftstra=DFe 55 
S: 13353 Berlin

S: Germany



N: Gustavo Pimental

E: gustavo.pimentel@synopsys.com

D: PCI driver for Synopsys DesignWare



N: Emanuel Pirker

E: epirker@edu.uni-klu.ac.at

D: AIC5800 IEEE 1394, RAW I/O on 1394

Documentation/admin-guide/hw-vuln/spectre.rst

+38 −6
Original line number Diff line number Diff line
@@ -138,11 +138,10 @@ associated with the source address of the indirect branch. Specifically, 
the BHB might be shared across privilege levels even in the presence of

Enhanced IBRS.



Currently the only known real-world BHB attack vector is via

unprivileged eBPF. Therefore, it's highly recommended to not enable

unprivileged eBPF, especially when eIBRS is used (without retpolines).

For a full mitigation against BHB attacks, it's recommended to use

retpolines (or eIBRS combined with retpolines).

Previously the only known real-world BHB attack vector was via unprivileged

eBPF. Further research has found attacks that don't require unprivileged eBPF.

For a full mitigation against BHB attacks it is recommended to set BHI_DIS_S or

use the BHB clearing sequence.



Attack scenarios

----------------
@@ -430,6 +429,23 @@ The possible values in this file are: 
  'PBRSB-eIBRS: Not affected'  CPU is not affected by PBRSB

  ===========================  =======================================================



  - Branch History Injection (BHI) protection status:



.. list-table::



 * - BHI: Not affected

   - System is not affected

 * - BHI: Retpoline

   - System is protected by retpoline

 * - BHI: BHI_DIS_S

   - System is protected by BHI_DIS_S

 * - BHI: SW loop, KVM SW loop

   - System is protected by software clearing sequence

 * - BHI: Vulnerable

   - System is vulnerable to BHI

 * - BHI: Vulnerable, KVM: SW loop

   - System is vulnerable; KVM is protected by software clearing sequence



Full mitigation might require a microcode update from the CPU

vendor. When the necessary microcode is not available, the kernel will

report vulnerability.
@@ -484,7 +500,11 @@ Spectre variant 2 


   Systems which support enhanced IBRS (eIBRS) enable IBRS protection once at

   boot, by setting the IBRS bit, and they're automatically protected against

   Spectre v2 variant attacks.

   some Spectre v2 variant attacks. The BHB can still influence the choice of

   indirect branch predictor entry, and although branch predictor entries are

   isolated between modes when eIBRS is enabled, the BHB itself is not isolated

   between modes. Systems which support BHI_DIS_S will set it to protect against

   BHI attacks.



   On Intel's enhanced IBRS systems, this includes cross-thread branch target

   injections on SMT systems (STIBP). In other words, Intel eIBRS enables
@@ -638,6 +658,18 @@ kernel command line. 
		spectre_v2=off. Spectre variant 1 mitigations

		cannot be disabled.



	spectre_bhi=



		[X86] Control mitigation of Branch History Injection

		(BHI) vulnerability.  This setting affects the deployment

		of the HW BHI control and the SW BHB clearing sequence.



		on

			(default) Enable the HW or SW mitigation as

			needed.

		off

			Disable the mitigation.



For spectre_v2_user see Documentation/admin-guide/kernel-parameters.txt



Mitigation selection guide

Documentation/admin-guide/kernel-parameters.txt

+10 −0
Original line number Diff line number Diff line
@@ -3444,6 +3444,7 @@ 
					       retbleed=off [X86]

					       spec_rstack_overflow=off [X86]

					       spec_store_bypass_disable=off [X86,PPC]

					       spectre_bhi=off [X86]

					       spectre_v2_user=off [X86]

					       srbds=off [X86,INTEL]

					       ssbd=force-off [ARM64]
@@ -6063,6 +6064,15 @@ 
	sonypi.*=	[HW] Sony Programmable I/O Control Device driver

			See Documentation/admin-guide/laptops/sonypi.rst



	spectre_bhi=	[X86] Control mitigation of Branch History Injection

			(BHI) vulnerability.  This setting affects the

			deployment of the HW BHI control and the SW BHB

			clearing sequence.



			on   - (default) Enable the HW or SW mitigation

			       as needed.

			off  - Disable the mitigation.



	spectre_v2=	[X86,EARLY] Control mitigation of Spectre variant 2

			(indirect branch speculation) vulnerability.

			The default operation protects the kernel from

Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst

+417 −180

File changed.

Preview size limit exceeded, changes collapsed.