1 files changed, 306 insertions, 0 deletions

diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt
new file mode 100644
index 000000000000..eb2dd2e6993b
--- /dev/null
+++ b/Documentation/sh/new-machine.txt
@@ -0,0 +1,306 @@
+
+                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
+heirarchy 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 ...
+
+It should also be noted that each board is required to have some certain
+headers. At the time of this writing, io.h is the only thing that needs
+to be provided for each board, and can generally just reference generic
+functions (with the exception of isa_port2addr).
+
+Next, for companion chips:
+.
+`-- arch
+    `-- sh
+        `-- cchips
+            `-- hd6446x
+                |-- hd64461
+                |   `-- cchip-specific files
+                `-- hd64465
+                    `-- 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
+also must add a directory in include/asm-sh for headers localized to this
+board. 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, 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/ heirarchy. 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.
+         */
+
+        /* 
+         * Presume all FooTech boards have the same broken timer,
+         * and also presume that we've defined foo_timer_init to
+         * do something useful.
+         */
+        board_time_init = foo_timer_init;
+
+        /* 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. Currently the machvec is slowly on its way out, but is still
+required for the time being. As such, let us take a look at what needs to be
+done for the machvec assignment.
+
+machvec functions fall into a number of categories:
+
+ - I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
+ - I/O remapping functions (ioremap etc)
+ - some initialisation functions
+ - a 'heartbeat' function
+ - some miscellaneous flags
+
+The tree can be built in two ways:
+ - as a fully generic build. All drivers are linked in, and all functions
+   go through the machvec
+ - as a machine specific build. In this case only the required drivers
+   will be linked in, and some macros may be redefined to not go through
+   the machvec where performance is important (in particular IO functions).
+
+There are three ways in which IO can be performed:
+ - none at all. This is really only useful for the 'unknown' machine type,
+   which us designed to run on a machine about which we know nothing, and
+   so all all IO instructions do nothing.
+ - fully custom. In this case all IO functions go to a machine specific
+   set of functions which can do what they like
+ - a generic set of functions. These will cope with most situations,
+   and rely on a single function, mv_port2addr, which is called through the
+   machine vector, and converts an IO address into a memory address, which
+   can be read from/written to directly.
+
+Thus adding a new machine involves the following steps (I will assume I am
+adding a machine called vapor):
+
+ - add a new file include/asm-sh/vapor/io.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.
+
+   This is the minimum that is required, however there are ample
+   opportunities to optimise this. In particular, by making the prototypes
+   inline function definitions, it is possible to inline the function when
+   building machine specific versions. Note that the machine vector
+   functions will still be needed, so that a module built for a generic
+   setup can be loaded.
+
+ - add a new file arch/sh/boards/vapor/mach.c. This contains the definition
+   of the machine vector. When building the machine specific version, this
+   will be the real machine vector (via an alias), while in the generic
+   version is used to initialise the machine vector, and then freed, by
+   making it initdata. This should be defined as:
+
+     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.
+
+A note about initialisation functions. Three initialisation functions are
+provided in the machine vector:
+ - mv_arch_init - called very early on from setup_arch
+ - mv_init_irq - called from init_IRQ, after the generic SH interrupt
+   initialisation
+ - mv_init_pci - currently not used
+
+Any other remaining functions which need to be called at start up can be
+added to the list using the __initcalls macro (or module_init if the code
+can be built as a module). Many generic drivers probe to see if the device
+they are targeting is present, however this may not always be appropriate,
+so a flag can be added to the machine vector which will be set on those
+machines which have the hardware in question, reducing the probe to a
+single conditional.
+
+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.
+