Print this page
4266 remove Makefile*.shared nonsense in uts
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/uts/README
+++ new/usr/src/uts/README
1 1 #
2 2 # CDDL HEADER START
3 3 #
4 4 # The contents of this file are subject to the terms of the
5 5 # Common Development and Distribution License (the "License").
6 6 # You may not use this file except in compliance with the License.
7 7 #
8 8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 # or http://www.opensolaris.org/os/licensing.
10 10 # See the License for the specific language governing permissions
11 11 # and limitations under the License.
12 12 #
13 13 # When distributing Covered Code, include this CDDL HEADER in each
14 14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 15 # If applicable, add the following below this CDDL HEADER, with the
16 16 # fields enclosed by brackets "[]" replaced with your own identifying
17 17 # information: Portions Copyright [yyyy] [name of copyright owner]
18 18 #
19 19 # CDDL HEADER END
20 20 #
21 21
22 22 #
23 23 # Copyright 2007 Sun Microsystems, Inc. All rights reserved.
24 24 # Use is subject to license terms.
25 25 #
26 26 # ident "%Z%%M% %I% %E% SMI"
27 27
28 28 KERNEL MAKEFILE STRUCTURE
29 29 -------------------------
30 30
31 31 The advent of dynamic loading of kernel modules has obsoleted the
32 32 4.x kernel configuration scheme which was centered around a derived
33 33 Makefile and a collection of derived header files generated by the
34 34 config(8) program. This file describes the structure of the replacement
35 35 "static" set of Makefiles.
36 36
37 37 Some additional secondary goals were associated with the generation
38 38 of these Makefiles. It should be noted that the ability to properly
39 39 deal with derived Makefiles is an explicit non-goal of the ongoing
40 40 NSE enhancements, so this project is a necessary consequence of that
41 41 decision.
42 42
43 43 All project goals are enumerated below:
44 44
45 45 1] To provide a set of static Makefiles to support kernel build
46 46 and installation.
47 47
48 48 2] To provide a set of static Makefiles which conform to the
49 49 "Makefiles Guidelines". (This document is currently available
50 50 on-line as "terminator:/usr/integration/doc/make.std")
51 51
52 52 3] To completely eliminate the config(8) program.
53 53
54 54 4] To provide a framework for linting the kernel (so that "lint free"
55 55 can be made an integration criterion, in addition to being general
56 56 good hygiene).
57 57
58 58 5] To eliminate the need for the small headers generated by config(8).
59 59 In the ddi/dki world this need is completely eliminated as drivers
60 60 will be expected to dynamically configure themselves. Interim support
61 61 for existing drivers will be provided.
62 62
63 63 6] To be able to "acquire" only the files needed to build a specific
64 64 module, if that is all that is needed.
65 65
66 66 7] To provide a framework suitable for the production of "implementation
67 67 architecture" independent modules.
68 68
69 69 8] To restructure the assembly language files to support the generation
70 70 of "lint-libraries" from them.
71 71
72 72 9] To provide support for the incidental Makefile targets many developers
73 73 are accustomed to (such as cscope and tags). These can be added to the
74 74 Makefiles asd required. (cscope is currently supported.)
75 75
76 76
77 77 GENERAL STRUCTURE
78 78 -----------------
79 79
80 80 The source code layout is not generally effected by the Makefiles. However,
81 81 the location of the generated files has changed dramatically.
82 82
83 83 "Implementation architecture" independent modules are produced in
84 84 individual directories (one per module) under the "instruction-set
85 85 architecture" directory (i.e.: sparc). Similarly, "implementation
86 86 architecture" dependent modules are produced in individual directories
87 87 under the "implementation architecture" directory (i.e.: sun4, sun4c).
88 88 It should be noted that currently (4/14/91) no implementation architecture
89 89 modules exist. This situation is expected to change shortly.
90 90
91 91 The driving Makefile for any module is located in the leaf directory
92 92 where the module (and associated objects) are built. After a 'make
93 93 clobber' operation, the Makefile is the only file remaining in that
94 94 directory. Common definitions and rules are contained in suffixed
95 95 Makefiles in non-leaf directories which are included in the leaf
96 96 Makefiles. Non-suffixed Makefiles in non-leaf directories generally
97 97 invoke lower level Makefiles to perform the actual tasks.
98 98
99 99 uts/Makefile
100 100 uts/sparc/Makefile
101 101 uts/sun4c/Makefile
102 102 uts/sun4c/svvs/Makefile
103 103 These Makefiles generally are cognizant of the components
104 104 made in subdirectories and invoke Makefiles in those sub-
105 105 directories to perform the actual build. Some targets (or
106 106 pseudo-targets) may be directly built at this level (such
107 107 as the cscope databases).
108 108
109 109 uts/Makefile.uts
110 110 Contains common definitions for all possible architectures.
111 111
112 112 uts/Makefile.targ
113 113 Contains common targets for all possible architectures.
114 114
115 115 uts/common/Makefile.files
116 116 uts/sun/Makefile.files
117 117 uts/sparc/Makefile.files
118 118 uts/sun4c/Makefile.files
119 119 uts/sun4/Makefile.files
120 120 These Makefiles are divided into two sections. The first
121 121 section can be viewed as the equivalent of the "files" (sparc
122 122 and sun4c) and "files.cmn" (common and sun) files. These
123 123 define the object lists which define each module. The second
124 124 section defines the appropriate header search paths and other
125 125 machine specific global build parameters.
126 126
127 127 uts/common/Makefile.rules
128 128 uts/sun/Makefile.rules
129 129 uts/sparc/Makefile.rules
130 130 uts/sun4c/Makefile.rules
131 131 uts/sun4/Makefile.rules
132 132 The files provide build rules (targets) which allow make to function
133 133 in a multiple directory environment. Each source tree below the
134 134 directory containing the Makefile has a build rule in the file.
135 135
136 136 uts/sun4c/Makefile.sun4c
137 137 uts/sun4/Makefile.sun4
138 138 These Makefile contains the definitions specific (defaults) to
139 139 the obvious "implementation architecture". These rules can be
140 140 overridden in specific leaf node Makefiles if necessary.
141 141
142 142 uts/sun4c/unix/Makefile
143 143 Main driving Makefile for building /unix.
144 144
↓ open down ↓ |
144 lines elided |
↑ open up ↑ |
145 145 uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
146 146 Main driving Makefile for building MODULE.kmod.
147 147
148 148 uts/sun4c/unix.static/Makefile
149 149 Main driving Makefile for building a static unix (for development
150 150 work only). This Makefile is known to NSE, but its targets are
151 151 not. This makefile may be copied to additional parallel directories
152 152 to build multiple configurations. This configuration is roughly
153 153 equivalent to the GENERIC kernel of SunOS 4.x.
154 154
155 -uts/*/Makefile.?.shared
156 - These denote Makefile contents which are shared between open and
157 - closed builds.
158 -
159 155 The Makefiles are verbosely commented. It is desired that they should
160 156 stay this way.
161 157
162 158
163 159 USE
164 160 ---
165 161
166 162 Issuing the command 'make' in the uts directory will cause all supported,
167 163 modularized kernels and modules to be built.
168 164
169 165 Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
170 166 will cause all supported, "implementation architecture" independent modules
171 167 for ARCHITECTURE to be built.
172 168
173 169 Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
174 170 will cause that kernel and all supported, "implementation architecture"
175 171 dependent modules for MACHINE to be built.
176 172
177 173 Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
178 174 kernel for MACHINE to be built (and unix.o).
179 175
180 176 Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
181 177 directory will cause MODULE.kmod to be built.
182 178
183 179
184 180 LINT
185 181 ----
186 182
187 183 Linting is fairly similar to the builds, but it has an additional complication.
188 184 In order to get meaningful output from lint pass2, all the modules must be
189 185 linted together. This is accomplished by each module being responsible to
190 186 produce its own pass1 output (file.ln, one per .c/.s file). It is also
191 187 responsible for placing the a lint-library (llib-lMODULE) in the
192 188 uts/MACHINE/lint-libs directory. The final full lint is accomplished by the
193 189 Makefile in the uts/MACHINE directory by linting all the lint-libraries
194 190 against each other.
195 191
196 192 Note that there is no equivalent to Locore.c in the current source base.
197 193 The C prototypes are in the .s files. As example:
198 194
199 195 #if defined(lint)
200 196 int
201 197 blort(int, int)
202 198 { return 0 }
203 199 #else /* lint */
204 200
205 201 ENTRY(blort)
206 202 ld [%i0],....
207 203 ....
208 204 SET_SIZE(blort)
209 205
210 206 #endif /* lint */
211 207
212 208
213 209 COMPONENT HIERARCHY
214 210 ------------------
215 211
216 212 The component hierarchy has been restructured to allow the acquisition of
217 213 more finely grained objects; specificly a kernel module. The basic component
218 214 structure is:
219 215
220 216 :src:uts.all --+--> :sparc --+--> :MODULES... (none currently)
221 217 |
222 218 +--> :sun4c --+--> :unix
223 219 | |
224 220 | +--> :MODULES...
225 221 | |
226 222 | +--> :unix.static
227 223 |
228 224 +--> :sun4 ---+--> :unix
229 225 | |
230 226 | +--> :MODULES...
231 227 | |
232 228 | +--> :unix.static
233 229 ...
234 230
235 231 The above diagram does not reflect the full component tree. The full component
236 232 tree may be displayed with the "nsecomp list -r :src:uts.all" command.
237 233
238 234
239 235 COMMON OPERATIONS
240 236 -----------------
241 237
242 238 Adding a New Kernel Module
243 239 --------------------------
244 240
245 241 0] Create the source files (and directories) as usual.
246 242
247 243 1] Edit uts/*/Makefile.files to define the set of objects. By convention
248 244 the symbolic name of this set is of the form MODULE_OBJS, where
249 245 MODULE is the module name (i.e.: namefs). The files in each subtree
250 246 should be defined in the Makefile.files in the root directory of that
251 247 subtree. Note that they are defined using the += operator, so that
252 248 the set can be built across multiple files. As example:
253 249
254 250 NAMEFS_OBJS += namevfs.o namevno.o
255 251
256 252 Each source file needs a build rule in the corresponding Makefile.rules
257 253 file (compilation and lint). A typical pair of entries would be:
258 254
259 255 $(OBJS_DIR)/mem.o: $(UTSBASE)/sun4c/io/mem.c
260 256 $(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
261 257
262 258 $(LINTS_DIR)/mem.ln: $(UTSBASE)/sun4c/io/mem.c
263 259 @($(LHEAD) $(LINT.c) $(UTSBASE)/sun4c/io/mem.c $(LTAIL))
264 260
265 261 2] Create build directories in the appropriate places. If the module
266 262 can be built in a machine independent way, this would be in the
267 263 "instruction set architecture" directory (i.e.: sparc). If not, these
268 264 directories would be created for all appropriate "implementation
269 265 architecture" dependent directories (i.e.: sun4, sun4c).
270 266
271 267 3] In each build directory, create a Makefile. This can usually be
272 268 accomplished by copying a Makefile from a parallel directory and
273 269 editing the following lines (in addition to comments).
274 270
275 271 MODULE = namefs
276 272 - replace with module name
277 273 OBJECTS = $(NAMEFS_OBJS:%=$(OBJS_DIR)/%)
278 274 LINTS = $(NAMEFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
279 275 - replace with MODULE_OBJS
280 276 ROOTMODULE = $(ROOT_FS_DIR)/$(MODULE).kmod
281 277 - replace directory part with the appropriate
282 278 installation directory name (see Makefile.uts)
283 279
284 280 If a custom version of modstubs.o is needed to check the undefines
285 281 for this routine, the following lines need to appear in the
286 282 Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)).
287 283
288 284 MODSTUBS_DIR = $(OBJS_DIR)
289 285 $(MODSTUBS_O) := AS_CPPFLAGS += -DNAMEFS_MODULE
290 286 - replace "-DNAMEFS_MODULE" with the appropriate flag
291 287 for the modstubs.o assembly.
292 288 CLEANFILES += $(MODSTUBS_O)
293 289
294 290 4] Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
295 291 the new module:
296 292
297 293 FS_KMODS += fd fifo namefs nfs proc spec ufs
298 294 ------
299 295 Any additional questions can be easily answered by looking at the many
300 296 existing examples.
301 297
302 298
303 299 Moving a Module to the "Implementation Architecture" Independent Build
304 300 ----------------------------------------------------------------------
305 301
306 302 1] Create the build directory under the appropriate "instruction
307 303 set architecture" build directory (i.e.: sparc/MODULE).
308 304
309 305 2] Move the Makefile from the "implementation architecture" build
310 306 directory (i.e.: sun4c/MODULE) to the directory created above.
311 307 Edit this Makefile to reflect the change of parent (trivial:
312 308 comments, paths and includes).
313 309
314 310 3] Edit the "implementation architecture" directory Makefile (i.e.:
315 311 Makefile.sun4c) to *not* know about this module and edit the
316 312 "instruction set architecture" directory Makefile (i.e.:
317 313 Makefile.sparc) to know about it.
318 314
↓ open down ↓ |
150 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX