diff --git a/sysdep/Doc b/sysdep/Doc index 430581f2..7ada9f48 100644 --- a/sysdep/Doc +++ b/sysdep/Doc @@ -1 +1,2 @@ +D sysdep.sgml C unix diff --git a/sysdep/sysdep.sgml b/sysdep/sysdep.sgml new file mode 100644 index 00000000..7d0d781f --- /dev/null +++ b/sysdep/sysdep.sgml @@ -0,0 +1,27 @@ + + +System dependent parts + +Introduction + +

We've tried to make BIRD as portable as possible, but unfortunately +communication with the network stack differs from one OS to another, +so we need at least some OS specific code. The good news is that this +code is isolated in a small set of modules: + + + is a header file with configuration information, +definition of the standard set of types and so on. + diff --git a/sysdep/unix/Doc b/sysdep/unix/Doc index 5ab11b4c..a17f425b 100644 --- a/sysdep/unix/Doc +++ b/sysdep/unix/Doc @@ -1,4 +1,3 @@ -H UNIX system dependent parts S log.c S krt.c # io.c is documented under Resources diff --git a/sysdep/unix/krt.c b/sysdep/unix/krt.c index 9bc29808..7aee1f6b 100644 --- a/sysdep/unix/krt.c +++ b/sysdep/unix/krt.c @@ -6,6 +6,39 @@ * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Kernel synchronization + * + * This system dependent module implements the Kernel and Device protocol, + * that is synchronization of interface lists and routing tables with the + * OS kernel. + * + * The whole kernel synchronization is a bit messy and touches some internals + * of the routing table engine, because routing table maintenance is a typical + * example of the proverbial compatibility between different Unices and we want + * to keep the overhead of our krt business as low as possible and avoid maintaining + * a local routing table copy. + * + * The kernel syncer can work in three different modes (according to system config header): + * Either with a single routing table and single KRT protocol [traditional Unix] + * or with many routing tables and separate krt protocols for all of them + * or with many routing tables, but every scan including all tables, so we start + * separate krt protocols which cooperate with each other [Linux 2.2]. + * In this case, we keep only a single scan timer. + * + * We use FIB node flags to keep track of route synchronization status. We also + * attach temporary &rte's to the routing tables, but it cannot harm the rest of + * BIRD since table synchronization is an atomic process. + * + * When starting up, we cheat by looking if there is another + * KRT instance to be initialized later and performing table scan + * only once for all the instances. + */ + +/* + * If you are brave enough, continue now. You cannot say you haven't been warned. + */ + #undef LOCAL_DEBUG #include "nest/bird.h" @@ -18,30 +51,6 @@ #include "unix.h" #include "krt.h" -/* - * The whole kernel synchronization is a bit messy and touches some internals - * of the routing table engine, because routing table maintenance is a typical - * example of the proverbial compatibility between different Unices and we want - * to keep the overhead of our krt business as low as possible and avoid maintaining - * a local routing table copy. - * - * The kernel syncer can work in three different modes (according to system config header): - * o Single routing table, single krt protocol. [traditional Unix] - * o Many routing tables, separate krt protocols for all of them. - * o Many routing tables, but every scan includes all tables, so we start - * separate krt protocols which cooperate with each other. [Linux 2.2] - * In this case, we keep only a single scan timer. - * - * The hacky bits: - * o We use FIB node flags to keep track of route synchronization status. - * o When starting up, we cheat by looking if there is another kernel - * krt instance to be initialized later and performing table scan - * only once for all the instances. - * o We attach temporary rte's to routing tables. - * - * If you are brave enough, continue now. You cannot say you haven't been warned. - */ - static int krt_uptodate(rte *k, rte *e); /* diff --git a/sysdep/unix/log.c b/sysdep/unix/log.c index 4a4532af..72450e5e 100644 --- a/sysdep/unix/log.c +++ b/sysdep/unix/log.c @@ -1,11 +1,18 @@ /* * BIRD Library -- Logging Functions * - * (c) 1998--1999 Martin Mares + * (c) 1998--2000 Martin Mares * * Can be freely distributed and used under the terms of the GNU GPL. */ +/** + * DOC: Logging + * + * The Logging module offers a simple set of functions for writing + * messages to system logs and to the debug output. + */ + #include #include #include @@ -94,6 +101,16 @@ vlog(int class, char *msg, va_list args) cli_echo(class, buf); } +/** + * log - log a message + * @msg: printf-like formatting string with message class information + * prepended (%L_DEBUG to %L_BUG, see |lib/birdlib.h|) + * + * This function formats a message according to the format string @msg + * and writes it to the corresponding logfile (as specified in the + * configuration). Please note that the message is automatically + * formatted as a full line, no need to include |\n| inside. + */ void log(char *msg, ...) { @@ -107,6 +124,13 @@ log(char *msg, ...) va_end(args); } +/** + * bug - report an internal error + * @msg: a printf-like error message + * + * This function logs an internal error and aborts execution + * of the program. + */ void bug(char *msg, ...) { @@ -117,6 +141,13 @@ bug(char *msg, ...) abort(); } +/** + * bug - report a fatal error + * @msg: a printf-like error message + * + * This function logs a fatal error and aborts execution + * of the program. + */ void die(char *msg, ...) { @@ -127,6 +158,13 @@ die(char *msg, ...) exit(1); } +/** + * debug - write to debug output + * @msg: a printf-like message + * + * This function formats the message @msg and prints it out + * to the debugging output. No newline character is appended. + */ void debug(char *msg, ...) {