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 ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/README

Version: -  FREEBSD  -  FREEBSD11  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1 
SearchContext: -  none  -  3  -  10 

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

Cache object: 826c97dd418c5111b7458f432ee4ce27


[ source navigation ] [ diff markup ] [ 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.