xref: /titanic_50/usr/src/uts/README (revision f3324781c875e2f9865c291e43f86ee710b0c145)
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
28KERNEL MAKEFILE STRUCTURE
29-------------------------
30
31The advent of dynamic loading of kernel modules has obsoleted the
324.x kernel configuration scheme which was centered around a derived
33Makefile and a collection of derived header files generated by the
34config(8) program. This file describes the structure of the replacement
35"static" set of Makefiles.
36
37Some additional secondary goals were associated with the generation
38of these Makefiles.  It should be noted that the ability to properly
39deal with derived Makefiles is an explicit non-goal of the ongoing
40NSE enhancements, so this project is a necessary consequence of that
41decision.
42
43All project goals are enumerated below:
44
451]  To provide a set of static Makefiles to support kernel build
46    and installation.
47
482]  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
523]  To completely eliminate the config(8) program.
53
544]  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
585]  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
636]  To be able to "acquire" only the files needed to build a specific
64    module, if that is all that is needed.
65
667]  To provide a framework suitable for the production of "implementation
67    architecture" independent modules.
68
698]  To restructure the assembly language files to support the generation
70    of "lint-libraries" from them.
71
729]  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
77GENERAL STRUCTURE
78-----------------
79
80The source code layout is not generally effected by the Makefiles. However,
81the location of the generated files has changed dramatically.
82
83"Implementation architecture" independent modules are produced in
84individual directories (one per module) under the "instruction-set
85architecture" directory (i.e.: sparc). Similarly, "implementation
86architecture" dependent modules are produced in individual directories
87under the "implementation architecture" directory (i.e.: sun4, sun4c).
88It should be noted that currently (4/14/91) no implementation architecture
89modules exist. This situation is expected to change shortly.
90
91The driving Makefile for any module is located in the leaf directory
92where the module (and associated objects) are built. After a 'make
93clobber' operation, the Makefile is the only file remaining in that
94directory. Common definitions and rules are contained in suffixed
95Makefiles in non-leaf directories which are included in the leaf
96Makefiles. Non-suffixed Makefiles in non-leaf directories generally
97invoke lower level Makefiles to perform the actual tasks.
98
99uts/Makefile
100uts/sparc/Makefile
101uts/sun4c/Makefile
102uts/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
109uts/Makefile.uts
110	Contains common definitions for all possible architectures.
111
112uts/Makefile.targ
113	Contains common targets for all possible architectures.
114
115uts/common/Makefile.files
116uts/sun/Makefile.files
117uts/sparc/Makefile.files
118uts/sun4c/Makefile.files
119uts/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
127uts/common/Makefile.rules
128uts/sun/Makefile.rules
129uts/sparc/Makefile.rules
130uts/sun4c/Makefile.rules
131uts/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
136uts/sun4c/Makefile.sun4c
137uts/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
142uts/sun4c/unix/Makefile
143	Main driving Makefile for building /unix.
144
145uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
146	Main driving Makefile for building MODULE.kmod.
147
148uts/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
155uts/*/Makefile.?.shared
156	These denote Makefile contents which are shared between open and
157	closed builds.
158
159The Makefiles are verbosely commented. It is desired that they should
160stay this way.
161
162
163USE
164---
165
166Issuing the command 'make' in the uts directory will cause all supported,
167modularized kernels and modules to be built.
168
169Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
170will cause all supported, "implementation architecture" independent modules
171for ARCHITECTURE to be built.
172
173Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
174will cause that kernel and all supported, "implementation architecture"
175dependent modules for MACHINE to be built.
176
177Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
178kernel for MACHINE to be built (and unix.o).
179
180Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
181directory will cause MODULE.kmod to be built.
182
183
184LINT
185----
186
187Linting is fairly similar to the builds, but it has an additional complication.
188In order to get meaningful output from lint pass2, all the modules must be
189linted together. This is accomplished by each module being responsible to
190produce its own pass1 output (file.ln, one per .c/.s file). It is also
191responsible for placing the a lint-library (llib-lMODULE) in the
192uts/MACHINE/lint-libs directory. The final full lint is accomplished by the
193Makefile in the uts/MACHINE directory by linting all the lint-libraries
194against each other.
195
196Note that there is no equivalent to Locore.c in the current source base.
197The C prototypes are in the .s files. As example:
198
199	#if defined(lint)
200	int
201	blort(int, int)
202	{ return 0 }
203	#else	/* lint */
204
205		ENTRY(blort)
206		ld	[%i0],....
207		....
208		SET_SIZE(blort)
209
210	#endif	/* lint */
211
212
213COMPONENT HIERARCHY
214------------------
215
216The component hierarchy has been restructured to allow the acquisition of
217more finely grained objects; specificly a kernel module. The basic component
218structure is:
219
220	:src:uts.all --+--> :sparc --+--> :MODULES... (none currently)
221		       |
222		       +--> :sun4c --+--> :unix
223		       |             |
224		       |             +--> :MODULES...
225		       |             |
226		       |             +--> :unix.static
227		       |
228		       +--> :sun4 ---+--> :unix
229		       |             |
230		       |             +--> :MODULES...
231		       |             |
232		       |             +--> :unix.static
233		       ...
234
235The above diagram does not reflect the full component tree. The full component
236tree may be displayed with the "nsecomp list -r :src:uts.all" command.
237
238
239COMMON OPERATIONS
240-----------------
241
242Adding a New Kernel Module
243--------------------------
244
245    0]  Create the source files (and directories) as usual.
246
247    1]  Edit uts/*/Makefile.files to define the set of objects. By convention
248	the symbolic name of this set is of the form MODULE_OBJS, where
249	MODULE is the module name (i.e.: namefs). The files in each subtree
250	should be defined in the Makefile.files in the root directory of that
251	subtree. Note that they are defined using the += operator, so that
252	the set can be built across multiple files. As example:
253
254		NAMEFS_OBJS +=	namevfs.o namevno.o
255
256	Each source file needs a build rule in the corresponding Makefile.rules
257	file (compilation and lint). A typical pair of entries would be:
258
259		$(OBJS_DIR)/mem.o:		$(UTSBASE)/sun4c/io/mem.c
260			$(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
261
262		$(LINTS_DIR)/mem.ln:		$(UTSBASE)/sun4c/io/mem.c
263			@($(LHEAD) $(LINT.c) $(UTSBASE)/sun4c/io/mem.c $(LTAIL))
264
265    2]	Create build directories in the appropriate places. If the module
266	can be built in a machine independent way, this would be in the
267	"instruction set architecture" directory (i.e.: sparc). If not, these
268	directories would be created for all appropriate "implementation
269	architecture" dependent directories (i.e.: sun4, sun4c).
270
271    3]  In each build directory, create a Makefile. This can usually be
272	accomplished by copying a Makefile from a parallel directory and
273	editing the following lines (in addition to comments).
274
275		MODULE		= namefs
276			- replace with module name
277		OBJECTS		= $(NAMEFS_OBJS:%=$(OBJS_DIR)/%)
278		LINTS		= $(NAMEFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
279			- replace with MODULE_OBJS
280		ROOTMODULE	= $(ROOT_FS_DIR)/$(MODULE).kmod
281			- replace directory part with the appropriate
282			  installation directory name (see Makefile.uts)
283
284	If a custom version of modstubs.o is needed to check the undefines
285	for this routine, the following lines need to appear in the
286	Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)).
287
288		MODSTUBS_DIR	 = $(OBJS_DIR)
289		$(MODSTUBS_O)	:= AS_CPPFLAGS += -DNAMEFS_MODULE
290			- replace "-DNAMEFS_MODULE" with the appropriate flag
291			  for the modstubs.o assembly.
292		CLEANFILES	+= $(MODSTUBS_O)
293
294    4]  Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
295	the new module:
296
297		FS_KMODS	+= fd fifo namefs nfs proc spec ufs
298					   ------
299Any additional questions can be easily answered by looking at the many
300existing examples.
301
302
303Moving a Module to the "Implementation Architecture" Independent Build
304----------------------------------------------------------------------
305
306    1]  Create the build directory under the appropriate "instruction
307	set architecture" build directory (i.e.: sparc/MODULE).
308
309    2]  Move the Makefile from the "implementation architecture" build
310	directory (i.e.: sun4c/MODULE) to the directory created above.
311	Edit this Makefile to reflect the change of parent (trivial:
312	comments, paths and includes).
313
314    3]  Edit the "implementation architecture" directory Makefile (i.e.:
315	Makefile.sun4c) to *not* know about this module and edit the
316	"instruction set architecture" directory Makefile (i.e.:
317	Makefile.sparc) to know about it.
318
319