From 58f7d004fddd2cccdb019be59b6cc7a8abe50510 Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Wed, 7 Jun 2000 13:25:53 +0000 Subject: Fixes to the progdoc. --- conf/cf-lex.l | 6 +++--- conf/conf.c | 6 +++--- doc/prog-intro.sgml | 22 ++++++++++----------- lib/event.c | 4 +--- lib/resource.sgml | 2 +- lib/slab.c | 4 ++-- nest/cli.c | 8 ++++---- nest/locks.c | 6 +++--- nest/neighbor.c | 6 +++--- nest/proto-hooks.c | 2 +- nest/proto.sgml | 2 +- nest/rt-fib.c | 4 ++-- nest/rt-table.c | 2 +- proto/bgp/bgp.c | 4 ++-- proto/rip/rip.c | 55 +++++++++++++++++++++++++++-------------------------- sysdep/unix/io.c | 4 ++-- sysdep/unix/krt.c | 10 +++++----- 17 files changed, 73 insertions(+), 74 deletions(-) diff --git a/conf/cf-lex.l b/conf/cf-lex.l index 49984f55..9dfe10ea 100644 --- a/conf/cf-lex.l +++ b/conf/cf-lex.l @@ -10,12 +10,12 @@ * DOC: Lexical analyzer * * The lexical analyzer used for configuration files and CLI commands - * is generated using the |flex| tool accompanied with a couple of + * is generated using the |flex| tool accompanied by a couple of * functions maintaining the hash tables containing information about * symbols and keywords. * * Each symbol is represented by a &symbol structure containing name - * of the symbol, its scope, symbol class (%SYM_PROTO for a name of a protocol, + * of the symbol, its lexical scope, symbol class (%SYM_PROTO for a name of a protocol, * %SYM_NUMBER for a numeric constant etc.) and class dependent data. * When an unknown symbol is encountered, it's automatically added to the * symbol table with class %SYM_VOID. @@ -454,7 +454,7 @@ cf_symbol_class_name(struct symbol *sym) * the |gen_parser.m4| script. * * Grammar snippets are files (usually with extension |.Y|) contributed - * by various BIRD modules to provide information about syntax of their + * by various BIRD modules in order to provide information about syntax of their * configuration and their CLI commands. Each snipped consists of several * section, each of them starting with a special keyword: |CF_HDR| for * a list of |#include| directives needed by the C code, |CF_DEFINES| diff --git a/conf/conf.c b/conf/conf.c index 232be3fd..d6e2425e 100644 --- a/conf/conf.c +++ b/conf/conf.c @@ -9,9 +9,9 @@ /** * DOC: Configuration manager * - * Configuration of BIRD is complex, but straightforward. There exist three + * Configuration of BIRD is complex, yet straightforward. There exist three * modules taking care of the configuration: config manager (which takes care - * of storage of config information and controls switching between configs), + * of storage of the config information and controls switching between configs), * lexical analyzer and parser. * * The configuration manager stores each config as a &config structure @@ -27,7 +27,7 @@ * * Loading of new configuration is very simple: just call config_alloc() * to get a new &config structure, then use config_parse() to parse a - * configuration file and fill all information in the structure + * configuration file and fill all fields of the structure * and finally ask the config manager to switch to the new * config by calling config_commit(). * diff --git a/doc/prog-intro.sgml b/doc/prog-intro.sgml index ac45ab24..f584f69b 100644 --- a/doc/prog-intro.sgml +++ b/doc/prog-intro.sgml @@ -2,12 +2,12 @@ Introduction -

This document describes the internal workings of the BIRD, its architecture, +

This document describes the internal workings of BIRD, its architecture, design decisions and rationale behind them. It also contains documentation on all the essential components of the system and their interfaces.

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 +to complex sequences of external events, respond 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 @@ -21,7 +21,7 @@ by the program source itself together with comments contained therein.

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 +features and added lots of new ones to overcome their shortcomings and to 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: @@ -36,8 +36,8 @@ This leads to abstraction of IP addresses and operations on them. Minimize OS dependent code to make porting as easy as possible. 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. +versions of the same OS. But we can isolate such code in special modules and +do the porting by changing or replacing 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. @@ -62,7 +62,7 @@ to read the new configuration and smoothly adapt to it without disturbing parts the routing process which are not affected by the change. Be able to be controlled online. -In addition to online reconfiguration, a routing daemon should be able to communicate +In addition to the 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 @@ -71,7 +71,7 @@ this, we implement a simple command-line protocol based on those used by FTP and (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). -Respond to all protocol events in real time. +Respond to all events in real time. 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 @@ -88,18 +88,18 @@ the following types of modules: -Core modules implement the core functions of BIRD as taking care +Core modules implement the core functions of BIRD: 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. Library modules 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 +which are a part of the standard libraries on some systems, but missing on other ones. Resource management modules take care of resources, their allocation -and automatic freeing when the module having requested them ceases to exist. +and automatic freeing when the module having requested shuts itself down. Configuration modules are fragments of lexical analyzer, grammar rules and the corresponding snippets of C code. For each group @@ -120,7 +120,7 @@ interface to the CLI. Implementation -

BIRD has been written in GNU C. We've considered using of C++, but we've +

BIRD has been written in GNU C. We've considered using 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. diff --git a/lib/event.c b/lib/event.c index 788aab42..9b5870d3 100644 --- a/lib/event.c +++ b/lib/event.c @@ -13,12 +13,10 @@ * Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller * parts, so that no module can monopolize the CPU. To split such a task, just create * an &event resource, point it to the function you want to have called and call ev_schedule() - * to ask the core to run the event when nothing more important will require attention. + * to ask the core to run the event when nothing more important requires attention. * * You can also define your own event lists (the &event_list structure), enqueue your * events in them and explicitly ask to run them. - * - * The actual implementation is system dependent. */ #include "nest/bird.h" diff --git a/lib/resource.sgml b/lib/resource.sgml index df02bbfc..6b6dd7d2 100644 --- a/lib/resource.sgml +++ b/lib/resource.sgml @@ -21,7 +21,7 @@ modules of BIRD, deallocates everything automatically when a module shuts down and it's is able to print out the list of resources and the corresponding modules they are allocated by. -

Each allocated resource (and from now we'll speak about allocated +

Each allocated resource (from now we'll speak about allocated resources only) is represented by a structure starting with a standard header (struct diff --git a/nest/cli.c b/nest/cli.c index 30ac7510..a917bcb3 100644 --- a/nest/cli.c +++ b/nest/cli.c @@ -26,12 +26,12 @@ * a continuation line, the whole prefix can be replaced by a single * white space character. * - * Reply codes starting with 0 describe `action successfully completed' messages, + * Reply codes starting with 0 stand for `action successfully completed' messages, * 1 means `table entry', 8 `runtime error' and 9 `syntax error'. * * Each CLI session is internally represented by a &cli structure and a * resource pool containing all resources associated with the connection, - * so that it can be easily freed whenever the connection closes, not depending + * so that it can be easily freed whenever the connection gets closed, not depending * on the current state of command processing. * * The CLI commands are declared as a part of the configuration grammar @@ -40,9 +40,9 @@ * it's switched to a special mode by prepending a fake token to the text, * so that it uses only the CLI command rules. Then the parser invokes * an execution routine corresponding to the command, which either constructs - * the whole reply and returns or (in case it expects the reply will be long) + * the whole reply and returns back or (in case it expects the reply will be long) * it prints a partial reply and asks the CLI module (using the @cont hook) - * to call it again when the output will be transferred to the user. + * to call it again when the output is transferred to the user. * * The @this_cli variable points to a &cli structure of the session being * currently parsed, but it's of course available only in command handlers diff --git a/nest/locks.c b/nest/locks.c index c1f7331e..11489b77 100644 --- a/nest/locks.c +++ b/nest/locks.c @@ -15,14 +15,14 @@ * occur only when the user specifies an invalid configuration and therefore * he deserves to get what he has asked for, but unfortunately they can also * arise legitimately when the daemon is reconfigured and there exists (although - * for a short time period only) an old protocol being shut down and a new one + * for a short time period only) an old protocol instance being shut down and a new one * willing to start up on the same interface. * * The solution is very simple: when any protocol wishes to use a network port - * or some other non-shareable resource, it asks the core to lock it and doesn't + * or some other non-shareable resource, it asks the core to lock it and it doesn't * use the resource until it's notified that it has acquired the lock. * - * Object locks are represented by &object_lock which is in turn a kind of + * Object locks are represented by &object_lock structures which are in turn a kind of * resource. Lockable resources are uniquely determined by resource type * (%OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or * multicast address the port is bound to), port number and interface. diff --git a/nest/neighbor.c b/nest/neighbor.c index 89c19ba3..c6e2f734 100644 --- a/nest/neighbor.c +++ b/nest/neighbor.c @@ -20,17 +20,17 @@ * The neighbor cache maintains a collection of neighbor entries. Each * entry represents one IP address corresponding to either our directly * connected neighbor or our own end of the link (when the scope of the - * address is set to %SCOPE_HOST) together with data belonging to a + * address is set to %SCOPE_HOST) together with per-neighbor data belonging to a * single protocol. * * Active entries represent known neighbors and are stored in a hash - * table (to allow fast retrieval based on IP address of the node) and + * table (to allow fast retrieval based on the IP address of the node) and * two linked lists: one global and one per-interface (allowing quick * processing of interface change events). Inactive entries exist only * when the protocol has explicitly requested it via the %NEF_STICKY * flag because it wishes to be notified when the node will again become * a neighbor. Such entries are enqueued in a special list which is walked - * whenever an interface becomes up. + * whenever an interface changes its state to up. * * When a neighbor event occurs (a neighbor gets disconnected or a sticky * inactive neighbor becomes connected), the protocol hook neigh_notify() diff --git a/nest/proto-hooks.c b/nest/proto-hooks.c index 29be6972..4035fdd7 100644 --- a/nest/proto-hooks.c +++ b/nest/proto-hooks.c @@ -9,7 +9,7 @@ /** * DOC: Protocol hooks * - * Each protocol provides a rich set of hook functions referred to by pointers + * Each protocol can provide a rich set of hook functions referred to by pointers * in either the &proto or &protocol structure. They are called by the core whenever * it wants the protocol to perform some action or to notify the protocol about * any change of its environment. All of the hooks can be set to %NULL which means diff --git a/nest/proto.sgml b/nest/proto.sgml index 3478d93a..6e20269b 100644 --- a/nest/proto.sgml +++ b/nest/proto.sgml @@ -67,7 +67,7 @@ the following states:

Unless the protocol is in the At any time, the core code can ask the protocol to shut down by calling its stop() hook. +

At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.

The name /* - * DOC: Output processing + * Output processing * * This part is responsible for getting packets out to the network. */ @@ -251,7 +252,7 @@ find_interface(struct proto *p, struct iface *what) } /* - * DOC: Input processing + * Input processing * * This part is responsible for any updates that come from network */ @@ -466,7 +467,7 @@ rip_rx(sock *s, int size) } /* - * DOC: Interface to bird core + * Interface to BIRD core */ static void @@ -482,10 +483,10 @@ rip_dump_entry( struct rip_entry *e ) * @t: timer * * Broadcast routing tables periodically (using rip_tx) and kill - * routes that are too old. Rip keeps its own entries in main routing - * table linked by link list (functions rip_rte_insert() and - * rip_rte_delete() are responsible for that), walks this list in timer - * and in case entry is too old, it is discarded. + * routes that are too old. RIP keeps a list of its own entries present + * in the core table by a linked list (functions rip_rte_insert() and + * rip_rte_delete() are responsible for that), it walks this list in the timer + * and in case an entry is too old, it is discarded. */ static void @@ -636,13 +637,13 @@ kill_iface(struct proto *p, struct rip_interface *i) /** * new_iface * @p: myself - * @new: interface to be created or %NULL if we are creating magic - * socket. Magic socket is used for listening, and is also used for - * sending requested responses. + * @new: interface to be created or %NULL if we are creating a magic + * socket. The magic socket is used for listening and also for + * sending requested responses. * @flags: interface flags * @patt: pattern this interface matched, used for access to config options * - * actually create struct interface and start listening to it + * Create an interface structure and start listening on the interface. */ static struct rip_interface * new_iface(struct proto *p, struct iface *new, unsigned long flags, struct iface_patt *patt ) diff --git a/sysdep/unix/io.c b/sysdep/unix/io.c index f503bb99..445bc7ce 100644 --- a/sysdep/unix/io.c +++ b/sysdep/unix/io.c @@ -78,11 +78,11 @@ tracked_fopen(pool *p, char *name, char *mode) * * Timers are resources which represent a wish of a module to call * a function at the specified time. The platform dependent code - * doesn't guarantee the exact timing, only that a timer function + * doesn't guarantee exact timing, only that a timer function * won't be called before the requested time. * * In BIRD, real time is represented by values of the &bird_clock_t type - * which are integral numbers corresponding to a number of seconds since + * which are integral numbers interpreted as a number of seconds since * a fixed (but platform dependent) epoch. The current time can be read * from a variable @now with reasonable accuracy. * diff --git a/sysdep/unix/krt.c b/sysdep/unix/krt.c index 2b4117c7..317d3f58 100644 --- a/sysdep/unix/krt.c +++ b/sysdep/unix/krt.c @@ -26,14 +26,14 @@ * 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. + * We use FIB node flags in the routing table to keep track of route + * synchronization status. We also attach temporary &rte's to the routing table, + * but it cannot do any harm to 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. - */ + * only once for all the instances. */ /* * If you are brave enough, continue now. You cannot say you haven't been warned. -- cgit v1.2.3