doxygen.h

一个开源的sip源代码

 *
 * For building PJLIB for Linux kernel target, there are additional steps required.
 * In general, the additional tasks are:
 *	- Declare some more variables in <b><tt>build.mak</tt></b> file (this
 *        has been explained in \ref build_mak_sec above).
 *      - Perform these two small modifications in kernel source tree.
 *
 * There are two small modification need to be applied to the kernel tree.
 *
 * <b>1. Edit <tt>Makefile</tt> in kernel root source tree.</b>
 *
 * Add the following lines at the end of the <tt>Makefile</tt> in your 
 * <tt>$KERNEL_SRC</tt> dir:
 \verbatim
script:
       $(SCRIPT)
 \endverbatim
 *
 * \note Remember to replace spaces with <b>tab</b> in the Makefile.
 *
 * The modification above is needed to capture kernel's \c $CFLAGS and 
 * \c $CFLAGS_MODULE which will be used for PJLIB's compilation.
 *
 * <b>2. Add Additional Exports.</b>
 *
 * We need the kernel to export some more symbols for our use. So we declare
 * the additional symbols to be exported in <tt>extra-exports.c</tt> file, and add
 * a this file to be compiled into the kernel:
 *
 *	- Copy the file <tt>extra-exports.c</tt> from <tt>pjlib/src/pj</tt> 
 *	  directory to <tt>$KERNEL_SRC/kernel/</tt> directory.
 *	- Edit <tt>Makefile</tt> in that directory, and add this line
 *        somewhere after the declaration of that variable:
 \verbatim
obj-y   += extra-exports.o
 \endverbatim
 *
 * To illustrate what have been done in your kernel source tree, below
 * is screenshot of my kernel source tree _after_ the modification.
 *
 \verbatim
[root@vpc-linux linux-2.6.7]# pwd
/usr/src/linux-2.6.7
[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# tail Makefile 

endif   # skip-makefile

FORCE:

.PHONY: script

script:
        $(SCRIPT)

[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# head kernel/extra-exports.c 
#include <linux/module.h>
#include <linux/syscalls.h>

EXPORT_SYMBOL(sys_select);

EXPORT_SYMBOL(sys_epoll_create);
EXPORT_SYMBOL(sys_epoll_ctl);
EXPORT_SYMBOL(sys_epoll_wait);

EXPORT_SYMBOL(sys_socket);
[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# 
[root@vpc-linux linux-2.6.7]# head -15 kernel/Makefile 
#
# Makefile for the linux kernel.
#

obj-y     = sched.o fork.o exec_domain.o panic.o printk.o profile.o \
            exit.o itimer.o time.o softirq.o resource.o \
            sysctl.o capability.o ptrace.o timer.o user.o \
            signal.o sys.o kmod.o workqueue.o pid.o \
            rcupdate.o intermodule.o extable.o params.o posix-timers.o \
            kthread.o

obj-y   +=  extra-exports.o

obj-$(CONFIG_FUTEX) += futex.o
obj-$(CONFIG_GENERIC_ISA_DMA) += dma.o
[root@vpc-linux linux-2.6.7]# 

 \endverbatim
 *
 * Then you must rebuild the kernel.
 * If you fail to do this, you won't be able to <b>insmod</b> pjlib.
 *
 * \note You will see a lots of warning messages during pjlib-test compilation.
 * The warning messages complain about unresolved symbols which are defined
 * in pjlib module. You can safely ignore these warnings. However, you can not
 * ignore warnings about non-pjlib unresolved symbols.
 *
 * 
 * @subsection makefile_explained_sec Makefile Explained
 *
 * The \a Makefile for each project (e.g. PJLIB, PJSIP, etc) should be
 * very similar in the contents. The Makefile is located under \c build
 * directory in each project subdir.
 *
 * @subsubsection pjlib_makefile_subsec PJLIB Makefile.
 *
 * Below is PJLIB's Makefile:
 *
 * \include build/Makefile
 *
 * @subsubsection pjlib_os_makefile_subsec PJLIB os-linux.mak.
 *
 * Below is file <tt><b>os-linux.mak</b></tt> file in 
 * <tt>$PJPROJECT/pjlib/build</tt> directory,
 * which is OS specific configuration file for Linux target that is specific 
 * for PJLIB project. For \b global OS specific configuration, please see
 * <tt>$PJPROJECT/build/os-*.mak</tt>.
 *
 * \include build/os-linux.mak
 *
 */


/*////////////////////////////////////////////////////////////////////////// */
/*
         PORTING PJLIB
 */



/**
 * @page porting_pjlib_pg Porting PJLIB
 *
 * \note
 * <b>Since version 0.5.8, PJLIB build system is now based on autoconf, so
 * most of the time we shouldn't need to apply the tweakings below to get
 * PJLIB working on a new platform. However, since the autoconf build system
 * still uses the old Makefile build system, the information below may still
 * be useful for reference.
 * </b>
 *
 * @section new_arch_sec Porting to New CPU Architecture
 *
 * Below is step-by-step guide to add support for new CPU architecture.
 * This sample is based on porting to Alpha architecture; however steps for 
 * porting to other CPU architectures should be pretty similar. 
 *
 * Also note that in this example, the operating system used is <b>Linux</b>.
 * Should you wish to add support for new operating system, then follow
 * the next section \ref porting_os_sec.
 *
 * Step-by-step guide to port to new CPU architecture:
 *  - decide the name for the new architecture. In this case, we choose
 *    <tt><b>alpha</b></tt>.
 *  - edit file <tt>$PJPROJECT/build.mak</tt>, and add new section for
 *    the new target:
 *    <pre>
 *      #
 *      # Linux alpha, gcc
 *      #
 *      export MACHINE_NAME := <b>alpha</b>
 *      export OS_NAME := linux
 *      export CC_NAME := gcc
 *      export HOST_NAME := unix
 *    </pre>
 *
 *  - create a new file <tt>$PJPROJECT/build/<b>m-alpha</b>.mak</tt>.
 *    Alternatively create a copy from other file in this directory.
 *    The contents of this file will look something like:
 *    <pre>
 *      export M_CFLAGS := $(CC_DEF)<b>PJ_M_ALPHA=1</b>
 *      export M_CXXFLAGS :=
 *      export M_LDFLAGS :=
 *      export M_SOURCES :=
 *    </pre>
 *  - create a new file <tt>$PJPROJECT/pjlib/include/pj/compat/<b>m_alpha.h</b></tt>.
 *    Alternatively create a copy from other header file in this directory.
 *    The contents of this file will look something like:
 *    <pre>
 *      #define PJ_HAS_PENTIUM          0
 *      #define PJ_IS_LITTLE_ENDIAN     1
 *      #define PJ_IS_BIG_ENDIAN        0
 *    </pre>
 *  - edit <tt>pjlib/include/pj/<b>config.h</b></tt>. Add new processor
 *    configuration in this header file, like follows:
 *    <pre>
 *      ...
 *      #elif defined (PJ_M_ALPHA) && PJ_M_ALPHA != 0
 *      #   include <pj/compat/m_alpha.h>
 *      ...
 *    </pre>
 *  - done. Build PJLIB with:
 *    <pre>
 *      $ cd $PJPROJECT/pjlib/build
 *      $ make dep
 *      $ make clean
 *      $ make
 *    </pre>
 *
 * @section porting_os_sec Porting to New Operating System Target
 *
 * This section will try to give you rough guideline on how to
 * port PJLIB to a new target. As a sample, we give the target a name tag, 
 * for example <tt><b>xos</b></tt> (for X OS). 
 *
 * @subsection new_compat_os_h_file_sec Create New Compat Header File
 *
 * You'll need to create a new header file 
 * <b><tt>include/pj/compat/os_xos.h</tt></b>. You can copy as a 
 * template other header file and edit it accordingly.
 *
 * @subsection modify_config_h_file_sec Modify config.h
 *
 * Then modify file <b><tt>include/pj/config.h</tt></b> to include
 * this file accordingly (e.g. when macro <tt><b>PJ_XOS</b></tt> is
 * defined):
 *
 \verbatim
 ...
 #elif defined(PJ_XOS)
 #  include <pj/compat/os_xos.h>
 #else
 #...
 \endverbatim
 * 
 * @subsection new_target_mak_file_sec Create New Global Make Config File
 *
 * Then you'll need to create global configuration file that
 * is specific for this OS, i.e. <tt><b>os-xos.mak</b></tt> in 
 * <tt><b>$PJPROJECT/build</b></tt> directory.
 *
 * At very minimum, the file will normally need to define
 * <tt><b>PJ_XOS=1</b></tt> in the \c CFLAGS section:
 *
 \verbatim
#
# $PJPROJECT/build/os-xos.mak:
#
export OS_CFLAGS   := $(CC_DEF)PJ_XOS=1
export OS_CXXFLAGS := 
export OS_LDFLAGS  :=
export OS_SOURCES  := 
 \endverbatim
 *
 *
 * @subsection new_target_prj_mak_file_sec Create New Project's Make Config File
 *
 * Then you'll need to create xos-specific configuration file
 * for PJLIB. This file is also named <tt><b>os-xos.mak</b></tt>,
 * but its located in <tt><b>pjlib/build</b></tt> directory.
 * This file will specify source files that are specific to
 * this OS to be included in the build process.
 *
 * Below is a sample:
 \verbatim
#
# pjlib/build/os-xos.mak:
#  XOS specific configuration for PJLIB.
#
export PJLIB_OBJS += 	os_core_xos.o \
                        os_error_unix.o \
                        os_time_ansi.o
export TEST_OBJS +=	main.o
export TARGETS	    =	pjlib pjlib-test
 \endverbatim
 *
 * @subsection new_target_src_sec Create and Edit Source Files
 *
 * You'll normally need to create at least these files:
 *  - <tt><b>os_core_xos.c</b></tt>: core OS specific
 *    functionality.
 *  - <tt><b>os_timestamp_xos.c</b></tt>: how to get timestamp
 *    in this OS.
 *
 * Depending on how things are done in your OS, you may need
 * to create these files:
 *  - <tt><b>os_error_*.c</b></tt>: how to manipulate
 *    OS error codes. Alternatively you may use existing
 *    <tt>os_error_unix.c</tt> if the OS has \c errno and
 *    \c strerror() function.
 *  - <tt><b>ioqueue_*.c</b></tt>: if the OS has specific method
 *    to perform asynchronous I/O. Alternatively you may
 *    use existing <tt>ioqueue_select.c</tt> if the OS supports
 *    \c select() function call.
 *  - <tt><b>sock_*.c</b></tt>: if the OS has specific method
 *    to perform socket communication. Alternatively you may
 *    use existing <tt>sock_bsd.c</tt> if the OS supports
 *    BSD socket API, and edit <tt>include/pj/compat/socket.h</tt>
 *    file accordingly.
 *
 * You will also need to check various files in 
 * <tt><b>include/pj/compat/*.h</b></tt>, to see if they're 
 * compatible with your OS.
 *
 * @subsection new_target_build_file_sec Build The Project
 *
 * After basic building blocks have been created for the OS, then
 * the easiest way to see which parts need to be fixed is by building
 * the project and see the error messages.
 *
 * @subsection new_target_edit_vs_new_file_sec Editing Existing Files vs Creating New File
 *
 * When you encounter compatibility errors in PJLIB during porting,
 * you have three options on how to fix the error:
 *  - edit the existing <tt>*.c</tt> file, and give it <tt>#ifdef</tt>
 *    switch for the new OS, or
 *  - edit <tt>include/pj/compat/*.h</tt> instead, or
 *  - create a totally new file.
 *
 * Basicly there is no strict rule on which approach is the best
 * to use, however the following guidelines may be used:
 *  - if the file is expected to be completely different than
 *    any existing file, then perhaps you should create a completely
 *    new file. For example, file <tt>os_core_xxx.c</tt> will 
 *    normally be different for each OS flavour.
 *  - if the difference can be localized in <tt>include/compat</tt>
 *    header file, and existing <tt>#ifdef</tt> switch is there,
 *    then preferably you should edit this <tt>include/compat</tt>
 *    header file.
 *  - if the existing <tt>*.c</tt> file has <tt>#ifdef</tt> switch,
 *    then you may add another <tt>#elif</tt> switch there. This
 *    normally is used for behaviors that are not totally
 *    different on each platform.
 *  - other than that above, use your own judgement on whether
 *    to edit the file or create new file etc.
 */

#endif	/* __PJ_DOXYGEN_H__ */