Name Date Size #Lines LOC

..13-Nov-2023-

common/H16-Feb-2024-

i86pc/H25-Aug-2023-

i86xpv/H03-Nov-2023-

intel/H16-Feb-2024-

sfmmu/H17-Apr-2023-

sparc/H13-Dec-2023-

sun/H17-Apr-2023-

sun4/H17-Apr-2023-

sun4u/H01-Jun-2023-

sun4v/H01-Jun-2023-

MakefileH A D17-Apr-20236.3 KiB21992

Makefile.mapfileH A D10-Dec-20211.5 KiB507

Makefile.targH A D17-Apr-202311.4 KiB435245

Makefile.utsH A D01-Jun-202320 KiB614317

READMEH A D14-Feb-202111.4 KiB314243

req.flgH A D14-Feb-20212.1 KiB6327

README

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