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