mqueue: apply mathematics distributivity on mq_bytes calculation

[safe/jmp/linux-2.6] / Documentation / kbuild / makefiles.txt

diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt
index 1ca535b..71c602d 100644 (file)
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -18,6 +18,7 @@ This document describes the Linux kernel Makefiles.
           --- 3.9 Dependency tracking
           --- 3.10 Special Rules
           --- 3.11 $(CC) support functions
           --- 3.9 Dependency tracking
           --- 3.10 Special Rules
           --- 3.11 $(CC) support functions

+          --- 3.12 $(LD) support functions

 
        === 4 Host Program support
           --- 4.1 Simple Host Program
 
        === 4 Host Program support
           --- 4.1 Simple Host Program


@@ -40,10 +41,16 @@ This document describes the Linux kernel Makefiles.
           --- 6.7 Custom kbuild commands
           --- 6.8 Preprocessing linker scripts
 
           --- 6.7 Custom kbuild commands
           --- 6.8 Preprocessing linker scripts
 

-       === 7 Kbuild Variables
-       === 8 Makefile language
-       === 9 Credits
-       === 10 TODO
+       === 7 Kbuild syntax for exported headers
+               --- 7.1 header-y
+               --- 7.2 objhdr-y
+               --- 7.3 destination-y
+               --- 7.4 unifdef-y (deprecated)
+
+       === 8 Kbuild Variables
+       === 9 Makefile language
+       === 10 Credits
+       === 11 TODO

 
 === 1 Overview
 
 
 === 1 Overview
 


@@ -276,40 +283,49 @@ more details, with real examples.
 
 --- 3.7 Compilation flags
 
 
 --- 3.7 Compilation flags
 

-    EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS
-
-       All the EXTRA_ variables apply only to the kbuild makefile
-       where they are assigned. The EXTRA_ variables apply to all
-       commands executed in the kbuild makefile.
+    ccflags-y, asflags-y and ldflags-y
+       The three flags listed above applies only to the kbuild makefile
+       where they are assigned. They are used for all the normal
+       cc, as and ld invocation happenign during a recursive build.
+       Note: Flags with the same behaviour were previously named:
+       EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
+       They are yet supported but their use are deprecated.

 
 

-       $(EXTRA_CFLAGS) specifies options for compiling C files with
-       $(CC).
+       ccflags-y specifies options for compiling C files with $(CC).

 
        Example:
                # drivers/sound/emu10k1/Makefile
 
        Example:
                # drivers/sound/emu10k1/Makefile

-               EXTRA_CFLAGS += -I$(obj)
-               ifdef DEBUG
-                   EXTRA_CFLAGS += -DEMU10K1_DEBUG
-               endif
+               ccflags-y += -I$(obj)
+               ccflags-$(DEBUG) += -DEMU10K1_DEBUG

 
 
        This variable is necessary because the top Makefile owns the
        variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
        entire tree.
 
 
 
        This variable is necessary because the top Makefile owns the
        variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
        entire tree.
 

-       $(EXTRA_AFLAGS) is a similar string for per-directory options
+       asflags-y is a similar string for per-directory options

        when compiling assembly language source.
 
        Example:
                #arch/x86_64/kernel/Makefile
        when compiling assembly language source.
 
        Example:
                #arch/x86_64/kernel/Makefile

-               EXTRA_AFLAGS := -traditional
+               asflags-y := -traditional

 
 
 
 

-       $(EXTRA_LDFLAGS) is a string for per-directory options to $(LD).
+       ldflags-y is a string for per-directory options to $(LD).

 
        Example:
                #arch/m68k/fpsp040/Makefile
 
        Example:
                #arch/m68k/fpsp040/Makefile

-               EXTRA_LDFLAGS := -x
+               ldflags-y := -x
+
+    subdir-ccflags-y, subdir-asflags-y
+       The two flags listed above are similar to ccflags-y and as-falgs-y.
+       The difference is that the subdir- variants has effect for the kbuild
+       file where tey are present and all subdirectories.
+       Options specified using subdir-* are added to the commandline before
+       the options specified using the non-subdir variants.
+
+       Example:
+               subdir-ccflags-y := -Werror

 
     CFLAGS_$@, AFLAGS_$@
 
 
     CFLAGS_$@, AFLAGS_$@
 


@@ -384,6 +400,20 @@ more details, with real examples.
        to prerequisites are referenced with $(src) (because they are not
        generated files).
 
        to prerequisites are referenced with $(src) (because they are not
        generated files).
 

+    $(kecho)
+       echoing information to user in a rule is often a good practice
+       but when execution "make -s" one does not expect to see any output
+       except for warnings/errors.
+       To support this kbuild define $(kecho) which will echo out the
+       text following $(kecho) to stdout except if "make -s" is used.
+
+       Example:
+               #arch/blackfin/boot/Makefile
+               $(obj)/vmImage: $(obj)/vmlinux.gz
+                       $(call if_changed,uimage)
+                       @$(kecho) 'Kernel: $@ is ready'
+
+

 --- 3.11 $(CC) support functions
 
        The kernel may be built with several different versions of
 --- 3.11 $(CC) support functions
 
        The kernel may be built with several different versions of


