Unleashed v1.4
[unleashed.git] / usr / src / uts / README
blobda2324864e862ff2859f4b314dd7e66b8fa789fa
2 # CDDL HEADER START
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.
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.
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]
19 # CDDL HEADER END
23 # Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
24 # Use is subject to license terms.
27 KERNEL MAKEFILE STRUCTURE
28 -------------------------
30 The advent of dynamic loading of kernel modules has obsoleted the
31 4.x kernel configuration scheme which was centered around a derived
32 Makefile and a collection of derived header files generated by the
33 config(8) program. This file describes the structure of the replacement
34 "static" set of Makefiles.
36 Some additional secondary goals were associated with the generation
37 of these Makefiles.  It should be noted that the ability to properly
38 deal with derived Makefiles is an explicit non-goal of the ongoing
39 NSE enhancements, so this project is a necessary consequence of that
40 decision.
42 All project goals are enumerated below:
44 1]  To provide a set of static Makefiles to support kernel build
45     and installation.
47 2]  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")
51 3]  To completely eliminate the config(8) program.
53 4]  To eliminate the need for the small headers generated by config(8).
54     In the ddi/dki world this need is completely eliminated as drivers
55     will be expected to dynamically configure themselves. Interim support
56     for existing drivers will be provided.
58 5]  To be able to "acquire" only the files needed to build a specific
59     module, if that is all that is needed.
61 6]  To provide a framework suitable for the production of "implementation
62     architecture" independent modules.
64 7]  To provide support for the incidental Makefile targets many developers
65     are accustomed to (such as cscope and tags). These can be added to the
66     Makefiles asd required. (cscope is currently supported.)
69 GENERAL STRUCTURE
70 -----------------
72 The source code layout is not generally effected by the Makefiles. However,
73 the location of the generated files has changed dramatically.
75 "Implementation architecture" independent modules are produced in
76 individual directories (one per module) under the "instruction-set
77 architecture" directory (i.e.: sparc). Similarly, "implementation
78 architecture" dependent modules are produced in individual directories
79 under the "implementation architecture" directory (i.e.: sun4, sun4c).
80 It should be noted that currently (4/14/91) no implementation architecture
81 modules exist. This situation is expected to change shortly.
83 The driving Makefile for any module is located in the leaf directory
84 where the module (and associated objects) are built. After a 'make
85 clobber' operation, the Makefile is the only file remaining in that
86 directory. Common definitions and rules are contained in suffixed
87 Makefiles in non-leaf directories which are included in the leaf
88 Makefiles. Non-suffixed Makefiles in non-leaf directories generally
89 invoke lower level Makefiles to perform the actual tasks.
91 uts/Makefile
92 uts/sparc/Makefile
93 uts/sun4c/Makefile
94         These Makefiles generally are cognizant of the components
95         made in subdirectories and invoke Makefiles in those sub-
96         directories to perform the actual build. Some targets (or
97         pseudo-targets) may be directly built at this level (such
98         as the cscope databases).
100 uts/Makefile.uts
101         Contains common definitions for all possible architectures.
103 uts/Makefile.targ
104         Contains common targets for all possible architectures.
106 uts/common/Makefile.files
107 uts/sun/Makefile.files
108 uts/sparc/Makefile.files
109 uts/sun4c/Makefile.files
110 uts/sun4/Makefile.files
111         These Makefiles are divided into two sections. The first
112         section can be viewed as the equivalent of the "files" (sparc
113         and sun4c) and "files.cmn" (common and sun) files. These
114         define the object lists which define each module. The second
115         section defines the appropriate header search paths and other
116         machine specific global build parameters.
118 uts/common/Makefile.rules
119 uts/sun/Makefile.rules
120 uts/sparc/Makefile.rules
121 uts/sun4c/Makefile.rules
122 uts/sun4/Makefile.rules
123         The files provide build rules (targets) which allow make to function
124         in a multiple directory environment. Each source tree below the
125         directory containing the Makefile has a build rule in the file.
127 uts/sun4c/Makefile.sun4c
128 uts/sun4/Makefile.sun4
129         These Makefile contains the definitions specific (defaults) to
130         the obvious "implementation architecture". These rules can be
131         overridden in specific leaf node Makefiles if necessary.
133 uts/sun4c/unix/Makefile
134         Main driving Makefile for building /unix.
136 uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
137         Main driving Makefile for building MODULE.kmod.
139 uts/sun4c/unix.static/Makefile
140         Main driving Makefile for building a static unix (for development
141         work only). This Makefile is known to NSE, but its targets are
142         not. This makefile may be copied to additional parallel directories
143         to build multiple configurations. This configuration is roughly
144         equivalent to the GENERIC kernel of SunOS 4.x.
146 The Makefiles are verbosely commented. It is desired that they should
147 stay this way.
153 Issuing the command 'make' in the uts directory will cause all supported,
154 modularized kernels and modules to be built.
156 Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
157 will cause all supported, "implementation architecture" independent modules
158 for ARCHITECTURE to be built.
160 Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
161 will cause that kernel and all supported, "implementation architecture"
162 dependent modules for MACHINE to be built.
164 Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
165 kernel for MACHINE to be built (and unix.o).
167 Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
168 directory will cause MODULE.kmod to be built.
171 COMPONENT HIERARCHY
172 ------------------
174 The component hierarchy has been restructured to allow the acquisition of
175 more finely grained objects; specificly a kernel module. The basic component
176 structure is:
178         :src:uts.all --+--> :sparc --+--> :MODULES... (none currently)
179                        |
180                        +--> :sun4c --+--> :unix
181                        |             |
182                        |             +--> :MODULES...
183                        |             |
184                        |             +--> :unix.static
185                        |
186                        +--> :sun4 ---+--> :unix
187                        |             |
188                        |             +--> :MODULES...
189                        |             |
190                        |             +--> :unix.static
191                        ...
193 The above diagram does not reflect the full component tree. The full component
194 tree may be displayed with the "nsecomp list -r :src:uts.all" command.
197 COMMON OPERATIONS
198 -----------------
200 Adding a New Kernel Module
201 --------------------------
203     0]  Create the source files (and directories) as usual.
205     1]  Edit uts/*/Makefile.files to define the set of objects. By convention
206         the symbolic name of this set is of the form MODULE_OBJS, where
207         MODULE is the module name (i.e.: namefs). The files in each subtree
208         should be defined in the Makefile.files in the root directory of that
209         subtree. Note that they are defined using the += operator, so that
210         the set can be built across multiple files. As example:
212                 NAMEFS_OBJS +=  namevfs.o namevno.o
214         Each source file needs a build rule in the corresponding Makefile.rules
215         file. A typical entry would be:
217                 $(OBJS_DIR)/mem.o:              $(UTSBASE)/sun4c/io/mem.c
218                         $(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
220     2]  Create build directories in the appropriate places. If the module
221         can be built in a machine independent way, this would be in the
222         "instruction set architecture" directory (i.e.: sparc). If not, these
223         directories would be created for all appropriate "implementation
224         architecture" dependent directories (i.e.: sun4, sun4c).
226     3]  In each build directory, create a Makefile. This can usually be
227         accomplished by copying a Makefile from a parallel directory and
228         editing the following lines (in addition to comments).
230                 MODULE          = namefs
231                         - replace with module name 
232                 OBJECTS         = $(NAMEFS_OBJS:%=$(OBJS_DIR)/%)
233                         - replace with MODULE_OBJS
234                 ROOTMODULE      = $(ROOT_FS_DIR)/$(MODULE).kmod
235                         - replace directory part with the appropriate
236                           installation directory name (see Makefile.uts)
238         If a custom version of modstubs.o is needed to check the undefines
239         for this routine, the following lines need to appear in the
240         Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)).
242                 MODSTUBS_DIR     = $(OBJS_DIR)
243                 $(MODSTUBS_O)   := AS_CPPFLAGS += -DNAMEFS_MODULE
244                         - replace "-DNAMEFS_MODULE" with the appropriate flag
245                           for the modstubs.o assembly.
246                 CLEANFILES      += $(MODSTUBS_O)
248     4]  Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
249         the new module:
251                 FS_KMODS        += fd fifo namefs nfs proc spec ufs
252                                            ------
253 Any additional questions can be easily answered by looking at the many
254 existing examples.
257 Moving a Module to the "Implementation Architecture" Independent Build
258 ----------------------------------------------------------------------
260     1]  Create the build directory under the appropriate "instruction
261         set architecture" build directory (i.e.: sparc/MODULE).
263     2]  Move the Makefile from the "implementation architecture" build
264         directory (i.e.: sun4c/MODULE) to the directory created above.
265         Edit this Makefile to reflect the change of parent (trivial:
266         comments, paths and includes).
268     3]  Edit the "implementation architecture" directory Makefile (i.e.:
269         Makefile.sun4c) to *not* know about this module and edit the
270         "instruction set architecture" directory Makefile (i.e.:
271         Makefile.sparc) to know about it.