usr/src/uts/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
  27 KERNEL MAKEFILE STRUCTURE
  28 -------------------------
  29
  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.
  35
  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.
  41
  42 All project goals are enumerated below:
  43
  44 1]  To provide a set of static Makefiles to support kernel build
  45     and installation.
  46
  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")
  50
  51 3]  To completely eliminate the config(8) program.
  52
  53 4]  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
  57 5]  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
  62 6]  To be able to "acquire" only the files needed to build a specific
  63     module, if that is all that is needed.
  64
  65 7]  To provide a framework suitable for the production of "implementation
  66     architecture" independent modules.
  67
  68 8]  To restructure the assembly language files to support the generation
  69     of "lint-libraries" from them.
  70
  71 9]  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
  76 GENERAL STRUCTURE
  77 -----------------
  78
  79 The source code layout is not generally effected by the Makefiles. However,
  80 the location of the generated files has changed dramatically.
  81
  82 "Implementation architecture" independent modules are produced in
  83 individual directories (one per module) under the "instruction-set
  84 architecture" directory (i.e.: sparc). Similarly, "implementation
  85 architecture" dependent modules are produced in individual directories
  86 under the "implementation architecture" directory (i.e.: sun4, sun4c).
  87 It should be noted that currently (4/14/91) no implementation architecture
  88 modules exist. This situation is expected to change shortly.
  89
  90 The driving Makefile for any module is located in the leaf directory
  91 where the module (and associated objects) are built. After a 'make
  92 clobber' operation, the Makefile is the only file remaining in that
  93 directory. Common definitions and rules are contained in suffixed
  94 Makefiles in non-leaf directories which are included in the leaf
  95 Makefiles. Non-suffixed Makefiles in non-leaf directories generally
  96 invoke lower level Makefiles to perform the actual tasks.
  97
  98 uts/Makefile
  99 uts/sparc/Makefile
 100 uts/sun4c/Makefile
 101 uts/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
 108 uts/Makefile.uts
 109         Contains common definitions for all possible architectures.
 110
 111 uts/Makefile.targ
 112         Contains common targets for all possible architectures.
 113
 114 uts/common/Makefile.files
 115 uts/sun/Makefile.files
 116 uts/sparc/Makefile.files
 117 uts/sun4c/Makefile.files
 118 uts/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
 126 uts/common/Makefile.rules
 127 uts/sun/Makefile.rules
 128 uts/sparc/Makefile.rules
 129 uts/sun4c/Makefile.rules
 130 uts/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
 135 uts/sun4c/Makefile.sun4c
 136 uts/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
 141 uts/sun4c/unix/Makefile
 142         Main driving Makefile for building /unix.
 143
 144 uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
 145         Main driving Makefile for building MODULE.kmod.
 146
 147 uts/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
 154 The Makefiles are verbosely commented. It is desired that they should
 155 stay this way.
 156
 157
 158 USE
 159 ---
 160
 161 Issuing the command 'make' in the uts directory will cause all supported,
 162 modularized kernels and modules to be built.
 163
 164 Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
 165 will cause all supported, "implementation architecture" independent modules
 166 for ARCHITECTURE to be built.
 167
 168 Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
 169 will cause that kernel and all supported, "implementation architecture"
 170 dependent modules for MACHINE to be built.
 171
 172 Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
 173 kernel for MACHINE to be built (and unix.o).
 174
 175 Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
 176 directory will cause MODULE.kmod to be built.
 177
 178
 179 LINT
 180 ----
 181
 182 Linting is fairly similar to the builds, but it has an additional complication.
 183 In order to get meaningful output from lint pass2, all the modules must be
 184 linted together. This is accomplished by each module being responsible to
 185 produce its own pass1 output (file.ln, one per .c/.s file). It is also
 186 responsible for placing the a lint-library (llib-lMODULE) in the
 187 uts/MACHINE/lint-libs directory. The final full lint is accomplished by the
 188 Makefile in the uts/MACHINE directory by linting all the lint-libraries
 189 against each other.
 190
 191 Note that there is no equivalent to Locore.c in the current source base.
 192 The 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
 208 COMPONENT HIERARCHY
 209 ------------------
 210
 211 The component hierarchy has been restructured to allow the acquisition of
 212 more finely grained objects; specificly a kernel module. The basic component
 213 structure 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
 230 The above diagram does not reflect the full component tree. The full component
 231 tree may be displayed with the "nsecomp list -r :src:uts.all" command.
 232
 233
 234 COMMON OPERATIONS
 235 -----------------
 236
 237 Adding 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                                            ------
 294 Any additional questions can be easily answered by looking at the many
 295 existing examples.
 296
 297
 298 Moving 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