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