1 |
3 |
xianfeng |
|
2 |
|
|
Adding a new board to LinuxSH
|
3 |
|
|
================================
|
4 |
|
|
|
5 |
|
|
Paul Mundt
|
6 |
|
|
|
7 |
|
|
This document attempts to outline what steps are necessary to add support
|
8 |
|
|
for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
|
9 |
|
|
also attempts to outline some of the noticeable changes between the 2.4
|
10 |
|
|
and the 2.5/2.6 SH backend.
|
11 |
|
|
|
12 |
|
|
1. New Directory Structure
|
13 |
|
|
==========================
|
14 |
|
|
|
15 |
|
|
The first thing to note is the new directory structure. Under 2.4, most
|
16 |
|
|
of the board-specific code (with the exception of stboards) ended up
|
17 |
|
|
in arch/sh/kernel/ directly, with board-specific headers ending up in
|
18 |
|
|
include/asm-sh/. For the new kernel, things are broken out by board type,
|
19 |
|
|
companion chip type, and CPU type. Looking at a tree view of this directory
|
20 |
|
|
hierarchy looks like the following:
|
21 |
|
|
|
22 |
|
|
Board-specific code:
|
23 |
|
|
|
24 |
|
|
.
|
25 |
|
|
|-- arch
|
26 |
|
|
| `-- sh
|
27 |
|
|
| `-- boards
|
28 |
|
|
| |-- adx
|
29 |
|
|
| | `-- board-specific files
|
30 |
|
|
| |-- bigsur
|
31 |
|
|
| | `-- board-specific files
|
32 |
|
|
| |
|
33 |
|
|
| ... more boards here ...
|
34 |
|
|
|
|
35 |
|
|
`-- include
|
36 |
|
|
`-- asm-sh
|
37 |
|
|
|-- adx
|
38 |
|
|
| `-- board-specific headers
|
39 |
|
|
|-- bigsur
|
40 |
|
|
| `-- board-specific headers
|
41 |
|
|
|
|
42 |
|
|
.. more boards here ...
|
43 |
|
|
|
44 |
|
|
Next, for companion chips:
|
45 |
|
|
.
|
46 |
|
|
`-- arch
|
47 |
|
|
`-- sh
|
48 |
|
|
`-- cchips
|
49 |
|
|
`-- hd6446x
|
50 |
|
|
|-- hd64461
|
51 |
|
|
| `-- cchip-specific files
|
52 |
|
|
`-- hd64465
|
53 |
|
|
`-- cchip-specific files
|
54 |
|
|
|
55 |
|
|
... and so on. Headers for the companion chips are treated the same way as
|
56 |
|
|
board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
|
57 |
|
|
hd64461-specific headers.
|
58 |
|
|
|
59 |
|
|
Finally, CPU family support is also abstracted:
|
60 |
|
|
.
|
61 |
|
|
|-- arch
|
62 |
|
|
| `-- sh
|
63 |
|
|
| |-- kernel
|
64 |
|
|
| | `-- cpu
|
65 |
|
|
| | |-- sh2
|
66 |
|
|
| | | `-- SH-2 generic files
|
67 |
|
|
| | |-- sh3
|
68 |
|
|
| | | `-- SH-3 generic files
|
69 |
|
|
| | `-- sh4
|
70 |
|
|
| | `-- SH-4 generic files
|
71 |
|
|
| `-- mm
|
72 |
|
|
| `-- This is also broken out per CPU family, so each family can
|
73 |
|
|
| have their own set of cache/tlb functions.
|
74 |
|
|
|
|
75 |
|
|
`-- include
|
76 |
|
|
`-- asm-sh
|
77 |
|
|
|-- cpu-sh2
|
78 |
|
|
| `-- SH-2 specific headers
|
79 |
|
|
|-- cpu-sh3
|
80 |
|
|
| `-- SH-3 specific headers
|
81 |
|
|
`-- cpu-sh4
|
82 |
|
|
`-- SH-4 specific headers
|
83 |
|
|
|
84 |
|
|
It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
|
85 |
|
|
need to be dealt with by the CPU family specific code.
|
86 |
|
|
|
87 |
|
|
2. Adding a New Board
|
88 |
|
|
=====================
|
89 |
|
|
|
90 |
|
|
The first thing to determine is whether the board you are adding will be
|
91 |
|
|
isolated, or whether it will be part of a family of boards that can mostly
|
92 |
|
|
share the same board-specific code with minor differences.
|
93 |
|
|
|
94 |
|
|
In the first case, this is just a matter of making a directory for your
|
95 |
|
|
board in arch/sh/boards/ and adding rules to hook your board in with the
|
96 |
|
|
build system (more on this in the next section). However, for board families
|
97 |
|
|
it makes more sense to have a common top-level arch/sh/boards/ directory
|
98 |
|
|
and then populate that with sub-directories for each member of the family.
|
99 |
|
|
Both the Solution Engine and the hp6xx boards are an example of this.
|
100 |
|
|
|
101 |
|
|
After you have setup your new arch/sh/boards/ directory, remember that you
|
102 |
|
|
should also add a directory in include/asm-sh for headers localized to this
|
103 |
|
|
board (if there are going to be more than one). In order to interoperate
|
104 |
|
|
seamlessly with the build system, it's best to have this directory the same
|
105 |
|
|
as the arch/sh/boards/ directory name, though if your board is again part of
|
106 |
|
|
a family, the build system has ways of dealing with this (via incdir-y
|
107 |
|
|
overloading), and you can feel free to name the directory after the family
|
108 |
|
|
member itself.
|
109 |
|
|
|
110 |
|
|
There are a few things that each board is required to have, both in the
|
111 |
|
|
arch/sh/boards and the include/asm-sh/ hierarchy. In order to better
|
112 |
|
|
explain this, we use some examples for adding an imaginary board. For
|
113 |
|
|
setup code, we're required at the very least to provide definitions for
|
114 |
|
|
get_system_type() and platform_setup(). For our imaginary board, this
|
115 |
|
|
might look something like:
|
116 |
|
|
|
117 |
|
|
/*
|
118 |
|
|
* arch/sh/boards/vapor/setup.c - Setup code for imaginary board
|
119 |
|
|
*/
|
120 |
|
|
#include
|
121 |
|
|
#include /* for board_time_init() */
|
122 |
|
|
|
123 |
|
|
const char *get_system_type(void)
|
124 |
|
|
{
|
125 |
|
|
return "FooTech Vaporboard";
|
126 |
|
|
}
|
127 |
|
|
|
128 |
|
|
int __init platform_setup(void)
|
129 |
|
|
{
|
130 |
|
|
/*
|
131 |
|
|
* If our hardware actually existed, we would do real
|
132 |
|
|
* setup here. Though it's also sane to leave this empty
|
133 |
|
|
* if there's no real init work that has to be done for
|
134 |
|
|
* this board.
|
135 |
|
|
*/
|
136 |
|
|
|
137 |
|
|
/*
|
138 |
|
|
* Presume all FooTech boards have the same broken timer,
|
139 |
|
|
* and also presume that we've defined foo_timer_init to
|
140 |
|
|
* do something useful.
|
141 |
|
|
*/
|
142 |
|
|
board_time_init = foo_timer_init;
|
143 |
|
|
|
144 |
|
|
/* Start-up imaginary PCI ... */
|
145 |
|
|
|
146 |
|
|
/* And whatever else ... */
|
147 |
|
|
|
148 |
|
|
return 0;
|
149 |
|
|
}
|
150 |
|
|
|
151 |
|
|
Our new imaginary board will also have to tie into the machvec in order for it
|
152 |
|
|
to be of any use.
|
153 |
|
|
|
154 |
|
|
machvec functions fall into a number of categories:
|
155 |
|
|
|
156 |
|
|
- I/O functions to IO memory (inb etc) and PCI/main memory (readb etc).
|
157 |
|
|
- I/O mapping functions (ioport_map, ioport_unmap, etc).
|
158 |
|
|
- a 'heartbeat' function.
|
159 |
|
|
- PCI and IRQ initialization routines.
|
160 |
|
|
- Consistent allocators (for boards that need special allocators,
|
161 |
|
|
particularly for allocating out of some board-specific SRAM for DMA
|
162 |
|
|
handles).
|
163 |
|
|
|
164 |
|
|
There are machvec functions added and removed over time, so always be sure to
|
165 |
|
|
consult include/asm-sh/machvec.h for the current state of the machvec.
|
166 |
|
|
|
167 |
|
|
The kernel will automatically wrap in generic routines for undefined function
|
168 |
|
|
pointers in the machvec at boot time, as machvec functions are referenced
|
169 |
|
|
unconditionally throughout most of the tree. Some boards have incredibly
|
170 |
|
|
sparse machvecs (such as the dreamcast and sh03), whereas others must define
|
171 |
|
|
virtually everything (rts7751r2d).
|
172 |
|
|
|
173 |
|
|
Adding a new machine is relatively trivial (using vapor as an example):
|
174 |
|
|
|
175 |
|
|
If the board-specific definitions are quite minimalistic, as is the case for
|
176 |
|
|
the vast majority of boards, simply having a single board-specific header is
|
177 |
|
|
sufficient.
|
178 |
|
|
|
179 |
|
|
- add a new file include/asm-sh/vapor.h which contains prototypes for
|
180 |
|
|
any machine specific IO functions prefixed with the machine name, for
|
181 |
|
|
example vapor_inb. These will be needed when filling out the machine
|
182 |
|
|
vector.
|
183 |
|
|
|
184 |
|
|
Note that these prototypes are generated automatically by setting
|
185 |
|
|
__IO_PREFIX to something sensible. A typical example would be:
|
186 |
|
|
|
187 |
|
|
#define __IO_PREFIX vapor
|
188 |
|
|
#include
|
189 |
|
|
|
190 |
|
|
somewhere in the board-specific header. Any boards being ported that still
|
191 |
|
|
have a legacy io.h should remove it entirely and switch to the new model.
|
192 |
|
|
|
193 |
|
|
- Add machine vector definitions to the board's setup.c. At a bare minimum,
|
194 |
|
|
this must be defined as something like:
|
195 |
|
|
|
196 |
|
|
struct sh_machine_vector mv_vapor __initmv = {
|
197 |
|
|
.mv_name = "vapor",
|
198 |
|
|
};
|
199 |
|
|
ALIAS_MV(vapor)
|
200 |
|
|
|
201 |
|
|
- finally add a file arch/sh/boards/vapor/io.c, which contains definitions of
|
202 |
|
|
the machine specific io functions (if there are enough to warrant it).
|
203 |
|
|
|
204 |
|
|
3. Hooking into the Build System
|
205 |
|
|
================================
|
206 |
|
|
|
207 |
|
|
Now that we have the corresponding directories setup, and all of the
|
208 |
|
|
board-specific code is in place, it's time to look at how to get the
|
209 |
|
|
whole mess to fit into the build system.
|
210 |
|
|
|
211 |
|
|
Large portions of the build system are now entirely dynamic, and merely
|
212 |
|
|
require the proper entry here and there in order to get things done.
|
213 |
|
|
|
214 |
|
|
The first thing to do is to add an entry to arch/sh/Kconfig, under the
|
215 |
|
|
"System type" menu:
|
216 |
|
|
|
217 |
|
|
config SH_VAPOR
|
218 |
|
|
bool "Vapor"
|
219 |
|
|
help
|
220 |
|
|
select Vapor if configuring for a FooTech Vaporboard.
|
221 |
|
|
|
222 |
|
|
next, this has to be added into arch/sh/Makefile. All boards require a
|
223 |
|
|
machdir-y entry in order to be built. This entry needs to be the name of
|
224 |
|
|
the board directory as it appears in arch/sh/boards, even if it is in a
|
225 |
|
|
sub-directory (in which case, all parent directories below arch/sh/boards/
|
226 |
|
|
need to be listed). For our new board, this entry can look like:
|
227 |
|
|
|
228 |
|
|
machdir-$(CONFIG_SH_VAPOR) += vapor
|
229 |
|
|
|
230 |
|
|
provided that we've placed everything in the arch/sh/boards/vapor/ directory.
|
231 |
|
|
|
232 |
|
|
Next, the build system assumes that your include/asm-sh directory will also
|
233 |
|
|
be named the same. If this is not the case (as is the case with multiple
|
234 |
|
|
boards belonging to a common family), then the directory name needs to be
|
235 |
|
|
implicitly appended to incdir-y. The existing code manages this for the
|
236 |
|
|
Solution Engine and hp6xx boards, so see these for an example.
|
237 |
|
|
|
238 |
|
|
Once that is taken care of, it's time to add an entry for the mach type.
|
239 |
|
|
This is done by adding an entry to the end of the arch/sh/tools/mach-types
|
240 |
|
|
list. The method for doing this is self explanatory, and so we won't waste
|
241 |
|
|
space restating it here. After this is done, you will be able to use
|
242 |
|
|
implicit checks for your board if you need this somewhere throughout the
|
243 |
|
|
common code, such as:
|
244 |
|
|
|
245 |
|
|
/* Make sure we're on the FooTech Vaporboard */
|
246 |
|
|
if (!mach_is_vapor())
|
247 |
|
|
return -ENODEV;
|
248 |
|
|
|
249 |
|
|
also note that the mach_is_boardname() check will be implicitly forced to
|
250 |
|
|
lowercase, regardless of the fact that the mach-types entries are all
|
251 |
|
|
uppercase. You can read the script if you really care, but it's pretty ugly,
|
252 |
|
|
so you probably don't want to do that.
|
253 |
|
|
|
254 |
|
|
Now all that's left to do is providing a defconfig for your new board. This
|
255 |
|
|
way, other people who end up with this board can simply use this config
|
256 |
|
|
for reference instead of trying to guess what settings are supposed to be
|
257 |
|
|
used on it.
|
258 |
|
|
|
259 |
|
|
Also, as soon as you have copied over a sample .config for your new board
|
260 |
|
|
(assume arch/sh/configs/vapor_defconfig), you can also use this directly as a
|
261 |
|
|
build target, and it will be implicitly listed as such in the help text.
|
262 |
|
|
|
263 |
|
|
Looking at the 'make help' output, you should now see something like:
|
264 |
|
|
|
265 |
|
|
Architecture specific targets (sh):
|
266 |
|
|
zImage - Compressed kernel image (arch/sh/boot/zImage)
|
267 |
|
|
adx_defconfig - Build for adx
|
268 |
|
|
cqreek_defconfig - Build for cqreek
|
269 |
|
|
dreamcast_defconfig - Build for dreamcast
|
270 |
|
|
...
|
271 |
|
|
vapor_defconfig - Build for vapor
|
272 |
|
|
|
273 |
|
|
which then allows you to do:
|
274 |
|
|
|
275 |
|
|
$ make ARCH=sh CROSS_COMPILE=sh4-linux- vapor_defconfig vmlinux
|
276 |
|
|
|
277 |
|
|
which will in turn copy the defconfig for this board, run it through
|
278 |
|
|
oldconfig (prompting you for any new options since the time of creation),
|
279 |
|
|
and start you on your way to having a functional kernel for your new
|
280 |
|
|
board.
|