The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

Name Size Last modified (GMT) Description
Folder common/ 2010-12-21 10:04:28
Folder i86pc/ 2010-12-21 10:04:41
Folder i86xpv/ 2010-12-21 10:04:42
Folder intel/ 2010-12-21 10:04:42
Folder sfmmu/ 2007-05-07 15:18:19
Folder sparc/ 2010-12-21 10:04:43
Folder sun/ 2010-07-06 12:29:15
Folder sun4/ 2010-02-12 13:19:14
Folder sun4u/ 2010-07-06 12:29:17
Folder sun4v/ 2010-12-21 10:04:43
File Makefile 7128 bytes 2010-07-06 12:27:42
File Makefile.targ 14124 bytes 2010-12-21 10:04:28
File Makefile.uts 22831 bytes 2010-12-21 10:04:28
File OPENSOLARIS.LICENSE 18924 bytes 2010-12-21 10:05:37
File README 11807 bytes 2007-05-07 15:17:47
File req.flg 2090 bytes 2008-02-17 10:01:38

    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 uts/*/Makefile.?.shared
  156         These denote Makefile contents which are shared between open and
  157         closed builds.
  158 
  159 The Makefiles are verbosely commented. It is desired that they should
  160 stay this way.
  161 
  162 
  163 USE
  164 ---
  165 
  166 Issuing the command 'make' in the uts directory will cause all supported,
  167 modularized kernels and modules to be built.
  168 
  169 Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
  170 will cause all supported, "implementation architecture" independent modules
  171 for ARCHITECTURE to be built.
  172 
  173 Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
  174 will cause that kernel and all supported, "implementation architecture"
  175 dependent modules for MACHINE to be built.
  176 
  177 Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
  178 kernel for MACHINE to be built (and unix.o).
  179 
  180 Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
  181 directory will cause MODULE.kmod to be built.
  182 
  183 
  184 LINT
  185 ----
  186 
  187 Linting is fairly similar to the builds, but it has an additional complication.
  188 In order to get meaningful output from lint pass2, all the modules must be
  189 linted together. This is accomplished by each module being responsible to
  190 produce its own pass1 output (file.ln, one per .c/.s file). It is also
  191 responsible for placing the a lint-library (llib-lMODULE) in the
  192 uts/MACHINE/lint-libs directory. The final full lint is accomplished by the
  193 Makefile in the uts/MACHINE directory by linting all the lint-libraries
  194 against each other.
  195 
  196 Note that there is no equivalent to Locore.c in the current source base.
  197 The 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 
  213 COMPONENT HIERARCHY
  214 ------------------
  215 
  216 The component hierarchy has been restructured to allow the acquisition of
  217 more finely grained objects; specificly a kernel module. The basic component
  218 structure 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 
  235 The above diagram does not reflect the full component tree. The full component
  236 tree may be displayed with the "nsecomp list -r :src:uts.all" command.
  237 
  238 
  239 COMMON OPERATIONS
  240 -----------------
  241 
  242 Adding 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                                            ------
  299 Any additional questions can be easily answered by looking at the many
  300 existing examples.
  301 
  302 
  303 Moving 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 

[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.