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 EXTERNAL_HEADERS/ 2012-10-05 07:23:04
Folder SETUP/ 2012-10-05 07:22:52
Folder bsd/ 2012-10-05 07:22:58
Folder config/ 2012-10-05 07:22:52
Folder iokit/ 2012-10-05 07:22:46
Folder libkern/ 2012-10-05 07:22:55
Folder libsa/ 2012-10-05 07:22:45
Folder libsyscall/ 2012-10-05 07:22:53
Folder makedefs/ 2012-10-05 07:23:04
Folder osfmk/ 2012-10-05 07:22:47
Folder pexpert/ 2012-10-05 07:22:51
Folder security/ 2012-10-05 07:22:51
Folder tools/ 2012-10-05 07:22:46
File APPLE_LICENSE 19829 bytes 2006-02-21 03:35:32
File Makefile 1650 bytes 2012-09-17 18:17:25
File README 10511 bytes 2012-09-17 18:17:25
File kgmacros 394761 bytes 2012-09-17 18:17:26
File lldbmacros.py 7829 bytes 2011-11-13 22:07:30

    1 Table of contents:
    2 A. How to build XNU
    3 B. How to install a new header file from XNU
    4 
    5 =============================================
    6 A. How to build XNU:
    7 
    8 1) Type: "make"
    9 
   10   This builds all the components for kernel, architecture, and machine
   11   configurations defined in TARGET_CONFIGS.  Additionally, we also support
   12   architectures defined in ARCH_CONFIGS and kernel configurations defined in 
   13   KERNEL_CONFIGS.  Note that TARGET_CONFIGS overrides any configurations defined
   14   in ARCH_CONFIGS and KERNEL_CONFIGS.
   15 
   16   By default, architecture defaults to the build machine 
   17   architecture, and the kernel configuration is set to build for DEVELOPMENT.
   18   
   19   This will also create a bootable image, mach_kernel,  and a kernel binary 
   20   with symbols, mach_kernel.sys.
   21 
   22 
   23         /* this is all you need to do to build with RELEASE kernel configuration  */
   24         make TARGET_CONFIGS="release x86_64 default" SDKROOT=/path/to/SDK
   25         
   26         or the following is equivalent (ommitted SDKROOT will use /)
   27         
   28         make ARCH_CONFIGS=X86_64
   29 
   30 2) Building a Component
   31 
   32   Go to the top directory in your XNU project.
   33 
   34   If you are using a sh-style shell, run the following command:
   35      $ . SETUP/setup.sh
   36 
   37   If you are using a csh-style shell, run the following command:
   38      % source SETUP/setup.csh
   39 
   40   This will define the following environmental variables:
   41     SRCROOT, OBJROOT, DSTROOT, SYMROOT
   42 
   43   From a component top directory:
   44 
   45     $ make all
   46 
   47   This builds a component for all architectures, kernel configurations, and
   48   machine configurations defined in TARGET_CONFIGS (or alternately ARCH_CONFIGS
   49   and KERNEL_CONFIGS).
   50   
   51   Example:
   52     $(OBJROOT)/RELEASE_X86_64/osfmk/RELEASE/osfmk.filelist: list of objects in osfmk component
   53 
   54   From the component top directory:
   55 
   56     $ make mach_kernel
   57 
   58   This includes your component in the bootable image, mach_kernel,  and 
   59   in the kernel binary with symbols, mach_kernel.sys.
   60 
   61   WARNING: If a component header file has been modified, you will have to do 
   62            the above procedure 1.
   63 
   64 3) Building DEBUG
   65 
   66   Define kernel configuration to DEBUG in your environment or when running a 
   67   make command.  Then, apply procedures 4, 5
   68 
   69   $ make TARGET_CONFIGS="DEBUG X86_64 DEFAULT" all
   70 
   71   or
   72 
   73   $ make KERNEL_CONFIGS=DEBUG ARCH_CONFIGS=X86_64 all
   74 
   75   or
   76 
   77   $ export TARGET_CONFIGS="DEBUG X86_64 DEFAULT"
   78   $ export SDKROOT=/path/to/SDK
   79   $ make all
   80 
   81   Example:
   82     $(OBJROOT)/DEBUG_X86_64/osfmk/DEBUG/osfmk.filelist: list of objects in osfmk component
   83     $(OBJROOT)/DEBUG_X86_64/mach_kernel: bootable image
   84 
   85 4) Building fat
   86 
   87   Define architectures in your environment or when running a make command.
   88   Apply procedures 3, 4, 5
   89 
   90   $ make TARGET_CONFIGS="RELEASE I386 DEFAULT RELEASE X86_64 DEFAULT" exporthdrs all
   91 
   92   or
   93 
   94   $ make ARCH_CONFIGS="I386 X86_64" exporthdrs all
   95 
   96   or
   97 
   98   $ export ARCH_CONFIGS="I386 X86_64"
   99   $ make exporthdrs all
  100 
  101 5) Verbose make 
  102    To display complete tool invocations rather than an abbreviated version,
  103    $ make VERBOSE=YES
  104 
  105 6) Debug information formats
  106    By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named mach_kernel.dSYM
  107    To select the older STABS debug information format (where debug information is embedded in the mach_kernel.sys image), set the BUILD_STABS environment variable.
  108    $ export BUILD_STABS=1
  109    $ make
  110 
  111 7) Build check before integration
  112 
  113   From the top directory, run:
  114 
  115     $ ~rc/bin/buildit . -arch i386 -arch x86_64 -arch armv7 -arch ppc -noinstallsrc -nosum
  116 
  117         
  118   xnu supports a number of XBS build aliases, which allow B&I to build
  119   the same source submission multiple times in different ways, to
  120   produce different results. Each build alias supports the standard
  121   "clean", "install", "installsrc", "installhdrs" targets, but
  122   conditionalize their behavior on the RC_ProjectName make variable
  123   which is passed as the -project argument to ~rc/bin/buildit, which
  124   can be one of:
  125 
  126   -project xnu          # the default, builds /mach_kernel, kernel-space
  127                         # headers, user-space headers, man pages,
  128                         # symbol-set kexts
  129 
  130   -project xnu_debug    # a DEBUG kernel in /AppleInternal with dSYM
  131 
  132   -project libkxld      # user-space version of kernel linker
  133 
  134   -project libkmod      # static library automatically linked into kexts
  135 
  136   -project Libsyscall   # automatically generate BSD syscall stubs
  137 
  138 
  139 
  140 8) Creating tags and cscope
  141 
  142   Set up your build environment as per instructions in 2a
  143 
  144   From the top directory, run:
  145 
  146     $ make tags         # this will build ctags and etags on a case-sensitive
  147                         # volume, only ctags on case-insensitive
  148 
  149     $ make TAGS         # this will build etags
  150 
  151     $ make cscope       # this will build cscope database
  152 
  153 9) Other makefile options
  154 
  155    $ make MAKEJOBS=-j8    # this will use 8 processes during the build. The default is 2x the number of active cores
  156 
  157    $ make -w              # trace recursive make invocations. Useful in combination with VERBOSE=YES
  158 
  159    $ make BUILD_LTO=1     # build with LLVM Link Time Optimization (experimental)
  160 
  161    $ make BUILD_INTEGRATED_ASSEMBLER=1 # build with LLVM integrated assembler (experimental)
  162 
  163 =============================================
  164 B. How to install a new header file from XNU
  165 
  166 [Note: This does not cover installing header files in IOKit framework]
  167 
  168 1) XNU installs header files at the following locations -
  169         a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  170         b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  171         c. $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  172         d. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  173         e. $(DSTROOT)/usr/include/
  174 
  175         Kernel.framework is used by kernel extensions.  System.framework 
  176         and /usr/include are used by user level applications.  The header 
  177         files in framework's "PrivateHeaders" are only available for Apple 
  178         Internal development.
  179 
  180 2) The directory containing the header file should have a Makefile that 
  181    creates the list of files that should be installed at different locations.
  182    If you are adding first header file in a directory, you will need to 
  183    create Makefile similar to xnu/bsd/sys/Makefile.
  184 
  185    Add your header file to the correct file list depending on where you want 
  186    to install it.   The default locations where the header files are installed 
  187    from each file list are -
  188 
  189    a. DATAFILES : To make header file available in user level -
  190           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  191           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  192           $(DSTROOT)/usr/include/
  193 
  194    b. PRIVATE_DATAFILES : To make header file available to Apple internal in 
  195       user level -
  196           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  197 
  198    c. KERNELFILES : To make header file available in kernel level - 
  199           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  200           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  201 
  202    d. PRIVATE_KERNELFILES : To make header file available to Apple internal 
  203       for kernel extensions - 
  204           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  205 
  206 3) The Makefile combines the file lists mentioned above into different 
  207    install lists which are used by build system to install the header files.
  208 
  209    If the install list that you are interested does not exist, create it
  210    by adding the appropriate file lists.  The default install lists, its 
  211    member file lists and their default location are described below - 
  212 
  213    a. INSTALL_MI_LIST : Installs header file to location that is available to 
  214       everyone in user level. 
  215       Locations -
  216           $(DSTROOT)/System/Library/Frameworks/System.framework/Headers
  217           $(DSTROOT)/usr/include/
  218       Definition -
  219           INSTALL_MI_LIST = ${DATAFILES}
  220 
  221    b. INSTALL_MI_LCL_LIST : Installs header file to location that is available
  222       for Apple internal in user level.
  223       Locations -
  224           $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders
  225       Definition -
  226           INSTALL_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES}
  227 
  228    c. INSTALL_KF_MI_LIST : Installs header file to location that is available
  229       to everyone for kernel extensions.
  230       Locations -
  231           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  232       Definition -
  233           INSTALL_KF_MI_LIST = ${KERNELFILES}
  234 
  235    d. INSTALL_KF_MI_LCL_LIST : Installs header file to location that is 
  236       available for Apple internal for kernel extensions.
  237       Locations -
  238           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
  239       Definition -
  240           INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES}
  241 
  242 4) If you want to install the header file in a sub-directory of the paths 
  243    described in (1), specify the directory name using two variable 
  244    INSTALL_MI_DIR and EXPORT_MI_DIR as follows - 
  245 
  246    INSTALL_MI_DIR = dirname
  247    EXPORT_MI_DIR = dirname
  248 
  249 5) A single header file can exist at different locations using the steps 
  250    mentioned above.  However it might not be desirable to make all the code
  251    in the header file available at all the locations.  For example, you 
  252    want to export a function only to kernel level but not user level.
  253 
  254    You can use C language's pre-processor directive (#ifdef, #endif, #ifndef)
  255    to control the text generated before a header file is installed.  The kernel 
  256    only includes the code if the conditional macro is TRUE and strips out 
  257    code for FALSE conditions from the header file.  
  258 
  259    Some pre-defined macros and their descriptions are -
  260    a. PRIVATE : If true, code is available to all of the xnu kernel and is 
  261       not available in kernel extensions and user level header files.  The 
  262       header files installed in all the paths described above in (1) will not 
  263       have code enclosed within this macro.
  264 
  265    b. KERNEL_PRIVATE : Same as PRIVATE
  266 
  267    c. BSD_KERNEL_PRIVATE : If true, code is available to the xnu/bsd part of 
  268       the kernel and is not available to rest of the kernel, kernel extensions 
  269       and user level header files.  The header files installed in all the 
  270       paths described above in (1) will not have code enclosed within this 
  271       macro.
  272 
  273    d. KERNEL :  If true, code is available only in kernel and kernel 
  274       extensions and is not available in user level header files.  Only the 
  275       header files installed in following paths will have the code - 
  276           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
  277           $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders

[ 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.