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