@@ -406,14 +436,14 @@ more details, with real examples.
        The second argument is optional, and if supplied will be used
        if first argument is not supported.
 
        The second argument is optional, and if supplied will be used
        if first argument is not supported.
 

-    ld-option
-       ld-option is used to check if $(CC) when used to link object files
+    cc-ldoption
+       cc-ldoption is used to check if $(CC) when used to link object files

        supports the given option.  An optional second option may be
        specified if first option are not supported.
 
        Example:
                #arch/i386/kernel/Makefile
        supports the given option.  An optional second option may be
        specified if first option are not supported.
 
        Example:
                #arch/i386/kernel/Makefile

-               vsyscall-flags += $(call ld-option, -Wl$(comma)--hash-style=sysv)
+               vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)

 
        In the above example, vsyscall-flags will be assigned the option
        -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
 
        In the above example, vsyscall-flags will be assigned the option
        -Wl$(comma)--hash-style=sysv if it is supported by $(CC).


@@ -424,6 +454,7 @@ more details, with real examples.
        as-instr checks if the assembler reports a specific instruction
        and then outputs either option1 or option2
        C escapes are supported in the test instruction
        as-instr checks if the assembler reports a specific instruction
        and then outputs either option1 or option2
        C escapes are supported in the test instruction

+       Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options

 
     cc-option
        cc-option is used to check if $(CC) supports a given option, and not
 
     cc-option
        cc-option is used to check if $(CC) supports a given option, and not


@@ -494,9 +525,9 @@ more details, with real examples.
 
        Example:
                #fs/reiserfs/Makefile
 
        Example:
                #fs/reiserfs/Makefile

-               EXTRA_CFLAGS := $(call cc-ifversion, -lt, 0402, -O1)
+               ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)

 
 

-       In this example, EXTRA_CFLAGS will be assigned the value -O1 if the
+       In this example, ccflags-y will be assigned the value -O1 if the

        $(CC) version is less than 4.2.
        cc-ifversion takes all the shell operators:
        -eq, -ne, -lt, -le, -gt, and -ge
        $(CC) version is less than 4.2.
        cc-ifversion takes all the shell operators:
        -eq, -ne, -lt, -le, -gt, and -ge


@@ -518,6 +549,41 @@ more details, with real examples.
        In this example for a specific GCC version the build will error out explaining
        to the user why it stops.
 
        In this example for a specific GCC version the build will error out explaining
        to the user why it stops.
 

+    cc-cross-prefix
+       cc-cross-prefix is used to check if there exists a $(CC) in path with
+       one of the listed prefixes. The first prefix where there exist a
+       prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
+       then nothing is returned.
+       Additional prefixes are separated by a single space in the
+       call of cc-cross-prefix.
+       This functionality is useful for architecture Makefiles that try
+       to set CROSS_COMPILE to well-known values but may have several
+       values to select between.
+       It is recommended only to try to set CROSS_COMPILE if it is a cross
+       build (host arch is different from target arch). And if CROSS_COMPILE
+       is already set then leave it with the old value.
+
+       Example:
+               #arch/m68k/Makefile
+               ifneq ($(SUBARCH),$(ARCH))
+                       ifeq ($(CROSS_COMPILE),)
+                              CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
+                       endif
+               endif
+
+--- 3.12 $(LD) support functions
+
+    ld-option
+       ld-option is used to check if $(LD) supports the supplied option.
+       ld-option takes two options as arguments.
+       The second argument is an optional option that can be used if the
+       first option is not supported by $(LD).
+
+       Example:
+               #Makefile
+               LDFLAGS_vmlinux += $(call really-ld-option, -X)
+
+

 === 4 Host Program support
 
 Kbuild supports building executables on the host for use during the
 === 4 Host Program support
 
 Kbuild supports building executables on the host for use during the


@@ -782,7 +848,7 @@ When kbuild executes, the following steps are followed (roughly):
        Example:
                #arch/s390/Makefile
                LDFLAGS         := -m elf_s390
        Example:
                #arch/s390/Makefile
                LDFLAGS         := -m elf_s390

-       Note: EXTRA_LDFLAGS can be used to further customise
+       Note: ldflags-y can be used to further customise

        the flags used. See chapter 3.7.
 
     LDFLAGS_MODULE     Options for $(LD) when linking modules
        the flags used. See chapter 3.7.
 
     LDFLAGS_MODULE     Options for $(LD) when linking modules


@@ -819,14 +885,14 @@ When kbuild executes, the following steps are followed (roughly):
        In this example, the binary $(obj)/image is a binary version of
        vmlinux. The usage of $(call if_changed,xxx) will be described later.
 
        In this example, the binary $(obj)/image is a binary version of
        vmlinux. The usage of $(call if_changed,xxx) will be described later.
 

