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, Version 1.0 only 6# (the "License"). You may not use this file except in compliance 7# with the License. 8# 9# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10# or http://www.opensolaris.org/os/licensing. 11# See the License for the specific language governing permissions 12# and limitations under the License. 13# 14# When distributing Covered Code, include this CDDL HEADER in each 15# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16# If applicable, add the following below this CDDL HEADER, with the 17# fields enclosed by brackets "[]" replaced with your own identifying 18# information: Portions Copyright [yyyy] [name of copyright owner] 19# 20# CDDL HEADER END 21# 22# Copyright 2005 Sun Microsystems, Inc. All rights reserved. 23# Use is subject to license terms. 24# 25#ident "%Z%%M% %I% %E% SMI" 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 154uts/*/Makefile.?.shared 155 These denote Makefile contents which are shared between open and 156 closed builds. 157 158The Makefiles are verbosely commented. It is desired that they should 159stay this way. 160 161 162USE 163--- 164 165Issuing the command 'make' in the uts directory will cause all supported, 166modularized kernels and modules to be built. 167 168Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc) 169will cause all supported, "implementation architecture" independent modules 170for ARCHITECTURE to be built. 171 172Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c) 173will cause that kernel and all supported, "implementation architecture" 174dependent modules for MACHINE to be built. 175 176Issuing the command 'make' in the uts/MACHINE/unix directory will cause the 177kernel for MACHINE to be built (and unix.o). 178 179Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE 180directory will cause MODULE.kmod to be built. 181 182 183LINT 184---- 185 186Linting is fairly similar to the builds, but it has an additional complication. 187In order to get meaningful output from lint pass2, all the modules must be 188linted together. This is accomplished by each module being responsible to 189produce its own pass1 output (file.ln, one per .c/.s file). It is also 190responsible for placing the a lint-library (llib-lMODULE) in the 191uts/MACHINE/lint-libs directory. The final full lint is accomplished by the 192Makefile in the uts/MACHINE directory by linting all the lint-libraries 193against each other. 194 195Note that there is no equivalent to Locore.c in the current source base. 196The C prototypes are in the .s files. As example: 197 198 #if defined(lint) 199 int 200 blort(int, int) 201 { return 0 } 202 #else /* lint */ 203 204 ENTRY(blort) 205 ld [%i0],.... 206 .... 207 SET_SIZE(blort) 208 209 #endif /* lint */ 210 211 212COMPONENT HIERARCHY 213------------------ 214 215The component hierarchy has been restructured to allow the acquisition of 216more finely grained objects; specificly a kernel module. The basic component 217structure is: 218 219 :src:uts.all --+--> :sparc --+--> :MODULES... (none currently) 220 | 221 +--> :sun4c --+--> :unix 222 | | 223 | +--> :MODULES... 224 | | 225 | +--> :unix.static 226 | 227 +--> :sun4 ---+--> :unix 228 | | 229 | +--> :MODULES... 230 | | 231 | +--> :unix.static 232 ... 233 234The above diagram does not reflect the full component tree. The full component 235tree may be displayed with the "nsecomp list -r :src:uts.all" command. 236 237 238COMMON OPERATIONS 239----------------- 240 241Adding a New Kernel Module 242-------------------------- 243 244 0] Create the source files (and directories) as usual. 245 246 1] Edit uts/*/Makefiles.files to define the set of objects. By convention 247 the symbolic name of this set is of the form MODULE_OBJS, where 248 MODULE is the module name (i.e.: namefs). The files in each subtree 249 should be defined in the Makefile.files in the root directory of that 250 subtree. Note that they are defined using the += operator, so that 251 the set can be built across multiple files. As example: 252 253 NAMEFS_OBJS += namevfs.o namevno.o 254 255 Each source file needs a build rule in the corresponding Makefile.rules 256 file (compilation and lint). A typical pair of entries would be: 257 258 $(OBJS_DIR)/mem.o: $(UTSBASE)/sun4c/io/mem.c 259 $(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c 260 261 $(LINTS_DIR)/mem.ln: $(UTSBASE)/sun4c/io/mem.c 262 @($(LHEAD) $(LINT.c) $(UTSBASE)/sun4c/io/mem.c $(LTAIL)) 263 264 2] Create build directories in the appropriate places. If the module 265 can be built in a machine independent way, this would be in the 266 "instruction set architecture" directory (i.e.: sparc). If not, these 267 directories would be created for all appropriate "implementation 268 architecture" dependent directories (i.e.: sun4, sun4c). 269 270 3] In each build directory, create a Makefile. This can usually be 271 accomplished by copying a Makefile from a parallel directory and 272 editing the following lines (in addition to comments). 273 274 MODULE = namefs 275 - replace with module name 276 OBJECTS = $(NAMEFS_OBJS:%=$(OBJS_DIR)/%) 277 LINTS = $(NAMEFS_OBJS:%.o=$(LINTS_DIR)/%.ln) 278 - replace with MODULE_OBJS 279 ROOTMODULE = $(ROOT_FS_DIR)/$(MODULE).kmod 280 - replace directory part with the appropriate 281 installation directory name (see Makefile.uts) 282 283 If a custom version of modstubs.o is needed to check the undefines 284 for this routine, the following lines need to appear in the 285 Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)). 286 287 MODSTUBS_DIR = $(OBJS_DIR) 288 $(MODSTUBS_O) := AS_CPPFLAGS += -DNAMEFS_MODULE 289 - replace "-DNAMEFS_MODULE" with the appropriate flag 290 for the modstubs.o assembly. 291 CLEANFILES += $(MODSTUBS_O) 292 293 4] Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about 294 the new module: 295 296 FS_KMODS += fd fifo namefs nfs proc spec ufs 297 ------ 298 299 5] Add the appropriate components using nsecomp. Continuing with 300 the namefs example: 301 302 $ nsecomp add :src:uts.all:sun4c Comp namefs 303 $ nsecomp add :src:uts.all:sun4c:namefs Targ \ 304 all%/usr/src/uts/sun4c/namefs/Makefile 305 306 This needs to be done for all appropriate "implementation 307 architectures". 308 309Any additional questions can be easily answered by looking at the many 310existing examples. 311 312 313Moving a Module to the "Implementation Architecture" Independent Build 314---------------------------------------------------------------------- 315 316 1] Create the build directory under the appropriate "instruction 317 set architecture" build directory (i.e.: sparc/MODULE). 318 319 2] Move the Makefile from the "implementation architecture" build 320 directory (i.e.: sun4c/MODULE) to the directory created above. 321 Edit this Makefile to reflect the change of parent (trivial: 322 comments, paths and includes). 323 324 3] Edit the "implementation architecture" directory Makefile (i.e.: 325 Makefile.sun4c) to *not* know about this module and edit the 326 "instruction set architecture" directory Makefile (i.e.: 327 Makefile.sparc) to know about it. 328 329