This one file should not really be in the top-level documentation
directory. core-api/ may not be a perfect fit but seems to be best, so
move it there. Adjust a couple of internal document references to make
them location-independent.
Cc: Jiri Slaby <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/{ => core-api}/asm-annotations.rst | 7 ++++---
Documentation/core-api/index.rst | 1 +
Documentation/index.rst | 8 --------
3 files changed, 5 insertions(+), 11 deletions(-)
rename Documentation/{ => core-api}/asm-annotations.rst (97%)
diff --git a/Documentation/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst
similarity index 97%
rename from Documentation/asm-annotations.rst
rename to Documentation/core-api/asm-annotations.rst
index a64f2ca469d4..bc514ed59887 100644
--- a/Documentation/asm-annotations.rst
+++ b/Documentation/core-api/asm-annotations.rst
@@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful
information. In particular, on properly annotated objects, ``objtool`` can be
run to check and fix the object if needed. Currently, ``objtool`` can report
missing frame pointer setup/destruction in functions. It can also
-automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
+automatically generate annotations for the ORC unwinder
+(Documentation/x86/orc-unwinder.rst)
for most code. Both of these are especially important to support reliable
-stack traces which are in turn necessary for :doc:`Kernel live patching
-<livepatch/livepatch>`.
+stack traces which are in turn necessary for kernel live patching
+(Documentation/livepatch/livepatch.rst).
Caveat and Discussion
---------------------
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dc95df462eea..f5d8e3779fe8 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -23,6 +23,7 @@ it.
printk-formats
printk-index
symbol-namespaces
+ asm-annotations
Data structures and low-level utilities
=======================================
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 7f63f70bb8d6..6d01c2e38573 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -89,14 +89,6 @@ platform firmwares.
devicetree/index
-Architecture-agnostic documentation
------------------------------------
-
-.. toctree::
- :maxdepth: 1
-
- asm-annotations
-
Architecture-specific documentation
-----------------------------------
--
2.37.2
On Thu, Sep 22, 2022 at 02:41:36PM -0600, Jonathan Corbet wrote:
> @@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful
> information. In particular, on properly annotated objects, ``objtool`` can be
> run to check and fix the object if needed. Currently, ``objtool`` can report
> missing frame pointer setup/destruction in functions. It can also
> -automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
> +automatically generate annotations for the ORC unwinder
> +(Documentation/x86/orc-unwinder.rst)
> for most code. Both of these are especially important to support reliable
> -stack traces which are in turn necessary for :doc:`Kernel live patching
> -<livepatch/livepatch>`.
> +stack traces which are in turn necessary for kernel live patching
> +(Documentation/livepatch/livepatch.rst).
Hi jon,
I think Sphinx internal references are better fit for these links:
---- >8 ----
diff --git a/Documentation/core-api/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst
index bc514ed598870c..d3071f131dad73 100644
--- a/Documentation/core-api/asm-annotations.rst
+++ b/Documentation/core-api/asm-annotations.rst
@@ -43,11 +43,10 @@ annotated objects like this, tools can be run on them to generate more useful
information. In particular, on properly annotated objects, ``objtool`` can be
run to check and fix the object if needed. Currently, ``objtool`` can report
missing frame pointer setup/destruction in functions. It can also
-automatically generate annotations for the ORC unwinder
-(Documentation/x86/orc-unwinder.rst)
+automatically generate annotations for the :ref:`ORC unwinder <orc-unwinder>`
for most code. Both of these are especially important to support reliable
-stack traces which are in turn necessary for kernel live patching
-(Documentation/livepatch/livepatch.rst).
+stack traces which are in turn necessary for :ref:`kernel live patching
+<kernel-livepatch>`.
Caveat and Discussion
---------------------
diff --git a/Documentation/livepatch/livepatch.rst b/Documentation/livepatch/livepatch.rst
index 68e3651e8af925..ebb8b05a9b0d3e 100644
--- a/Documentation/livepatch/livepatch.rst
+++ b/Documentation/livepatch/livepatch.rst
@@ -1,3 +1,5 @@
+.. _kernel-livepatch:
+
=========
Livepatch
=========
diff --git a/Documentation/x86/orc-unwinder.rst b/Documentation/x86/orc-unwinder.rst
index cdb257015bd9e8..b26368c3892d3d 100644
--- a/Documentation/x86/orc-unwinder.rst
+++ b/Documentation/x86/orc-unwinder.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
+.. _orc-unwinder:
+
============
ORC unwinder
============
Thanks.
--
An old man doll... just what I always wanted! - Clara
Hi Jonathan,
I love your patch! Perhaps something to improve:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on lwn-2.6/docs-next kees/for-next/pstore linus/master v6.0-rc6 next-20220923]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Jonathan-Corbet/docs-promote-the-title-of-process-index-html/20220923-054245
base: git://git.lwn.net/linux.git docs-next
reproduce:
# https://github.com/intel-lab-lkp/linux/commit/e145630c472c664fce38db475f55f78dca7038fb
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Jonathan-Corbet/docs-promote-the-title-of-process-index-html/20220923-054245
git checkout e145630c472c664fce38db475f55f78dca7038fb
make menuconfig
# enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
make htmldocs
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <[email protected]>
All warnings (new ones prefixed by >>):
>> Warning: scripts/checkpatch.pl references a file that doesn't exist: Documentation/asm-annotations.rst
--
0-DAY CI Kernel Test Service
https://01.org/lkp
On Thu, Sep 22, 2022 at 02:41:36PM -0600, Jonathan Corbet wrote:
> This one file should not really be in the top-level documentation
> directory. core-api/ may not be a perfect fit but seems to be best, so
> move it there. Adjust a couple of internal document references to make
> them location-independent.
>
> Cc: Jiri Slaby <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
Reviewed-by: David Vernet <[email protected]>
Certainly seems better for it to live under Core utilities compared to
where it is now.
On Thu, Sep 22, 2022 at 02:41:36PM -0600, Jonathan Corbet wrote:
> diff --git a/Documentation/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst
> similarity index 97%
> rename from Documentation/asm-annotations.rst
> rename to Documentation/core-api/asm-annotations.rst
> index a64f2ca469d4..bc514ed59887 100644
> --- a/Documentation/asm-annotations.rst
> +++ b/Documentation/core-api/asm-annotations.rst
> @@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful
> information. In particular, on properly annotated objects, ``objtool`` can be
> run to check and fix the object if needed. Currently, ``objtool`` can report
> missing frame pointer setup/destruction in functions. It can also
> -automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
> +automatically generate annotations for the ORC unwinder
> +(Documentation/x86/orc-unwinder.rst)
> for most code. Both of these are especially important to support reliable
> -stack traces which are in turn necessary for :doc:`Kernel live patching
> -<livepatch/livepatch>`.
> +stack traces which are in turn necessary for kernel live patching
> +(Documentation/livepatch/livepatch.rst).
>
Hi jon,
kernel test robot reported non-existent reference ([1]), so I have
applied the fixup:
---- >8 ----
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 79e759aac543b8..812af52f97d2cf 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3751,7 +3751,7 @@ sub process {
if ($realfile =~ /\.S$/ &&
$line =~ /^\+\s*(?:[A-Z]+_)?SYM_[A-Z]+_(?:START|END)(?:_[A-Z_]+)?\s*\(\s*\.L/) {
WARN("AVOID_L_PREFIX",
- "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/asm-annotations.rst\n" . $herecurr);
+ "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
}
# check we are in a valid source file C or perl if not then ignore this hunk
Thanks.
[1]: https://lore.kernel.org/linux-doc/[email protected]/
--
An old man doll... just what I always wanted! - Clara
Bagas Sanjaya <[email protected]> writes:
> kernel test robot reported non-existent reference ([1]), so I have
> applied the fixup:
Yeah, I get those emails too; already fixed in my tree. I was clearly
in too much of a hurry to get that posting out...
Thanks,
jon