[RFC,0/2] Begin reorganizing the arch documentation

  This two-patch series is a bare beginning of a project to reorganize the
Documentation directory somewhat; it's a toe in the water to see how many
sharks chomp at it.

The top-level Documentation/ directory, despite the efforts of the last few
years, is still a mess; there is too much stuff there, making it harder to
find anything.  We do not organize our source directories that way, and for
good reasons.

To bring the docs closer to the source organization, create a directory
Documentation/arch and move the x86 docs there, updating all of the
internal references that are broken by the move.  The appearance of the
rendered documentation does not change.  I've deliberately not changed
any overly long lines generated to keep the diff easy to read; that can
be fixed up later if warranted.

I can also break the second patch up if maintainers want to handle pieces
of it separately.

I think this move is worthwhile (for the other arches too) because it will
make our documentation better organized in a way that matches the source
and easier to navigate.  It will also make easier to experiment with tools
like intersphinx.

On the other hand, it *is* a fair amount of churn.  If it's more than
people can handle, I'll quietly back away and we'll muddle along as we have
been; this isn't something I'm going to dig in my heels over.

Also, it is worth noting that, while the rendered HTML looks the same,
links that went to Documentation/x86 (on https://kernel.org, say) will be
broken by this change.  We have never considered whether we care about
preserving external links to the rendered docs on kernel.org or not; I
don't think we should break them without thinking about it.

Thoughts?

Thanks,

jon


Jonathan Corbet (2):
  docs: create a top-level arch/ directory
  docs: move x86 documentation into Documentation/arch/

 Documentation/admin-guide/hw-vuln/mds.rst     |  2 +-
 .../admin-guide/hw-vuln/tsx_async_abort.rst   |  2 +-
 .../admin-guide/kernel-parameters.rst         |  6 ++--
 .../admin-guide/kernel-parameters.txt         |  8 +++---
 Documentation/admin-guide/ras.rst             |  2 +-
 Documentation/admin-guide/sysctl/kernel.rst   |  4 +--
 Documentation/arch.rst                        | 28 -------------------
 Documentation/arch/index.rst                  | 28 +++++++++++++++++++
 .../{ => arch}/x86/amd-memory-encryption.rst  |  0
 Documentation/{ => arch}/x86/amd_hsmp.rst     |  0
 Documentation/{ => arch}/x86/boot.rst         |  4 +--
 Documentation/{ => arch}/x86/booting-dt.rst   |  2 +-
 Documentation/{ => arch}/x86/buslock.rst      |  0
 Documentation/{ => arch}/x86/cpuinfo.rst      |  0
 Documentation/{ => arch}/x86/earlyprintk.rst  |  0
 Documentation/{ => arch}/x86/elf_auxvec.rst   |  0
 Documentation/{ => arch}/x86/entry_64.rst     |  0
 .../{ => arch}/x86/exception-tables.rst       |  0
 Documentation/{ => arch}/x86/features.rst     |  0
 Documentation/{ => arch}/x86/i386/IO-APIC.rst |  0
 Documentation/{ => arch}/x86/i386/index.rst   |  0
 Documentation/{ => arch}/x86/ifs.rst          |  0
 Documentation/{ => arch}/x86/index.rst        |  0
 Documentation/{ => arch}/x86/intel-hfi.rst    |  0
 Documentation/{ => arch}/x86/intel_txt.rst    |  0
 Documentation/{ => arch}/x86/iommu.rst        |  0
 .../{ => arch}/x86/kernel-stacks.rst          |  0
 Documentation/{ => arch}/x86/mds.rst          |  0
 Documentation/{ => arch}/x86/microcode.rst    |  0
 Documentation/{ => arch}/x86/mtrr.rst         |  2 +-
 Documentation/{ => arch}/x86/orc-unwinder.rst |  0
 Documentation/{ => arch}/x86/pat.rst          |  0
 Documentation/{ => arch}/x86/pti.rst          |  0
 Documentation/{ => arch}/x86/resctrl.rst      |  0
 Documentation/{ => arch}/x86/sgx.rst          |  0
 Documentation/{ => arch}/x86/sva.rst          |  0
 Documentation/{ => arch}/x86/tdx.rst          |  0
 Documentation/{ => arch}/x86/tlb.rst          |  0
 Documentation/{ => arch}/x86/topology.rst     |  0
 .../{ => arch}/x86/tsx_async_abort.rst        |  0
 .../{ => arch}/x86/usb-legacy-support.rst     |  0
 .../{ => arch}/x86/x86_64/5level-paging.rst   |  2 +-
 .../{ => arch}/x86/x86_64/boot-options.rst    |  4 +--
 .../x86/x86_64/cpu-hotplug-spec.rst           |  0
 .../x86/x86_64/fake-numa-for-cpusets.rst      |  2 +-
 Documentation/{ => arch}/x86/x86_64/fsgs.rst  |  0
 Documentation/{ => arch}/x86/x86_64/index.rst |  0
 .../{ => arch}/x86/x86_64/machinecheck.rst    |  0
 Documentation/{ => arch}/x86/x86_64/mm.rst    |  0
 Documentation/{ => arch}/x86/x86_64/uefi.rst  |  0
 Documentation/{ => arch}/x86/xstate.rst       |  0
 Documentation/{ => arch}/x86/zero-page.rst    |  0
 Documentation/core-api/asm-annotations.rst    |  2 +-
 Documentation/driver-api/device-io.rst        |  2 +-
 Documentation/index.rst                       |  2 +-
 Documentation/virt/kvm/api.rst                |  2 +-
 MAINTAINERS                                   | 12 ++++----
 arch/arm/Kconfig                              |  2 +-
 arch/x86/Kconfig                              | 10 +++----
 arch/x86/Kconfig.debug                        |  2 +-
 arch/x86/boot/header.S                        |  2 +-
 arch/x86/entry/entry_64.S                     |  2 +-
 arch/x86/include/asm/bootparam_utils.h        |  2 +-
 arch/x86/include/asm/page_64_types.h          |  2 +-
 arch/x86/include/asm/pgtable_64_types.h       |  2 +-
 arch/x86/kernel/cpu/microcode/amd.c           |  2 +-
 arch/x86/kernel/cpu/resctrl/monitor.c         |  2 +-
 arch/x86/kernel/cpu/sgx/sgx.h                 |  2 +-
 arch/x86/kernel/kexec-bzimage64.c             |  2 +-
 arch/x86/kernel/pci-dma.c                     |  2 +-
 arch/x86/mm/pat/set_memory.c                  |  2 +-
 arch/x86/mm/tlb.c                             |  2 +-
 arch/x86/platform/pvh/enlighten.c             |  2 +-
 drivers/vhost/vhost.c                         |  2 +-
 security/Kconfig                              |  2 +-
 tools/include/linux/err.h                     |  2 +-
 tools/objtool/Documentation/objtool.txt       |  2 +-
 77 files changed, 82 insertions(+), 82 deletions(-)
 delete mode 100644 Documentation/arch.rst
 create mode 100644 Documentation/arch/index.rst
 rename Documentation/{ => arch}/x86/amd-memory-encryption.rst (100%)
 rename Documentation/{ => arch}/x86/amd_hsmp.rst (100%)
 rename Documentation/{ => arch}/x86/boot.rst (99%)
 rename Documentation/{ => arch}/x86/booting-dt.rst (96%)
 rename Documentation/{ => arch}/x86/buslock.rst (100%)
 rename Documentation/{ => arch}/x86/cpuinfo.rst (100%)
 rename Documentation/{ => arch}/x86/earlyprintk.rst (100%)
 rename Documentation/{ => arch}/x86/elf_auxvec.rst (100%)
 rename Documentation/{ => arch}/x86/entry_64.rst (100%)
 rename Documentation/{ => arch}/x86/exception-tables.rst (100%)
 rename Documentation/{ => arch}/x86/features.rst (100%)
 rename Documentation/{ => arch}/x86/i386/IO-APIC.rst (100%)
 rename Documentation/{ => arch}/x86/i386/index.rst (100%)
 rename Documentation/{ => arch}/x86/ifs.rst (100%)
 rename Documentation/{ => arch}/x86/index.rst (100%)
 rename Documentation/{ => arch}/x86/intel-hfi.rst (100%)
 rename Documentation/{ => arch}/x86/intel_txt.rst (100%)
 rename Documentation/{ => arch}/x86/iommu.rst (100%)
 rename Documentation/{ => arch}/x86/kernel-stacks.rst (100%)
 rename Documentation/{ => arch}/x86/mds.rst (100%)
 rename Documentation/{ => arch}/x86/microcode.rst (100%)
 rename Documentation/{ => arch}/x86/mtrr.rst (99%)
 rename Documentation/{ => arch}/x86/orc-unwinder.rst (100%)
 rename Documentation/{ => arch}/x86/pat.rst (100%)
 rename Documentation/{ => arch}/x86/pti.rst (100%)
 rename Documentation/{ => arch}/x86/resctrl.rst (100%)
 rename Documentation/{ => arch}/x86/sgx.rst (100%)
 rename Documentation/{ => arch}/x86/sva.rst (100%)
 rename Documentation/{ => arch}/x86/tdx.rst (100%)
 rename Documentation/{ => arch}/x86/tlb.rst (100%)
 rename Documentation/{ => arch}/x86/topology.rst (100%)
 rename Documentation/{ => arch}/x86/tsx_async_abort.rst (100%)
 rename Documentation/{ => arch}/x86/usb-legacy-support.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/5level-paging.rst (98%)
 rename Documentation/{ => arch}/x86/x86_64/boot-options.rst (98%)
 rename Documentation/{ => arch}/x86/x86_64/cpu-hotplug-spec.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/fake-numa-for-cpusets.rst (97%)
 rename Documentation/{ => arch}/x86/x86_64/fsgs.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/index.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/machinecheck.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/mm.rst (100%)
 rename Documentation/{ => arch}/x86/x86_64/uefi.rst (100%)
 rename Documentation/{ => arch}/x86/xstate.rst (100%)
 rename Documentation/{ => arch}/x86/zero-page.rst (100%)
  

On 3/15/23 14:15, Jonathan Corbet wrote:
> On the other hand, it *is* a fair amount of churn.  If it's more than
> people can handle, I'll quietly back away and we'll muddle along as we have
> been; this isn't something I'm going to dig in my heels over.

I'm not fundamentally opposed to this.  It'll probably cost me a few
keystrokes in moments of confusion, but that's the price of progress. :)

Things in Documentation/ have also been mobile enough in recent years
that I tend to "find Documentation | grep something" rather than try to
remember the paths for things.  Adding an arch/ in there won't hurt
anything.

> Also, it is worth noting that, while the rendered HTML looks the same,
> links that went to Documentation/x86 (on https://kernel.org, say) will be
> broken by this change.  We have never considered whether we care about
> preserving external links to the rendered docs on kernel.org or not; I
> don't think we should break them without thinking about it.

I don't think this is a big deal.  Folks that are doing explicit versions:

	https://www.kernel.org/doc/html/v6.0/x86/

won't break and folks that are using "latest":

	https://www.kernel.org/doc/html/latest/x86/

are kinda already playing with fire.  I guess we could ask the
kernel.org admins to see how many 404's folks get after the docs get
moved.  They could _theoretically_ redirect users from the old to new URL:

	doc/html/latest/x86 => doc/html/latest/arch/x86

but I doubt it's worth it for this one little directory.
  

Dave Hansen <dave.hansen@intel.com> writes:

> On 3/15/23 14:15, Jonathan Corbet wrote:
>> On the other hand, it *is* a fair amount of churn.  If it's more than
>> people can handle, I'll quietly back away and we'll muddle along as we have
>> been; this isn't something I'm going to dig in my heels over.
>
> I'm not fundamentally opposed to this.  It'll probably cost me a few
> keystrokes in moments of confusion, but that's the price of progress. :)
>
> Things in Documentation/ have also been mobile enough in recent years
> that I tend to "find Documentation | grep something" rather than try to
> remember the paths for things.  Adding an arch/ in there won't hurt
> anything.

So, if I'm not going to get tarred and feathered for this, I'd like to
proceed, and am wondering what the best way is.  Patch 1 is a pure docs
change that won't affect anybody.  I could also apply #2 if I could get
an ack from the x86 community, but that is sure to create conflicts with
tip and get us all more cheery notes from Stephen Rothwell.

I could do the "fix up and send at the end of the merge window" trick
with it.  Or perhaps some of this should go via tip?  Suggestions
welcome.

Thanks,

jon
  

On 3/23/23 11:48, Jonathan Corbet wrote:
> I could do the "fix up and send at the end of the merge window" trick
> with it.

That would work for me.

>  Or perhaps some of this should go via tip?  Suggestions welcome.

Since we have so many branches, we'll still have to do the merges
between whatever branch carries the move and the actual doc-update branches.

The end-of-the-merge-window is nice for us maintainers because we can
ask the submitters to do any rebasing.
  

Dave Hansen <dave.hansen@intel.com> writes:

> On 3/23/23 11:48, Jonathan Corbet wrote:
>> I could do the "fix up and send at the end of the merge window" trick
>> with it.
>
> That would work for me.
>
>>  Or perhaps some of this should go via tip?  Suggestions welcome.
>
> Since we have so many branches, we'll still have to do the merges
> between whatever branch carries the move and the actual doc-update branches.
>
> The end-of-the-merge-window is nice for us maintainers because we can
> ask the submitters to do any rebasing.

Now that I look...the only thing in linux-next currently that conflicts
is the shadow-stack series; if that continues, it might not be necessary
to do anything special.

Thanks,

jon
  

Jonathan Corbet <corbet@lwn.net> writes:

> Now that I look...the only thing in linux-next currently that conflicts
> is the shadow-stack series; if that continues, it might not be necessary
> to do anything special.

There's an FPU patch now too.  Git seems to handle the conflicts *almost*
seamlessly, though.  So, FYI, I think I'll go ahead and drop this change
into docs-next, which will probably get us a cheery note from Stephen in
the near future.

(Stephen: the change is simply:

  mv Documentation/x86 Documentation/arch/x86

the only fix I had to do in my test merge was to add the new
shadow-stack document in the new directory).

Thanks,

jon
  

Hi Jon,

On Thu, 30 Mar 2023 12:52:40 -0600 Jonathan Corbet <corbet@lwn.net> wrote:
>
> Jonathan Corbet <corbet@lwn.net> writes:
> 
> > Now that I look...the only thing in linux-next currently that conflicts
> > is the shadow-stack series; if that continues, it might not be necessary
> > to do anything special.  
> 
> There's an FPU patch now too.  Git seems to handle the conflicts *almost*
> seamlessly, though.  So, FYI, I think I'll go ahead and drop this change
> into docs-next, which will probably get us a cheery note from Stephen in
> the near future.
> 
> (Stephen: the change is simply:
> 
>   mv Documentation/x86 Documentation/arch/x86
> 
> the only fix I had to do in my test merge was to add the new
> shadow-stack document in the new directory).

Thanks for the heads up.  Git moved the file and I just had to "git add"
it in the new place.