Home | History | Annotate | Download | only in uts
      1     0    stevel #
      2     0    stevel # CDDL HEADER START
      3     0    stevel #
      4     0    stevel # The contents of this file are subject to the terms of the
      5  3957  th199096 # Common Development and Distribution License (the "License").
      6  3957  th199096 # You may not use this file except in compliance with the License.
      7     0    stevel #
      8     0    stevel # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
      9     0    stevel # or http://www.opensolaris.org/os/licensing.
     10     0    stevel # See the License for the specific language governing permissions
     11     0    stevel # and limitations under the License.
     12     0    stevel #
     13     0    stevel # When distributing Covered Code, include this CDDL HEADER in each
     14     0    stevel # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     15     0    stevel # If applicable, add the following below this CDDL HEADER, with the
     16     0    stevel # fields enclosed by brackets "[]" replaced with your own identifying
     17     0    stevel # information: Portions Copyright [yyyy] [name of copyright owner]
     18     0    stevel #
     19     0    stevel # CDDL HEADER END
     20     0    stevel #
     21  3957  th199096 
     22  3957  th199096 #
     23  3957  th199096 # Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
     24     0    stevel # Use is subject to license terms.
     25     0    stevel #
     26  3957  th199096 # ident	"%Z%%M%	%I%	%E% SMI"
     27     0    stevel 
     28     0    stevel KERNEL MAKEFILE STRUCTURE
     29     0    stevel -------------------------
     30     0    stevel 
     31     0    stevel The advent of dynamic loading of kernel modules has obsoleted the
     32     0    stevel 4.x kernel configuration scheme which was centered around a derived
     33     0    stevel Makefile and a collection of derived header files generated by the
     34     0    stevel config(8) program. This file describes the structure of the replacement
     35     0    stevel "static" set of Makefiles.
     36     0    stevel 
     37     0    stevel Some additional secondary goals were associated with the generation
     38     0    stevel of these Makefiles.  It should be noted that the ability to properly
     39     0    stevel deal with derived Makefiles is an explicit non-goal of the ongoing
     40     0    stevel NSE enhancements, so this project is a necessary consequence of that
     41     0    stevel decision.
     42     0    stevel 
     43     0    stevel All project goals are enumerated below:
     44     0    stevel 
     45     0    stevel 1]  To provide a set of static Makefiles to support kernel build
     46     0    stevel     and installation.
     47     0    stevel 
     48     0    stevel 2]  To provide a set of static Makefiles which conform to the
     49     0    stevel     "Makefiles Guidelines".  (This document is currently available
     50     0    stevel     on-line as "terminator:/usr/integration/doc/make.std")
     51     0    stevel 
     52     0    stevel 3]  To completely eliminate the config(8) program.
     53     0    stevel 
     54     0    stevel 4]  To provide a framework for linting the kernel (so that "lint free"
     55     0    stevel     can be made an integration criterion, in addition to being general
     56     0    stevel     good hygiene).
     57     0    stevel 
     58     0    stevel 5]  To eliminate the need for the small headers generated by config(8).
     59     0    stevel     In the ddi/dki world this need is completely eliminated as drivers
     60     0    stevel     will be expected to dynamically configure themselves. Interim support
     61     0    stevel     for existing drivers will be provided.
     62     0    stevel 
     63     0    stevel 6]  To be able to "acquire" only the files needed to build a specific
     64     0    stevel     module, if that is all that is needed.
     65     0    stevel 
     66     0    stevel 7]  To provide a framework suitable for the production of "implementation
     67     0    stevel     architecture" independent modules.
     68     0    stevel 
     69     0    stevel 8]  To restructure the assembly language files to support the generation
     70     0    stevel     of "lint-libraries" from them.
     71     0    stevel 
     72     0    stevel 9]  To provide support for the incidental Makefile targets many developers
     73     0    stevel     are accustomed to (such as cscope and tags). These can be added to the
     74     0    stevel     Makefiles asd required. (cscope is currently supported.)
     75     0    stevel 
     76     0    stevel 
     77     0    stevel GENERAL STRUCTURE
     78     0    stevel -----------------
     79     0    stevel 
     80     0    stevel The source code layout is not generally effected by the Makefiles. However,
     81     0    stevel the location of the generated files has changed dramatically.
     82     0    stevel 
     83     0    stevel "Implementation architecture" independent modules are produced in
     84     0    stevel individual directories (one per module) under the "instruction-set
     85     0    stevel architecture" directory (i.e.: sparc). Similarly, "implementation
     86     0    stevel architecture" dependent modules are produced in individual directories
     87     0    stevel under the "implementation architecture" directory (i.e.: sun4, sun4c).
     88     0    stevel It should be noted that currently (4/14/91) no implementation architecture
     89     0    stevel modules exist. This situation is expected to change shortly.
     90     0    stevel 
     91     0    stevel The driving Makefile for any module is located in the leaf directory
     92     0    stevel where the module (and associated objects) are built. After a 'make
     93     0    stevel clobber' operation, the Makefile is the only file remaining in that
     94     0    stevel directory. Common definitions and rules are contained in suffixed
     95     0    stevel Makefiles in non-leaf directories which are included in the leaf
     96     0    stevel Makefiles. Non-suffixed Makefiles in non-leaf directories generally
     97     0    stevel invoke lower level Makefiles to perform the actual tasks.
     98     0    stevel 
     99     0    stevel uts/Makefile
    100     0    stevel uts/sparc/Makefile
    101     0    stevel uts/sun4c/Makefile
    102     0    stevel uts/sun4c/svvs/Makefile
    103     0    stevel 	These Makefiles generally are cognizant of the components
    104     0    stevel 	made in subdirectories and invoke Makefiles in those sub-
    105     0    stevel 	directories to perform the actual build. Some targets (or
    106     0    stevel 	pseudo-targets) may be directly built at this level (such
    107     0    stevel 	as the cscope databases).
    108     0    stevel 
    109     0    stevel uts/Makefile.uts
    110     0    stevel 	Contains common definitions for all possible architectures.
    111     0    stevel 
    112     0    stevel uts/Makefile.targ
    113     0    stevel 	Contains common targets for all possible architectures.
    114     0    stevel 
    115     0    stevel uts/common/Makefile.files
    116     0    stevel uts/sun/Makefile.files
    117     0    stevel uts/sparc/Makefile.files
    118     0    stevel uts/sun4c/Makefile.files
    119     0    stevel uts/sun4/Makefile.files
    120     0    stevel 	These Makefiles are divided into two sections. The first
    121     0    stevel 	section can be viewed as the equivalent of the "files" (sparc
    122     0    stevel 	and sun4c) and "files.cmn" (common and sun) files. These
    123     0    stevel 	define the object lists which define each module. The second
    124     0    stevel 	section defines the appropriate header search paths and other
    125     0    stevel 	machine specific global build parameters.
    126     0    stevel 
    127     0    stevel uts/common/Makefile.rules
    128     0    stevel uts/sun/Makefile.rules
    129     0    stevel uts/sparc/Makefile.rules
    130     0    stevel uts/sun4c/Makefile.rules
    131     0    stevel uts/sun4/Makefile.rules
    132     0    stevel 	The files provide build rules (targets) which allow make to function
    133     0    stevel 	in a multiple directory environment. Each source tree below the
    134     0    stevel 	directory containing the Makefile has a build rule in the file.
    135     0    stevel 
    136     0    stevel uts/sun4c/Makefile.sun4c
    137     0    stevel uts/sun4/Makefile.sun4
    138     0    stevel 	These Makefile contains the definitions specific (defaults) to
    139     0    stevel 	the obvious "implementation architecture". These rules can be
    140     0    stevel 	overridden in specific leaf node Makefiles if necessary.
    141     0    stevel 
    142     0    stevel uts/sun4c/unix/Makefile
    143     0    stevel 	Main driving Makefile for building /unix.
    144     0    stevel 
    145     0    stevel uts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
    146     0    stevel 	Main driving Makefile for building MODULE.kmod.
    147     0    stevel 
    148     0    stevel uts/sun4c/unix.static/Makefile
    149     0    stevel 	Main driving Makefile for building a static unix (for development
    150     0    stevel 	work only). This Makefile is known to NSE, but its targets are
    151     0    stevel 	not. This makefile may be copied to additional parallel directories
    152     0    stevel 	to build multiple configurations. This configuration is roughly
    153     0    stevel 	equivalent to the GENERIC kernel of SunOS 4.x.
    154     0    stevel 
    155  1167    kupfer uts/*/Makefile.?.shared
    156  1167    kupfer 	These denote Makefile contents which are shared between open and
    157  1167    kupfer 	closed builds.
    158  1167    kupfer 
    159     0    stevel The Makefiles are verbosely commented. It is desired that they should
    160     0    stevel stay this way.
    161     0    stevel 
    162     0    stevel 
    163     0    stevel USE
    164     0    stevel ---
    165     0    stevel 
    166     0    stevel Issuing the command 'make' in the uts directory will cause all supported,
    167     0    stevel modularized kernels and modules to be built.
    168     0    stevel 
    169     0    stevel Issuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
    170     0    stevel will cause all supported, "implementation architecture" independent modules
    171     0    stevel for ARCHITECTURE to be built.
    172     0    stevel 
    173     0    stevel Issuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
    174     0    stevel will cause that kernel and all supported, "implementation architecture"
    175     0    stevel dependent modules for MACHINE to be built.
    176     0    stevel 
    177     0    stevel Issuing the command 'make' in the uts/MACHINE/unix directory will cause the
    178     0    stevel kernel for MACHINE to be built (and unix.o).
    179     0    stevel 
    180     0    stevel Issuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
    181     0    stevel directory will cause MODULE.kmod to be built.
    182     0    stevel 
    183     0    stevel 
    184     0    stevel LINT
    185     0    stevel ----
    186     0    stevel 
    187     0    stevel Linting is fairly similar to the builds, but it has an additional complication.
    188     0    stevel In order to get meaningful output from lint pass2, all the modules must be
    189     0    stevel linted together. This is accomplished by each module being responsible to
    190     0    stevel produce its own pass1 output (file.ln, one per .c/.s file). It is also
    191     0    stevel responsible for placing the a lint-library (llib-lMODULE) in the
    192     0    stevel uts/MACHINE/lint-libs directory. The final full lint is accomplished by the
    193     0    stevel Makefile in the uts/MACHINE directory by linting all the lint-libraries
    194     0    stevel against each other.
    195     0    stevel 
    196     0    stevel Note that there is no equivalent to Locore.c in the current source base.
    197     0    stevel The C prototypes are in the .s files. As example:
    198     0    stevel 
    199     0    stevel 	#if defined(lint)
    200     0    stevel 	int
    201     0    stevel 	blort(int, int)
    202     0    stevel 	{ return 0 }
    203     0    stevel 	#else	/* lint */
    204     0    stevel 
    205     0    stevel 		ENTRY(blort)
    206     0    stevel 		ld	[%i0],....
    207     0    stevel 		....
    208     0    stevel 		SET_SIZE(blort)
    209     0    stevel 
    210     0    stevel 	#endif	/* lint */
    211     0    stevel 
    212     0    stevel 
    213     0    stevel COMPONENT HIERARCHY
    214     0    stevel ------------------
    215     0    stevel 
    216     0    stevel The component hierarchy has been restructured to allow the acquisition of
    217     0    stevel more finely grained objects; specificly a kernel module. The basic component
    218     0    stevel structure is:
    219     0    stevel 
    220     0    stevel 	:src:uts.all --+--> :sparc --+--> :MODULES... (none currently)
    221     0    stevel 		       |
    222     0    stevel 		       +--> :sun4c --+--> :unix
    223     0    stevel 		       |             |
    224     0    stevel 		       |             +--> :MODULES...
    225     0    stevel 		       |             |
    226     0    stevel 		       |             +--> :unix.static
    227     0    stevel 		       |
    228     0    stevel 		       +--> :sun4 ---+--> :unix
    229     0    stevel 		       |             |
    230     0    stevel 		       |             +--> :MODULES...
    231     0    stevel 		       |             |
    232     0    stevel 		       |             +--> :unix.static
    233     0    stevel 		       ...
    234     0    stevel 
    235     0    stevel The above diagram does not reflect the full component tree. The full component
    236     0    stevel tree may be displayed with the "nsecomp list -r :src:uts.all" command.
    237     0    stevel 
    238     0    stevel 
    239     0    stevel COMMON OPERATIONS
    240     0    stevel -----------------
    241     0    stevel 
    242     0    stevel Adding a New Kernel Module
    243     0    stevel --------------------------
    244     0    stevel 
    245     0    stevel     0]  Create the source files (and directories) as usual.
    246     0    stevel 
    247  3957  th199096     1]  Edit uts/*/Makefile.files to define the set of objects. By convention
    248     0    stevel 	the symbolic name of this set is of the form MODULE_OBJS, where
    249     0    stevel 	MODULE is the module name (i.e.: namefs). The files in each subtree
    250     0    stevel 	should be defined in the Makefile.files in the root directory of that
    251     0    stevel 	subtree. Note that they are defined using the += operator, so that
    252     0    stevel 	the set can be built across multiple files. As example:
    253     0    stevel 
    254     0    stevel 		NAMEFS_OBJS +=	namevfs.o namevno.o
    255     0    stevel 
    256     0    stevel 	Each source file needs a build rule in the corresponding Makefile.rules
    257     0    stevel 	file (compilation and lint). A typical pair of entries would be:
    258     0    stevel 
    259     0    stevel 		$(OBJS_DIR)/mem.o:		$(UTSBASE)/sun4c/io/mem.c
    260     0    stevel 			$(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
    261     0    stevel 
    262     0    stevel 		$(LINTS_DIR)/mem.ln:		$(UTSBASE)/sun4c/io/mem.c
    263     0    stevel 			@($(LHEAD) $(LINT.c) $(UTSBASE)/sun4c/io/mem.c $(LTAIL))
    264     0    stevel 
    265     0    stevel     2]	Create build directories in the appropriate places. If the module
    266     0    stevel 	can be built in a machine independent way, this would be in the
    267     0    stevel 	"instruction set architecture" directory (i.e.: sparc). If not, these
    268     0    stevel 	directories would be created for all appropriate "implementation
    269     0    stevel 	architecture" dependent directories (i.e.: sun4, sun4c).
    270     0    stevel 
    271     0    stevel     3]  In each build directory, create a Makefile. This can usually be
    272     0    stevel 	accomplished by copying a Makefile from a parallel directory and
    273     0    stevel 	editing the following lines (in addition to comments).
    274     0    stevel 
    275     0    stevel 		MODULE		= namefs
    276     0    stevel 			- replace with module name 
    277     0    stevel 		OBJECTS		= $(NAMEFS_OBJS:%=$(OBJS_DIR)/%)
    278     0    stevel 		LINTS		= $(NAMEFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
    279     0    stevel 			- replace with MODULE_OBJS
    280     0    stevel 		ROOTMODULE	= $(ROOT_FS_DIR)/$(MODULE).kmod
    281     0    stevel 			- replace directory part with the appropriate
    282     0    stevel 			  installation directory name (see Makefile.uts)
    283     0    stevel 
    284     0    stevel 	If a custom version of modstubs.o is needed to check the undefines
    285     0    stevel 	for this routine, the following lines need to appear in the
    286     0    stevel 	Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)).
    287     0    stevel 
    288     0    stevel 		MODSTUBS_DIR	 = $(OBJS_DIR)
    289     0    stevel 		$(MODSTUBS_O)	:= AS_CPPFLAGS += -DNAMEFS_MODULE
    290     0    stevel 			- replace "-DNAMEFS_MODULE" with the appropriate flag
    291     0    stevel 			  for the modstubs.o assembly.
    292     0    stevel 		CLEANFILES	+= $(MODSTUBS_O)
    293     0    stevel 
    294     0    stevel     4]  Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
    295     0    stevel 	the new module:
    296     0    stevel 
    297     0    stevel 		FS_KMODS	+= fd fifo namefs nfs proc spec ufs
    298     0    stevel 					   ------
    299     0    stevel Any additional questions can be easily answered by looking at the many
    300     0    stevel existing examples.
    301     0    stevel 
    302     0    stevel 
    303     0    stevel Moving a Module to the "Implementation Architecture" Independent Build
    304     0    stevel ----------------------------------------------------------------------
    305     0    stevel 
    306     0    stevel     1]  Create the build directory under the appropriate "instruction
    307     0    stevel 	set architecture" build directory (i.e.: sparc/MODULE).
    308     0    stevel 
    309     0    stevel     2]  Move the Makefile from the "implementation architecture" build
    310     0    stevel 	directory (i.e.: sun4c/MODULE) to the directory created above.
    311     0    stevel 	Edit this Makefile to reflect the change of parent (trivial:
    312     0    stevel 	comments, paths and includes).
    313     0    stevel 
    314     0    stevel     3]  Edit the "implementation architecture" directory Makefile (i.e.:
    315     0    stevel 	Makefile.sun4c) to *not* know about this module and edit the
    316     0    stevel 	"instruction set architecture" directory Makefile (i.e.:
    317     0    stevel 	Makefile.sparc) to know about it.
    318     0    stevel 
    319