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