diff options
Diffstat (limited to 'Documentation/sh/new-machine.txt')
| -rw-r--r-- | Documentation/sh/new-machine.txt | 306 |
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 00000000000..eb2dd2e6993 --- /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. + |