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 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.
  57
  58 5]  To be able to "acquire" only the files needed to build a specific
  59     module, if that is all that is needed.
  60
  61 6]  To provide a framework suitable for the production of "implementation
  62     architecture" independent modules.
  63
  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.)
  67
  68
  69 GENERAL STRUCTURE
  70 -----------------
  71
  72 The source code layout is not generally effected by the Makefiles. However,
  73 the location of the generated files has changed dramatically.
  74
  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.
  82
  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.
  90
  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).
  99
 100 uts/Makefile.uts
 101         Contains common definitions for all possible architectures.
 102
 103 uts/Makefile.targ
 104         Contains common targets for all possible architectures.
 105
 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.
 117
 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.
 126
 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.
 132
 133 uts/sun4c/unix/Makefile
 134         Main driving Makefile for building /unix.
 135
 136 uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
 137         Main driving Makefile for building MODULE.kmod.
 138
 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.
 145
 146 The Makefiles are verbosely commented. It is desired that they should
 147 stay this way.
 148
 149
 150 USE
 151 ---
 152
 153 Issuing the command 'make' in the uts directory will cause all supported,
 154 modularized kernels and modules to be built.
 155
 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.
 159
 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.
 163
 164 Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
 165 kernel for MACHINE to be built (and unix.o).
 166
 167 Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
 168 directory will cause MODULE.kmod to be built.
 169
 170
 171 COMPONENT HIERARCHY
 172 ------------------
 173
 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:
 177
 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                        ...
 192
 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.
 195
 196
 197 COMMON OPERATIONS
 198 -----------------
 199
 200 Adding a New Kernel Module
 201 --------------------------
 202
 203     0]  Create the source files (and directories) as usual.
 204
 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:
 211
 212                 NAMEFS_OBJS +=  namevfs.o namevno.o
 213
 214         Each source file needs a build rule in the corresponding Makefile.rules
 215         file. A typical entry would be:
 216
 217                 $(OBJS_DIR)/mem.o:              $(UTSBASE)/sun4c/io/mem.c
 218                         $(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
 219
 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).
 225
 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).
 229
 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)
 237
 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)).
 241
 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)
 247
 248     4]  Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
 249         the new module:
 250
 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.
 255
 256
 257 Moving a Module to the "Implementation Architecture" Independent Build
 258 ----------------------------------------------------------------------
 259
 260     1]  Create the build directory under the appropriate "instruction
 261         set architecture" build directory (i.e.: sparc/MODULE).
 262
 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).
 267
 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.
 272