2020-05-01 15:40:02

by Mauro Carvalho Chehab

[permalink] [raw]
Subject: [PATCH 07/14] docs: add IRQ documentation at the core-api book

There are 4 IRQ documentation files under Documentation/*.txt.

Move them into a new directory (core-api/irq) and add a new
index file for it.

While here, use a title markup for the Debugging section of the
irq-domain.rst file.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
Documentation/admin-guide/kernel-per-CPU-kthreads.rst | 2 +-
Documentation/core-api/index.rst | 1 +
Documentation/{IRQ.txt => core-api/irq/concepts.rst} | 0
Documentation/core-api/irq/index.rst | 11 +++++++++++
.../irq/irq-affinity.rst} | 0
.../{IRQ-domain.txt => core-api/irq/irq-domain.rst} | 3 ++-
.../irq/irqflags-tracing.rst} | 0
Documentation/ia64/irq-redir.rst | 2 +-
Documentation/networking/scaling.rst | 4 ++--
Documentation/translations/zh_CN/IRQ.txt | 4 ++--
MAINTAINERS | 2 +-
12 files changed, 22 insertions(+), 9 deletions(-)
rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
create mode 100644 Documentation/core-api/irq/index.rst
rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)

diff --git a/Documentation/admin-guide/hw-vuln/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst
index f83212fae4d5..3eeeb488d955 100644
--- a/Documentation/admin-guide/hw-vuln/l1tf.rst
+++ b/Documentation/admin-guide/hw-vuln/l1tf.rst
@@ -268,7 +268,7 @@ Guest mitigation mechanisms
/proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
available at:

- https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
+ https://www.kernel.org/doc/Documentation/core-api/irq/irq-affinity.rst

.. _smt_control:

diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
index 21818aca4708..dc36aeb65d0a 100644
--- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
+++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
@@ -10,7 +10,7 @@ them to a "housekeeping" CPU dedicated to such work.
References
==========

-- Documentation/IRQ-affinity.txt: Binding interrupts to sets of CPUs.
+- Documentation/core-api/irq/irq-affinity.rst: Binding interrupts to sets of CPUs.

- Documentation/admin-guide/cgroup-v1: Using cgroups to bind tasks to sets of CPUs.

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index ab056b3626f4..49a885e83a55 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -52,6 +52,7 @@ How Linux keeps everything from happening at the same time. See

atomic_ops
refcount-vs-atomic
+ irq/index
local_ops
padata
../RCU/index
diff --git a/Documentation/IRQ.txt b/Documentation/core-api/irq/concepts.rst
similarity index 100%
rename from Documentation/IRQ.txt
rename to Documentation/core-api/irq/concepts.rst
diff --git a/Documentation/core-api/irq/index.rst b/Documentation/core-api/irq/index.rst
new file mode 100644
index 000000000000..0d65d11e5420
--- /dev/null
+++ b/Documentation/core-api/irq/index.rst
@@ -0,0 +1,11 @@
+====
+IRQs
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ concepts
+ irq-affinity
+ irq-domain
+ irqflags-tracing
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/core-api/irq/irq-affinity.rst
similarity index 100%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/core-api/irq/irq-affinity.rst
diff --git a/Documentation/IRQ-domain.txt b/Documentation/core-api/irq/irq-domain.rst
similarity index 99%
rename from Documentation/IRQ-domain.txt
rename to Documentation/core-api/irq/irq-domain.rst
index 507775cce753..096db12f32d5 100644
--- a/Documentation/IRQ-domain.txt
+++ b/Documentation/core-api/irq/irq-domain.rst
@@ -263,7 +263,8 @@ needs to:
Hierarchy irq_domain is in no way x86 specific, and is heavily used to
support other architectures, such as ARM, ARM64 etc.

-=== Debugging ===
+Debugging
+=========

Most of the internals of the IRQ subsystem are exposed in debugfs by
turning CONFIG_GENERIC_IRQ_DEBUGFS on.
diff --git a/Documentation/irqflags-tracing.txt b/Documentation/core-api/irq/irqflags-tracing.rst
similarity index 100%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/core-api/irq/irqflags-tracing.rst
diff --git a/Documentation/ia64/irq-redir.rst b/Documentation/ia64/irq-redir.rst
index 39bf94484a15..6bbbbe4f73ef 100644
--- a/Documentation/ia64/irq-redir.rst
+++ b/Documentation/ia64/irq-redir.rst
@@ -7,7 +7,7 @@ IRQ affinity on IA64 platforms

By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
controlled. The behavior on IA64 platforms is slightly different from
-that described in Documentation/IRQ-affinity.txt for i386 systems.
+that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems.

Because of the usage of SAPIC mode and physical destination mode the
IRQ target is one particular CPU and cannot be a mask of several
diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst
index f78d7bf27ff5..8f0347b9fb3d 100644
--- a/Documentation/networking/scaling.rst
+++ b/Documentation/networking/scaling.rst
@@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
an IRQ may be handled on any CPU. Because a non-negligible part of packet
processing takes place in receive interrupt handling, it is advantageous
to spread receive interrupts between CPUs. To manually adjust the IRQ
-affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
+affinity of each interrupt see Documentation/core-api/irq/irq-affinity.rst. Some systems
will be running irqbalance, a daemon that dynamically optimizes IRQ
assignments and as a result may override any manual settings.

@@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::

This file implements a bitmap of CPUs. RPS is disabled when it is zero
(the default), in which case packets are processed on the interrupting
-CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
+CPU. Documentation/core-api/irq/irq-affinity.rst explains how CPUs are assigned to
the bitmap.


diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
index 956026d5cf82..9aec8dca4fcf 100644
--- a/Documentation/translations/zh_CN/IRQ.txt
+++ b/Documentation/translations/zh_CN/IRQ.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/IRQ.txt
+Chinese translated version of Documentation/core-api/irq/index.rst

If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
Maintainer: Eric W. Biederman <[email protected]>
Chinese maintainer: Fu Wei <[email protected]>
---------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
+Documentation/core-api/irq/index.rst 的中文翻译

如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/MAINTAINERS b/MAINTAINERS
index a1d7af532950..6eb3d85a646f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8974,7 +8974,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
M: Marc Zyngier <[email protected]>
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
-F: Documentation/IRQ-domain.txt
+F: Documentation/core-api/irq/irq-domain.rst
F: include/linux/irqdomain.h
F: kernel/irq/irqdomain.c
F: kernel/irq/msi.c
--
2.25.4


2020-05-02 07:45:07

by Mike Rapoport

[permalink] [raw]
Subject: Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

Hello Mauro,

On Fri, May 01, 2020 at 05:37:51PM +0200, Mauro Carvalho Chehab wrote:
> There are 4 IRQ documentation files under Documentation/*.txt.
>
> Move them into a new directory (core-api/irq) and add a new
> index file for it.

Just curious, why IRQ docs got their subdirectory and DMA didn't :)

> While here, use a title markup for the Debugging section of the
> irq-domain.rst file.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Documentation/admin-guide/hw-vuln/l1tf.rst | 2 +-
> Documentation/admin-guide/kernel-per-CPU-kthreads.rst | 2 +-
> Documentation/core-api/index.rst | 1 +
> Documentation/{IRQ.txt => core-api/irq/concepts.rst} | 0
> Documentation/core-api/irq/index.rst | 11 +++++++++++
> .../irq/irq-affinity.rst} | 0
> .../{IRQ-domain.txt => core-api/irq/irq-domain.rst} | 3 ++-
> .../irq/irqflags-tracing.rst} | 0
> Documentation/ia64/irq-redir.rst | 2 +-
> Documentation/networking/scaling.rst | 4 ++--
> Documentation/translations/zh_CN/IRQ.txt | 4 ++--
> MAINTAINERS | 2 +-
> 12 files changed, 22 insertions(+), 9 deletions(-)
> rename Documentation/{IRQ.txt => core-api/irq/concepts.rst} (100%)
> create mode 100644 Documentation/core-api/irq/index.rst
> rename Documentation/{IRQ-affinity.txt => core-api/irq/irq-affinity.rst} (100%)
> rename Documentation/{IRQ-domain.txt => core-api/irq/irq-domain.rst} (99%)
> rename Documentation/{irqflags-tracing.txt => core-api/irq/irqflags-tracing.rst} (100%)
>
> diff --git a/Documentation/admin-guide/hw-vuln/l1tf.rst b/Documentation/admin-guide/hw-vuln/l1tf.rst
> index f83212fae4d5..3eeeb488d955 100644
> --- a/Documentation/admin-guide/hw-vuln/l1tf.rst
> +++ b/Documentation/admin-guide/hw-vuln/l1tf.rst
> @@ -268,7 +268,7 @@ Guest mitigation mechanisms
> /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
> available at:
>
> - https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
> + https://www.kernel.org/doc/Documentation/core-api/irq/irq-affinity.rst
>
> .. _smt_control:
>
> diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
> index 21818aca4708..dc36aeb65d0a 100644
> --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
> +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
> @@ -10,7 +10,7 @@ them to a "housekeeping" CPU dedicated to such work.
> References
> ==========
>
> -- Documentation/IRQ-affinity.txt: Binding interrupts to sets of CPUs.
> +- Documentation/core-api/irq/irq-affinity.rst: Binding interrupts to sets of CPUs.
>
> - Documentation/admin-guide/cgroup-v1: Using cgroups to bind tasks to sets of CPUs.
>
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index ab056b3626f4..49a885e83a55 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -52,6 +52,7 @@ How Linux keeps everything from happening at the same time. See
>
> atomic_ops
> refcount-vs-atomic
> + irq/index
> local_ops
> padata
> ../RCU/index
> diff --git a/Documentation/IRQ.txt b/Documentation/core-api/irq/concepts.rst
> similarity index 100%
> rename from Documentation/IRQ.txt
> rename to Documentation/core-api/irq/concepts.rst
> diff --git a/Documentation/core-api/irq/index.rst b/Documentation/core-api/irq/index.rst
> new file mode 100644
> index 000000000000..0d65d11e5420
> --- /dev/null
> +++ b/Documentation/core-api/irq/index.rst
> @@ -0,0 +1,11 @@
> +====
> +IRQs
> +====
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + concepts
> + irq-affinity
> + irq-domain
> + irqflags-tracing
> diff --git a/Documentation/IRQ-affinity.txt b/Documentation/core-api/irq/irq-affinity.rst
> similarity index 100%
> rename from Documentation/IRQ-affinity.txt
> rename to Documentation/core-api/irq/irq-affinity.rst
> diff --git a/Documentation/IRQ-domain.txt b/Documentation/core-api/irq/irq-domain.rst
> similarity index 99%
> rename from Documentation/IRQ-domain.txt
> rename to Documentation/core-api/irq/irq-domain.rst
> index 507775cce753..096db12f32d5 100644
> --- a/Documentation/IRQ-domain.txt
> +++ b/Documentation/core-api/irq/irq-domain.rst
> @@ -263,7 +263,8 @@ needs to:
> Hierarchy irq_domain is in no way x86 specific, and is heavily used to
> support other architectures, such as ARM, ARM64 etc.
>
> -=== Debugging ===
> +Debugging
> +=========
>
> Most of the internals of the IRQ subsystem are exposed in debugfs by
> turning CONFIG_GENERIC_IRQ_DEBUGFS on.
> diff --git a/Documentation/irqflags-tracing.txt b/Documentation/core-api/irq/irqflags-tracing.rst
> similarity index 100%
> rename from Documentation/irqflags-tracing.txt
> rename to Documentation/core-api/irq/irqflags-tracing.rst
> diff --git a/Documentation/ia64/irq-redir.rst b/Documentation/ia64/irq-redir.rst
> index 39bf94484a15..6bbbbe4f73ef 100644
> --- a/Documentation/ia64/irq-redir.rst
> +++ b/Documentation/ia64/irq-redir.rst
> @@ -7,7 +7,7 @@ IRQ affinity on IA64 platforms
>
> By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
> controlled. The behavior on IA64 platforms is slightly different from
> -that described in Documentation/IRQ-affinity.txt for i386 systems.
> +that described in Documentation/core-api/irq/irq-affinity.rst for i386 systems.
>
> Because of the usage of SAPIC mode and physical destination mode the
> IRQ target is one particular CPU and cannot be a mask of several
> diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst
> index f78d7bf27ff5..8f0347b9fb3d 100644
> --- a/Documentation/networking/scaling.rst
> +++ b/Documentation/networking/scaling.rst
> @@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
> an IRQ may be handled on any CPU. Because a non-negligible part of packet
> processing takes place in receive interrupt handling, it is advantageous
> to spread receive interrupts between CPUs. To manually adjust the IRQ
> -affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
> +affinity of each interrupt see Documentation/core-api/irq/irq-affinity.rst. Some systems
> will be running irqbalance, a daemon that dynamically optimizes IRQ
> assignments and as a result may override any manual settings.
>
> @@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::
>
> This file implements a bitmap of CPUs. RPS is disabled when it is zero
> (the default), in which case packets are processed on the interrupting
> -CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
> +CPU. Documentation/core-api/irq/irq-affinity.rst explains how CPUs are assigned to
> the bitmap.
>
>
> diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
> index 956026d5cf82..9aec8dca4fcf 100644
> --- a/Documentation/translations/zh_CN/IRQ.txt
> +++ b/Documentation/translations/zh_CN/IRQ.txt
> @@ -1,4 +1,4 @@
> -Chinese translated version of Documentation/IRQ.txt
> +Chinese translated version of Documentation/core-api/irq/index.rst
>
> If you have any comment or update to the content, please contact the
> original document maintainer directly. However, if you have a problem
> @@ -9,7 +9,7 @@ or if there is a problem with the translation.
> Maintainer: Eric W. Biederman <[email protected]>
> Chinese maintainer: Fu Wei <[email protected]>
> ---------------------------------------------------------------------
> -Documentation/IRQ.txt 的中文翻译
> +Documentation/core-api/irq/index.rst 的中文翻译
>
> 如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
> 交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
> diff --git a/MAINTAINERS b/MAINTAINERS
> index a1d7af532950..6eb3d85a646f 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8974,7 +8974,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
> M: Marc Zyngier <[email protected]>
> S: Maintained
> T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
> -F: Documentation/IRQ-domain.txt
> +F: Documentation/core-api/irq/irq-domain.rst
> F: include/linux/irqdomain.h
> F: kernel/irq/irqdomain.c
> F: kernel/irq/msi.c
> --
> 2.25.4
>

--
Sincerely yours,
Mike.

2020-05-02 10:18:31

by Mauro Carvalho Chehab

[permalink] [raw]
Subject: Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

Em Sat, 2 May 2020 10:41:33 +0300
Mike Rapoport <[email protected]> escreveu:

> Hello Mauro,
>
> On Fri, May 01, 2020 at 05:37:51PM +0200, Mauro Carvalho Chehab wrote:
> > There are 4 IRQ documentation files under Documentation/*.txt.
> >
> > Move them into a new directory (core-api/irq) and add a new
> > index file for it.
>
> Just curious, why IRQ docs got their subdirectory and DMA didn't :)

Heh, you got me... :-)

The rationale I used is that DMA fits nicely being close to other
memory related documents. As those currently don't have a subdir,
I opted to not create a DMA-specific dir. I admit that his is a
weak reason. I wouldn't mind placing them on a separate subdir,
if you think it would be worth.

Thanks,
Mauro

2020-05-02 11:24:11

by Mike Rapoport

[permalink] [raw]
Subject: Re: [PATCH 07/14] docs: add IRQ documentation at the core-api book

On Sat, May 02, 2020 at 12:16:41PM +0200, Mauro Carvalho Chehab wrote:
> Em Sat, 2 May 2020 10:41:33 +0300
> Mike Rapoport <[email protected]> escreveu:
>
> > Hello Mauro,
> >
> > On Fri, May 01, 2020 at 05:37:51PM +0200, Mauro Carvalho Chehab wrote:
> > > There are 4 IRQ documentation files under Documentation/*.txt.
> > >
> > > Move them into a new directory (core-api/irq) and add a new
> > > index file for it.
> >
> > Just curious, why IRQ docs got their subdirectory and DMA didn't :)
>
> Heh, you got me... :-)
>
> The rationale I used is that DMA fits nicely being close to other
> memory related documents. As those currently don't have a subdir,
> I opted to not create a DMA-specific dir. I admit that his is a
> weak reason. I wouldn't mind placing them on a separate subdir,
> if you think it would be worth.

I'm Ok without a dir as well :)

> Thanks,
> Mauro

--
Sincerely yours,
Mike.