Added the introduction chapter of progdoc.

4 files changed, 159 insertions, 4 deletions

diff --git a/Doc b/Doc
index 0ba53c6..512160a 100644
--- a/Doc
+++ b/Doc
@@ -1,3 +1,4 @@
+D prog-intro.sgml
 C lib
 C nest
 C conf
diff --git a/TODO b/TODO
index 6819510..ecf00d8 100644
--- a/TODO
+++ b/TODO
@@ -80,6 +80,7 @@ o  "About routing tables" by melo byt podstatne podrobnejsi (vysvetlit, co vlast
    ze lze prenaset routy mezi tabulkami (odkaz na protokol pipe), ze k tabulkam
    jsou pres filtry pripojeny protokoly atd.) Asi z toho udelat samostatnou kapitolu.
 o  Zminit logy a kategorie hlasek.
+o  Chybi installation requirements: tedy ze potrebujeme GCC a GNU make.
 
 Filtry:
 
diff --git a/doc/prog-intro.sgml b/doc/prog-intro.sgml
new file mode 100644
index 0000000..18637fe
--- /dev/null
+++ b/doc/prog-intro.sgml
@@ -0,0 +1,151 @@
+<sect>BIRD Design
+
+<sect1>Introduction
+
+<p>This document describes the internal workings of the BIRD, its architecture,
+design decisions and rationale behind them. It also contains documentation on
+all the essential components of the system and their interfaces.
+
+<p>Routing daemons are very complicated things which need to act in real time
+to complex sequences external events, react correctly even to the most erroneous behavior
+of their environment and still handle enormous amount of data with reasonable
+speed. Due to all of this, their design is very tricky as one needs to carefully
+balance between efficiency, stability and (last, but not least) simplicity of
+the program and it would be possible to write literally hundreds of pages about
+all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness
+is a sister of talent", we've tried to write a much shorter document highlighting
+the most important stuff and leaving the boring technical details better explained
+by the program source itself together with comments contained therein.
+
+<sect1>Design goals
+
+<p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
+daemons and also at some of the operating systems used on dedicated routers, gathered all important
+features and added lots of new ones to overcome their shortcomings and better match the requirements
+of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
+planning, the following set of design goals has arisen:
+
+<itemize>
+
+<item><it>Support all the standard routing protocols and make it easy to add new ones.</it>
+This leads to modularity and clean separation between the core and the protocols.
+
+<item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it>
+This leads to abstraction of IP addresses and operations on them.
+
+<item><it>Minimize OS dependent code to make porting as easy as possible.</it>
+Unfortunately, such code cannot be avoided at all as the details of communication with
+the IP stack differ from OS to OS and they often vary even between different
+versions of the same OS, but we can isolate such code in special modules and
+do the porting by changing just these modules.
+Also, don't rely on specific features of various operating systems, but be able
+to make use of them if they are available.
+
+<item><it>Allow multiple routing tables.</it>
+Easily solvable by abstracting out routing tables and the corresponding operations.
+
+<item><it>Offer powerful route filtering.</it>
+There already were several attempts to incorporate route filters to a dynamic router,
+but most of them have used simple sequences of filtering rules which were very inflexible
+and hard to use for any non-trivial filters. We've decided to employ a simple loop-free
+programming language having access to all the route attributes and being able to
+modify the most of them.
+
+<item><it>Support easy configuration and re-configuration.</it>
+Most routers use a simple configuration language designed ad hoc with no structure at all
+and allow online changes of configuration by using their command-line interface, thus
+any complex re-configurations are hard to achieve without replacing the configuration
+file and restarting the whole router. We've decided to use a more general approach: to
+have a configuration defined in a context-free language with blocks and nesting, to
+perform all configuration changes by editing the configuration file, but to be able
+to read the new configuration and smoothly adapt to it without disturbing parts of
+the routing process which are not affected by the change.
+
+<item><it>Be able to be controlled online.</it>
+In addition to online reconfiguration, a routing daemon should be able to communicate
+with the user and with many other programs (primarily scripts used for network maintenance)
+in order to make it possible to inspect contents of routing tables, status of all
+routing protocols and also to control their behavior (i.e., it should be possible
+to disable, enable or reset a protocol without restarting all the others). To achieve
+this, we implement a simple command-line protocol based on those used by FTP and SMTP
+(that is textual commands and textual replies accompanied by a numeric code which makes
+them both readable to a human and easy to recognize in software).
+
+<item><it>Respond to all protocol events in real time.</it>
+A typical solution to this problem is to use lots of threads to separate the workings
+of all the routing protocols and also of the user interface parts and to hope that
+the scheduler will assign time to them in a fair enough manner. This is surely a good
+solution, but we have resisted the temptation and preferred to avoid the overhead of threading
+and the large number of locks involved and preferred a event driven architecture with
+our own scheduling of events.
+
+</itemize>
+
+<sect1>Architecture
+
+<p>The requirements set above have lead to a simple modular architecture containing
+the following types of modules:
+
+<descrip>
+
+<tagp>Core modules</tagp> implement the core functions of BIRD as taking care
+of routing tables, keeping protocol status, interacting with the user using
+the Command-Line Interface (to be called CLI in the rest of this document)
+etc.
+
+<tagp>Library modules</tagp> form a large set of various library functions
+implementing several data abstractions, utility functions and also functions
+which are a part of standard libraries on some systems, but missing on other
+ones.
+
+<tagp>Resource management modules</tagp> take care of resources, their allocation
+and automatic freeing when the module having requested them ceases to exist.
+
+<tagp>Configuration modules</tagp> are fragments of lexical analyzer,
+grammar rules and the corresponding snippets of C code. For each group
+of code modules (core, each protocol, filters) there exist a configuration
+module taking care of all the related configuration stuff.
+
+<tagp>Filters</tagp> implement the route filtering language.
+
+<tagp>Protocol modules</tagp> implement the individual routing protocols.
+
+<tagp>System-dependent modules</tagp> implement the interface between BIRD
+and specific operating systems.
+
+<tagp>The client</tagp> is a simple program providing an easy, though friendly
+interface to the CLI.
+
+</descrip>
+
+<sect1>Implementation
+
+<p>BIRD has been written in GNU C. We've considered using of C++, but we've
+preferred the simplicity and straightforward nature of C which gives us fine
+control over all implementation details and on the other hand enough
+instruments to build the abstractions we need.
+
+<p>The building process is controlled by a set of Makefiles for GNU Make,
+intermixed with several Perl and shell scripts.
+
+<p>The initial configuration of the daemon, detection of system features
+and selection of the right modules to include for the particular OS
+and the set of protocols the user has chosen is performed by a configure
+script created using GNU Autoconf.
+
+<p>The parser of the configuration is generated by the GNU Bison.
+
+<p>The documentation is generated using <file/SGMLtools/ with our own DTD
+and mapping rules. The printed form of the documentation is first converted
+from SGML to <LaTeX> and then processed by <LaTeX> and <file/dvips/ to
+produce a PostScript file.
+
+<p>The comments from C sources which form a part of the programmer's
+documentation are extracted using a modified version of the <file/kernel-doc/
+tool.
+
+
+<!--
+LocalWords:  IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
+LocalWords:  PostScript
+ -->
diff --git a/lib/Doc b/lib/Doc
index f1579a3..bf1b406 100644
--- a/lib/Doc
+++ b/lib/Doc
@@ -2,11 +2,13 @@ H Library
 S checksum.c md5.c
 S ip.c ipv4.c ipv6.c
 S lists.c
-S mempool.c
-S slab.c
-S socket.h
 S bitops.c
-S event.c
 S patmatch.c
 S printf.c
 S unaligned.h
+H Resource management
+S resource.c
+S mempool.c
+S slab.c
+S socket.h
+S event.c