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/ 2009-09-10 23:52:26
Folder SETUP/ 2009-09-10 23:52:26
Folder bsd/ 2009-09-10 23:52:28
Folder config/ 2009-09-10 23:52:28
Folder iokit/ 2009-09-10 23:52:24
Folder libkern/ 2009-09-10 23:52:28
Folder libsa/ 2009-09-10 23:52:27
Folder libsyscall/ 2009-09-10 23:52:27
Folder makedefs/ 2009-09-10 23:52:25
Folder osfmk/ 2009-09-10 23:52:28
Folder pexpert/ 2009-09-10 23:52:28
Folder security/ 2009-09-10 23:52:25
Folder tools/ 2009-09-10 23:52:22
File APPLE_LICENSE 19829 bytes 2009-09-10 23:52:26
File Makefile 1592 bytes 2009-09-10 23:52:24
File README 10570 bytes 2009-09-10 23:52:24
File kgmacros 278945 bytes 2009-09-10 23:52:26

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