-    AFLAGS             $(AS) assembler flags
+    KBUILD_AFLAGS              $(AS) assembler flags

 
        Default value - see top level Makefile
        Append or modify as required per architecture.
 
        Example:
                #arch/sparc64/Makefile
 
        Default value - see top level Makefile
        Append or modify as required per architecture.
 
        Example:
                #arch/sparc64/Makefile

-               AFLAGS += -m64 -mcpu=ultrasparc
+               KBUILD_AFLAGS += -m64 -mcpu=ultrasparc

 
     KBUILD_CFLAGS              $(CC) compiler flags
 
 
     KBUILD_CFLAGS              $(CC) compiler flags
 


@@ -1098,8 +1164,8 @@ When kbuild executes, the following steps are followed (roughly):
        specified options when building the target vmlinux.lds.
 
        When building the *.lds target, kbuild uses the variables:
        specified options when building the target vmlinux.lds.
 
        When building the *.lds target, kbuild uses the variables:

-       CPPFLAGS        : Set in top-level Makefile
-       EXTRA_CPPFLAGS  : May be set in the kbuild makefile
+       KBUILD_CPPFLAGS : Set in top-level Makefile
+       cppflags-y      : May be set in the kbuild makefile

        CPPFLAGS_$(@F)  : Target specific flags.
                          Note that the full filename is used in this
                          assignment.
        CPPFLAGS_$(@F)  : Target specific flags.
                          Note that the full filename is used in this
                          assignment.


@@ -1107,8 +1173,69 @@ When kbuild executes, the following steps are followed (roughly):
        The kbuild infrastructure for *lds file are used in several
        architecture-specific files.
 
        The kbuild infrastructure for *lds file are used in several
        architecture-specific files.
 

+=== 7 Kbuild syntax for exported headers
+
+The kernel include a set of headers that is exported to userspace.
+Many headers can be exported as-is but other headers requires  a
+minimal pre-processing before they are ready for user-space.
+The pre-processing does:
+- drop kernel specific annotations
+- drop include of compiler.h
+- drop all sections that is kernel internat (guarded by ifdef __KERNEL__)
+
+Each relevant directory contain a file name "Kbuild" which specify the
+headers to be exported.
+See subsequent chapter for the syntax of the Kbuild file.
+
+       --- 7.1 header-y
+
+       header-y specify header files to be exported.
+
+               Example:
+                       #include/linux/Kbuild
+                       header-y += usb/
+                       header-y += aio_abi.h
+
+       The convention is to list one file per line and
+       preferably in alphabetic order.
+
+       header-y also specify which subdirectories to visit.
+       A subdirectory is identified by a trailing '/' which
+       can be seen in the example above for the usb subdirectory.
+
+       Subdirectories are visited before their parent directories.
+
+       --- 7.2 objhdr-y
+
+       objhdr-y specifies generated files to be exported.
+       Generated files are special as they need to be looked
+       up in another directory when doing 'make O=...' builds.
+
+               Example:
+                       #include/linux/Kbuild
+                       objhdr-y += version.h
+
+       --- 7.3 destination-y
+
+       When an architecture have a set of exported headers that needs to be
+       exported to a different directory destination-y is used.
+       destination-y specify the destination directory for all exported
+       headers in the file where it is present.
+
+               Example:
+                       #arch/xtensa/platforms/s6105/include/platform/Kbuild
+                       destination-y := include/linux
+
+       In the example above all exported headers in the Kbuild file
+       will be located in the directory "include/linux" when exported.
+
+
+       --- 7.4 unifdef-y (deprecated)
+
+       unifdef-y is deprecated. A direct replacement is header-y.
+

 
 

-=== 7 Kbuild Variables
+=== 8 Kbuild Variables

 
 The top Makefile exports the following variables:
 
 
 The top Makefile exports the following variables:
 


@@ -1170,7 +1297,7 @@ The top Makefile exports the following variables:
        INSTALL_MOD_STRIP will used as the option(s) to the strip command.
 
 
        INSTALL_MOD_STRIP will used as the option(s) to the strip command.
 
 

-=== 8 Makefile language
+=== 9 Makefile language

 
 The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
 use only the documented features of GNU Make, but they do use many
 
 The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
 use only the documented features of GNU Make, but they do use many


@@ -1189,14 +1316,14 @@ time the left-hand side is used.
 There are some cases where "=" is appropriate.  Usually, though, ":="
 is the right choice.
 
 There are some cases where "=" is appropriate.  Usually, though, ":="
 is the right choice.
 

-=== 9 Credits
+=== 10 Credits

 
 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 Updates by Sam Ravnborg <sam@ravnborg.org>
 Language QA by Jan Engelhardt <jengelh@gmx.de>
 
 
 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 Updates by Sam Ravnborg <sam@ravnborg.org>
 Language QA by Jan Engelhardt <jengelh@gmx.de>
 

-=== 10 TODO
+=== 11 TODO

 
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
 
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.