docs: move superh documentation under Documentation/arch/
authorJonathan Corbet <corbet@lwn.net>
Thu, 23 Mar 2023 20:17:42 +0000 (14:17 -0600)
committerJonathan Corbet <corbet@lwn.net>
Thu, 30 Mar 2023 19:00:35 +0000 (13:00 -0600)
Architecture-specific documentation is being moved into Documentation/arch/
as a way of cleaning up the top-level documentation directory and making
the docs hierarchy more closely match the source hierarchy.  Move
Documentation/sh into arch/ and fix all in-tree references.

Cc: Yoshinori Sato <ysato@users.sourceforge.jp>
Cc: Rich Felker <dalias@libc.org>
Cc: John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
13 files changed:
Documentation/arch/index.rst
Documentation/arch/sh/booting.rst [new file with mode: 0644]
Documentation/arch/sh/features.rst [new file with mode: 0644]
Documentation/arch/sh/index.rst [new file with mode: 0644]
Documentation/arch/sh/new-machine.rst [new file with mode: 0644]
Documentation/arch/sh/register-banks.rst [new file with mode: 0644]
Documentation/sh/booting.rst [deleted file]
Documentation/sh/features.rst [deleted file]
Documentation/sh/index.rst [deleted file]
Documentation/sh/new-machine.rst [deleted file]
Documentation/sh/register-banks.rst [deleted file]
MAINTAINERS
arch/sh/Kconfig.cpu

index 8ec614488bd24e8934488139a7a3deff8256ea28..792f58e30f253fe074ea886bb8886380232e303f 100644 (file)
@@ -22,7 +22,7 @@ implementation.
    ../powerpc/index
    ../riscv/index
    ../s390/index
-   ../sh/index
+   sh/index
    sparc/index
    x86/index
    xtensa/index
