Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib / include / pj / doxygen.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJ_DOXYGEN_H__
21 #define __PJ_DOXYGEN_H__
22
23 /**
24  * @file doxygen.h
25  * @brief Doxygen's mainpage.
26  */
27
28 /*////////////////////////////////////////////////////////////////////////// */
29 /*
30         INTRODUCTION PAGE
31  */
32
33 /**
34  * @mainpage Welcome to PJLIB!
35  *
36  * @section intro_sec What is PJLIB
37  *
38  * PJLIB is an Open Source, small footprint framework library written in C for 
39  * making scalable applications. Because of its small footprint, it can be used
40  * in embedded applications (we hope so!), but yet the library is also aimed for
41  * facilitating the creation of high performance protocol stacks.
42  *
43  * PJLIB is released under GPL terms.
44  *
45  * @section download_sec Download
46  *
47  * PJLIB and all documentation can be downloaded from 
48  * http://www.pjsip.org.
49  *
50  *
51  * @section how_to_use_sec About This Documentation
52  *
53  * This document is generated directly from PJLIB source file using
54  * \a doxygen (http://www.doxygen.org). Doxygen is a great (and free!) 
55  * tools for generating such documentation.
56  *
57  *
58  * @subsection find_samples_subsec How to Read This Document
59  *
60  * This documentation is laid out more to be a reference guide instead
61  * of tutorial, therefore first time users may find it difficult to
62  * grasp PJLIB by reading this document alone.
63  *
64  * However, we've tried our best to make this document easy to follow.
65  * For first time users, we would suggest that you follow these steps
66  * when reading this documentation:
67  *
68  *  - continue reading this introduction chapter. At the end of this
69  *    chapter, you'll find section called \ref pjlib_fundamentals_sec
70  *    which should guide you to understand basic things about PJLIB.
71  *
72  *  - find information about specific features that you want to use
73  *    in PJLIB. Use the <b>Module Index</b> to find out about all 
74  *    features in PJLIB (if you're browsing the HTML documentation,
75  *    click on the \a Module link on top of the page, or if you're
76  *    reading the PDF documentation, click on \a Module \a Documentation
77  *    on the navigation pane on the left).
78  *
79  * @subsection doc_organize_sec How To's
80  *
81  * Please find below links to specific tasks that you probably
82  * want to do:
83  *
84  *  - <b>How to Build PJLIB</b>
85  *\n
86  * Please refer to \ref pjlib_build_sys_pg page for more information.
87  *
88  *  - <b>How to Use PJLIB in My Application</b>
89  *\n
90  * Please refer to \ref configure_app_sec for more information.
91  *
92  *  - <b>How to Port PJLIB</b>
93  *\n
94  * Please refer to \ref porting_pjlib_pg page.
95  *
96  *  - <b>Where to Read Samples Documentation</b>
97  *\n
98  * Most of the modules provide link to the corresponding sample file.
99  * Alternatively, to get the list of all examples, you can click on 
100  * <b>Related Pages</b> on the top of HTML document or on 
101  * <b>PJLIB Page Documentation</b> on navigation pane of your PDF reader.
102  *
103  *  - <b>How to Submit Code to PJLIB Project</b>
104  *\n
105  * Please read \ref pjlib_coding_convention_page before submitting
106  * your code. Send your code as patch against current Subversion tree
107  * to the appropriate mailing list.
108  *
109  *
110  * @section features_sec Features
111  *
112  * @subsection open_source_feat It's Open Source!
113  *
114  * PJLIB is currently released on GPL license, but other arrangements
115  * can be made with the author.
116  *
117  * @subsection extreme_portable_feat Extreme Portability
118  *
119  * PJLIB is designed to be extremely portable. It can run on any kind
120  * of processors (16-bit, 32-bit, or 64-bit, big or little endian, single
121  * or multi-processors) and operating systems. Floating point or no
122  * floating point. Multi-threading or not.
123  * It can even run in environment where no ANSI LIBC is available. 
124  *
125  * Currently PJLIB is known to run on these platforms:
126  *  - Win32/x86 (Win95/98/ME, NT/2000/XP/2003, mingw).
127  *  - arm, WinCE and Windows Mobile.
128  *  - Linux/x86, (user mode and as <b>kernel module</b>(!)).
129  *  - Linux/alpha
130  *  - Solaris/ultra.
131  *  - MacOS X/powerpc
132  *  - RTEMS (x86 and powerpc).
133  *
134  * And efforts is under way to port PJLIB on:
135  *  - Symbian OS
136  *
137  *
138  * @subsection small_size_feat Small in Size
139  *
140  * One of the primary objectives is to have library that is small in size for
141  * typical embedded applications. As a rough guidance, we aim to keep the 
142  * library size below 100KB for it to be considered as small.
143  * As the result, most of the functionalities in the library can be tailored
144  * to meet the requirements; user can enable/disable specific functionalities
145  * to get the desired size/performance/functionality balance.
146  *
147  * For more info, please see @ref pj_config.
148  *
149  *
150  * @subsection big_perform_feat Big in Performance
151  *
152  * Almost everything in PJLIB is designed to achieve the highest possible
153  * performance out of the target platform. 
154  *
155  *
156  * @subsection no_dyn_mem No Dynamic Memory Allocations
157  *
158  * The central idea of PJLIB is that for applications to run as fast as it can,
159  * it should not use \a malloc() at all, but instead should get the memory 
160  * from a preallocated storage pool. There are few things that can be 
161  * optimized with this approach:
162  *
163  *  - \a alloc() is a O(1) operation.
164  *  - no mutex is used inside alloc(). It is assumed that synchronization 
165  *    will be used in higher abstraction by application anyway.
166  *  - no \a free() is required. All chunks will be deleted when the pool is 
167  *    destroyed.
168  *
169  * The performance gained on some systems can be as high as 30x speed up
170  * against \a malloc() and \a free() on certain configurations, but of
171  * course your mileage may vary. 
172  *
173  * For more information, see \ref PJ_POOL_GROUP
174  *
175  * 
176  * @subsection os_abstract_feat Operating System Abstraction
177  *
178  * PJLIB has abstractions for features that are normally not portable 
179  * across operating systems: 
180  *  - @ref PJ_THREAD
181  *\n
182  *    Portable thread manipulation.
183  *  - @ref PJ_TLS
184  *\n
185  *    Storing data in thread's private data.
186  *  - @ref PJ_MUTEX
187  *\n
188  *    Mutual exclusion protection.
189  *  - @ref PJ_SEM
190  *\n
191  *    Semaphores.
192  *  - @ref PJ_ATOMIC
193  *\n
194  *    Atomic variables and their operations.
195  *  - @ref PJ_CRIT_SEC
196  *\n
197  *    Fast locking of critical sections.
198  *  - @ref PJ_LOCK
199  *\n
200  *    High level abstraction for lock objects.
201  *  - @ref PJ_EVENT
202  *\n
203  *    Event object.
204  *  - @ref PJ_TIME
205  *\n
206  *    Portable time manipulation.
207  *  - @ref PJ_TIMESTAMP
208  *\n
209  *    High resolution time value.
210  *  - etc.
211  *
212  *
213  * @subsection ll_network_io_sec Low-Level Network I/O
214  *
215  * PJLIB has very portable abstraction and fairly complete set of API for
216  * doing network I/O communications. At the lowest level, PJLIB provides:
217  *
218  *  - @ref PJ_SOCK
219  *\n
220  *    A highly portable socket abstraction, runs on all kind of
221  *    network APIs such as standard BSD socket, Windows socket, Linux
222  *    \b kernel socket, PalmOS networking API, etc.
223  *
224  *  - @ref pj_addr_resolve
225  *\n
226  *    Portable address resolution, which implements #pj_gethostbyname().
227  *
228  *  - @ref PJ_SOCK_SELECT
229  *\n
230  *    A portable \a select() like API (#pj_sock_select()) which can be
231  *    implemented with various back-end.
232  *
233  *
234  *
235  * @subsection timer_mgmt_sec Timer Management
236  *
237  * A passive framework for managing timer, see @ref PJ_TIMER for more info.
238  * There is also function to retrieve high resolution timestamp
239  * from the system (see @ref PJ_TIMESTAMP).
240  *
241  *
242  * @subsection data_struct_sec Various Data Structures
243  *
244  * Various data structures are provided in the library:
245  *
246  *  - @ref PJ_PSTR
247  *  - @ref PJ_ARRAY
248  *  - @ref PJ_HASH
249  *  - @ref PJ_LIST
250  *  - @ref PJ_RBTREE
251  *
252  *
253  * @subsection exception_sec Exception Construct
254  *
255  * A convenient TRY/CATCH like construct to propagate errors, which by
256  * default are used by the @ref PJ_POOL_GROUP "memory pool" and 
257  * the lexical scanner in pjlib-util. The exception
258  * construct can be used to write programs like below:
259  *
260  * <pre>
261  *    #define SYNTAX_ERROR  1
262  *
263  *    PJ_TRY {
264  *       msg = NULL;
265  *       msg = parse_msg(buf, len);
266  *    }
267  *    PJ_CATCH ( SYNTAX_ERROR ) {
268  *       .. handle error ..
269  *    }
270  *    PJ_END;
271  * </pre>
272  *
273  * Please see @ref PJ_EXCEPT for more information.
274  *
275  *
276  * @subsection logging_sec Logging Facility
277  *
278  * PJLIB @ref PJ_LOG consists of macros to write logging information to
279  * some output device. Some of the features of the logging facility:
280  *
281  *  - the verbosity can be fine-tuned both at compile time (to control
282  *    the library size) or run-time (to control the verbosity of the
283  *    information).
284  *  - output device is configurable (e.g. stdout, printk, file, etc.)
285  *  - log decoration is configurable.
286  *
287  * See @ref PJ_LOG for more information.
288  *
289  *
290  * @subsection guid_gen_sec Random and GUID Generation
291  *
292  * PJLIB provides facility to create random string 
293  * (#pj_create_random_string()) or globally unique identifier
294  * (see @ref PJ_GUID).
295  *
296  *
297  *
298  * @section configure_app_sec Configuring Application to use PJLIB
299  *
300  * @subsection pjlib_compil_sec Building PJLIB
301  *
302  * Follow the instructions in \ref pjlib_build_sys_pg to build
303  * PJLIB.
304  *
305  * @subsection pjlib_compil_app_sec Building Applications with PJLIB
306  *
307  * Use the following settings when building applications with PJLIB.
308  *
309  * @subsubsection compil_inc_dir_sec Include Search Path
310  *
311  * Add this to your include search path ($PJLIB is PJLIB root directory):
312  * <pre>
313  *   $PJLIB/include
314  * </pre>
315  *
316  * @subsubsection compil_inc_file_sec Include PJLIB Header
317  *
318  * To include all PJLIB headers:
319  * \verbatim
320     #include <pjlib.h>
321    \endverbatim
322  *
323  * Alternatively, you can include individual PJLIB headers like this:
324  * \verbatim
325      #include <pj/log.h>
326      #include <pj/os.h>
327   \endverbatim
328  *
329  *
330  * @subsubsection compil_lib_dir_sec Library Path
331  *
332  * Add this to your library search path:
333  * <pre>
334  *   $PJLIB/lib
335  * </pre>
336  *
337  * Then add the appropriate PJLIB library to your link specification. For
338  * example, you would add \c libpj-i386-linux-gcc.a when you're building
339  * applications in Linux.
340  *
341  *
342  * @subsection pjlib_fundamentals_sec Principles in Using PJLIB
343  *
344  * Few things that you \b MUST do when using PJLIB, to make sure that
345  * you create trully portable applications.
346  *
347  * @subsubsection call_pjlib_init_sec Call pj_init()
348  *
349  * Before you do anything else, call \c pj_init(). This would make sure that
350  * PJLIB system is properly set up.
351  *
352  * @subsubsection no_ansi_subsec Do NOT Use ANSI C
353  *
354  * Contrary to popular teaching, ANSI C (and LIBC) is not the most portable
355  * library in the world, nor it's the most ubiquitous. For example, LIBC
356  * is not available in Linux kernel. Also normally LIBC will be excluded
357  * from compilation of RTOSes to reduce size.
358  *
359  * So for maximum portability, do NOT use ANSI C. Do not even try to include
360  * any other header files outside <include/pj>. Stick with the functionalities
361  * provided by PJLIB. 
362  *
363  *
364  * @subsubsection string_rep_subsubsec Use pj_str_t instead of C Strings
365  *
366  * PJLIB uses pj_str_t instead of normal C strings. You SHOULD follow this
367  * convention too. Remember, ANSI string-h is not always available. And
368  * PJLIB string is faster!
369  *
370  * @subsubsection mem_alloc_subsubsec Use Pool for Memory Allocations
371  *
372  * You MUST NOT use \a malloc() or any other memory allocation functions.
373  * Use PJLIB @ref PJ_POOL_GROUP instead! It's faster and most portable.
374  *
375  * @subsection logging_subsubsec Use Logging for Text Display
376  *
377  * DO NOT use <stdio.h> for text output. Use PJLIB @ref PJ_LOG instead.
378  *
379  *
380  * @section porting_pjlib_sec0 Porting PJLIB
381  *
382  * Please see \ref porting_pjlib_pg page on more information to port
383  * PJLIB to new target.
384  *
385  * @section enjoy_sec Enjoy Using PJLIB!
386  *
387  * We hope that you find PJLIB usefull for your application. If you
388  * have any questions, suggestions, critics, bug fixes, or anything
389  * else, we would be happy to hear it.
390  *
391  * Enjoy using PJLIB!
392  *
393  * Benny Prijono < bennylp at pjsip dot org >
394  */
395
396
397
398 /*////////////////////////////////////////////////////////////////////////// */
399 /*
400          CODING CONVENTION
401  */
402
403 /**
404  * @page pjlib_coding_convention_page Coding Convention
405  *
406  * Before you submit your code/patches to be included with PJLIB, you must
407  * make sure that your code is compliant with PJLIB coding convention.
408  * <b>This is very important!</b> Otherwise we would not accept your code.
409  *
410  * @section coding_conv_editor_sec Editor Settings
411  *
412  * The single most important thing in the whole coding convention is editor 
413  * settings. It's more important than the correctness of your code (bugs will
414  * only crash the system, but incorrect tab size is mental!).
415  *
416  * Kindly set your editor as follows:
417  *  - tab size to \b 8.
418  *  - indentation to \b 4.
419  *
420  * With \c vi, you can do it with:
421  * <pre>
422  *  :se ts=8
423  *  :se sts=4
424  * </pre>
425  *
426  * You should replace tab with eight spaces.
427  *
428  * @section coding_conv_detail_sec Coding Style
429  *
430  * Coding style MUST strictly follow K&R style. The rest of coding style
431  * must follow current style. You SHOULD be able to observe the style
432  * currently used by PJLIB from PJLIB sources, and apply the style to your 
433  * code. If you're not able to do simple thing like to observe PJLIB
434  * coding style from the sources, then logic dictates that your ability to
435  * observe more difficult area in PJLIB such as memory allocation strategy, 
436  * concurrency, etc is questionable.
437  *
438  * @section coding_conv_comment_sec Commenting Your Code
439  *
440  * Public API (e.g. in header files) MUST have doxygen compliant comments.
441  *
442  */
443
444
445 /*////////////////////////////////////////////////////////////////////////// */
446 /*
447         BUILDING AND INSTALLING PJLIB
448  */
449
450
451
452 /**
453  * @page pjlib_build_sys_pg Building, and Installing PJLIB
454  *
455  * @section build_sys_install_sec Build and Installation
456  *
457  * \note
458  * <b>The most up-to-date information on building and installing PJLIB
459  *  should be found in the website, under "Getting Started" document.
460  *  More over, the new PJLIB build system is now based on autoconf,
461  *  so some of the information here might not be relevant anymore 
462  *  (although most still are, since the autoconf script still use
463  *  the old Makefile system as the backend).</b>
464  *
465  * @subsection build_sys_install_win32_sec Visual Studio
466  *
467  * The PJLIB Visual Studio workspace supports the building of PJLIB
468  * for Win32 target. Although currently only the Visual Studio 6 Workspace is
469  * actively maintained, developers with later version of Visual Studio
470  * can easily imports VS6 workspace into their IDE.
471  *
472  * To start building PJLIB projects with Visual Studio 6 or later, open
473  * the \a workspace file in the corresponding \b \c build directory. You have
474  * several choices on which \a dsw file to open:
475  \verbatim
476   $PJPROJECT/pjlib/build/pjlib.dsw
477   $PJPROJECT/pjsip/build/pjsip.dsw
478  ..etc
479  \endverbatim
480  *
481  * The easiest way is to open <tt>pjsip_apps.dsw</tt> file in \b \c $PJPROJECT/pjsip-apps/build
482  * directory, and build pjsua project or the samples project. 
483  * However this will not build the complete projects. 
484  * For example, the PJLIB test is not included in this workspace. 
485  * To build the complete projects, you must
486  * open and build each \a dsw file in \c build directory in each
487  * subprojects. For example, to open the complete PJLIB workspace, open
488  * <tt>pjlib.dsw</tt> in <tt>$PJPROJECT/pjlib/build</tt> directory.
489  *
490  *
491  * @subsubsection config_site_create_vc_sec Create config_site.h
492  *
493  * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
494  * is supposed to contain configuration that is specific to your site/target.
495  * This file is not part of PJLIB, so you must create it yourself. Normally
496  * you just need to create a blank file.
497  *
498  * The reason why it's not included in PJLIB is so that you would not accidently
499  * overwrite your site configuration.
500  *
501  * If you fail to do this, Visual C will complain with error like: 
502  *
503  * <b>"fatal error C1083: Cannot open include file: 'pj/config_site.h': No such file 
504  * or directory"</b>.
505  *
506  * @subsubsection build_vc_subsubsec Build the Projects
507  *
508  * Just hit the build button!
509  *
510  *
511  * @subsection build_sys_install_unix_sec Make System
512  *
513  * For other targets, PJLIB provides a rather comprehensive build system
514  * that uses GNU \a make (and only GNU \a make will work). 
515  * Currently, the build system supports building * PJLIB for these targets:
516  *  - i386/Win32/mingw
517  *  - i386/Linux
518  *  - i386/Linux (kernel)
519  *  - alpha/linux
520  *  - sparc/SunOS
521  *  - etc..
522  *
523  *
524  * @subsubsection build_req_sec Requirements
525  *
526  * In order to use the \c make based build system, you MUST have:
527  *
528  *  - <b>GNU make</b>
529  *\n
530  *    The Makefiles heavily utilize GNU make commands which most likely
531  *    are not available in other \c make system.
532  *  - <b>bash</b> shell is recommended.
533  *\n
534  *    Specificly, there is a command <tt>"echo -n"</tt> which may not work
535  *    in other shells. This command is used when generating dependencies
536  *    (<tt>make dep</tt>) and it's located in 
537  *    <tt>$PJPROJECT/build/rules.mak</tt>.
538  *  - <b>ar</b>, <b>ranlib</b> from GNU binutils
539  *\n
540  *    In your system has different <tt>ar</tt> or <tt>ranlib</tt> (e.g. they
541  *    may have been installed as <tt>gar</tt> and <tt>granlib</tt>), then
542  *    either you create the relevant symbolic links, <b>or</b> modify
543  *    <tt>$PJPROJECT/build/cc-gcc.mak</tt> and rename <tt>ar</tt> and
544  *    <tt>ranlib</tt> to the appropriate names.
545  *  - <b>gcc</b> to generate dependency.
546  *\n
547  *    Currently the build system uses <tt>"gcc -MM"</tt> to generate build
548  *    dependencies. If <tt>gcc</tt> is not desired to generate dependency,
549  *    then either you don't run <tt>make dep</tt>, <b>or</b> edit
550  *    <tt>$PJPROJECT/build/rules.mak</tt> to calculate dependency using
551  *    your prefered method. (And let me know when you do so so that I can
552  *    update the file. :) )
553  *
554  * @subsubsection build_overview_sec Building the Project
555  *
556  * Generally, steps required to build the PJLIB are:
557  *
558  \verbatim
559    $ cd /home/user/pjproject
560    $ ./configure
561    $ touch pjlib/include/pj/config_site.h
562    $ make dep
563    $ make
564  \endverbatim
565  *
566  * The above process will build all static libraries and all applications.
567  *
568  * \note the <tt>configure</tt> script is not a proper autoconf script,
569  * but rather a simple shell script to detect current host. This script
570  * currently does not support cross-compilation.
571  *
572  * \note For Linux kernel target, there are additional steps required, which
573  * will be explained in section \ref linux_kern_target_subsec.
574  *
575  * @subsubsection build_mak_sec Cross Compilation
576  * 
577  * For cross compilation, you will need to edit the \c build.mak file in 
578  * \c $PJPROJECT root directory manually. Please see <b>README-configure</b> file
579  * in the root directory for more information.
580  *
581  * For Linux kernel target, you are also required to declare the following
582  * variables in this file:
583  *      - \c KERNEL_DIR: full path of kernel source tree.
584  *      - \c KERNEL_ARCH: kernel ARCH options (e.g. "ARCH=um"), or leave blank
585  *           for default.
586  *      - \c PJPROJECT_DIR: full path of PJPROJECT source tree.
587  *
588  * Apart from these, there are also additional steps required to build
589  * Linux kernel target, which will be explained in \ref linux_kern_target_subsec.
590  *
591  * @subsubsection build_dir_sec Files in "build" Directory
592  *
593  * The <tt>*.mak</tt> files in \c $PJPROJECT/build directory are used to specify
594  * the configuration for the specified compiler, target machine target 
595  * operating system, and host options. These files will be executed
596  * (included) by \a make during building process, depending on the values
597  * specified in <b>$PJPROJECT/build.mak</b> file.
598  *
599  * Normally you don't need to edit these files, except when you're porting
600  * PJLIB to new target.
601  *
602  * Below are the description of some files in this directory:
603  *
604  *  - <tt>rules.mak</tt>: contains generic rules always included during make.
605  *  - <tt>cc-gcc.mak</tt>: rules when gcc is used for compiler.
606  *  - <tt>cc-vc.mak</tt>: rules when MSVC compiler is used.
607  *  - <tt>host-mingw.mak</tt>: rules for building in mingw host.
608  *  - <tt>host-unix.mak</tt>: rules for building in Unix/Posix host.
609  *  - <tt>host-win32.mak</tt>: rules for building in Win32 command console
610  *    (only valid when VC is used).
611  *  - <tt>m-i386.mak</tt>: rules when target machine is an i386 processor.
612  *  - <tt>m-m68k.mak</tt>: rules when target machine is an m68k processor.
613  *  - <tt>os-linux.mak</tt>: rules when target OS is Linux.
614  *  - <tt>os-linux-kernel.mak</tt>: rules when PJLIB is to be build as
615  *    part of Linux kernel.
616  *  - <tt>os-win32.mak</tt>: rules when target OS is Win32.
617  *
618  *
619  * @subsubsection config_site_create_sec Create config_site.h
620  *
621  * The file <tt><b>$PJPROJECT/pjlib/include/pj/config_site.h</b></tt>
622  * is supposed to contain configuration that is specific to your site/target.
623  * This file is not part of PJLIB, so you must create it yourself.
624  *
625  * The reason why it's not included in PJLIB is so that you would not accidently
626  * overwrite your site configuration.
627  *
628  *
629  * @subsubsection invoking_make_sec Invoking make
630  *
631  * Normally, \a make is invoked in \c build directory under each project.
632  * For example, to build PJLIB, you would invoke \a make in
633  * \c $PJPROJECT/pjlib/build directory like below:
634  *
635  \verbatim
636    $ cd pjlib/build
637    $ make
638  \endverbatim
639  *
640  * Alternatively you may invoke <tt>make</tt> in <tt>$PJPROJECT</tt> 
641  * directory, to build all projects under that directory (e.g. 
642  * PJLIB, PJSIP, etc.).
643  *
644  *
645  * @subsubsection linux_kern_target_subsec Linux Kernel Target
646  *
647  * \note
648  * <b>BUILDING APPLICATIONS IN LINUX KERNEL MODE IS A VERY DANGEROUS BUSINESS.
649  * YOU MAY CRASH THE WHOLE OF YOUR SYSTEM, CORRUPT YOUR HARDISK, ETC. PJLIB
650  * KERNEL MODULES ARE STILL IN EXPERIMENTAL PHASE. DO NOT RUN IT IN PRODUCTION
651  * SYSTEMS OR OTHER SYSTEMS WHERE RISK OF LOSS OF DATA IS NOT ACCEPTABLE.
652  * YOU HAVE BEEN WARNED.</b>
653  *
654  * \note
655  * <b>User Mode Linux (UML)</b> provides excellent way to experiment with Linux
656  * kernel without risking the stability of the host system. See
657  * http://user-mode-linux.sourceforge.net for details.
658  *
659  * \note
660  * I only use <b>UML</b> to experiment with PJLIB kernel modules.
661  * <b>I wouldn't be so foolish to use my host Linux machine to experiment
662  * with this.</b> 
663  *
664  * \note
665  * You have been warned.
666  *
667  * For building PJLIB for Linux kernel target, there are additional steps required.
668  * In general, the additional tasks are:
669  *      - Declare some more variables in <b><tt>build.mak</tt></b> file (this
670  *        has been explained in \ref build_mak_sec above).
671  *      - Perform these two small modifications in kernel source tree.
672  *
673  * There are two small modification need to be applied to the kernel tree.
674  *
675  * <b>1. Edit <tt>Makefile</tt> in kernel root source tree.</b>
676  *
677  * Add the following lines at the end of the <tt>Makefile</tt> in your 
678  * <tt>$KERNEL_SRC</tt> dir:
679  \verbatim
680 script:
681        $(SCRIPT)
682  \endverbatim
683  *
684  * \note Remember to replace spaces with <b>tab</b> in the Makefile.
685  *
686  * The modification above is needed to capture kernel's \c $CFLAGS and 
687  * \c $CFLAGS_MODULE which will be used for PJLIB's compilation.
688  *
689  * <b>2. Add Additional Exports.</b>
690  *
691  * We need the kernel to export some more symbols for our use. So we declare
692  * the additional symbols to be exported in <tt>extra-exports.c</tt> file, and add
693  * a this file to be compiled into the kernel:
694  *
695  *      - Copy the file <tt>extra-exports.c</tt> from <tt>pjlib/src/pj</tt> 
696  *        directory to <tt>$KERNEL_SRC/kernel/</tt> directory.
697  *      - Edit <tt>Makefile</tt> in that directory, and add this line
698  *        somewhere after the declaration of that variable:
699  \verbatim
700 obj-y   += extra-exports.o
701  \endverbatim
702  *
703  * To illustrate what have been done in your kernel source tree, below
704  * is screenshot of my kernel source tree _after_ the modification.
705  *
706  \verbatim
707 [root@vpc-linux linux-2.6.7]# pwd
708 /usr/src/linux-2.6.7
709 [root@vpc-linux linux-2.6.7]# 
710 [root@vpc-linux linux-2.6.7]# 
711 [root@vpc-linux linux-2.6.7]# tail Makefile 
712
713 endif   # skip-makefile
714
715 FORCE:
716
717 .PHONY: script
718
719 script:
720         $(SCRIPT)
721
722 [root@vpc-linux linux-2.6.7]# 
723 [root@vpc-linux linux-2.6.7]# 
724 [root@vpc-linux linux-2.6.7]# head kernel/extra-exports.c 
725 #include <linux/module.h>
726 #include <linux/syscalls.h>
727
728 EXPORT_SYMBOL(sys_select);
729
730 EXPORT_SYMBOL(sys_epoll_create);
731 EXPORT_SYMBOL(sys_epoll_ctl);
732 EXPORT_SYMBOL(sys_epoll_wait);
733
734 EXPORT_SYMBOL(sys_socket);
735 [root@vpc-linux linux-2.6.7]# 
736 [root@vpc-linux linux-2.6.7]# 
737 [root@vpc-linux linux-2.6.7]# head -15 kernel/Makefile 
738 #
739 # Makefile for the linux kernel.
740 #
741
742 obj-y     = sched.o fork.o exec_domain.o panic.o printk.o profile.o \
743             exit.o itimer.o time.o softirq.o resource.o \
744             sysctl.o capability.o ptrace.o timer.o user.o \
745             signal.o sys.o kmod.o workqueue.o pid.o \
746             rcupdate.o intermodule.o extable.o params.o posix-timers.o \
747             kthread.o
748
749 obj-y   +=  extra-exports.o
750
751 obj-$(CONFIG_FUTEX) += futex.o
752 obj-$(CONFIG_GENERIC_ISA_DMA) += dma.o
753 [root@vpc-linux linux-2.6.7]# 
754
755  \endverbatim
756  *
757  * Then you must rebuild the kernel.
758  * If you fail to do this, you won't be able to <b>insmod</b> pjlib.
759  *
760  * \note You will see a lots of warning messages during pjlib-test compilation.
761  * The warning messages complain about unresolved symbols which are defined
762  * in pjlib module. You can safely ignore these warnings. However, you can not
763  * ignore warnings about non-pjlib unresolved symbols.
764  *
765  * 
766  * @subsection makefile_explained_sec Makefile Explained
767  *
768  * The \a Makefile for each project (e.g. PJLIB, PJSIP, etc) should be
769  * very similar in the contents. The Makefile is located under \c build
770  * directory in each project subdir.
771  *
772  * @subsubsection pjlib_makefile_subsec PJLIB Makefile.
773  *
774  * Below is PJLIB's Makefile:
775  *
776  * \include build/Makefile
777  *
778  * @subsubsection pjlib_os_makefile_subsec PJLIB os-linux.mak.
779  *
780  * Below is file <tt><b>os-linux.mak</b></tt> file in 
781  * <tt>$PJPROJECT/pjlib/build</tt> directory,
782  * which is OS specific configuration file for Linux target that is specific 
783  * for PJLIB project. For \b global OS specific configuration, please see
784  * <tt>$PJPROJECT/build/os-*.mak</tt>.
785  *
786  * \include build/os-linux.mak
787  *
788  */
789
790
791 /*////////////////////////////////////////////////////////////////////////// */
792 /*
793          PORTING PJLIB
794  */
795
796
797
798 /**
799  * @page porting_pjlib_pg Porting PJLIB
800  *
801  * \note
802  * <b>Since version 0.5.8, PJLIB build system is now based on autoconf, so
803  * most of the time we shouldn't need to apply the tweakings below to get
804  * PJLIB working on a new platform. However, since the autoconf build system
805  * still uses the old Makefile build system, the information below may still
806  * be useful for reference.
807  * </b>
808  *
809  * @section new_arch_sec Porting to New CPU Architecture
810  *
811  * Below is step-by-step guide to add support for new CPU architecture.
812  * This sample is based on porting to Alpha architecture; however steps for 
813  * porting to other CPU architectures should be pretty similar. 
814  *
815  * Also note that in this example, the operating system used is <b>Linux</b>.
816  * Should you wish to add support for new operating system, then follow
817  * the next section \ref porting_os_sec.
818  *
819  * Step-by-step guide to port to new CPU architecture:
820  *  - decide the name for the new architecture. In this case, we choose
821  *    <tt><b>alpha</b></tt>.
822  *  - edit file <tt>$PJPROJECT/build.mak</tt>, and add new section for
823  *    the new target:
824  *    <pre>
825  *      #
826  *      # Linux alpha, gcc
827  *      #
828  *      export MACHINE_NAME := <b>alpha</b>
829  *      export OS_NAME := linux
830  *      export CC_NAME := gcc
831  *      export HOST_NAME := unix
832  *    </pre>
833  *
834  *  - create a new file <tt>$PJPROJECT/build/<b>m-alpha</b>.mak</tt>.
835  *    Alternatively create a copy from other file in this directory.
836  *    The contents of this file will look something like:
837  *    <pre>
838  *      export M_CFLAGS := $(CC_DEF)<b>PJ_M_ALPHA=1</b>
839  *      export M_CXXFLAGS :=
840  *      export M_LDFLAGS :=
841  *      export M_SOURCES :=
842  *    </pre>
843  *  - create a new file <tt>$PJPROJECT/pjlib/include/pj/compat/<b>m_alpha.h</b></tt>.
844  *    Alternatively create a copy from other header file in this directory.
845  *    The contents of this file will look something like:
846  *    <pre>
847  *      #define PJ_HAS_PENTIUM          0
848  *      #define PJ_IS_LITTLE_ENDIAN     1
849  *      #define PJ_IS_BIG_ENDIAN        0
850  *    </pre>
851  *  - edit <tt>pjlib/include/pj/<b>config.h</b></tt>. Add new processor
852  *    configuration in this header file, like follows:
853  *    <pre>
854  *      ...
855  *      #elif defined (PJ_M_ALPHA) && PJ_M_ALPHA != 0
856  *      #   include <pj/compat/m_alpha.h>
857  *      ...
858  *    </pre>
859  *  - done. Build PJLIB with:
860  *    <pre>
861  *      $ cd $PJPROJECT/pjlib/build
862  *      $ make dep
863  *      $ make clean
864  *      $ make
865  *    </pre>
866  *
867  * @section porting_os_sec Porting to New Operating System Target
868  *
869  * This section will try to give you rough guideline on how to
870  * port PJLIB to a new target. As a sample, we give the target a name tag, 
871  * for example <tt><b>xos</b></tt> (for X OS). 
872  *
873  * @subsection new_compat_os_h_file_sec Create New Compat Header File
874  *
875  * You'll need to create a new header file 
876  * <b><tt>include/pj/compat/os_xos.h</tt></b>. You can copy as a 
877  * template other header file and edit it accordingly.
878  *
879  * @subsection modify_config_h_file_sec Modify config.h
880  *
881  * Then modify file <b><tt>include/pj/config.h</tt></b> to include
882  * this file accordingly (e.g. when macro <tt><b>PJ_XOS</b></tt> is
883  * defined):
884  *
885  \verbatim
886  ...
887  #elif defined(PJ_XOS)
888  #  include <pj/compat/os_xos.h>
889  #else
890  #...
891  \endverbatim
892  * 
893  * @subsection new_target_mak_file_sec Create New Global Make Config File
894  *
895  * Then you'll need to create global configuration file that
896  * is specific for this OS, i.e. <tt><b>os-xos.mak</b></tt> in 
897  * <tt><b>$PJPROJECT/build</b></tt> directory.
898  *
899  * At very minimum, the file will normally need to define
900  * <tt><b>PJ_XOS=1</b></tt> in the \c CFLAGS section:
901  *
902  \verbatim
903 #
904 # $PJPROJECT/build/os-xos.mak:
905 #
906 export OS_CFLAGS   := $(CC_DEF)PJ_XOS=1
907 export OS_CXXFLAGS := 
908 export OS_LDFLAGS  :=
909 export OS_SOURCES  := 
910  \endverbatim
911  *
912  *
913  * @subsection new_target_prj_mak_file_sec Create New Project's Make Config File
914  *
915  * Then you'll need to create xos-specific configuration file
916  * for PJLIB. This file is also named <tt><b>os-xos.mak</b></tt>,
917  * but its located in <tt><b>pjlib/build</b></tt> directory.
918  * This file will specify source files that are specific to
919  * this OS to be included in the build process.
920  *
921  * Below is a sample:
922  \verbatim
923 #
924 # pjlib/build/os-xos.mak:
925 #  XOS specific configuration for PJLIB.
926 #
927 export PJLIB_OBJS +=    os_core_xos.o \
928                         os_error_unix.o \
929                         os_time_ansi.o
930 export TEST_OBJS +=     main.o
931 export TARGETS      =   pjlib pjlib-test
932  \endverbatim
933  *
934  * @subsection new_target_src_sec Create and Edit Source Files
935  *
936  * You'll normally need to create at least these files:
937  *  - <tt><b>os_core_xos.c</b></tt>: core OS specific
938  *    functionality.
939  *  - <tt><b>os_timestamp_xos.c</b></tt>: how to get timestamp
940  *    in this OS.
941  *
942  * Depending on how things are done in your OS, you may need
943  * to create these files:
944  *  - <tt><b>os_error_*.c</b></tt>: how to manipulate
945  *    OS error codes. Alternatively you may use existing
946  *    <tt>os_error_unix.c</tt> if the OS has \c errno and
947  *    \c strerror() function.
948  *  - <tt><b>ioqueue_*.c</b></tt>: if the OS has specific method
949  *    to perform asynchronous I/O. Alternatively you may
950  *    use existing <tt>ioqueue_select.c</tt> if the OS supports
951  *    \c select() function call.
952  *  - <tt><b>sock_*.c</b></tt>: if the OS has specific method
953  *    to perform socket communication. Alternatively you may
954  *    use existing <tt>sock_bsd.c</tt> if the OS supports
955  *    BSD socket API, and edit <tt>include/pj/compat/socket.h</tt>
956  *    file accordingly.
957  *
958  * You will also need to check various files in 
959  * <tt><b>include/pj/compat/*.h</b></tt>, to see if they're 
960  * compatible with your OS.
961  *
962  * @subsection new_target_build_file_sec Build The Project
963  *
964  * After basic building blocks have been created for the OS, then
965  * the easiest way to see which parts need to be fixed is by building
966  * the project and see the error messages.
967  *
968  * @subsection new_target_edit_vs_new_file_sec Editing Existing Files vs Creating New File
969  *
970  * When you encounter compatibility errors in PJLIB during porting,
971  * you have three options on how to fix the error:
972  *  - edit the existing <tt>*.c</tt> file, and give it <tt>#ifdef</tt>
973  *    switch for the new OS, or
974  *  - edit <tt>include/pj/compat/*.h</tt> instead, or
975  *  - create a totally new file.
976  *
977  * Basicly there is no strict rule on which approach is the best
978  * to use, however the following guidelines may be used:
979  *  - if the file is expected to be completely different than
980  *    any existing file, then perhaps you should create a completely
981  *    new file. For example, file <tt>os_core_xxx.c</tt> will 
982  *    normally be different for each OS flavour.
983  *  - if the difference can be localized in <tt>include/compat</tt>
984  *    header file, and existing <tt>#ifdef</tt> switch is there,
985  *    then preferably you should edit this <tt>include/compat</tt>
986  *    header file.
987  *  - if the existing <tt>*.c</tt> file has <tt>#ifdef</tt> switch,
988  *    then you may add another <tt>#elif</tt> switch there. This
989  *    normally is used for behaviors that are not totally
990  *    different on each platform.
991  *  - other than that above, use your own judgement on whether
992  *    to edit the file or create new file etc.
993  */
994
995 #endif  /* __PJ_DOXYGEN_H__ */
996