xref: /onnv-gate/usr/src/uts/README (revision 3957:86c9dda5df37)
10Sstevel@tonic-gate#
20Sstevel@tonic-gate# CDDL HEADER START
30Sstevel@tonic-gate#
40Sstevel@tonic-gate# The contents of this file are subject to the terms of the
5*3957Sth199096# Common Development and Distribution License (the "License").
6*3957Sth199096# You may not use this file except in compliance with the License.
70Sstevel@tonic-gate#
80Sstevel@tonic-gate# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
90Sstevel@tonic-gate# or http://www.opensolaris.org/os/licensing.
100Sstevel@tonic-gate# See the License for the specific language governing permissions
110Sstevel@tonic-gate# and limitations under the License.
120Sstevel@tonic-gate#
130Sstevel@tonic-gate# When distributing Covered Code, include this CDDL HEADER in each
140Sstevel@tonic-gate# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
150Sstevel@tonic-gate# If applicable, add the following below this CDDL HEADER, with the
160Sstevel@tonic-gate# fields enclosed by brackets "[]" replaced with your own identifying
170Sstevel@tonic-gate# information: Portions Copyright [yyyy] [name of copyright owner]
180Sstevel@tonic-gate#
190Sstevel@tonic-gate# CDDL HEADER END
200Sstevel@tonic-gate#
21*3957Sth199096
22*3957Sth199096#
23*3957Sth199096# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
240Sstevel@tonic-gate# Use is subject to license terms.
250Sstevel@tonic-gate#
26*3957Sth199096# ident	"%Z%%M%	%I%	%E% SMI"
270Sstevel@tonic-gate
280Sstevel@tonic-gateKERNEL MAKEFILE STRUCTURE
290Sstevel@tonic-gate-------------------------
300Sstevel@tonic-gate
310Sstevel@tonic-gateThe advent of dynamic loading of kernel modules has obsoleted the
320Sstevel@tonic-gate4.x kernel configuration scheme which was centered around a derived
330Sstevel@tonic-gateMakefile and a collection of derived header files generated by the
340Sstevel@tonic-gateconfig(8) program. This file describes the structure of the replacement
350Sstevel@tonic-gate"static" set of Makefiles.
360Sstevel@tonic-gate
370Sstevel@tonic-gateSome additional secondary goals were associated with the generation
380Sstevel@tonic-gateof these Makefiles.  It should be noted that the ability to properly
390Sstevel@tonic-gatedeal with derived Makefiles is an explicit non-goal of the ongoing
400Sstevel@tonic-gateNSE enhancements, so this project is a necessary consequence of that
410Sstevel@tonic-gatedecision.
420Sstevel@tonic-gate
430Sstevel@tonic-gateAll project goals are enumerated below:
440Sstevel@tonic-gate
450Sstevel@tonic-gate1]  To provide a set of static Makefiles to support kernel build
460Sstevel@tonic-gate    and installation.
470Sstevel@tonic-gate
480Sstevel@tonic-gate2]  To provide a set of static Makefiles which conform to the
490Sstevel@tonic-gate    "Makefiles Guidelines".  (This document is currently available
500Sstevel@tonic-gate    on-line as "terminator:/usr/integration/doc/make.std")
510Sstevel@tonic-gate
520Sstevel@tonic-gate3]  To completely eliminate the config(8) program.
530Sstevel@tonic-gate
540Sstevel@tonic-gate4]  To provide a framework for linting the kernel (so that "lint free"
550Sstevel@tonic-gate    can be made an integration criterion, in addition to being general
560Sstevel@tonic-gate    good hygiene).
570Sstevel@tonic-gate
580Sstevel@tonic-gate5]  To eliminate the need for the small headers generated by config(8).
590Sstevel@tonic-gate    In the ddi/dki world this need is completely eliminated as drivers
600Sstevel@tonic-gate    will be expected to dynamically configure themselves. Interim support
610Sstevel@tonic-gate    for existing drivers will be provided.
620Sstevel@tonic-gate
630Sstevel@tonic-gate6]  To be able to "acquire" only the files needed to build a specific
640Sstevel@tonic-gate    module, if that is all that is needed.
650Sstevel@tonic-gate
660Sstevel@tonic-gate7]  To provide a framework suitable for the production of "implementation
670Sstevel@tonic-gate    architecture" independent modules.
680Sstevel@tonic-gate
690Sstevel@tonic-gate8]  To restructure the assembly language files to support the generation
700Sstevel@tonic-gate    of "lint-libraries" from them.
710Sstevel@tonic-gate
720Sstevel@tonic-gate9]  To provide support for the incidental Makefile targets many developers
730Sstevel@tonic-gate    are accustomed to (such as cscope and tags). These can be added to the
740Sstevel@tonic-gate    Makefiles asd required. (cscope is currently supported.)
750Sstevel@tonic-gate
760Sstevel@tonic-gate
770Sstevel@tonic-gateGENERAL STRUCTURE
780Sstevel@tonic-gate-----------------
790Sstevel@tonic-gate
800Sstevel@tonic-gateThe source code layout is not generally effected by the Makefiles. However,
810Sstevel@tonic-gatethe location of the generated files has changed dramatically.
820Sstevel@tonic-gate
830Sstevel@tonic-gate"Implementation architecture" independent modules are produced in
840Sstevel@tonic-gateindividual directories (one per module) under the "instruction-set
850Sstevel@tonic-gatearchitecture" directory (i.e.: sparc). Similarly, "implementation
860Sstevel@tonic-gatearchitecture" dependent modules are produced in individual directories
870Sstevel@tonic-gateunder the "implementation architecture" directory (i.e.: sun4, sun4c).
880Sstevel@tonic-gateIt should be noted that currently (4/14/91) no implementation architecture
890Sstevel@tonic-gatemodules exist. This situation is expected to change shortly.
900Sstevel@tonic-gate
910Sstevel@tonic-gateThe driving Makefile for any module is located in the leaf directory
920Sstevel@tonic-gatewhere the module (and associated objects) are built. After a 'make
930Sstevel@tonic-gateclobber' operation, the Makefile is the only file remaining in that
940Sstevel@tonic-gatedirectory. Common definitions and rules are contained in suffixed
950Sstevel@tonic-gateMakefiles in non-leaf directories which are included in the leaf
960Sstevel@tonic-gateMakefiles. Non-suffixed Makefiles in non-leaf directories generally
970Sstevel@tonic-gateinvoke lower level Makefiles to perform the actual tasks.
980Sstevel@tonic-gate
990Sstevel@tonic-gateuts/Makefile
1000Sstevel@tonic-gateuts/sparc/Makefile
1010Sstevel@tonic-gateuts/sun4c/Makefile
1020Sstevel@tonic-gateuts/sun4c/svvs/Makefile
1030Sstevel@tonic-gate	These Makefiles generally are cognizant of the components
1040Sstevel@tonic-gate	made in subdirectories and invoke Makefiles in those sub-
1050Sstevel@tonic-gate	directories to perform the actual build. Some targets (or
1060Sstevel@tonic-gate	pseudo-targets) may be directly built at this level (such
1070Sstevel@tonic-gate	as the cscope databases).
1080Sstevel@tonic-gate
1090Sstevel@tonic-gateuts/Makefile.uts
1100Sstevel@tonic-gate	Contains common definitions for all possible architectures.
1110Sstevel@tonic-gate
1120Sstevel@tonic-gateuts/Makefile.targ
1130Sstevel@tonic-gate	Contains common targets for all possible architectures.
1140Sstevel@tonic-gate
1150Sstevel@tonic-gateuts/common/Makefile.files
1160Sstevel@tonic-gateuts/sun/Makefile.files
1170Sstevel@tonic-gateuts/sparc/Makefile.files
1180Sstevel@tonic-gateuts/sun4c/Makefile.files
1190Sstevel@tonic-gateuts/sun4/Makefile.files
1200Sstevel@tonic-gate	These Makefiles are divided into two sections. The first
1210Sstevel@tonic-gate	section can be viewed as the equivalent of the "files" (sparc
1220Sstevel@tonic-gate	and sun4c) and "files.cmn" (common and sun) files. These
1230Sstevel@tonic-gate	define the object lists which define each module. The second
1240Sstevel@tonic-gate	section defines the appropriate header search paths and other
1250Sstevel@tonic-gate	machine specific global build parameters.
1260Sstevel@tonic-gate
1270Sstevel@tonic-gateuts/common/Makefile.rules
1280Sstevel@tonic-gateuts/sun/Makefile.rules
1290Sstevel@tonic-gateuts/sparc/Makefile.rules
1300Sstevel@tonic-gateuts/sun4c/Makefile.rules
1310Sstevel@tonic-gateuts/sun4/Makefile.rules
1320Sstevel@tonic-gate	The files provide build rules (targets) which allow make to function
1330Sstevel@tonic-gate	in a multiple directory environment. Each source tree below the
1340Sstevel@tonic-gate	directory containing the Makefile has a build rule in the file.
1350Sstevel@tonic-gate
1360Sstevel@tonic-gateuts/sun4c/Makefile.sun4c
1370Sstevel@tonic-gateuts/sun4/Makefile.sun4
1380Sstevel@tonic-gate	These Makefile contains the definitions specific (defaults) to
1390Sstevel@tonic-gate	the obvious "implementation architecture". These rules can be
1400Sstevel@tonic-gate	overridden in specific leaf node Makefiles if necessary.
1410Sstevel@tonic-gate
1420Sstevel@tonic-gateuts/sun4c/unix/Makefile
1430Sstevel@tonic-gate	Main driving Makefile for building /unix.
1440Sstevel@tonic-gate
1450Sstevel@tonic-gateuts/sun4c/MODULE/Makefile (for MODULE in arp, aoutexec, ...)
1460Sstevel@tonic-gate	Main driving Makefile for building MODULE.kmod.
1470Sstevel@tonic-gate
1480Sstevel@tonic-gateuts/sun4c/unix.static/Makefile
1490Sstevel@tonic-gate	Main driving Makefile for building a static unix (for development
1500Sstevel@tonic-gate	work only). This Makefile is known to NSE, but its targets are
1510Sstevel@tonic-gate	not. This makefile may be copied to additional parallel directories
1520Sstevel@tonic-gate	to build multiple configurations. This configuration is roughly
1530Sstevel@tonic-gate	equivalent to the GENERIC kernel of SunOS 4.x.
1540Sstevel@tonic-gate
1551167Skupferuts/*/Makefile.?.shared
1561167Skupfer	These denote Makefile contents which are shared between open and
1571167Skupfer	closed builds.
1581167Skupfer
1590Sstevel@tonic-gateThe Makefiles are verbosely commented. It is desired that they should
1600Sstevel@tonic-gatestay this way.
1610Sstevel@tonic-gate
1620Sstevel@tonic-gate
1630Sstevel@tonic-gateUSE
1640Sstevel@tonic-gate---
1650Sstevel@tonic-gate
1660Sstevel@tonic-gateIssuing the command 'make' in the uts directory will cause all supported,
1670Sstevel@tonic-gatemodularized kernels and modules to be built.
1680Sstevel@tonic-gate
1690Sstevel@tonic-gateIssuing the command 'make' in a uts/ARCHITECTURE directory (i.e.: uts/sparc)
1700Sstevel@tonic-gatewill cause all supported, "implementation architecture" independent modules
1710Sstevel@tonic-gatefor ARCHITECTURE to be built.
1720Sstevel@tonic-gate
1730Sstevel@tonic-gateIssuing the command 'make' in a uts/MACHINE directory (i.e.: uts/sun4c)
1740Sstevel@tonic-gatewill cause that kernel and all supported, "implementation architecture"
1750Sstevel@tonic-gatedependent modules for MACHINE to be built.
1760Sstevel@tonic-gate
1770Sstevel@tonic-gateIssuing the command 'make' in the uts/MACHINE/unix directory will cause the
1780Sstevel@tonic-gatekernel for MACHINE to be built (and unix.o).
1790Sstevel@tonic-gate
1800Sstevel@tonic-gateIssuing the command 'make' in a uts/MACHINE/MODULE or a uts/ARCHITECTURE/MODULE
1810Sstevel@tonic-gatedirectory will cause MODULE.kmod to be built.
1820Sstevel@tonic-gate
1830Sstevel@tonic-gate
1840Sstevel@tonic-gateLINT
1850Sstevel@tonic-gate----
1860Sstevel@tonic-gate
1870Sstevel@tonic-gateLinting is fairly similar to the builds, but it has an additional complication.
1880Sstevel@tonic-gateIn order to get meaningful output from lint pass2, all the modules must be
1890Sstevel@tonic-gatelinted together. This is accomplished by each module being responsible to
1900Sstevel@tonic-gateproduce its own pass1 output (file.ln, one per .c/.s file). It is also
1910Sstevel@tonic-gateresponsible for placing the a lint-library (llib-lMODULE) in the
1920Sstevel@tonic-gateuts/MACHINE/lint-libs directory. The final full lint is accomplished by the
1930Sstevel@tonic-gateMakefile in the uts/MACHINE directory by linting all the lint-libraries
1940Sstevel@tonic-gateagainst each other.
1950Sstevel@tonic-gate
1960Sstevel@tonic-gateNote that there is no equivalent to Locore.c in the current source base.
1970Sstevel@tonic-gateThe C prototypes are in the .s files. As example:
1980Sstevel@tonic-gate
1990Sstevel@tonic-gate	#if defined(lint)
2000Sstevel@tonic-gate	int
2010Sstevel@tonic-gate	blort(int, int)
2020Sstevel@tonic-gate	{ return 0 }
2030Sstevel@tonic-gate	#else	/* lint */
2040Sstevel@tonic-gate
2050Sstevel@tonic-gate		ENTRY(blort)
2060Sstevel@tonic-gate		ld	[%i0],....
2070Sstevel@tonic-gate		....
2080Sstevel@tonic-gate		SET_SIZE(blort)
2090Sstevel@tonic-gate
2100Sstevel@tonic-gate	#endif	/* lint */
2110Sstevel@tonic-gate
2120Sstevel@tonic-gate
2130Sstevel@tonic-gateCOMPONENT HIERARCHY
2140Sstevel@tonic-gate------------------
2150Sstevel@tonic-gate
2160Sstevel@tonic-gateThe component hierarchy has been restructured to allow the acquisition of
2170Sstevel@tonic-gatemore finely grained objects; specificly a kernel module. The basic component
2180Sstevel@tonic-gatestructure is:
2190Sstevel@tonic-gate
2200Sstevel@tonic-gate	:src:uts.all --+--> :sparc --+--> :MODULES... (none currently)
2210Sstevel@tonic-gate		       |
2220Sstevel@tonic-gate		       +--> :sun4c --+--> :unix
2230Sstevel@tonic-gate		       |             |
2240Sstevel@tonic-gate		       |             +--> :MODULES...
2250Sstevel@tonic-gate		       |             |
2260Sstevel@tonic-gate		       |             +--> :unix.static
2270Sstevel@tonic-gate		       |
2280Sstevel@tonic-gate		       +--> :sun4 ---+--> :unix
2290Sstevel@tonic-gate		       |             |
2300Sstevel@tonic-gate		       |             +--> :MODULES...
2310Sstevel@tonic-gate		       |             |
2320Sstevel@tonic-gate		       |             +--> :unix.static
2330Sstevel@tonic-gate		       ...
2340Sstevel@tonic-gate
2350Sstevel@tonic-gateThe above diagram does not reflect the full component tree. The full component
2360Sstevel@tonic-gatetree may be displayed with the "nsecomp list -r :src:uts.all" command.
2370Sstevel@tonic-gate
2380Sstevel@tonic-gate
2390Sstevel@tonic-gateCOMMON OPERATIONS
2400Sstevel@tonic-gate-----------------
2410Sstevel@tonic-gate
2420Sstevel@tonic-gateAdding a New Kernel Module
2430Sstevel@tonic-gate--------------------------
2440Sstevel@tonic-gate
2450Sstevel@tonic-gate    0]  Create the source files (and directories) as usual.
2460Sstevel@tonic-gate
247*3957Sth199096    1]  Edit uts/*/Makefile.files to define the set of objects. By convention
2480Sstevel@tonic-gate	the symbolic name of this set is of the form MODULE_OBJS, where
2490Sstevel@tonic-gate	MODULE is the module name (i.e.: namefs). The files in each subtree
2500Sstevel@tonic-gate	should be defined in the Makefile.files in the root directory of that
2510Sstevel@tonic-gate	subtree. Note that they are defined using the += operator, so that
2520Sstevel@tonic-gate	the set can be built across multiple files. As example:
2530Sstevel@tonic-gate
2540Sstevel@tonic-gate		NAMEFS_OBJS +=	namevfs.o namevno.o
2550Sstevel@tonic-gate
2560Sstevel@tonic-gate	Each source file needs a build rule in the corresponding Makefile.rules
2570Sstevel@tonic-gate	file (compilation and lint). A typical pair of entries would be:
2580Sstevel@tonic-gate
2590Sstevel@tonic-gate		$(OBJS_DIR)/mem.o:		$(UTSBASE)/sun4c/io/mem.c
2600Sstevel@tonic-gate			$(COMPILE.c) -o $@ $(UTSBASE)/sun4c/io/mem.c
2610Sstevel@tonic-gate
2620Sstevel@tonic-gate		$(LINTS_DIR)/mem.ln:		$(UTSBASE)/sun4c/io/mem.c
2630Sstevel@tonic-gate			@($(LHEAD) $(LINT.c) $(UTSBASE)/sun4c/io/mem.c $(LTAIL))
2640Sstevel@tonic-gate
2650Sstevel@tonic-gate    2]	Create build directories in the appropriate places. If the module
2660Sstevel@tonic-gate	can be built in a machine independent way, this would be in the
2670Sstevel@tonic-gate	"instruction set architecture" directory (i.e.: sparc). If not, these
2680Sstevel@tonic-gate	directories would be created for all appropriate "implementation
2690Sstevel@tonic-gate	architecture" dependent directories (i.e.: sun4, sun4c).
2700Sstevel@tonic-gate
2710Sstevel@tonic-gate    3]  In each build directory, create a Makefile. This can usually be
2720Sstevel@tonic-gate	accomplished by copying a Makefile from a parallel directory and
2730Sstevel@tonic-gate	editing the following lines (in addition to comments).
2740Sstevel@tonic-gate
2750Sstevel@tonic-gate		MODULE		= namefs
2760Sstevel@tonic-gate			- replace with module name
2770Sstevel@tonic-gate		OBJECTS		= $(NAMEFS_OBJS:%=$(OBJS_DIR)/%)
2780Sstevel@tonic-gate		LINTS		= $(NAMEFS_OBJS:%.o=$(LINTS_DIR)/%.ln)
2790Sstevel@tonic-gate			- replace with MODULE_OBJS
2800Sstevel@tonic-gate		ROOTMODULE	= $(ROOT_FS_DIR)/$(MODULE).kmod
2810Sstevel@tonic-gate			- replace directory part with the appropriate
2820Sstevel@tonic-gate			  installation directory name (see Makefile.uts)
2830Sstevel@tonic-gate
2840Sstevel@tonic-gate	If a custom version of modstubs.o is needed to check the undefines
2850Sstevel@tonic-gate	for this routine, the following lines need to appear in the
2860Sstevel@tonic-gate	Makefile (after the inclusion of Makefile.mach (i.e.: Makefile.sun4c)).
2870Sstevel@tonic-gate
2880Sstevel@tonic-gate		MODSTUBS_DIR	 = $(OBJS_DIR)
2890Sstevel@tonic-gate		$(MODSTUBS_O)	:= AS_CPPFLAGS += -DNAMEFS_MODULE
2900Sstevel@tonic-gate			- replace "-DNAMEFS_MODULE" with the appropriate flag
2910Sstevel@tonic-gate			  for the modstubs.o assembly.
2920Sstevel@tonic-gate		CLEANFILES	+= $(MODSTUBS_O)
2930Sstevel@tonic-gate
2940Sstevel@tonic-gate    4]  Edit the parent Makefile.mach (i.e.: Makefile.sun4c) to know about
2950Sstevel@tonic-gate	the new module:
2960Sstevel@tonic-gate
2970Sstevel@tonic-gate		FS_KMODS	+= fd fifo namefs nfs proc spec ufs
2980Sstevel@tonic-gate					   ------
2990Sstevel@tonic-gateAny additional questions can be easily answered by looking at the many
3000Sstevel@tonic-gateexisting examples.
3010Sstevel@tonic-gate
3020Sstevel@tonic-gate
3030Sstevel@tonic-gateMoving a Module to the "Implementation Architecture" Independent Build
3040Sstevel@tonic-gate----------------------------------------------------------------------
3050Sstevel@tonic-gate
3060Sstevel@tonic-gate    1]  Create the build directory under the appropriate "instruction
3070Sstevel@tonic-gate	set architecture" build directory (i.e.: sparc/MODULE).
3080Sstevel@tonic-gate
3090Sstevel@tonic-gate    2]  Move the Makefile from the "implementation architecture" build
3100Sstevel@tonic-gate	directory (i.e.: sun4c/MODULE) to the directory created above.
3110Sstevel@tonic-gate	Edit this Makefile to reflect the change of parent (trivial:
3120Sstevel@tonic-gate	comments, paths and includes).
3130Sstevel@tonic-gate
3140Sstevel@tonic-gate    3]  Edit the "implementation architecture" directory Makefile (i.e.:
3150Sstevel@tonic-gate	Makefile.sun4c) to *not* know about this module and edit the
3160Sstevel@tonic-gate	"instruction set architecture" directory Makefile (i.e.:
3170Sstevel@tonic-gate	Makefile.sparc) to know about it.
3180Sstevel@tonic-gate
319