Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame] | 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 | |