diff --git a/Documentation/arch/sh/booting.rst b/Documentation/arch/sh/booting.rst
new file mode 100644 (file)
index 0000000..d851c49
--- /dev/null
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+DeviceTree Booting
+------------------
+
+  Device-tree compatible SH bootloaders are expected to provide the physical
+  address of the device tree blob in r4. Since legacy bootloaders did not
+  guarantee any particular initial register state, kernels built to
+  inter-operate with old bootloaders must either use a builtin DTB or
+  select a legacy board option (something other than CONFIG_SH_DEVICE_TREE)
+  that does not use device tree. Support for the latter is being phased out
+  in favor of device tree.
diff --git a/Documentation/arch/sh/features.rst b/Documentation/arch/sh/features.rst
new file mode 100644 (file)
index 0000000..f722af3
--- /dev/null
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features sh
diff --git a/Documentation/arch/sh/index.rst b/Documentation/arch/sh/index.rst
new file mode 100644 (file)
index 0000000..c647767
--- /dev/null
@@ -0,0 +1,56 @@
+=======================
+SuperH Interfaces Guide
+=======================
+
+:Author: Paul Mundt
+
+.. toctree::
+    :maxdepth: 1
+
+    booting
+    new-machine
+    register-banks
+
+    features
+
+Memory Management
+=================
+
+SH-4
+----
+
+Store Queue API
+~~~~~~~~~~~~~~~
+
+.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
+   :export:
+
+Machine Specific Interfaces
+===========================
+
+mach-dreamcast
+--------------
+
+.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
+   :internal:
+
+mach-x3proto
+------------
+
+.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
+   :export:
+
+Busses
+======
+
+SuperHyway
+----------
+
+.. kernel-doc:: drivers/sh/superhyway/superhyway.c
+   :export:
+
+Maple
+-----
+
+.. kernel-doc:: drivers/sh/maple/maple.c
+   :export:
diff --git a/Documentation/arch/sh/new-machine.rst b/Documentation/arch/sh/new-machine.rst
new file mode 100644 (file)
index 0000000..e501c52
--- /dev/null
@@ -0,0 +1,277 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================
+Adding a new board to LinuxSH
+=============================
+
+               Paul Mundt <lethal@linux-sh.org>
+
+This document attempts to outline what steps are necessary to add support
+for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
+also attempts to outline some of the noticeable changes between the 2.4
+and the 2.5/2.6 SH backend.
+
+1. New Directory Structure
+==========================
+
+The first thing to note is the new directory structure. Under 2.4, most
+of the board-specific code (with the exception of stboards) ended up
+in arch/sh/kernel/ directly, with board-specific headers ending up in
+include/asm-sh/. For the new kernel, things are broken out by board type,
+companion chip type, and CPU type. Looking at a tree view of this directory
+hierarchy looks like the following:
+
+Board-specific code::
+
+    .
+    |-- arch
+    |   `-- sh
+    |       `-- boards
+    |           |-- adx
+    |           |   `-- board-specific files
+    |           |-- bigsur
+    |           |   `-- board-specific files
+    |           |
+    |           ... more boards here ...
+    |
+    `-- include
+       `-- asm-sh
+           |-- adx
+           |   `-- board-specific headers
+           |-- bigsur
+           |   `-- board-specific headers
+           |
+           .. more boards here ...
+
+Next, for companion chips::
+
+    .
+    `-- arch
+       `-- sh
+           `-- cchips
+               `-- hd6446x
+                   `-- hd64461
+                       `-- cchip-specific files
+
+... and so on. Headers for the companion chips are treated the same way as
+board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
+hd64461-specific headers.
+
+Finally, CPU family support is also abstracted::
+
+    .
+    |-- arch
+    |   `-- sh
+    |       |-- kernel
+    |       |   `-- cpu
+    |       |       |-- sh2
+    |       |       |   `-- SH-2 generic files
+    |       |       |-- sh3
+    |       |       |   `-- SH-3 generic files
+    |       |       `-- sh4
+    |       |           `-- SH-4 generic files
+    |       `-- mm
+    |           `-- This is also broken out per CPU family, so each family can
+    |               have their own set of cache/tlb functions.
+    |
+    `-- include
+       `-- asm-sh
+           |-- cpu-sh2
+           |   `-- SH-2 specific headers
+           |-- cpu-sh3
+           |   `-- SH-3 specific headers
+           `-- cpu-sh4
+               `-- SH-4 specific headers
+
+It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
+need to be dealt with by the CPU family specific code.
+
+2. Adding a New Board
+=====================
+
+The first thing to determine is whether the board you are adding will be
+isolated, or whether it will be part of a family of boards that can mostly
+share the same board-specific code with minor differences.
+
+In the first case, this is just a matter of making a directory for your
+board in arch/sh/boards/ and adding rules to hook your board in with the
+build system (more on this in the next section). However, for board families
+it makes more sense to have a common top-level arch/sh/boards/ directory
+and then populate that with sub-directories for each member of the family.
+Both the Solution Engine and the hp6xx boards are an example of this.
+
+After you have setup your new arch/sh/boards/ directory, remember that you
+should also add a directory in include/asm-sh for headers localized to this
+board (if there are going to be more than one). In order to interoperate
+seamlessly with the build system, it's best to have this directory the same
+as the arch/sh/boards/ directory name, though if your board is again part of
+a family, the build system has ways of dealing with this (via incdir-y
+overloading), and you can feel free to name the directory after the family
+member itself.
+
+There are a few things that each board is required to have, both in the
+arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
+explain this, we use some examples for adding an imaginary board. For
+setup code, we're required at the very least to provide definitions for
+get_system_type() and platform_setup(). For our imaginary board, this
+might look something like::
+
+    /*
+    * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
+    */
+    #include <linux/init.h>
+
+    const char *get_system_type(void)
+    {
+           return "FooTech Vaporboard";
+    }
+
+    int __init platform_setup(void)
+    {
+           /*
+           * If our hardware actually existed, we would do real
+           * setup here. Though it's also sane to leave this empty
+           * if there's no real init work that has to be done for
+           * this board.
+           */
+
+           /* Start-up imaginary PCI ... */
+
+           /* And whatever else ... */
+
+           return 0;
+    }
+
+Our new imaginary board will also have to tie into the machvec in order for it
+to be of any use.
+
+machvec functions fall into a number of categories:
+
+ - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
+ - I/O mapping functions (ioport_map, ioport_unmap, etc).
+ - a 'heartbeat' function.
+ - PCI and IRQ initialization routines.
+ - Consistent allocators (for boards that need special allocators,
+   particularly for allocating out of some board-specific SRAM for DMA
+   handles).
+
+There are machvec functions added and removed over time, so always be sure to
+consult include/asm-sh/machvec.h for the current state of the machvec.
+
+The kernel will automatically wrap in generic routines for undefined function
+pointers in the machvec at boot time, as machvec functions are referenced
+unconditionally throughout most of the tree. Some boards have incredibly
+sparse machvecs (such as the dreamcast and sh03), whereas others must define
+virtually everything (rts7751r2d).
+
+Adding a new machine is relatively trivial (using vapor as an example):
+
+If the board-specific definitions are quite minimalistic, as is the case for
+the vast majority of boards, simply having a single board-specific header is
+sufficient.
+
+ - add a new file include/asm-sh/vapor.h which contains prototypes for
+   any machine specific IO functions prefixed with the machine name, for
+   example vapor_inb. These will be needed when filling out the machine
+   vector.
+
+   Note that these prototypes are generated automatically by setting
+   __IO_PREFIX to something sensible. A typical example would be::
+
+       #define __IO_PREFIX vapor
+       #include <asm/io_generic.h>
+
+   somewhere in the board-specific header. Any boards being ported that still
+   have a legacy io.h should remove it entirely and switch to the new model.
+
+ - Add machine vector definitions to the board's setup.c. At a bare minimum,
+   this must be defined as something like::
+
+       struct sh_machine_vector mv_vapor __initmv = {
+               .mv_name = "vapor",
+       };
+       ALIAS_MV(vapor)
+
+ - finally add a file arch/sh/boards/vapor/io.c, which contains definitions of
+   the machine specific io functions (if there are enough to warrant it).
+
+3. Hooking into the Build System
+================================
+
+Now that we have the corresponding directories setup, and all of the
+board-specific code is in place, it's time to look at how to get the
+whole mess to fit into the build system.
+
+Large portions of the build system are now entirely dynamic, and merely
+require the proper entry here and there in order to get things done.
+
+The first thing to do is to add an entry to arch/sh/Kconfig, under the
+"System type" menu::
+
+    config SH_VAPOR
+           bool "Vapor"
+           help
+           select Vapor if configuring for a FooTech Vaporboard.
+
+next, this has to be added into arch/sh/Makefile. All boards require a
+machdir-y entry in order to be built. This entry needs to be the name of
+the board directory as it appears in arch/sh/boards, even if it is in a
+sub-directory (in which case, all parent directories below arch/sh/boards/
+need to be listed). For our new board, this entry can look like::
+
+    machdir-$(CONFIG_SH_VAPOR) += vapor
+
+provided that we've placed everything in the arch/sh/boards/vapor/ directory.
+
+Next, the build system assumes that your include/asm-sh directory will also
+be named the same. If this is not the case (as is the case with multiple
+boards belonging to a common family), then the directory name needs to be
+implicitly appended to incdir-y. The existing code manages this for the
+Solution Engine and hp6xx boards, so see these for an example.
+
+Once that is taken care of, it's time to add an entry for the mach type.
+This is done by adding an entry to the end of the arch/sh/tools/mach-types
+list. The method for doing this is self explanatory, and so we won't waste
+space restating it here. After this is done, you will be able to use
+implicit checks for your board if you need this somewhere throughout the
+common code, such as::
+
+       /* Make sure we're on the FooTech Vaporboard */
+       if (!mach_is_vapor())
+               return -ENODEV;
+
+also note that the mach_is_boardname() check will be implicitly forced to
+lowercase, regardless of the fact that the mach-types entries are all
+uppercase. You can read the script if you really care, but it's pretty ugly,
+so you probably don't want to do that.
+
+Now all that's left to do is providing a defconfig for your new board. This
+way, other people who end up with this board can simply use this config
+for reference instead of trying to guess what settings are supposed to be
+used on it.
+
+Also, as soon as you have copied over a sample .config for your new board
+(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a
+build target, and it will be implicitly listed as such in the help text.
+
+Looking at the 'make help' output, you should now see something like:
+
+Architecture specific targets (sh):
+
+  =======================   =============================================
+  zImage                    Compressed kernel image (arch/sh/boot/zImage)
+  adx_defconfig             Build for adx
+  cqreek_defconfig          Build for cqreek
+  dreamcast_defconfig       Build for dreamcast
+  ...
+  vapor_defconfig           Build for vapor
+  =======================   =============================================
+
+which then allows you to do::
+
+    $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux
+
+which will in turn copy the defconfig for this board, run it through
+oldconfig (prompting you for any new options since the time of creation),
+and start you on your way to having a functional kernel for your new
+board.
diff --git a/Documentation/arch/sh/register-banks.rst b/Documentation/arch/sh/register-banks.rst
new file mode 100644 (file)
index 0000000..2bef5c8
--- /dev/null
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================================
+Notes on register bank usage in the kernel
+==========================================
+
+Introduction
+------------
+
+The SH-3 and SH-4 CPU families traditionally include a single partial register
+bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
+may have more full-featured banking or simply no such capabilities at all.
+
+SR.RB banking
+-------------
+
+In the case of this type of banking, banked registers are mapped directly to
+r0 ... r7 if SR.RB is set to the bank we are interested in, otherwise ldc/stc
+can still be used to reference the banked registers (as r0_bank ... r7_bank)
+when in the context of another bank. The developer must keep the SR.RB value
+in mind when writing code that utilizes these banked registers, for obvious
+reasons. Userspace is also not able to poke at the bank1 values, so these can
+be used rather effectively as scratch registers by the kernel.
+
+Presently the kernel uses several of these registers.
+
+       - r0_bank, r1_bank (referenced as k0 and k1, used for scratch
+         registers when doing exception handling).
+
+       - r2_bank (used to track the EXPEVT/INTEVT code)
+
+               - Used by do_IRQ() and friends for doing irq mapping based off
+                 of the interrupt exception vector jump table offset
+
+       - r6_bank (global interrupt mask)
+
+               - The SR.IMASK interrupt handler makes use of this to set the
+                 interrupt priority level (used by local_irq_enable())
+
+       - r7_bank (current)
diff --git a/Documentation/sh/booting.rst b/Documentation/sh/booting.rst
deleted file mode 100644 (file)
index d851c49..0000000
+++ /dev/null
@@ -1,12 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-DeviceTree Booting
-------------------
-
-  Device-tree compatible SH bootloaders are expected to provide the physical
-  address of the device tree blob in r4. Since legacy bootloaders did not
-  guarantee any particular initial register state, kernels built to
-  inter-operate with old bootloaders must either use a builtin DTB or
-  select a legacy board option (something other than CONFIG_SH_DEVICE_TREE)
-  that does not use device tree. Support for the latter is being phased out
-  in favor of device tree.
diff --git a/Documentation/sh/features.rst b/Documentation/sh/features.rst
deleted file mode 100644 (file)
index f722af3..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-.. kernel-feat:: $srctree/Documentation/features sh
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
deleted file mode 100644 (file)
index c647767..0000000
+++ /dev/null
@@ -1,56 +0,0 @@
-=======================
-SuperH Interfaces Guide
-=======================
-
-:Author: Paul Mundt
-
-.. toctree::
-    :maxdepth: 1
-
-    booting
-    new-machine
-    register-banks
-
-    features
-
-Memory Management
-=================
-
-SH-4
-----
-
-Store Queue API
-~~~~~~~~~~~~~~~
-
-.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
-   :export:
-
-Machine Specific Interfaces
-===========================
-
-mach-dreamcast
---------------
-
-.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
-   :internal:
-
-mach-x3proto
-------------
-
-.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
-   :export:
-
-Busses
-======
-
-SuperHyway
-----------
-
-.. kernel-doc:: drivers/sh/superhyway/superhyway.c
-   :export:
-
-Maple
------
-
-.. kernel-doc:: drivers/sh/maple/maple.c
-   :export:
diff --git a/Documentation/sh/new-machine.rst b/Documentation/sh/new-machine.rst
deleted file mode 100644 (file)
index e501c52..0000000
+++ /dev/null
@@ -1,277 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-=============================
-Adding a new board to LinuxSH
-=============================
-
-               Paul Mundt <lethal@linux-sh.org>
-
-This document attempts to outline what steps are necessary to add support
-for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
-also attempts to outline some of the noticeable changes between the 2.4
-and the 2.5/2.6 SH backend.
-
-1. New Directory Structure
-==========================
-
-The first thing to note is the new directory structure. Under 2.4, most
-of the board-specific code (with the exception of stboards) ended up
-in arch/sh/kernel/ directly, with board-specific headers ending up in
-include/asm-sh/. For the new kernel, things are broken out by board type,
-companion chip type, and CPU type. Looking at a tree view of this directory
-hierarchy looks like the following:
-
-Board-specific code::
-
-    .
-    |-- arch
-    |   `-- sh
-    |       `-- boards
-    |           |-- adx
-    |           |   `-- board-specific files
-    |           |-- bigsur
-    |           |   `-- board-specific files
-    |           |
-    |           ... more boards here ...
-    |
-    `-- include
-       `-- asm-sh
-           |-- adx
-           |   `-- board-specific headers
-           |-- bigsur
-           |   `-- board-specific headers
-           |
-           .. more boards here ...
-
-Next, for companion chips::
-
-    .
-    `-- arch
-       `-- sh
-           `-- cchips
-               `-- hd6446x
-                   `-- hd64461
-                       `-- cchip-specific files
-
-... and so on. Headers for the companion chips are treated the same way as
-board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
-hd64461-specific headers.
-
-Finally, CPU family support is also abstracted::
-
-    .
-    |-- arch
-    |   `-- sh
-    |       |-- kernel
-    |       |   `-- cpu
-    |       |       |-- sh2
-    |       |       |   `-- SH-2 generic files
-    |       |       |-- sh3
-    |       |       |   `-- SH-3 generic files
-    |       |       `-- sh4
-    |       |           `-- SH-4 generic files
-    |       `-- mm
-    |           `-- This is also broken out per CPU family, so each family can
-    |               have their own set of cache/tlb functions.
-    |
-    `-- include
-       `-- asm-sh
-           |-- cpu-sh2
-           |   `-- SH-2 specific headers
-           |-- cpu-sh3
-           |   `-- SH-3 specific headers
-           `-- cpu-sh4
-               `-- SH-4 specific headers
-
-It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
-need to be dealt with by the CPU family specific code.
-
-2. Adding a New Board
-=====================
-
-The first thing to determine is whether the board you are adding will be
-isolated, or whether it will be part of a family of boards that can mostly
-share the same board-specific code with minor differences.
-
-In the first case, this is just a matter of making a directory for your
-board in arch/sh/boards/ and adding rules to hook your board in with the
-build system (more on this in the next section). However, for board families
-it makes more sense to have a common top-level arch/sh/boards/ directory
-and then populate that with sub-directories for each member of the family.
-Both the Solution Engine and the hp6xx boards are an example of this.
-
-After you have setup your new arch/sh/boards/ directory, remember that you
-should also add a directory in include/asm-sh for headers localized to this
-board (if there are going to be more than one). In order to interoperate
-seamlessly with the build system, it's best to have this directory the same
-as the arch/sh/boards/ directory name, though if your board is again part of
-a family, the build system has ways of dealing with this (via incdir-y
-overloading), and you can feel free to name the directory after the family
-member itself.
-
-There are a few things that each board is required to have, both in the
-arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
-explain this, we use some examples for adding an imaginary board. For
-setup code, we're required at the very least to provide definitions for
-get_system_type() and platform_setup(). For our imaginary board, this
-might look something like::
-
-    /*
-    * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
-    */
-    #include <linux/init.h>
-
-    const char *get_system_type(void)
-    {
-           return "FooTech Vaporboard";
-    }
-
-    int __init platform_setup(void)
-    {
-           /*
-           * If our hardware actually existed, we would do real
-           * setup here. Though it's also sane to leave this empty
-           * if there's no real init work that has to be done for
-           * this board.
-           */
-
-           /* Start-up imaginary PCI ... */
-
-           /* And whatever else ... */
-
-           return 0;
-    }
-
-Our new imaginary board will also have to tie into the machvec in order for it
-to be of any use.
-
-machvec functions fall into a number of categories:
-
- - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
- - I/O mapping functions (ioport_map, ioport_unmap, etc).
- - a 'heartbeat' function.
- - PCI and IRQ initialization routines.
- - Consistent allocators (for boards that need special allocators,
-   particularly for allocating out of some board-specific SRAM for DMA
-   handles).
-
-There are machvec functions added and removed over time, so always be sure to
-consult include/asm-sh/machvec.h for the current state of the machvec.
-
-The kernel will automatically wrap in generic routines for undefined function
-pointers in the machvec at boot time, as machvec functions are referenced
-unconditionally throughout most of the tree. Some boards have incredibly
-sparse machvecs (such as the dreamcast and sh03), whereas others must define
-virtually everything (rts7751r2d).
-
-Adding a new machine is relatively trivial (using vapor as an example):
-
-If the board-specific definitions are quite minimalistic, as is the case for
-the vast majority of boards, simply having a single board-specific header is
-sufficient.
-
- - add a new file include/asm-sh/vapor.h which contains prototypes for
-   any machine specific IO functions prefixed with the machine name, for
-   example vapor_inb. These will be needed when filling out the machine
-   vector.
-
-   Note that these prototypes are generated automatically by setting
-   __IO_PREFIX to something sensible. A typical example would be::
-
-       #define __IO_PREFIX vapor
-       #include <asm/io_generic.h>
-
-   somewhere in the board-specific header. Any boards being ported that still
-   have a legacy io.h should remove it entirely and switch to the new model.
-
- - Add machine vector definitions to the board's setup.c. At a bare minimum,
-   this must be defined as something like::
-
-       struct sh_machine_vector mv_vapor __initmv = {
-               .mv_name = "vapor",
-       };
-       ALIAS_MV(vapor)
-
- - finally add a file arch/sh/boards/vapor/io.c, which contains definitions of
-   the machine specific io functions (if there are enough to warrant it).
-
-3. Hooking into the Build System
-================================
-
-Now that we have the corresponding directories setup, and all of the
-board-specific code is in place, it's time to look at how to get the
-whole mess to fit into the build system.
-
-Large portions of the build system are now entirely dynamic, and merely
-require the proper entry here and there in order to get things done.
-
-The first thing to do is to add an entry to arch/sh/Kconfig, under the
-"System type" menu::
-
-    config SH_VAPOR
-           bool "Vapor"
-           help
-           select Vapor if configuring for a FooTech Vaporboard.
-
-next, this has to be added into arch/sh/Makefile. All boards require a
-machdir-y entry in order to be built. This entry needs to be the name of
-the board directory as it appears in arch/sh/boards, even if it is in a
-sub-directory (in which case, all parent directories below arch/sh/boards/
-need to be listed). For our new board, this entry can look like::
-
-    machdir-$(CONFIG_SH_VAPOR) += vapor
-
-provided that we've placed everything in the arch/sh/boards/vapor/ directory.
-
-Next, the build system assumes that your include/asm-sh directory will also
-be named the same. If this is not the case (as is the case with multiple
-boards belonging to a common family), then the directory name needs to be
-implicitly appended to incdir-y. The existing code manages this for the
-Solution Engine and hp6xx boards, so see these for an example.
-
-Once that is taken care of, it's time to add an entry for the mach type.
-This is done by adding an entry to the end of the arch/sh/tools/mach-types
-list. The method for doing this is self explanatory, and so we won't waste
-space restating it here. After this is done, you will be able to use
-implicit checks for your board if you need this somewhere throughout the
-common code, such as::
-
-       /* Make sure we're on the FooTech Vaporboard */
-       if (!mach_is_vapor())
-               return -ENODEV;
-
-also note that the mach_is_boardname() check will be implicitly forced to
-lowercase, regardless of the fact that the mach-types entries are all
-uppercase. You can read the script if you really care, but it's pretty ugly,
-so you probably don't want to do that.
-
-Now all that's left to do is providing a defconfig for your new board. This
-way, other people who end up with this board can simply use this config
-for reference instead of trying to guess what settings are supposed to be
-used on it.
-
-Also, as soon as you have copied over a sample .config for your new board
-(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a
-build target, and it will be implicitly listed as such in the help text.
-
-Looking at the 'make help' output, you should now see something like:
-
-Architecture specific targets (sh):
-
-  =======================   =============================================
-  zImage                    Compressed kernel image (arch/sh/boot/zImage)
-  adx_defconfig             Build for adx
-  cqreek_defconfig          Build for cqreek
-  dreamcast_defconfig       Build for dreamcast
-  ...
-  vapor_defconfig           Build for vapor
-  =======================   =============================================
-
-which then allows you to do::
-
-    $ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux
-
-which will in turn copy the defconfig for this board, run it through
-oldconfig (prompting you for any new options since the time of creation),
-and start you on your way to having a functional kernel for your new
-board.
diff --git a/Documentation/sh/register-banks.rst b/Documentation/sh/register-banks.rst
deleted file mode 100644 (file)
index 2bef5c8..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-==========================================
-Notes on register bank usage in the kernel
-==========================================
-
-Introduction
-------------
-
-The SH-3 and SH-4 CPU families traditionally include a single partial register
-bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
-may have more full-featured banking or simply no such capabilities at all.
-
-SR.RB banking
--------------
-
-In the case of this type of banking, banked registers are mapped directly to
-r0 ... r7 if SR.RB is set to the bank we are interested in, otherwise ldc/stc
-can still be used to reference the banked registers (as r0_bank ... r7_bank)
-when in the context of another bank. The developer must keep the SR.RB value
-in mind when writing code that utilizes these banked registers, for obvious
-reasons. Userspace is also not able to poke at the bank1 values, so these can
-be used rather effectively as scratch registers by the kernel.
-
-Presently the kernel uses several of these registers.
-
-       - r0_bank, r1_bank (referenced as k0 and k1, used for scratch
-         registers when doing exception handling).
-
-       - r2_bank (used to track the EXPEVT/INTEVT code)
-
-               - Used by do_IRQ() and friends for doing irq mapping based off
-                 of the interrupt exception vector jump table offset
-
-       - r6_bank (global interrupt mask)
-
-               - The SR.IMASK interrupt handler makes use of this to set the
-                 interrupt priority level (used by local_irq_enable())
-
-       - r7_bank (current)
index 250df8cee46328dca8d5aa281e2656c29395f95c..cf4eb913ea1212f315d101a868e085c668b04554 100644 (file)
@@ -20125,7 +20125,7 @@ M:      John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>
 L:     linux-sh@vger.kernel.org
 S:     Maintained
 Q:     http://patchwork.kernel.org/project/linux-sh/list/
-F:     Documentation/sh/
+F:     Documentation/arch/sh/
 F:     arch/sh/
 F:     drivers/sh/
 
index fff419f3d7574c16e5f965559ad98d449d5180f1..336c54369636d7290a46cfc5478f94f4a26806c0 100644 (file)
@@ -85,7 +85,7 @@ config CPU_HAS_SR_RB
          that are lacking this bit must have another method in place for
          accomplishing what is taken care of by the banked registers.
 
-         See <file:Documentation/sh/register-banks.rst> for further
+         See <file:Documentation/arch/sh/register-banks.rst> for further
          information on SR.RB and register banking in the kernel in general.
 
 config CPU_HAS_PTEAEX