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