Annotation of embedaddon/bird2/doc/prog.sgml, revision 1.1
1.1 ! misho 1: <!doctype birddoc system>
! 2:
! 3: <!--
! 4: BIRD: Programmer's Documentation
! 5:
! 6: Copyright (c) 2000 Martin Mares <mj@ucw.cz>
! 7: -->
! 8:
! 9: <book>
! 10: <progdoc>
! 11:
! 12: <title>BIRD Programmer's Documentation
! 13: <author>
! 14: Ondrej Filip <it/<feela@network.cz>/,
! 15: Pavel Machek <it/<pavel@ucw.cz>/,
! 16: Martin Mares <it/<mj@ucw.cz>/,
! 17: Ondrej Zajicek <it/<santiago@crfreenet.org>/
! 18: </author>
! 19:
! 20: <abstract>
! 21: This document contains programmer's documentation for the BIRD Internet Routing Daemon project.
! 22: </abstract>
! 23:
! 24: <!-- Table of contents -->
! 25: <toc>
! 26:
! 27: <!-- Begin the document -->
! 28: <chapt>BIRD Design
! 29:
! 30: <sect>Introduction
! 31:
! 32: <p>This document describes the internal workings of BIRD, its architecture,
! 33: design decisions and rationale behind them. It also contains documentation on
! 34: all the essential components of the system and their interfaces.
! 35:
! 36: <p>Routing daemons are complicated things which need to act in real time
! 37: to complex sequences of external events, respond correctly even to the most erroneous behavior
! 38: of their environment and still handle enormous amount of data with reasonable
! 39: speed. Due to all of this, their design is very tricky as one needs to carefully
! 40: balance between efficiency, stability and (last, but not least) simplicity of
! 41: the program and it would be possible to write literally hundreds of pages about
! 42: all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness
! 43: is a sister of talent", we've tried to write a much shorter document highlighting
! 44: the most important stuff and leaving the boring technical details better explained
! 45: by the program source itself together with comments contained therein.
! 46:
! 47: <sect>Design goals
! 48:
! 49: <p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
! 50: daemons and also at some of the operating systems used on dedicated routers, gathered all important
! 51: features and added lots of new ones to overcome their shortcomings and to better match the requirements
! 52: of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
! 53: planning, the following set of design goals has arisen:
! 54:
! 55: <itemize>
! 56:
! 57: <item><it>Support all the standard routing protocols and make it easy to add new ones.</it>
! 58: This leads to modularity and clean separation between the core and the protocols.
! 59:
! 60: <item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it>
! 61: This leads to abstraction of IP addresses and operations on them.
! 62:
! 63: <item><it>Minimize OS dependent code to make porting as easy as possible.</it>
! 64: Unfortunately, such code cannot be avoided at all as the details of communication with
! 65: the IP stack differ from OS to OS and they often vary even between different
! 66: versions of the same OS. But we can isolate such code in special modules and
! 67: do the porting by changing or replacing just these modules.
! 68: Also, don't rely on specific features of various operating systems, but be able
! 69: to make use of them if they are available.
! 70:
! 71: <item><it>Allow multiple routing tables.</it>
! 72: Easily solvable by abstracting out routing tables and the corresponding operations.
! 73:
! 74: <item><it>Offer powerful route filtering.</it>
! 75: There already were several attempts to incorporate route filters to a dynamic router,
! 76: but most of them have used simple sequences of filtering rules which were very inflexible
! 77: and hard to use for non-trivial filters. We've decided to employ a simple loop-free
! 78: programming language having access to all the route attributes and being able to
! 79: modify the most of them.
! 80:
! 81: <item><it>Support easy configuration and re-configuration.</it>
! 82: Most routers use a simple configuration language designed ad hoc with no structure at all
! 83: and allow online changes of configuration by using their command-line interface, thus
! 84: any complex re-configurations are hard to achieve without replacing the configuration
! 85: file and restarting the whole router. We've decided to use a more general approach: to
! 86: have a configuration defined in a context-free language with blocks and nesting, to
! 87: perform all configuration changes by editing the configuration file, but to be able
! 88: to read the new configuration and smoothly adapt to it without disturbing parts of
! 89: the routing process which are not affected by the change.
! 90:
! 91: <item><it>Be able to be controlled online.</it>
! 92: In addition to the online reconfiguration, a routing daemon should be able to communicate
! 93: with the user and with many other programs (primarily scripts used for network maintenance)
! 94: in order to make it possible to inspect contents of routing tables, status of all
! 95: routing protocols and also to control their behavior (disable, enable or reset a protocol without restarting all the others). To achieve
! 96: this, we implement a simple command-line protocol based on those used by FTP and SMTP
! 97: (that is textual commands and textual replies accompanied by a numeric code which makes
! 98: them both readable to a human and easy to recognize in software).
! 99:
! 100: <item><it>Respond to all events in real time.</it>
! 101: A typical solution to this problem is to use lots of threads to separate the workings
! 102: of all the routing protocols and also of the user interface parts and to hope that
! 103: the scheduler will assign time to them in a fair enough manner. This is surely a good
! 104: solution, but we have resisted the temptation and preferred to avoid the overhead of threading
! 105: and the large number of locks involved and preferred a event driven architecture with
! 106: our own scheduling of events. An unpleasant consequence of such an approach
! 107: is that long lasting tasks must be split to more parts linked by special
! 108: events or timers to make the CPU available for other tasks as well.
! 109:
! 110: </itemize>
! 111:
! 112: <sect>Architecture
! 113:
! 114: <p>The requirements set above have lead to a simple modular architecture containing
! 115: the following types of modules:
! 116:
! 117: <descrip>
! 118:
! 119: <tagp>Core modules</tagp> implement the core functions of BIRD: taking care
! 120: of routing tables, keeping protocol status, interacting with the user using
! 121: the Command-Line Interface (to be called CLI in the rest of this document)
! 122: etc.
! 123:
! 124: <tagp>Library modules</tagp> form a large set of various library functions
! 125: implementing several data abstractions, utility functions and also functions
! 126: which are a part of the standard libraries on some systems, but missing on other
! 127: ones.
! 128:
! 129: <tagp>Resource management modules</tagp> take care of resources, their allocation
! 130: and automatic freeing when the module having requested shuts itself down.
! 131:
! 132: <tagp>Configuration modules</tagp> are fragments of lexical analyzer,
! 133: grammar rules and the corresponding snippets of C code. For each group
! 134: of code modules (core, each protocol, filters) there exist a configuration
! 135: module taking care of all the related configuration stuff.
! 136:
! 137: <tagp>The filter</tagp> implements the route filtering language.
! 138:
! 139: <tagp>Protocol modules</tagp> implement the individual routing protocols.
! 140:
! 141: <tagp>System-dependent modules</tagp> implement the interface between BIRD
! 142: and specific operating systems.
! 143:
! 144: <tagp>The client</tagp> is a simple program providing an easy, though friendly
! 145: interface to the CLI.
! 146:
! 147: </descrip>
! 148:
! 149: <sect>Implementation
! 150:
! 151: <p>BIRD has been written in GNU C. We've considered using C++, but we've
! 152: preferred the simplicity and straightforward nature of C which gives us fine
! 153: control over all implementation details and on the other hand enough
! 154: instruments to build the abstractions we need.
! 155:
! 156: <p>The modules are statically linked to produce a single executable file
! 157: (except for the client which stands on its own).
! 158:
! 159: <p>The building process is controlled by a set of Makefiles for GNU Make,
! 160: intermixed with several Perl and shell scripts.
! 161:
! 162: <p>The initial configuration of the daemon, detection of system features
! 163: and selection of the right modules to include for the particular OS
! 164: and the set of protocols the user has chosen is performed by a configure
! 165: script generated by GNU Autoconf.
! 166:
! 167: <p>The parser of the configuration is generated by the GNU Bison.
! 168:
! 169: <p>The documentation is generated using <file/SGMLtools/ with our own DTD
! 170: and mapping rules which produce both an online version in HTML and
! 171: a neatly formatted one for printing (first converted
! 172: from SGML to &latex; and then processed by &tex; and <file/dvips/ to
! 173: get a PostScript file).
! 174:
! 175: <p>The comments from C sources which form a part of the programmer's
! 176: documentation are extracted using a modified version of the <file/kernel-doc/
! 177: tool.
! 178:
! 179: <p>If you want to work on BIRD, it's highly recommended to configure it
! 180: with a <tt/--enable-debug/ switch which enables some internal consistency
! 181: checks and it also links BIRD with a memory allocation checking library
! 182: if you have one (either <tt/efence/ or <tt/dmalloc/).
! 183:
! 184: <!--
! 185: LocalWords: IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
! 186: LocalWords: PostScript
! 187: -->
! 188: <chapt>Core
! 189: <sect>Forwarding Information Base
! 190: <p>
! 191: <p>
! 192: FIB is a data structure designed for storage of routes indexed by their
! 193: network prefixes. It supports insertion, deletion, searching by prefix,
! 194: `routing' (in CIDR sense, that is searching for a longest prefix matching
! 195: a given IP address) and (which makes the structure very tricky to implement)
! 196: asynchronous reading, that is enumerating the contents of a FIB while other
! 197: modules add, modify or remove entries.
! 198: <p>
! 199: Internally, each FIB is represented as a collection of nodes of type <struct/fib_node/
! 200: indexed using a sophisticated hashing mechanism.
! 201: We use two-stage hashing where we calculate a 16-bit primary hash key independent
! 202: on hash table size and then we just divide the primary keys modulo table size
! 203: to get a real hash key used for determining the bucket containing the node.
! 204: The lists of nodes in each bucket are sorted according to the primary hash
! 205: key, hence if we keep the total number of buckets to be a power of two,
! 206: re-hashing of the structure keeps the relative order of the nodes.
! 207: <p>
! 208: To get the asynchronous reading consistent over node deletions, we need to
! 209: keep a list of readers for each node. When a node gets deleted, its readers
! 210: are automatically moved to the next node in the table.
! 211: <p>
! 212: Basic FIB operations are performed by functions defined by this module,
! 213: enumerating of FIB contents is accomplished by using the <func/FIB_WALK()/ macro
! 214: or <func/FIB_ITERATE_START()/ if you want to do it asynchronously.
! 215: <p>
! 216: For simple iteration just place the body of the loop between <func/FIB_WALK()/ and
! 217: <func/FIB_WALK_END()/. You can't modify the FIB during the iteration (you can modify
! 218: data in the node, but not add or remove nodes).
! 219: <p>
! 220: If you need more freedom, you can use the FIB_ITERATE_*() group of macros.
! 221: First, you initialize an iterator with <func/FIB_ITERATE_INIT()/. Then you can put
! 222: the loop body in between <func/FIB_ITERATE_START()/ and <func/FIB_ITERATE_END()/. In
! 223: addition, the iteration can be suspended by calling <func/FIB_ITERATE_PUT()/.
! 224: This'll link the iterator inside the FIB. While suspended, you may modify the
! 225: FIB, exit the current function, etc. To resume the iteration, enter the loop
! 226: again. You can use <func/FIB_ITERATE_UNLINK()/ to unlink the iterator (while
! 227: iteration is suspended) in cases like premature end of FIB iteration.
! 228: <p>
! 229: Note that the iterator must not be destroyed when the iteration is suspended,
! 230: the FIB would then contain a pointer to invalid memory. Therefore, after each
! 231: <func/FIB_ITERATE_INIT()/ or <func/FIB_ITERATE_PUT()/ there must be either
! 232: <func/FIB_ITERATE_START()/ or <func/FIB_ITERATE_UNLINK()/ before the iterator is destroyed.
! 233:
! 234:
! 235: <function><p><type>void</type>
! 236: <funcdef>fib_init</funcdef>
! 237: (<type>struct fib *</type> <param>f</param>, <type>pool *</type> <param>p</param>, <type>unsigned</type> <param>node_size</param>, <type>unsigned</type> <param>hash_order</param>, <type>fib_init_func</type> <param>init</param>) -- initialize a new FIB
! 238:
! 239: <funcsect>Arguments
! 240: <p><descrip>
! 241: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 242: the FIB to be initialized (the structure itself being allocated by the caller)
! 243: <tagp><type>pool *</type> <param>p</param></tagp>
! 244: pool to allocate the nodes in
! 245: <tagp><type>unsigned</type> <param>node_size</param></tagp>
! 246: node size to be used (each node consists of a standard header <struct/fib_node/
! 247: followed by user data)
! 248: <tagp><type>unsigned</type> <param>hash_order</param></tagp>
! 249: initial hash order (a binary logarithm of hash table size), 0 to use default order
! 250: (recommended)
! 251: <tagp><type>fib_init_func</type> <param>init</param></tagp>
! 252: pointer a function to be called to initialize a newly created node
! 253: </descrip>
! 254: <funcsect>Description
! 255: <p>
! 256: This function initializes a newly allocated FIB and prepares it for use.
! 257: </function>
! 258: <function><p><type>void *</type>
! 259: <funcdef>fib_find</funcdef>
! 260: (<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) -- search for FIB node by prefix
! 261:
! 262: <funcsect>Arguments
! 263: <p><descrip>
! 264: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 265: FIB to search in
! 266: <tagp><type>ip_addr *</type> <param>a</param></tagp>
! 267: pointer to IP address of the prefix
! 268: <tagp><type>int</type> <param>len</param></tagp>
! 269: prefix length
! 270: </descrip>
! 271: <funcsect>Description
! 272: <p>
! 273: Search for a FIB node corresponding to the given prefix, return
! 274: a pointer to it or <const/NULL/ if no such node exists.
! 275: </function>
! 276: <function><p><type>void *</type>
! 277: <funcdef>fib_get</funcdef>
! 278: (<type>struct fib *</type> <param>f</param>, <type>ip_addr *</type> <param>a</param>, <type>int</type> <param>len</param>) -- find or create a FIB node
! 279:
! 280: <funcsect>Arguments
! 281: <p><descrip>
! 282: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 283: FIB to work with
! 284: <tagp><type>ip_addr *</type> <param>a</param></tagp>
! 285: pointer to IP address of the prefix
! 286: <tagp><type>int</type> <param>len</param></tagp>
! 287: prefix length
! 288: </descrip>
! 289: <funcsect>Description
! 290: <p>
! 291: Search for a FIB node corresponding to the given prefix and
! 292: return a pointer to it. If no such node exists, create it.
! 293: </function>
! 294: <function><p><type>void *</type>
! 295: <funcdef>fib_route</funcdef>
! 296: (<type>struct fib *</type> <param>f</param>, <type>ip_addr</type> <param>a</param>, <type>int</type> <param>len</param>) -- CIDR routing lookup
! 297:
! 298: <funcsect>Arguments
! 299: <p><descrip>
! 300: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 301: FIB to search in
! 302: <tagp><type>ip_addr</type> <param>a</param></tagp>
! 303: pointer to IP address of the prefix
! 304: <tagp><type>int</type> <param>len</param></tagp>
! 305: prefix length
! 306: </descrip>
! 307: <funcsect>Description
! 308: <p>
! 309: Search for a FIB node with longest prefix matching the given
! 310: network, that is a node which a CIDR router would use for routing
! 311: that network.
! 312: </function>
! 313: <function><p><type>void</type>
! 314: <funcdef>fib_delete</funcdef>
! 315: (<type>struct fib *</type> <param>f</param>, <type>void *</type> <param>E</param>) -- delete a FIB node
! 316:
! 317: <funcsect>Arguments
! 318: <p><descrip>
! 319: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 320: FIB to delete from
! 321: <tagp><type>void *</type> <param>E</param></tagp>
! 322: entry to delete
! 323: </descrip>
! 324: <funcsect>Description
! 325: <p>
! 326: This function removes the given entry from the FIB,
! 327: taking care of all the asynchronous readers by shifting
! 328: them to the next node in the canonical reading order.
! 329: </function>
! 330: <function><p><type>void</type>
! 331: <funcdef>fib_free</funcdef>
! 332: (<type>struct fib *</type> <param>f</param>) -- delete a FIB
! 333:
! 334: <funcsect>Arguments
! 335: <p><descrip>
! 336: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 337: FIB to be deleted
! 338: </descrip>
! 339: <funcsect>Description
! 340: <p>
! 341: This function deletes a FIB -- it frees all memory associated
! 342: with it and all its entries.
! 343: </function>
! 344: <function><p><type>void</type>
! 345: <funcdef>fib_check</funcdef>
! 346: (<type>struct fib *</type> <param>f</param>) -- audit a FIB
! 347:
! 348: <funcsect>Arguments
! 349: <p><descrip>
! 350: <tagp><type>struct fib *</type> <param>f</param></tagp>
! 351: FIB to be checked
! 352: </descrip>
! 353: <funcsect>Description
! 354: <p>
! 355: This debugging function audits a FIB by checking its internal consistency.
! 356: Use when you suspect somebody of corrupting innocent data structures.
! 357: </function>
! 358: <sect>Routing tables
! 359: <p>
! 360: <p>
! 361: Routing tables are probably the most important structures BIRD uses. They
! 362: hold all the information about known networks, the associated routes and
! 363: their attributes.
! 364: <p>
! 365: There are multiple routing tables (a primary one together with any
! 366: number of secondary ones if requested by the configuration). Each table
! 367: is basically a FIB containing entries describing the individual
! 368: destination networks. For each network (represented by structure <struct/net/),
! 369: there is a one-way linked list of route entries (<struct/rte/), the first entry
! 370: on the list being the best one (i.e., the one we currently use
! 371: for routing), the order of the other ones is undetermined.
! 372: <p>
! 373: The <struct/rte/ contains information specific to the route (preference, protocol
! 374: metrics, time of last modification etc.) and a pointer to a <struct/rta/ structure
! 375: (see the route attribute module for a precise explanation) holding the
! 376: remaining route attributes which are expected to be shared by multiple
! 377: routes in order to conserve memory.
! 378:
! 379:
! 380: <function><p><type>rte *</type>
! 381: <funcdef>rte_find</funcdef>
! 382: (<type>net *</type> <param>net</param>, <type>struct rte_src *</type> <param>src</param>) -- find a route
! 383:
! 384: <funcsect>Arguments
! 385: <p><descrip>
! 386: <tagp><type>net *</type> <param>net</param></tagp>
! 387: network node
! 388: <tagp><type>struct rte_src *</type> <param>src</param></tagp>
! 389: route source
! 390: </descrip>
! 391: <funcsect>Description
! 392: <p>
! 393: The <func/rte_find()/ function returns a route for destination <param/net/
! 394: which is from route source <param/src/.
! 395: </function>
! 396: <function><p><type>rte *</type>
! 397: <funcdef>rte_get_temp</funcdef>
! 398: (<type>rta *</type> <param>a</param>) -- get a temporary <struct/rte/
! 399:
! 400: <funcsect>Arguments
! 401: <p><descrip>
! 402: <tagp><type>rta *</type> <param>a</param></tagp>
! 403: attributes to assign to the new route (a <struct/rta/; in case it's
! 404: un-cached, <func/rte_update()/ will create a cached copy automatically)
! 405: </descrip>
! 406: <funcsect>Description
! 407: <p>
! 408: Create a temporary <struct/rte/ and bind it with the attributes <param/a/.
! 409: Also set route preference to the default preference set for
! 410: the protocol.
! 411: </function>
! 412: <function><p><type>rte *</type>
! 413: <funcdef>rte_cow_rta</funcdef>
! 414: (<type>rte *</type> <param>r</param>, <type>linpool *</type> <param>lp</param>) -- get a private writable copy of <struct/rte/ with writable <struct/rta/
! 415:
! 416: <funcsect>Arguments
! 417: <p><descrip>
! 418: <tagp><type>rte *</type> <param>r</param></tagp>
! 419: a route entry to be copied
! 420: <tagp><type>linpool *</type> <param>lp</param></tagp>
! 421: a linpool from which to allocate <struct/rta/
! 422: </descrip>
! 423: <funcsect>Description
! 424: <p>
! 425: <func/rte_cow_rta()/ takes a <struct/rte/ and prepares it and associated <struct/rta/ for
! 426: modification. There are three possibilities: First, both <struct/rte/ and <struct/rta/ are
! 427: private copies, in that case they are returned unchanged. Second, <struct/rte/ is
! 428: private copy, but <struct/rta/ is cached, in that case <struct/rta/ is duplicated using
! 429: <func/rta_do_cow()/. Third, both <struct/rte/ is shared and <struct/rta/ is cached, in that case
! 430: both structures are duplicated by <func/rte_do_cow()/ and <func/rta_do_cow()/.
! 431: <p>
! 432: Note that in the second case, cached <struct/rta/ loses one reference, while private
! 433: copy created by <func/rta_do_cow()/ is a shallow copy sharing indirect data (eattrs,
! 434: nexthops, ...) with it. To work properly, original shared <struct/rta/ should have
! 435: another reference during the life of created private copy.
! 436: <funcsect>Result
! 437: <p>
! 438: a pointer to the new writable <struct/rte/ with writable <struct/rta/.
! 439: </function>
! 440: <function><p><type>void</type>
! 441: <funcdef>rte_announce</funcdef>
! 442: (<type>rtable *</type> <param>tab</param>, <type>unsigned</type> <param>type</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>rte *</type> <param>new_best</param>, <type>rte *</type> <param>old_best</param>, <type>rte *</type> <param>before_old</param>) -- announce a routing table change
! 443:
! 444: <funcsect>Arguments
! 445: <p><descrip>
! 446: <tagp><type>rtable *</type> <param>tab</param></tagp>
! 447: table the route has been added to
! 448: <tagp><type>unsigned</type> <param>type</param></tagp>
! 449: type of route announcement (RA_OPTIMAL or RA_ANY)
! 450: <tagp><type>net *</type> <param>net</param></tagp>
! 451: network in question
! 452: <tagp><type>rte *</type> <param>new</param></tagp>
! 453: the new route to be announced
! 454: <tagp><type>rte *</type> <param>old</param></tagp>
! 455: the previous route for the same network
! 456: <tagp><type>rte *</type> <param>new_best</param></tagp>
! 457: the new best route for the same network
! 458: <tagp><type>rte *</type> <param>old_best</param></tagp>
! 459: the previous best route for the same network
! 460: <tagp><type>rte *</type> <param>before_old</param></tagp>
! 461: The previous route before <param/old/ for the same network.
! 462: If <param/before_old/ is NULL <param/old/ was the first.
! 463: </descrip>
! 464: <funcsect>Description
! 465: <p>
! 466: This function gets a routing table update and announces it
! 467: to all protocols that acccepts given type of route announcement
! 468: and are connected to the same table by their announcement hooks.
! 469: <p>
! 470: Route announcement of type <const/RA_OPTIMAL/ si generated when optimal
! 471: route (in routing table <param/tab/) changes. In that case <param/old/ stores the
! 472: old optimal route.
! 473: <p>
! 474: Route announcement of type <const/RA_ANY/ si generated when any route (in
! 475: routing table <param/tab/) changes In that case <param/old/ stores the old route
! 476: from the same protocol.
! 477: <p>
! 478: For each appropriate protocol, we first call its <func/import_control()/
! 479: hook which performs basic checks on the route (each protocol has a
! 480: right to veto or force accept of the route before any filter is
! 481: asked) and adds default values of attributes specific to the new
! 482: protocol (metrics, tags etc.). Then it consults the protocol's
! 483: export filter and if it accepts the route, the <func/rt_notify()/ hook of
! 484: the protocol gets called.
! 485: </function>
! 486: <function><p><type>void</type>
! 487: <funcdef>rte_free</funcdef>
! 488: (<type>rte *</type> <param>e</param>) -- delete a <struct/rte/
! 489:
! 490: <funcsect>Arguments
! 491: <p><descrip>
! 492: <tagp><type>rte *</type> <param>e</param></tagp>
! 493: <struct/rte/ to be deleted
! 494: </descrip>
! 495: <funcsect>Description
! 496: <p>
! 497: <func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to.
! 498: </function>
! 499: <function><p><type>void</type>
! 500: <funcdef>rte_update2</funcdef>
! 501: (<type>struct announce_hook *</type> <param>ah</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>struct rte_src *</type> <param>src</param>) -- enter a new update to a routing table
! 502:
! 503: <funcsect>Arguments
! 504: <p><descrip>
! 505: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
! 506: pointer to table announce hook
! 507: <tagp><type>net *</type> <param>net</param></tagp>
! 508: network node
! 509: <tagp><type>rte *</type> <param>new</param></tagp>
! 510: a <struct/rte/ representing the new route or <const/NULL/ for route removal.
! 511: <tagp><type>struct rte_src *</type> <param>src</param></tagp>
! 512: protocol originating the update
! 513: </descrip>
! 514: <funcsect>Description
! 515: <p>
! 516: This function is called by the routing protocols whenever they discover
! 517: a new route or wish to update/remove an existing route. The right announcement
! 518: sequence is to build route attributes first (either un-cached with <param/aflags/ set
! 519: to zero or a cached one using <func/rta_lookup()/; in this case please note that
! 520: you need to increase the use count of the attributes yourself by calling
! 521: <func/rta_clone()/), call <func/rte_get_temp()/ to obtain a temporary <struct/rte/, fill in all
! 522: the appropriate data and finally submit the new <struct/rte/ by calling <func/rte_update()/.
! 523: <p>
! 524: <param/src/ specifies the protocol that originally created the route and the meaning
! 525: of protocol-dependent data of <param/new/. If <param/new/ is not <const/NULL/, <param/src/ have to be the
! 526: same value as <param/new/->attrs->proto. <param/p/ specifies the protocol that called
! 527: <func/rte_update()/. In most cases it is the same protocol as <param/src/. <func/rte_update()/
! 528: stores <param/p/ in <param/new/->sender;
! 529: <p>
! 530: When <func/rte_update()/ gets any route, it automatically validates it (checks,
! 531: whether the network and next hop address are valid IP addresses and also
! 532: whether a normal routing protocol doesn't try to smuggle a host or link
! 533: scope route to the table), converts all protocol dependent attributes stored
! 534: in the <struct/rte/ to temporary extended attributes, consults import filters of the
! 535: protocol to see if the route should be accepted and/or its attributes modified,
! 536: stores the temporary attributes back to the <struct/rte/.
! 537: <p>
! 538: Now, having a "public" version of the route, we
! 539: automatically find any old route defined by the protocol <param/src/
! 540: for network <param/n/, replace it by the new one (or removing it if <param/new/ is <const/NULL/),
! 541: recalculate the optimal route for this destination and finally broadcast
! 542: the change (if any) to all routing protocols by calling <func/rte_announce()/.
! 543: <p>
! 544: All memory used for attribute lists and other temporary allocations is taken
! 545: from a special linear pool <param/rte_update_pool/ and freed when <func/rte_update()/
! 546: finishes.
! 547: </function>
! 548: <function><p><type>void</type>
! 549: <funcdef>rt_refresh_begin</funcdef>
! 550: (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- start a refresh cycle
! 551:
! 552: <funcsect>Arguments
! 553: <p><descrip>
! 554: <tagp><type>rtable *</type> <param>t</param></tagp>
! 555: related routing table
! 556: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
! 557: related announce hook
! 558: </descrip>
! 559: <funcsect>Description
! 560: <p>
! 561: This function starts a refresh cycle for given routing table and announce
! 562: hook. The refresh cycle is a sequence where the protocol sends all its valid
! 563: routes to the routing table (by <func/rte_update()/). After that, all protocol
! 564: routes (more precisely routes with <param/ah/ as <param/sender/) not sent during the
! 565: refresh cycle but still in the table from the past are pruned. This is
! 566: implemented by marking all related routes as stale by REF_STALE flag in
! 567: <func/rt_refresh_begin()/, then marking all related stale routes with REF_DISCARD
! 568: flag in <func/rt_refresh_end()/ and then removing such routes in the prune loop.
! 569: </function>
! 570: <function><p><type>void</type>
! 571: <funcdef>rt_refresh_end</funcdef>
! 572: (<type>rtable *</type> <param>t</param>, <type>struct announce_hook *</type> <param>ah</param>) -- end a refresh cycle
! 573:
! 574: <funcsect>Arguments
! 575: <p><descrip>
! 576: <tagp><type>rtable *</type> <param>t</param></tagp>
! 577: related routing table
! 578: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
! 579: related announce hook
! 580: </descrip>
! 581: <funcsect>Description
! 582: <p>
! 583: This function starts a refresh cycle for given routing table and announce
! 584: hook. See <func/rt_refresh_begin()/ for description of refresh cycles.
! 585: </function>
! 586: <function><p><type>void</type>
! 587: <funcdef>rte_dump</funcdef>
! 588: (<type>rte *</type> <param>e</param>) -- dump a route
! 589:
! 590: <funcsect>Arguments
! 591: <p><descrip>
! 592: <tagp><type>rte *</type> <param>e</param></tagp>
! 593: <struct/rte/ to be dumped
! 594: </descrip>
! 595: <funcsect>Description
! 596: <p>
! 597: This functions dumps contents of a <struct/rte/ to debug output.
! 598: </function>
! 599: <function><p><type>void</type>
! 600: <funcdef>rt_dump</funcdef>
! 601: (<type>rtable *</type> <param>t</param>) -- dump a routing table
! 602:
! 603: <funcsect>Arguments
! 604: <p><descrip>
! 605: <tagp><type>rtable *</type> <param>t</param></tagp>
! 606: routing table to be dumped
! 607: </descrip>
! 608: <funcsect>Description
! 609: <p>
! 610: This function dumps contents of a given routing table to debug output.
! 611: </function>
! 612: <function><p><type>void</type>
! 613: <funcdef>rt_dump_all</funcdef>
! 614: (<param>void</param>) -- dump all routing tables
! 615:
! 616: <funcsect>Description
! 617: <p>
! 618: <p>
! 619: This function dumps contents of all routing tables to debug output.
! 620: </function>
! 621: <function><p><type>void</type>
! 622: <funcdef>rt_init</funcdef>
! 623: (<param>void</param>) -- initialize routing tables
! 624:
! 625: <funcsect>Description
! 626: <p>
! 627: <p>
! 628: This function is called during BIRD startup. It initializes the
! 629: routing table module.
! 630: </function>
! 631: <function><p><type>int</type>
! 632: <funcdef>rt_prune_table</funcdef>
! 633: (<type>rtable *</type> <param>tab</param>) -- prune a routing table
! 634:
! 635: <funcsect>Arguments
! 636: <p><descrip>
! 637: <tagp><type>rtable *</type> <param>tab</param></tagp>
! 638: a routing table for pruning
! 639: </descrip>
! 640: <funcsect>Description
! 641: <p>
! 642: This function scans the routing table <param/tab/ and removes routes belonging to
! 643: flushing protocols, discarded routes and also stale network entries, in a
! 644: similar fashion like <func/rt_prune_loop()/. Returns 1 when all such routes are
! 645: pruned. Contrary to <func/rt_prune_loop()/, this function is not a part of the
! 646: protocol flushing loop, but it is called from <func/rt_event()/ for just one routing
! 647: table.
! 648: <p>
! 649: Note that <func/rt_prune_table()/ and <func/rt_prune_loop()/ share (for each table) the
! 650: prune state (<param/prune_state/) and also the pruning iterator (<param/prune_fit/).
! 651: </function>
! 652: <function><p><type>int</type>
! 653: <funcdef>rt_prune_loop</funcdef>
! 654: (<param>void</param>) -- prune routing tables
! 655:
! 656: <funcsect>Description
! 657: <p>
! 658: <p>
! 659: The prune loop scans routing tables and removes routes belonging to flushing
! 660: protocols, discarded routes and also stale network entries. Returns 1 when
! 661: all such routes are pruned. It is a part of the protocol flushing loop.
! 662: </function>
! 663: <function><p><type>void</type>
! 664: <funcdef>rt_lock_table</funcdef>
! 665: (<type>rtable *</type> <param>r</param>) -- lock a routing table
! 666:
! 667: <funcsect>Arguments
! 668: <p><descrip>
! 669: <tagp><type>rtable *</type> <param>r</param></tagp>
! 670: routing table to be locked
! 671: </descrip>
! 672: <funcsect>Description
! 673: <p>
! 674: Lock a routing table, because it's in use by a protocol,
! 675: preventing it from being freed when it gets undefined in a new
! 676: configuration.
! 677: </function>
! 678: <function><p><type>void</type>
! 679: <funcdef>rt_unlock_table</funcdef>
! 680: (<type>rtable *</type> <param>r</param>) -- unlock a routing table
! 681:
! 682: <funcsect>Arguments
! 683: <p><descrip>
! 684: <tagp><type>rtable *</type> <param>r</param></tagp>
! 685: routing table to be unlocked
! 686: </descrip>
! 687: <funcsect>Description
! 688: <p>
! 689: Unlock a routing table formerly locked by <func/rt_lock_table()/,
! 690: that is decrease its use count and delete it if it's scheduled
! 691: for deletion by configuration changes.
! 692: </function>
! 693: <function><p><type>void</type>
! 694: <funcdef>rt_commit</funcdef>
! 695: (<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>) -- commit new routing table configuration
! 696:
! 697: <funcsect>Arguments
! 698: <p><descrip>
! 699: <tagp><type>struct config *</type> <param>new</param></tagp>
! 700: new configuration
! 701: <tagp><type>struct config *</type> <param>old</param></tagp>
! 702: original configuration or <const/NULL/ if it's boot time config
! 703: </descrip>
! 704: <funcsect>Description
! 705: <p>
! 706: Scan differences between <param/old/ and <param/new/ configuration and modify
! 707: the routing tables according to these changes. If <param/new/ defines a
! 708: previously unknown table, create it, if it omits a table existing
! 709: in <param/old/, schedule it for deletion (it gets deleted when all protocols
! 710: disconnect from it by calling <func/rt_unlock_table()/), if it exists
! 711: in both configurations, leave it unchanged.
! 712: </function>
! 713: <function><p><type>int</type>
! 714: <funcdef>rt_feed_baby</funcdef>
! 715: (<type>struct proto *</type> <param>p</param>) -- advertise routes to a new protocol
! 716:
! 717: <funcsect>Arguments
! 718: <p><descrip>
! 719: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 720: protocol to be fed
! 721: </descrip>
! 722: <funcsect>Description
! 723: <p>
! 724: This function performs one pass of advertisement of routes to a newly
! 725: initialized protocol. It's called by the protocol code as long as it
! 726: has something to do. (We avoid transferring all the routes in single
! 727: pass in order not to monopolize CPU time.)
! 728: </function>
! 729: <function><p><type>void</type>
! 730: <funcdef>rt_feed_baby_abort</funcdef>
! 731: (<type>struct proto *</type> <param>p</param>) -- abort protocol feeding
! 732:
! 733: <funcsect>Arguments
! 734: <p><descrip>
! 735: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 736: protocol
! 737: </descrip>
! 738: <funcsect>Description
! 739: <p>
! 740: This function is called by the protocol code when the protocol
! 741: stops or ceases to exist before the last iteration of <func/rt_feed_baby()/
! 742: has finished.
! 743: </function>
! 744: <function><p><type>net *</type>
! 745: <funcdef>net_find</funcdef>
! 746: (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- find a network entry
! 747:
! 748: <funcsect>Arguments
! 749: <p><descrip>
! 750: <tagp><type>rtable *</type> <param>tab</param></tagp>
! 751: a routing table
! 752: <tagp><type>ip_addr</type> <param>addr</param></tagp>
! 753: address of the network
! 754: <tagp><type>unsigned</type> <param>len</param></tagp>
! 755: length of the network prefix
! 756: </descrip>
! 757: <funcsect>Description
! 758: <p>
! 759: <func/net_find()/ looks up the given network in routing table <param/tab/ and
! 760: returns a pointer to its <struct/net/ entry or <const/NULL/ if no such network
! 761: exists.
! 762: </function>
! 763: <function><p><type>net *</type>
! 764: <funcdef>net_get</funcdef>
! 765: (<type>rtable *</type> <param>tab</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>len</param>) -- obtain a network entry
! 766:
! 767: <funcsect>Arguments
! 768: <p><descrip>
! 769: <tagp><type>rtable *</type> <param>tab</param></tagp>
! 770: a routing table
! 771: <tagp><type>ip_addr</type> <param>addr</param></tagp>
! 772: address of the network
! 773: <tagp><type>unsigned</type> <param>len</param></tagp>
! 774: length of the network prefix
! 775: </descrip>
! 776: <funcsect>Description
! 777: <p>
! 778: <func/net_get()/ looks up the given network in routing table <param/tab/ and
! 779: returns a pointer to its <struct/net/ entry. If no such entry exists, it's
! 780: created.
! 781: </function>
! 782: <function><p><type>rte *</type>
! 783: <funcdef>rte_cow</funcdef>
! 784: (<type>rte *</type> <param>r</param>) -- copy a route for writing
! 785:
! 786: <funcsect>Arguments
! 787: <p><descrip>
! 788: <tagp><type>rte *</type> <param>r</param></tagp>
! 789: a route entry to be copied
! 790: </descrip>
! 791: <funcsect>Description
! 792: <p>
! 793: <func/rte_cow()/ takes a <struct/rte/ and prepares it for modification. The exact action
! 794: taken depends on the flags of the <struct/rte/ -- if it's a temporary entry, it's
! 795: just returned unchanged, else a new temporary entry with the same contents
! 796: is created.
! 797: <p>
! 798: The primary use of this function is inside the filter machinery -- when
! 799: a filter wants to modify <struct/rte/ contents (to change the preference or to
! 800: attach another set of attributes), it must ensure that the <struct/rte/ is not
! 801: shared with anyone else (and especially that it isn't stored in any routing
! 802: table).
! 803: <funcsect>Result
! 804: <p>
! 805: a pointer to the new writable <struct/rte/.
! 806: </function>
! 807: <sect>Route attribute cache
! 808: <p>
! 809: <p>
! 810: Each route entry carries a set of route attributes. Several of them
! 811: vary from route to route, but most attributes are usually common
! 812: for a large number of routes. To conserve memory, we've decided to
! 813: store only the varying ones directly in the <struct/rte/ and hold the rest
! 814: in a special structure called <struct/rta/ which is shared among all the
! 815: <struct/rte/'s with these attributes.
! 816: <p>
! 817: Each <struct/rta/ contains all the static attributes of the route (i.e.,
! 818: those which are always present) as structure members and a list of
! 819: dynamic attributes represented by a linked list of <struct/ea_list/
! 820: structures, each of them consisting of an array of <struct/eattr/'s containing
! 821: the individual attributes. An attribute can be specified more than once
! 822: in the <struct/ea_list/ chain and in such case the first occurrence overrides
! 823: the others. This semantics is used especially when someone (for example
! 824: a filter) wishes to alter values of several dynamic attributes, but
! 825: it wants to preserve the original attribute lists maintained by
! 826: another module.
! 827: <p>
! 828: Each <struct/eattr/ contains an attribute identifier (split to protocol ID and
! 829: per-protocol attribute ID), protocol dependent flags, a type code (consisting
! 830: of several bit fields describing attribute characteristics) and either an
! 831: embedded 32-bit value or a pointer to a <struct/adata/ structure holding attribute
! 832: contents.
! 833: <p>
! 834: There exist two variants of <struct/rta/'s -- cached and un-cached ones. Un-cached
! 835: <struct/rta/'s can have arbitrarily complex structure of <struct/ea_list/'s and they
! 836: can be modified by any module in the route processing chain. Cached
! 837: <struct/rta/'s have their attribute lists normalized (that means at most one
! 838: <struct/ea_list/ is present and its values are sorted in order to speed up
! 839: searching), they are stored in a hash table to make fast lookup possible
! 840: and they are provided with a use count to allow sharing.
! 841: <p>
! 842: Routing tables always contain only cached <struct/rta/'s.
! 843:
! 844:
! 845: <function><p><type>struct mpnh *</type>
! 846: <funcdef>mpnh_merge</funcdef>
! 847: (<type>struct mpnh *</type> <param>x</param>, <type>struct mpnh *</type> <param>y</param>, <type>int</type> <param>rx</param>, <type>int</type> <param>ry</param>, <type>int</type> <param>max</param>, <type>linpool *</type> <param>lp</param>) -- merge nexthop lists
! 848:
! 849: <funcsect>Arguments
! 850: <p><descrip>
! 851: <tagp><type>struct mpnh *</type> <param>x</param></tagp>
! 852: list 1
! 853: <tagp><type>struct mpnh *</type> <param>y</param></tagp>
! 854: list 2
! 855: <tagp><type>int</type> <param>rx</param></tagp>
! 856: reusability of list <param/x/
! 857: <tagp><type>int</type> <param>ry</param></tagp>
! 858: reusability of list <param/y/
! 859: <tagp><type>int</type> <param>max</param></tagp>
! 860: max number of nexthops
! 861: <tagp><type>linpool *</type> <param>lp</param></tagp>
! 862: linpool for allocating nexthops
! 863: </descrip>
! 864: <funcsect>Description
! 865: <p>
! 866: The <func/mpnh_merge()/ function takes two nexthop lists <param/x/ and <param/y/ and merges them,
! 867: eliminating possible duplicates. The input lists must be sorted and the
! 868: result is sorted too. The number of nexthops in result is limited by <param/max/.
! 869: New nodes are allocated from linpool <param/lp/.
! 870: <p>
! 871: The arguments <param/rx/ and <param/ry/ specify whether corresponding input lists may be
! 872: consumed by the function (i.e. their nodes reused in the resulting list), in
! 873: that case the caller should not access these lists after that. To eliminate
! 874: issues with deallocation of these lists, the caller should use some form of
! 875: bulk deallocation (e.g. stack or linpool) to free these nodes when the
! 876: resulting list is no longer needed. When reusability is not set, the
! 877: corresponding lists are not modified nor linked from the resulting list.
! 878: </function>
! 879: <function><p><type>eattr *</type>
! 880: <funcdef>ea_find</funcdef>
! 881: (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>) -- find an extended attribute
! 882:
! 883: <funcsect>Arguments
! 884: <p><descrip>
! 885: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 886: attribute list to search in
! 887: <tagp><type>unsigned</type> <param>id</param></tagp>
! 888: attribute ID to search for
! 889: </descrip>
! 890: <funcsect>Description
! 891: <p>
! 892: Given an extended attribute list, <func/ea_find()/ searches for a first
! 893: occurrence of an attribute with specified ID, returning either a pointer
! 894: to its <struct/eattr/ structure or <const/NULL/ if no such attribute exists.
! 895: </function>
! 896: <function><p><type>eattr *</type>
! 897: <funcdef>ea_walk</funcdef>
! 898: (<type>struct ea_walk_state *</type> <param>s</param>, <type>uint</type> <param>id</param>, <type>uint</type> <param>max</param>) -- walk through extended attributes
! 899:
! 900: <funcsect>Arguments
! 901: <p><descrip>
! 902: <tagp><type>struct ea_walk_state *</type> <param>s</param></tagp>
! 903: walk state structure
! 904: <tagp><type>uint</type> <param>id</param></tagp>
! 905: start of attribute ID interval
! 906: <tagp><type>uint</type> <param>max</param></tagp>
! 907: length of attribute ID interval
! 908: </descrip>
! 909: <funcsect>Description
! 910: <p>
! 911: Given an extended attribute list, <func/ea_walk()/ walks through the list looking
! 912: for first occurrences of attributes with ID in specified interval from <param/id/ to
! 913: (<param/id/ + <param/max/ - 1), returning pointers to found <struct/eattr/ structures, storing its
! 914: walk state in <param/s/ for subsequent calls.
! 915: <p>
! 916: The function <func/ea_walk()/ is supposed to be called in a loop, with initially
! 917: zeroed walk state structure <param/s/ with filled the initial extended attribute
! 918: list, returning one found attribute in each call or <const/NULL/ when no other
! 919: attribute exists. The extended attribute list or the arguments should not be
! 920: modified between calls. The maximum value of <param/max/ is 128.
! 921: </function>
! 922: <function><p><type>int</type>
! 923: <funcdef>ea_get_int</funcdef>
! 924: (<type>ea_list *</type> <param>e</param>, <type>unsigned</type> <param>id</param>, <type>int</type> <param>def</param>) -- fetch an integer attribute
! 925:
! 926: <funcsect>Arguments
! 927: <p><descrip>
! 928: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 929: attribute list
! 930: <tagp><type>unsigned</type> <param>id</param></tagp>
! 931: attribute ID
! 932: <tagp><type>int</type> <param>def</param></tagp>
! 933: default value
! 934: </descrip>
! 935: <funcsect>Description
! 936: <p>
! 937: This function is a shortcut for retrieving a value of an integer attribute
! 938: by calling <func/ea_find()/ to find the attribute, extracting its value or returning
! 939: a provided default if no such attribute is present.
! 940: </function>
! 941: <function><p><type>void</type>
! 942: <funcdef>ea_sort</funcdef>
! 943: (<type>ea_list *</type> <param>e</param>) -- sort an attribute list
! 944:
! 945: <funcsect>Arguments
! 946: <p><descrip>
! 947: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 948: list to be sorted
! 949: </descrip>
! 950: <funcsect>Description
! 951: <p>
! 952: This function takes a <struct/ea_list/ chain and sorts the attributes
! 953: within each of its entries.
! 954: <p>
! 955: If an attribute occurs multiple times in a single <struct/ea_list/,
! 956: <func/ea_sort()/ leaves only the first (the only significant) occurrence.
! 957: </function>
! 958: <function><p><type>unsigned</type>
! 959: <funcdef>ea_scan</funcdef>
! 960: (<type>ea_list *</type> <param>e</param>) -- estimate attribute list size
! 961:
! 962: <funcsect>Arguments
! 963: <p><descrip>
! 964: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 965: attribute list
! 966: </descrip>
! 967: <funcsect>Description
! 968: <p>
! 969: This function calculates an upper bound of the size of
! 970: a given <struct/ea_list/ after merging with <func/ea_merge()/.
! 971: </function>
! 972: <function><p><type>void</type>
! 973: <funcdef>ea_merge</funcdef>
! 974: (<type>ea_list *</type> <param>e</param>, <type>ea_list *</type> <param>t</param>) -- merge segments of an attribute list
! 975:
! 976: <funcsect>Arguments
! 977: <p><descrip>
! 978: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 979: attribute list
! 980: <tagp><type>ea_list *</type> <param>t</param></tagp>
! 981: buffer to store the result to
! 982: </descrip>
! 983: <funcsect>Description
! 984: <p>
! 985: This function takes a possibly multi-segment attribute list
! 986: and merges all of its segments to one.
! 987: <p>
! 988: The primary use of this function is for <struct/ea_list/ normalization:
! 989: first call <func/ea_scan()/ to determine how much memory will the result
! 990: take, then allocate a buffer (usually using <func/alloca()/), merge the
! 991: segments with <func/ea_merge()/ and finally sort and prune the result
! 992: by calling <func/ea_sort()/.
! 993: </function>
! 994: <function><p><type>int</type>
! 995: <funcdef>ea_same</funcdef>
! 996: (<type>ea_list *</type> <param>x</param>, <type>ea_list *</type> <param>y</param>) -- compare two <struct/ea_list/'s
! 997:
! 998: <funcsect>Arguments
! 999: <p><descrip>
! 1000: <tagp><type>ea_list *</type> <param>x</param></tagp>
! 1001: attribute list
! 1002: <tagp><type>ea_list *</type> <param>y</param></tagp>
! 1003: attribute list
! 1004: </descrip>
! 1005: <funcsect>Description
! 1006: <p>
! 1007: <func/ea_same()/ compares two normalized attribute lists <param/x/ and <param/y/ and returns
! 1008: 1 if they contain the same attributes, 0 otherwise.
! 1009: </function>
! 1010: <function><p><type>void</type>
! 1011: <funcdef>ea_show</funcdef>
! 1012: (<type>struct cli *</type> <param>c</param>, <type>eattr *</type> <param>e</param>) -- print an <struct/eattr/ to CLI
! 1013:
! 1014: <funcsect>Arguments
! 1015: <p><descrip>
! 1016: <tagp><type>struct cli *</type> <param>c</param></tagp>
! 1017: destination CLI
! 1018: <tagp><type>eattr *</type> <param>e</param></tagp>
! 1019: attribute to be printed
! 1020: </descrip>
! 1021: <funcsect>Description
! 1022: <p>
! 1023: This function takes an extended attribute represented by its <struct/eattr/
! 1024: structure and prints it to the CLI according to the type information.
! 1025: <p>
! 1026: If the protocol defining the attribute provides its own
! 1027: <func/get_attr()/ hook, it's consulted first.
! 1028: </function>
! 1029: <function><p><type>void</type>
! 1030: <funcdef>ea_dump</funcdef>
! 1031: (<type>ea_list *</type> <param>e</param>) -- dump an extended attribute
! 1032:
! 1033: <funcsect>Arguments
! 1034: <p><descrip>
! 1035: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 1036: attribute to be dumped
! 1037: </descrip>
! 1038: <funcsect>Description
! 1039: <p>
! 1040: <func/ea_dump()/ dumps contents of the extended attribute given to
! 1041: the debug output.
! 1042: </function>
! 1043: <function><p><type>uint</type>
! 1044: <funcdef>ea_hash</funcdef>
! 1045: (<type>ea_list *</type> <param>e</param>) -- calculate an <struct/ea_list/ hash key
! 1046:
! 1047: <funcsect>Arguments
! 1048: <p><descrip>
! 1049: <tagp><type>ea_list *</type> <param>e</param></tagp>
! 1050: attribute list
! 1051: </descrip>
! 1052: <funcsect>Description
! 1053: <p>
! 1054: <func/ea_hash()/ takes an extended attribute list and calculated a hopefully
! 1055: uniformly distributed hash value from its contents.
! 1056: </function>
! 1057: <function><p><type>ea_list *</type>
! 1058: <funcdef>ea_append</funcdef>
! 1059: (<type>ea_list *</type> <param>to</param>, <type>ea_list *</type> <param>what</param>) -- concatenate <struct/ea_list/'s
! 1060:
! 1061: <funcsect>Arguments
! 1062: <p><descrip>
! 1063: <tagp><type>ea_list *</type> <param>to</param></tagp>
! 1064: destination list (can be <const/NULL/)
! 1065: <tagp><type>ea_list *</type> <param>what</param></tagp>
! 1066: list to be appended (can be <const/NULL/)
! 1067: </descrip>
! 1068: <funcsect>Description
! 1069: <p>
! 1070: This function appends the <struct/ea_list/ <param/what/ at the end of
! 1071: <struct/ea_list/ <param/to/ and returns a pointer to the resulting list.
! 1072: </function>
! 1073: <function><p><type>rta *</type>
! 1074: <funcdef>rta_lookup</funcdef>
! 1075: (<type>rta *</type> <param>o</param>) -- look up a <struct/rta/ in attribute cache
! 1076:
! 1077: <funcsect>Arguments
! 1078: <p><descrip>
! 1079: <tagp><type>rta *</type> <param>o</param></tagp>
! 1080: a un-cached <struct/rta/
! 1081: </descrip>
! 1082: <funcsect>Description
! 1083: <p>
! 1084: <func/rta_lookup()/ gets an un-cached <struct/rta/ structure and returns its cached
! 1085: counterpart. It starts with examining the attribute cache to see whether
! 1086: there exists a matching entry. If such an entry exists, it's returned and
! 1087: its use count is incremented, else a new entry is created with use count
! 1088: set to 1.
! 1089: <p>
! 1090: The extended attribute lists attached to the <struct/rta/ are automatically
! 1091: converted to the normalized form.
! 1092: </function>
! 1093: <function><p><type>void</type>
! 1094: <funcdef>rta_dump</funcdef>
! 1095: (<type>rta *</type> <param>a</param>) -- dump route attributes
! 1096:
! 1097: <funcsect>Arguments
! 1098: <p><descrip>
! 1099: <tagp><type>rta *</type> <param>a</param></tagp>
! 1100: attribute structure to dump
! 1101: </descrip>
! 1102: <funcsect>Description
! 1103: <p>
! 1104: This function takes a <struct/rta/ and dumps its contents to the debug output.
! 1105: </function>
! 1106: <function><p><type>void</type>
! 1107: <funcdef>rta_dump_all</funcdef>
! 1108: (<param>void</param>) -- dump attribute cache
! 1109:
! 1110: <funcsect>Description
! 1111: <p>
! 1112: <p>
! 1113: This function dumps the whole contents of route attribute cache
! 1114: to the debug output.
! 1115: </function>
! 1116: <function><p><type>void</type>
! 1117: <funcdef>rta_init</funcdef>
! 1118: (<param>void</param>) -- initialize route attribute cache
! 1119:
! 1120: <funcsect>Description
! 1121: <p>
! 1122: <p>
! 1123: This function is called during initialization of the routing
! 1124: table module to set up the internals of the attribute cache.
! 1125: </function>
! 1126: <function><p><type>rta *</type>
! 1127: <funcdef>rta_clone</funcdef>
! 1128: (<type>rta *</type> <param>r</param>) -- clone route attributes
! 1129:
! 1130: <funcsect>Arguments
! 1131: <p><descrip>
! 1132: <tagp><type>rta *</type> <param>r</param></tagp>
! 1133: a <struct/rta/ to be cloned
! 1134: </descrip>
! 1135: <funcsect>Description
! 1136: <p>
! 1137: <func/rta_clone()/ takes a cached <struct/rta/ and returns its identical cached
! 1138: copy. Currently it works by just returning the original <struct/rta/ with
! 1139: its use count incremented.
! 1140: </function>
! 1141: <function><p><type>void</type>
! 1142: <funcdef>rta_free</funcdef>
! 1143: (<type>rta *</type> <param>r</param>) -- free route attributes
! 1144:
! 1145: <funcsect>Arguments
! 1146: <p><descrip>
! 1147: <tagp><type>rta *</type> <param>r</param></tagp>
! 1148: a <struct/rta/ to be freed
! 1149: </descrip>
! 1150: <funcsect>Description
! 1151: <p>
! 1152: If you stop using a <struct/rta/ (for example when deleting a route which uses
! 1153: it), you need to call <func/rta_free()/ to notify the attribute cache the
! 1154: attribute is no longer in use and can be freed if you were the last
! 1155: user (which <func/rta_free()/ tests by inspecting the use count).
! 1156: </function>
! 1157: <!--
! 1158: BIRD Programmer's Guide: Protocols
! 1159:
! 1160: (c) 2000 Martin Mares <mj@ucw.cz>
! 1161: -->
! 1162:
! 1163: <sect>Routing protocols
! 1164:
! 1165: <sect1>Introduction
! 1166:
! 1167: <p>The routing protocols are the bird's heart and a fine amount of code
! 1168: is dedicated to their management and for providing support functions to them.
! 1169: (-: Actually, this is the reason why the directory with sources of the core
! 1170: code is called <tt/nest/ :-).
! 1171:
! 1172: <p>When talking about protocols, one need to distinguish between <em/protocols/
! 1173: and protocol <em/instances/. A protocol exists exactly once, not depending on whether
! 1174: it's configured or not and it can have an arbitrary number of instances corresponding
! 1175: to its "incarnations" requested by the configuration file. Each instance is completely
! 1176: autonomous, has its own configuration, its own status, its own set of routes and its
! 1177: own set of interfaces it works on.
! 1178:
! 1179: <p>A protocol is represented by a <struct/protocol/ structure containing all the basic
! 1180: information (protocol name, default settings and pointers to most of the protocol
! 1181: hooks). All these structures are linked in the <param/protocol_list/ list.
! 1182:
! 1183: <p>Each instance has its own <struct/proto/ structure describing all its properties: protocol
! 1184: type, configuration, a resource pool where all resources belonging to the instance
! 1185: live, various protocol attributes (take a look at the declaration of <struct/proto/ in
! 1186: <tt/protocol.h/), protocol states (see below for what do they mean), connections
! 1187: to routing tables, filters attached to the protocol
! 1188: and finally a set of pointers to the rest of protocol hooks (they
! 1189: are the same for all instances of the protocol, but in order to avoid extra
! 1190: indirections when calling the hooks from the fast path, they are stored directly
! 1191: in <struct/proto/). The instance is always linked in both the global instance list
! 1192: (<param/proto_list/) and a per-status list (either <param/active_proto_list/ for
! 1193: running protocols, <param/initial_proto_list/ for protocols being initialized or
! 1194: <param/flush_proto_list/ when the protocol is being shut down).
! 1195:
! 1196: <p>The protocol hooks are described in the next chapter, for more information about
! 1197: configuration of protocols, please refer to the configuration chapter and also
! 1198: to the description of the <func/proto_commit/ function.
! 1199:
! 1200: <sect1>Protocol states
! 1201:
! 1202: <p>As startup and shutdown of each protocol are complex processes which can be affected
! 1203: by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.),
! 1204: we have decided to supervise them by a pair of simple state machines -- the protocol
! 1205: state machine and a core state machine.
! 1206:
! 1207: <p>The <em/protocol state machine/ corresponds to internal state of the protocol
! 1208: and the protocol can alter its state whenever it wants to. There are
! 1209: the following states:
! 1210:
! 1211: <descrip>
! 1212: <tag/PS_DOWN/ The protocol is down and waits for being woken up by calling its
! 1213: start() hook.
! 1214: <tag/PS_START/ The protocol is waiting for connection with the rest of the
! 1215: network. It's active, it has resources allocated, but it still doesn't want
! 1216: any routes since it doesn't know what to do with them.
! 1217: <tag/PS_UP/ The protocol is up and running. It communicates with the core,
! 1218: delivers routes to tables and wants to hear announcement about route changes.
! 1219: <tag/PS_STOP/ The protocol has been shut down (either by being asked by the
! 1220: core code to do so or due to having encountered a protocol error).
! 1221: </descrip>
! 1222:
! 1223: <p>Unless the protocol is in the <tt/PS_DOWN/ state, it can decide to change
! 1224: its state by calling the <func/proto_notify_state/ function.
! 1225:
! 1226: <p>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
! 1227:
! 1228: <p>The <em/core state machine/ takes care of the core view of protocol state.
! 1229: The states are traversed according to changes of the protocol state machine, but
! 1230: sometimes the transitions are delayed if the core needs to finish some actions
! 1231: (for example sending of new routes to the protocol) before proceeding to the
! 1232: new state. There are the following core states:
! 1233:
! 1234: <descrip>
! 1235: <tag/FS_HUNGRY/ The protocol is down, it doesn't have any routes and
! 1236: doesn't want them.
! 1237: <tag/FS_FEEDING/ The protocol has reached the <tt/PS_UP/ state, but
! 1238: we are still busy sending the initial set of routes to it.
! 1239: <tag/FS_HAPPY/ The protocol is up and has complete routing information.
! 1240: <tag/FS_FLUSHING/ The protocol is shutting down (it's in either <tt/PS_STOP/
! 1241: or <tt/PS_DOWN/ state) and we're flushing all of its routes from the
! 1242: routing tables.
! 1243: </descrip>
! 1244:
! 1245: <sect1>Functions of the protocol module
! 1246:
! 1247: <p>The protocol module provides the following functions:
! 1248: <function><p><type>void *</type>
! 1249: <funcdef>proto_new</funcdef>
! 1250: (<type>struct proto_config *</type> <param>c</param>, <type>unsigned</type> <param>size</param>) -- create a new protocol instance
! 1251:
! 1252: <funcsect>Arguments
! 1253: <p><descrip>
! 1254: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
! 1255: protocol configuration
! 1256: <tagp><type>unsigned</type> <param>size</param></tagp>
! 1257: size of protocol data structure (each protocol instance is represented by
! 1258: a structure starting with generic part [struct <struct/proto/] and continued
! 1259: with data specific to the protocol)
! 1260: </descrip>
! 1261: <funcsect>Description
! 1262: <p>
! 1263: When a new configuration has been read in, the core code starts
! 1264: initializing all the protocol instances configured by calling their
! 1265: <func/init()/ hooks with the corresponding instance configuration. The initialization
! 1266: code of the protocol is expected to create a new instance according to the
! 1267: configuration by calling this function and then modifying the default settings
! 1268: to values wanted by the protocol.
! 1269: </function>
! 1270: <function><p><type>struct announce_hook *</type>
! 1271: <funcdef>proto_add_announce_hook</funcdef>
! 1272: (<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>, <type>struct proto_stats *</type> <param>stats</param>) -- connect protocol to a routing table
! 1273:
! 1274: <funcsect>Arguments
! 1275: <p><descrip>
! 1276: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1277: protocol instance
! 1278: <tagp><type>struct rtable *</type> <param>t</param></tagp>
! 1279: routing table to connect to
! 1280: <tagp><type>struct proto_stats *</type> <param>stats</param></tagp>
! 1281: per-table protocol statistics
! 1282: </descrip>
! 1283: <funcsect>Description
! 1284: <p>
! 1285: This function creates a connection between the protocol instance <param/p/ and the
! 1286: routing table <param/t/, making the protocol hear all changes in the table.
! 1287: <p>
! 1288: The announce hook is linked in the protocol ahook list. Announce hooks are
! 1289: allocated from the routing table resource pool and when protocol accepts
! 1290: routes also in the table ahook list. The are linked to the table ahook list
! 1291: and unlinked from it depending on export_state (in <func/proto_want_export_up()/ and
! 1292: <func/proto_want_export_down()/) and they are automatically freed after the protocol
! 1293: is flushed (in <func/proto_fell_down()/).
! 1294: <p>
! 1295: Unless you want to listen to multiple routing tables (as the Pipe protocol
! 1296: does), you needn't to worry about this function since the connection to the
! 1297: protocol's primary routing table is initialized automatically by the core
! 1298: code.
! 1299: </function>
! 1300: <function><p><type>struct announce_hook *</type>
! 1301: <funcdef>proto_find_announce_hook</funcdef>
! 1302: (<type>struct proto *</type> <param>p</param>, <type>struct rtable *</type> <param>t</param>) -- find announce hooks
! 1303:
! 1304: <funcsect>Arguments
! 1305: <p><descrip>
! 1306: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1307: protocol instance
! 1308: <tagp><type>struct rtable *</type> <param>t</param></tagp>
! 1309: routing table
! 1310: </descrip>
! 1311: <funcsect>Description
! 1312: <p>
! 1313: Returns pointer to announce hook or NULL
! 1314: </function>
! 1315: <function><p><type>void *</type>
! 1316: <funcdef>proto_config_new</funcdef>
! 1317: (<type>struct protocol *</type> <param>pr</param>, <type>int</type> <param>class</param>) -- create a new protocol configuration
! 1318:
! 1319: <funcsect>Arguments
! 1320: <p><descrip>
! 1321: <tagp><type>struct protocol *</type> <param>pr</param></tagp>
! 1322: protocol the configuration will belong to
! 1323: <tagp><type>int</type> <param>class</param></tagp>
! 1324: SYM_PROTO or SYM_TEMPLATE
! 1325: </descrip>
! 1326: <funcsect>Description
! 1327: <p>
! 1328: Whenever the configuration file says that a new instance
! 1329: of a routing protocol should be created, the parser calls
! 1330: <func/proto_config_new()/ to create a configuration entry for this
! 1331: instance (a structure staring with the <struct/proto_config/ header
! 1332: containing all the generic items followed by protocol-specific
! 1333: ones). Also, the configuration entry gets added to the list
! 1334: of protocol instances kept in the configuration.
! 1335: <p>
! 1336: The function is also used to create protocol templates (when class
! 1337: SYM_TEMPLATE is specified), the only difference is that templates
! 1338: are not added to the list of protocol instances and therefore not
! 1339: initialized during <func/protos_commit()/).
! 1340: </function>
! 1341: <function><p><type>void</type>
! 1342: <funcdef>proto_copy_config</funcdef>
! 1343: (<type>struct proto_config *</type> <param>dest</param>, <type>struct proto_config *</type> <param>src</param>) -- copy a protocol configuration
! 1344:
! 1345: <funcsect>Arguments
! 1346: <p><descrip>
! 1347: <tagp><type>struct proto_config *</type> <param>dest</param></tagp>
! 1348: destination protocol configuration
! 1349: <tagp><type>struct proto_config *</type> <param>src</param></tagp>
! 1350: source protocol configuration
! 1351: </descrip>
! 1352: <funcsect>Description
! 1353: <p>
! 1354: Whenever a new instance of a routing protocol is created from the
! 1355: template, <func/proto_copy_config()/ is called to copy a content of
! 1356: the source protocol configuration to the new protocol configuration.
! 1357: Name, class and a node in protos list of <param/dest/ are kept intact.
! 1358: <func/copy_config()/ protocol hook is used to copy protocol-specific data.
! 1359: </function>
! 1360: <function><p><type>void</type>
! 1361: <funcdef>protos_preconfig</funcdef>
! 1362: (<type>struct config *</type> <param>c</param>) -- pre-configuration processing
! 1363:
! 1364: <funcsect>Arguments
! 1365: <p><descrip>
! 1366: <tagp><type>struct config *</type> <param>c</param></tagp>
! 1367: new configuration
! 1368: </descrip>
! 1369: <funcsect>Description
! 1370: <p>
! 1371: This function calls the <func/preconfig()/ hooks of all routing
! 1372: protocols available to prepare them for reading of the new
! 1373: configuration.
! 1374: </function>
! 1375: <function><p><type>void</type>
! 1376: <funcdef>protos_postconfig</funcdef>
! 1377: (<type>struct config *</type> <param>c</param>) -- post-configuration processing
! 1378:
! 1379: <funcsect>Arguments
! 1380: <p><descrip>
! 1381: <tagp><type>struct config *</type> <param>c</param></tagp>
! 1382: new configuration
! 1383: </descrip>
! 1384: <funcsect>Description
! 1385: <p>
! 1386: This function calls the <func/postconfig()/ hooks of all protocol
! 1387: instances specified in configuration <param/c/. The hooks are not
! 1388: called for protocol templates.
! 1389: </function>
! 1390: <function><p><type>void</type>
! 1391: <funcdef>protos_commit</funcdef>
! 1392: (<type>struct config *</type> <param>new</param>, <type>struct config *</type> <param>old</param>, <type>int</type> <param>force_reconfig</param>, <type>int</type> <param>type</param>) -- commit new protocol configuration
! 1393:
! 1394: <funcsect>Arguments
! 1395: <p><descrip>
! 1396: <tagp><type>struct config *</type> <param>new</param></tagp>
! 1397: new configuration
! 1398: <tagp><type>struct config *</type> <param>old</param></tagp>
! 1399: old configuration or <const/NULL/ if it's boot time config
! 1400: <tagp><type>int</type> <param>force_reconfig</param></tagp>
! 1401: force restart of all protocols (used for example
! 1402: when the router ID changes)
! 1403: <tagp><type>int</type> <param>type</param></tagp>
! 1404: type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
! 1405: </descrip>
! 1406: <funcsect>Description
! 1407: <p>
! 1408: Scan differences between <param/old/ and <param/new/ configuration and adjust all
! 1409: protocol instances to conform to the new configuration.
! 1410: <p>
! 1411: When a protocol exists in the new configuration, but it doesn't in the
! 1412: original one, it's immediately started. When a collision with the other
! 1413: running protocol would arise, the new protocol will be temporarily stopped
! 1414: by the locking mechanism.
! 1415: <p>
! 1416: When a protocol exists in the old configuration, but it doesn't in the
! 1417: new one, it's shut down and deleted after the shutdown completes.
! 1418: <p>
! 1419: When a protocol exists in both configurations, the core decides
! 1420: whether it's possible to reconfigure it dynamically - it checks all
! 1421: the core properties of the protocol (changes in filters are ignored
! 1422: if type is RECONFIG_SOFT) and if they match, it asks the
! 1423: <func/reconfigure()/ hook of the protocol to see if the protocol is able
! 1424: to switch to the new configuration. If it isn't possible, the
! 1425: protocol is shut down and a new instance is started with the new
! 1426: configuration after the shutdown is completed.
! 1427: </function>
! 1428: <sect>Graceful restart recovery
! 1429: <p>
! 1430: <p>
! 1431: Graceful restart of a router is a process when the routing plane (e.g. BIRD)
! 1432: restarts but both the forwarding plane (e.g kernel routing table) and routing
! 1433: neighbors keep proper routes, and therefore uninterrupted packet forwarding
! 1434: is maintained.
! 1435: <p>
! 1436: BIRD implements graceful restart recovery by deferring export of routes to
! 1437: protocols until routing tables are refilled with the expected content. After
! 1438: start, protocols generate routes as usual, but routes are not propagated to
! 1439: them, until protocols report that they generated all routes. After that,
! 1440: graceful restart recovery is finished and the export (and the initial feed)
! 1441: to protocols is enabled.
! 1442: <p>
! 1443: When graceful restart recovery need is detected during initialization, then
! 1444: enabled protocols are marked with <param/gr_recovery/ flag before start. Such
! 1445: protocols then decide how to proceed with graceful restart, participation is
! 1446: voluntary. Protocols could lock the recovery by <func/proto_graceful_restart_lock()/
! 1447: (stored in <param/gr_lock/ flag), which means that they want to postpone the end of
! 1448: the recovery until they converge and then unlock it. They also could set
! 1449: <param/gr_wait/ before advancing to <const/PS_UP/, which means that the core should defer
! 1450: route export to that protocol until the end of the recovery. This should be
! 1451: done by protocols that expect their neigbors to keep the proper routes
! 1452: (kernel table, BGP sessions with BGP graceful restart capability).
! 1453: <p>
! 1454: The graceful restart recovery is finished when either all graceful restart
! 1455: locks are unlocked or when graceful restart wait timer fires.
! 1456:
! 1457:
! 1458: <function><p><type>void</type>
! 1459: <funcdef>graceful_restart_recovery</funcdef>
! 1460: (<param>void</param>) -- request initial graceful restart recovery
! 1461:
! 1462: <funcsect>Graceful restart recovery
! 1463: <p>
! 1464: <p>
! 1465: Called by the platform initialization code if the need for recovery
! 1466: after graceful restart is detected during boot. Have to be called
! 1467: before <func/protos_commit()/.
! 1468: </function>
! 1469: <function><p><type>void</type>
! 1470: <funcdef>graceful_restart_init</funcdef>
! 1471: (<param>void</param>) -- initialize graceful restart
! 1472:
! 1473: <funcsect>Description
! 1474: <p>
! 1475: <p>
! 1476: When graceful restart recovery was requested, the function starts an active
! 1477: phase of the recovery and initializes graceful restart wait timer. The
! 1478: function have to be called after <func/protos_commit()/.
! 1479: </function>
! 1480: <function><p><type>void</type>
! 1481: <funcdef>graceful_restart_done</funcdef>
! 1482: (<type>struct timer *t</type> <param>UNUSED</param>) -- finalize graceful restart
! 1483:
! 1484: <funcsect>Arguments
! 1485: <p><descrip>
! 1486: <tagp><type>struct timer *t</type> <param>UNUSED</param></tagp>
! 1487: -- undescribed --
! 1488: </descrip>
! 1489: <funcsect>Description
! 1490: <p>
! 1491: When there are no locks on graceful restart, the functions finalizes the
! 1492: graceful restart recovery. Protocols postponing route export until the end of
! 1493: the recovery are awakened and the export to them is enabled. All other
! 1494: related state is cleared. The function is also called when the graceful
! 1495: restart wait timer fires (but there are still some locks).
! 1496: </function>
! 1497: <function><p><type>void</type>
! 1498: <funcdef>proto_graceful_restart_lock</funcdef>
! 1499: (<type>struct proto *</type> <param>p</param>) -- lock graceful restart by protocol
! 1500:
! 1501: <funcsect>Arguments
! 1502: <p><descrip>
! 1503: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1504: protocol instance
! 1505: </descrip>
! 1506: <funcsect>Description
! 1507: <p>
! 1508: This function allows a protocol to postpone the end of graceful restart
! 1509: recovery until it converges. The lock is removed when the protocol calls
! 1510: <func/proto_graceful_restart_unlock()/ or when the protocol is stopped.
! 1511: <p>
! 1512: The function have to be called during the initial phase of graceful restart
! 1513: recovery and only for protocols that are part of graceful restart (i.e. their
! 1514: <param/gr_recovery/ is set), which means it should be called from protocol start
! 1515: hooks.
! 1516: </function>
! 1517: <function><p><type>void</type>
! 1518: <funcdef>proto_graceful_restart_unlock</funcdef>
! 1519: (<type>struct proto *</type> <param>p</param>) -- unlock graceful restart by protocol
! 1520:
! 1521: <funcsect>Arguments
! 1522: <p><descrip>
! 1523: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1524: protocol instance
! 1525: </descrip>
! 1526: <funcsect>Description
! 1527: <p>
! 1528: This function unlocks a lock from <func/proto_graceful_restart_lock()/. It is also
! 1529: automatically called when the lock holding protocol went down.
! 1530: </function>
! 1531: <function><p><type>void</type>
! 1532: <funcdef>protos_dump_all</funcdef>
! 1533: (<param>void</param>) -- dump status of all protocols
! 1534:
! 1535: <funcsect>Description
! 1536: <p>
! 1537: <p>
! 1538: This function dumps status of all existing protocol instances to the
! 1539: debug output. It involves printing of general status information
! 1540: such as protocol states, its position on the protocol lists
! 1541: and also calling of a <func/dump()/ hook of the protocol to print
! 1542: the internals.
! 1543: </function>
! 1544: <function><p><type>void</type>
! 1545: <funcdef>proto_build</funcdef>
! 1546: (<type>struct protocol *</type> <param>p</param>) -- make a single protocol available
! 1547:
! 1548: <funcsect>Arguments
! 1549: <p><descrip>
! 1550: <tagp><type>struct protocol *</type> <param>p</param></tagp>
! 1551: the protocol
! 1552: </descrip>
! 1553: <funcsect>Description
! 1554: <p>
! 1555: After the platform specific initialization code uses <func/protos_build()/
! 1556: to add all the standard protocols, it should call <func/proto_build()/ for
! 1557: all platform specific protocols to inform the core that they exist.
! 1558: </function>
! 1559: <function><p><type>void</type>
! 1560: <funcdef>protos_build</funcdef>
! 1561: (<param>void</param>) -- build a protocol list
! 1562:
! 1563: <funcsect>Description
! 1564: <p>
! 1565: <p>
! 1566: This function is called during BIRD startup to insert
! 1567: all standard protocols to the global protocol list. Insertion
! 1568: of platform specific protocols (such as the kernel syncer)
! 1569: is in the domain of competence of the platform dependent
! 1570: startup code.
! 1571: </function>
! 1572: <function><p><type>void</type>
! 1573: <funcdef>proto_set_message</funcdef>
! 1574: (<type>struct proto *</type> <param>p</param>, <type>char *</type> <param>msg</param>, <type>int</type> <param>len</param>) -- set administrative message to protocol
! 1575:
! 1576: <funcsect>Arguments
! 1577: <p><descrip>
! 1578: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1579: protocol
! 1580: <tagp><type>char *</type> <param>msg</param></tagp>
! 1581: message
! 1582: <tagp><type>int</type> <param>len</param></tagp>
! 1583: message length (-1 for NULL-terminated string)
! 1584: </descrip>
! 1585: <funcsect>Description
! 1586: <p>
! 1587: The function sets administrative message (string) related to protocol state
! 1588: change. It is called by the nest code for manual enable/disable/restart
! 1589: commands all routes to the protocol, and by protocol-specific code when the
! 1590: protocol state change is initiated by the protocol. Using NULL message clears
! 1591: the last message. The message string may be either NULL-terminated or with an
! 1592: explicit length.
! 1593: </function>
! 1594: <function><p><type>void</type>
! 1595: <funcdef>proto_request_feeding</funcdef>
! 1596: (<type>struct proto *</type> <param>p</param>) -- request feeding routes to the protocol
! 1597:
! 1598: <funcsect>Arguments
! 1599: <p><descrip>
! 1600: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1601: given protocol
! 1602: </descrip>
! 1603: <funcsect>Description
! 1604: <p>
! 1605: Sometimes it is needed to send again all routes to the
! 1606: protocol. This is called feeding and can be requested by this
! 1607: function. This would cause protocol export state transition
! 1608: to ES_FEEDING (during feeding) and when completed, it will
! 1609: switch back to ES_READY. This function can be called even
! 1610: when feeding is already running, in that case it is restarted.
! 1611: </function>
! 1612: <function><p><type>void</type>
! 1613: <funcdef>proto_notify_limit</funcdef>
! 1614: (<type>struct announce_hook *</type> <param>ah</param>, <type>struct proto_limit *</type> <param>l</param>, <type>int</type> <param>dir</param>, <type>u32</type> <param>rt_count</param>)
! 1615: <funcsect>Arguments
! 1616: <p><descrip>
! 1617: <tagp><type>struct announce_hook *</type> <param>ah</param></tagp>
! 1618: announce hook
! 1619: <tagp><type>struct proto_limit *</type> <param>l</param></tagp>
! 1620: limit being hit
! 1621: <tagp><type>int</type> <param>dir</param></tagp>
! 1622: limit direction (PLD_*)
! 1623: <tagp><type>u32</type> <param>rt_count</param></tagp>
! 1624: the number of routes
! 1625: </descrip>
! 1626: <funcsect>Description
! 1627: <p>
! 1628: The function is called by the route processing core when limit <param/l/
! 1629: is breached. It activates the limit and tooks appropriate action
! 1630: according to <param/l/->action.
! 1631: </function>
! 1632: <function><p><type>void</type>
! 1633: <funcdef>proto_notify_state</funcdef>
! 1634: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>ps</param>) -- notify core about protocol state change
! 1635:
! 1636: <funcsect>Arguments
! 1637: <p><descrip>
! 1638: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1639: protocol the state of which has changed
! 1640: <tagp><type>unsigned</type> <param>ps</param></tagp>
! 1641: the new status
! 1642: </descrip>
! 1643: <funcsect>Description
! 1644: <p>
! 1645: Whenever a state of a protocol changes due to some event internal
! 1646: to the protocol (i.e., not inside a <func/start()/ or <func/shutdown()/ hook),
! 1647: it should immediately notify the core about the change by calling
! 1648: <func/proto_notify_state()/ which will write the new state to the <struct/proto/
! 1649: structure and take all the actions necessary to adapt to the new
! 1650: state. State change to PS_DOWN immediately frees resources of protocol
! 1651: and might execute start callback of protocol; therefore,
! 1652: it should be used at tail positions of protocol callbacks.
! 1653: </function>
! 1654: <sect>Protocol hooks
! 1655: <p>
! 1656: <p>
! 1657: Each protocol can provide a rich set of hook functions referred to by pointers
! 1658: in either the <struct/proto/ or <struct/protocol/ structure. They are called by the core whenever
! 1659: it wants the protocol to perform some action or to notify the protocol about
! 1660: any change of its environment. All of the hooks can be set to <const/NULL/ which means
! 1661: to ignore the change or to take a default action.
! 1662:
! 1663:
! 1664: <function><p><type>void</type>
! 1665: <funcdef>preconfig</funcdef>
! 1666: (<type>struct protocol *</type> <param>p</param>, <type>struct config *</type> <param>c</param>) -- protocol preconfiguration
! 1667:
! 1668: <funcsect>Arguments
! 1669: <p><descrip>
! 1670: <tagp><type>struct protocol *</type> <param>p</param></tagp>
! 1671: a routing protocol
! 1672: <tagp><type>struct config *</type> <param>c</param></tagp>
! 1673: new configuration
! 1674: </descrip>
! 1675: <funcsect>Description
! 1676: <p>
! 1677: The <func/preconfig()/ hook is called before parsing of a new configuration.
! 1678: </function>
! 1679: <function><p><type>void</type>
! 1680: <funcdef>postconfig</funcdef>
! 1681: (<type>struct proto_config *</type> <param>c</param>) -- instance post-configuration
! 1682:
! 1683: <funcsect>Arguments
! 1684: <p><descrip>
! 1685: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
! 1686: instance configuration
! 1687: </descrip>
! 1688: <funcsect>Description
! 1689: <p>
! 1690: The <func/postconfig()/ hook is called for each configured instance after
! 1691: parsing of the new configuration is finished.
! 1692: </function>
! 1693: <function><p><type>struct proto *</type>
! 1694: <funcdef>init</funcdef>
! 1695: (<type>struct proto_config *</type> <param>c</param>) -- initialize an instance
! 1696:
! 1697: <funcsect>Arguments
! 1698: <p><descrip>
! 1699: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
! 1700: instance configuration
! 1701: </descrip>
! 1702: <funcsect>Description
! 1703: <p>
! 1704: The <func/init()/ hook is called by the core to create a protocol instance
! 1705: according to supplied protocol configuration.
! 1706: <funcsect>Result
! 1707: <p>
! 1708: a pointer to the instance created
! 1709: </function>
! 1710: <function><p><type>int</type>
! 1711: <funcdef>reconfigure</funcdef>
! 1712: (<type>struct proto *</type> <param>p</param>, <type>struct proto_config *</type> <param>c</param>) -- request instance reconfiguration
! 1713:
! 1714: <funcsect>Arguments
! 1715: <p><descrip>
! 1716: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1717: an instance
! 1718: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
! 1719: new configuration
! 1720: </descrip>
! 1721: <funcsect>Description
! 1722: <p>
! 1723: The core calls the <func/reconfigure()/ hook whenever it wants to ask the
! 1724: protocol for switching to a new configuration. If the reconfiguration
! 1725: is possible, the hook returns 1. Otherwise, it returns 0 and the core
! 1726: will shut down the instance and start a new one with the new configuration.
! 1727: <p>
! 1728: After the protocol confirms reconfiguration, it must no longer keep any
! 1729: references to the old configuration since the memory it's stored in can
! 1730: be re-used at any time.
! 1731: </function>
! 1732: <function><p><type>void</type>
! 1733: <funcdef>dump</funcdef>
! 1734: (<type>struct proto *</type> <param>p</param>) -- dump protocol state
! 1735:
! 1736: <funcsect>Arguments
! 1737: <p><descrip>
! 1738: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1739: an instance
! 1740: </descrip>
! 1741: <funcsect>Description
! 1742: <p>
! 1743: This hook dumps the complete state of the instance to the
! 1744: debug output.
! 1745: </function>
! 1746: <function><p><type>void</type>
! 1747: <funcdef>dump_attrs</funcdef>
! 1748: (<type>rte *</type> <param>e</param>) -- dump protocol-dependent attributes
! 1749:
! 1750: <funcsect>Arguments
! 1751: <p><descrip>
! 1752: <tagp><type>rte *</type> <param>e</param></tagp>
! 1753: a route entry
! 1754: </descrip>
! 1755: <funcsect>Description
! 1756: <p>
! 1757: This hook dumps all attributes in the <struct/rte/ which belong to this
! 1758: protocol to the debug output.
! 1759: </function>
! 1760: <function><p><type>int</type>
! 1761: <funcdef>start</funcdef>
! 1762: (<type>struct proto *</type> <param>p</param>) -- request instance startup
! 1763:
! 1764: <funcsect>Arguments
! 1765: <p><descrip>
! 1766: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1767: protocol instance
! 1768: </descrip>
! 1769: <funcsect>Description
! 1770: <p>
! 1771: The <func/start()/ hook is called by the core when it wishes to start
! 1772: the instance. Multitable protocols should lock their tables here.
! 1773: <funcsect>Result
! 1774: <p>
! 1775: new protocol state
! 1776: </function>
! 1777: <function><p><type>int</type>
! 1778: <funcdef>shutdown</funcdef>
! 1779: (<type>struct proto *</type> <param>p</param>) -- request instance shutdown
! 1780:
! 1781: <funcsect>Arguments
! 1782: <p><descrip>
! 1783: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1784: protocol instance
! 1785: </descrip>
! 1786: <funcsect>Description
! 1787: <p>
! 1788: The <func/stop()/ hook is called by the core when it wishes to shut
! 1789: the instance down for some reason.
! 1790: <funcsect>Returns
! 1791: <p>
! 1792: new protocol state
! 1793: </function>
! 1794: <function><p><type>void</type>
! 1795: <funcdef>cleanup</funcdef>
! 1796: (<type>struct proto *</type> <param>p</param>) -- request instance cleanup
! 1797:
! 1798: <funcsect>Arguments
! 1799: <p><descrip>
! 1800: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1801: protocol instance
! 1802: </descrip>
! 1803: <funcsect>Description
! 1804: <p>
! 1805: The <func/cleanup()/ hook is called by the core when the protocol became
! 1806: hungry/down, i.e. all protocol ahooks and routes are flushed.
! 1807: Multitable protocols should unlock their tables here.
! 1808: </function>
! 1809: <function><p><type>void</type>
! 1810: <funcdef>get_status</funcdef>
! 1811: (<type>struct proto *</type> <param>p</param>, <type>byte *</type> <param>buf</param>) -- get instance status
! 1812:
! 1813: <funcsect>Arguments
! 1814: <p><descrip>
! 1815: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1816: protocol instance
! 1817: <tagp><type>byte *</type> <param>buf</param></tagp>
! 1818: buffer to be filled with the status string
! 1819: </descrip>
! 1820: <funcsect>Description
! 1821: <p>
! 1822: This hook is called by the core if it wishes to obtain an brief one-line user friendly
! 1823: representation of the status of the instance to be printed by the <cf/show protocols/
! 1824: command.
! 1825: </function>
! 1826: <function><p><type>void</type>
! 1827: <funcdef>get_route_info</funcdef>
! 1828: (<type>rte *</type> <param>e</param>, <type>byte *</type> <param>buf</param>, <type>ea_list *</type> <param>attrs</param>) -- get route information
! 1829:
! 1830: <funcsect>Arguments
! 1831: <p><descrip>
! 1832: <tagp><type>rte *</type> <param>e</param></tagp>
! 1833: a route entry
! 1834: <tagp><type>byte *</type> <param>buf</param></tagp>
! 1835: buffer to be filled with the resulting string
! 1836: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
! 1837: extended attributes of the route
! 1838: </descrip>
! 1839: <funcsect>Description
! 1840: <p>
! 1841: This hook is called to fill the buffer <param/buf/ with a brief user friendly
! 1842: representation of metrics of a route belonging to this protocol.
! 1843: </function>
! 1844: <function><p><type>int</type>
! 1845: <funcdef>get_attr</funcdef>
! 1846: (<type>eattr *</type> <param>a</param>, <type>byte *</type> <param>buf</param>, <type>int</type> <param>buflen</param>) -- get attribute information
! 1847:
! 1848: <funcsect>Arguments
! 1849: <p><descrip>
! 1850: <tagp><type>eattr *</type> <param>a</param></tagp>
! 1851: an extended attribute
! 1852: <tagp><type>byte *</type> <param>buf</param></tagp>
! 1853: buffer to be filled with attribute information
! 1854: <tagp><type>int</type> <param>buflen</param></tagp>
! 1855: a length of the <param/buf/ parameter
! 1856: </descrip>
! 1857: <funcsect>Description
! 1858: <p>
! 1859: The <func/get_attr()/ hook is called by the core to obtain a user friendly
! 1860: representation of an extended route attribute. It can either leave
! 1861: the whole conversion to the core (by returning <const/GA_UNKNOWN/), fill
! 1862: in only attribute name (and let the core format the attribute value
! 1863: automatically according to the type field; by returning <const/GA_NAME/)
! 1864: or doing the whole conversion (used in case the value requires extra
! 1865: care; return <const/GA_FULL/).
! 1866: </function>
! 1867: <function><p><type>void</type>
! 1868: <funcdef>if_notify</funcdef>
! 1869: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct iface *</type> <param>i</param>) -- notify instance about interface changes
! 1870:
! 1871: <funcsect>Arguments
! 1872: <p><descrip>
! 1873: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1874: protocol instance
! 1875: <tagp><type>unsigned</type> <param>flags</param></tagp>
! 1876: interface change flags
! 1877: <tagp><type>struct iface *</type> <param>i</param></tagp>
! 1878: the interface in question
! 1879: </descrip>
! 1880: <funcsect>Description
! 1881: <p>
! 1882: This hook is called whenever any network interface changes its status.
! 1883: The change is described by a combination of status bits (<const/IF_CHANGE_xxx/)
! 1884: in the <param/flags/ parameter.
! 1885: </function>
! 1886: <function><p><type>void</type>
! 1887: <funcdef>ifa_notify</funcdef>
! 1888: (<type>struct proto *</type> <param>p</param>, <type>unsigned</type> <param>flags</param>, <type>struct ifa *</type> <param>a</param>) -- notify instance about interface address changes
! 1889:
! 1890: <funcsect>Arguments
! 1891: <p><descrip>
! 1892: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1893: protocol instance
! 1894: <tagp><type>unsigned</type> <param>flags</param></tagp>
! 1895: address change flags
! 1896: <tagp><type>struct ifa *</type> <param>a</param></tagp>
! 1897: the interface address
! 1898: </descrip>
! 1899: <funcsect>Description
! 1900: <p>
! 1901: This hook is called to notify the protocol instance about an interface
! 1902: acquiring or losing one of its addresses. The change is described by
! 1903: a combination of status bits (<const/IF_CHANGE_xxx/) in the <param/flags/ parameter.
! 1904: </function>
! 1905: <function><p><type>void</type>
! 1906: <funcdef>rt_notify</funcdef>
! 1907: (<type>struct proto *</type> <param>p</param>, <type>net *</type> <param>net</param>, <type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>, <type>ea_list *</type> <param>attrs</param>) -- notify instance about routing table change
! 1908:
! 1909: <funcsect>Arguments
! 1910: <p><descrip>
! 1911: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 1912: protocol instance
! 1913: <tagp><type>net *</type> <param>net</param></tagp>
! 1914: a network entry
! 1915: <tagp><type>rte *</type> <param>new</param></tagp>
! 1916: new route for the network
! 1917: <tagp><type>rte *</type> <param>old</param></tagp>
! 1918: old route for the network
! 1919: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
! 1920: extended attributes associated with the <param/new/ entry
! 1921: </descrip>
! 1922: <funcsect>Description
! 1923: <p>
! 1924: The <func/rt_notify()/ hook is called to inform the protocol instance about
! 1925: changes in the connected routing table <param/table/, that is a route <param/old/
! 1926: belonging to network <param/net/ being replaced by a new route <param/new/ with
! 1927: extended attributes <param/attrs/. Either <param/new/ or <param/old/ or both can be <const/NULL/
! 1928: if the corresponding route doesn't exist.
! 1929: <p>
! 1930: If the type of route announcement is RA_OPTIMAL, it is an
! 1931: announcement of optimal route change, <param/new/ stores the new optimal
! 1932: route and <param/old/ stores the old optimal route.
! 1933: <p>
! 1934: If the type of route announcement is RA_ANY, it is an announcement
! 1935: of any route change, <param/new/ stores the new route and <param/old/ stores the
! 1936: old route from the same protocol.
! 1937: <p>
! 1938: <param/p/->accept_ra_types specifies which kind of route announcements
! 1939: protocol wants to receive.
! 1940: </function>
! 1941: <function><p><type>void</type>
! 1942: <funcdef>neigh_notify</funcdef>
! 1943: (<type>neighbor *</type> <param>neigh</param>) -- notify instance about neighbor status change
! 1944:
! 1945: <funcsect>Arguments
! 1946: <p><descrip>
! 1947: <tagp><type>neighbor *</type> <param>neigh</param></tagp>
! 1948: a neighbor cache entry
! 1949: </descrip>
! 1950: <funcsect>Description
! 1951: <p>
! 1952: The <func/neigh_notify()/ hook is called by the neighbor cache whenever
! 1953: a neighbor changes its state, that is it gets disconnected or a
! 1954: sticky neighbor gets connected.
! 1955: </function>
! 1956: <function><p><type>ea_list *</type>
! 1957: <funcdef>make_tmp_attrs</funcdef>
! 1958: (<type>rte *</type> <param>e</param>, <type>struct linpool *</type> <param>pool</param>) -- convert embedded attributes to temporary ones
! 1959:
! 1960: <funcsect>Arguments
! 1961: <p><descrip>
! 1962: <tagp><type>rte *</type> <param>e</param></tagp>
! 1963: route entry
! 1964: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
! 1965: linear pool to allocate attribute memory in
! 1966: </descrip>
! 1967: <funcsect>Description
! 1968: <p>
! 1969: This hook is called by the routing table functions if they need
! 1970: to convert the protocol attributes embedded directly in the <struct/rte/
! 1971: to temporary extended attributes in order to distribute them
! 1972: to other protocols or to filters. <func/make_tmp_attrs()/ creates
! 1973: an <struct/ea_list/ in the linear pool <param/pool/, fills it with values of the
! 1974: temporary attributes and returns a pointer to it.
! 1975: </function>
! 1976: <function><p><type>void</type>
! 1977: <funcdef>store_tmp_attrs</funcdef>
! 1978: (<type>rte *</type> <param>e</param>, <type>ea_list *</type> <param>attrs</param>) -- convert temporary attributes to embedded ones
! 1979:
! 1980: <funcsect>Arguments
! 1981: <p><descrip>
! 1982: <tagp><type>rte *</type> <param>e</param></tagp>
! 1983: route entry
! 1984: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
! 1985: temporary attributes to be converted
! 1986: </descrip>
! 1987: <funcsect>Description
! 1988: <p>
! 1989: This hook is an exact opposite of <func/make_tmp_attrs()/ -- it takes
! 1990: a list of extended attributes and converts them to attributes
! 1991: embedded in the <struct/rte/ corresponding to this protocol.
! 1992: <p>
! 1993: You must be prepared for any of the attributes being missing
! 1994: from the list and use default values instead.
! 1995: </function>
! 1996: <function><p><type>int</type>
! 1997: <funcdef>import_control</funcdef>
! 1998: (<type>struct proto *</type> <param>p</param>, <type>rte **</type> <param>e</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) -- pre-filtering decisions on route import
! 1999:
! 2000: <funcsect>Arguments
! 2001: <p><descrip>
! 2002: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 2003: protocol instance the route is going to be imported to
! 2004: <tagp><type>rte **</type> <param>e</param></tagp>
! 2005: the route in question
! 2006: <tagp><type>ea_list **</type> <param>attrs</param></tagp>
! 2007: extended attributes of the route
! 2008: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
! 2009: linear pool for allocation of all temporary data
! 2010: </descrip>
! 2011: <funcsect>Description
! 2012: <p>
! 2013: The <func/import_control()/ hook is called as the first step of a exporting
! 2014: a route from a routing table to the protocol instance. It can modify
! 2015: route attributes and force acceptance or rejection of the route regardless
! 2016: of user-specified filters. See <func/rte_announce()/ for a complete description
! 2017: of the route distribution process.
! 2018: <p>
! 2019: The standard use of this hook is to reject routes having originated
! 2020: from the same instance and to set default values of the protocol's metrics.
! 2021: <funcsect>Result
! 2022: <p>
! 2023: 1 if the route has to be accepted, -1 if rejected and 0 if it
! 2024: should be passed to the filters.
! 2025: </function>
! 2026: <function><p><type>int</type>
! 2027: <funcdef>rte_recalculate</funcdef>
! 2028: (<type>struct rtable *</type> <param>table</param>, <type>struct network *</type> <param>net</param>, <type>struct rte *</type> <param>new</param>, <type>struct rte *</type> <param>old</param>, <type>struct rte *</type> <param>old_best</param>) -- prepare routes for comparison
! 2029:
! 2030: <funcsect>Arguments
! 2031: <p><descrip>
! 2032: <tagp><type>struct rtable *</type> <param>table</param></tagp>
! 2033: a routing table
! 2034: <tagp><type>struct network *</type> <param>net</param></tagp>
! 2035: a network entry
! 2036: <tagp><type>struct rte *</type> <param>new</param></tagp>
! 2037: new route for the network
! 2038: <tagp><type>struct rte *</type> <param>old</param></tagp>
! 2039: old route for the network
! 2040: <tagp><type>struct rte *</type> <param>old_best</param></tagp>
! 2041: old best route for the network (may be NULL)
! 2042: </descrip>
! 2043: <funcsect>Description
! 2044: <p>
! 2045: This hook is called when a route change (from <param/old/ to <param/new/ for a
! 2046: <param/net/ entry) is propagated to a <param/table/. It may be used to prepare
! 2047: routes for comparison by <func/rte_better()/ in the best route
! 2048: selection. <param/new/ may or may not be in <param/net/->routes list,
! 2049: <param/old/ is not there.
! 2050: <funcsect>Result
! 2051: <p>
! 2052: 1 if the ordering implied by <func/rte_better()/ changes enough
! 2053: that full best route calculation have to be done, 0 otherwise.
! 2054: </function>
! 2055: <function><p><type>int</type>
! 2056: <funcdef>rte_better</funcdef>
! 2057: (<type>rte *</type> <param>new</param>, <type>rte *</type> <param>old</param>) -- compare metrics of two routes
! 2058:
! 2059: <funcsect>Arguments
! 2060: <p><descrip>
! 2061: <tagp><type>rte *</type> <param>new</param></tagp>
! 2062: the new route
! 2063: <tagp><type>rte *</type> <param>old</param></tagp>
! 2064: the original route
! 2065: </descrip>
! 2066: <funcsect>Description
! 2067: <p>
! 2068: This hook gets called when the routing table contains two routes
! 2069: for the same network which have originated from different instances
! 2070: of a single protocol and it wants to select which one is preferred
! 2071: over the other one. Protocols usually decide according to route metrics.
! 2072: <funcsect>Result
! 2073: <p>
! 2074: 1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise.
! 2075: </function>
! 2076: <function><p><type>int</type>
! 2077: <funcdef>rte_same</funcdef>
! 2078: (<type>rte *</type> <param>e1</param>, <type>rte *</type> <param>e2</param>) -- compare two routes
! 2079:
! 2080: <funcsect>Arguments
! 2081: <p><descrip>
! 2082: <tagp><type>rte *</type> <param>e1</param></tagp>
! 2083: route
! 2084: <tagp><type>rte *</type> <param>e2</param></tagp>
! 2085: route
! 2086: </descrip>
! 2087: <funcsect>Description
! 2088: <p>
! 2089: The <func/rte_same()/ hook tests whether the routes <param/e1/ and <param/e2/ belonging
! 2090: to the same protocol instance have identical contents. Contents of
! 2091: <struct/rta/, all the extended attributes and <struct/rte/ preference are checked
! 2092: by the core code, no need to take care of them here.
! 2093: <funcsect>Result
! 2094: <p>
! 2095: 1 if <param/e1/ is identical to <param/e2/, 0 otherwise.
! 2096: </function>
! 2097: <function><p><type>void</type>
! 2098: <funcdef>rte_insert</funcdef>
! 2099: (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route insertion
! 2100:
! 2101: <funcsect>Arguments
! 2102: <p><descrip>
! 2103: <tagp><type>net *</type> <param>n</param></tagp>
! 2104: network
! 2105: <tagp><type>rte *</type> <param>e</param></tagp>
! 2106: route
! 2107: </descrip>
! 2108: <funcsect>Description
! 2109: <p>
! 2110: This hook is called whenever a <struct/rte/ belonging to the instance
! 2111: is accepted for insertion to a routing table.
! 2112: <p>
! 2113: Please avoid using this function in new protocols.
! 2114: </function>
! 2115: <function><p><type>void</type>
! 2116: <funcdef>rte_remove</funcdef>
! 2117: (<type>net *</type> <param>n</param>, <type>rte *</type> <param>e</param>) -- notify instance about route removal
! 2118:
! 2119: <funcsect>Arguments
! 2120: <p><descrip>
! 2121: <tagp><type>net *</type> <param>n</param></tagp>
! 2122: network
! 2123: <tagp><type>rte *</type> <param>e</param></tagp>
! 2124: route
! 2125: </descrip>
! 2126: <funcsect>Description
! 2127: <p>
! 2128: This hook is called whenever a <struct/rte/ belonging to the instance
! 2129: is removed from a routing table.
! 2130: <p>
! 2131: Please avoid using this function in new protocols.
! 2132: </function>
! 2133: <sect>Interfaces
! 2134: <p>
! 2135: <p>
! 2136: The interface module keeps track of all network interfaces in the
! 2137: system and their addresses.
! 2138: <p>
! 2139: Each interface is represented by an <struct/iface/ structure which carries
! 2140: interface capability flags (<const/IF_MULTIACCESS/, <const/IF_BROADCAST/ etc.),
! 2141: MTU, interface name and index and finally a linked list of network
! 2142: prefixes assigned to the interface, each one represented by
! 2143: struct <struct/ifa/.
! 2144: <p>
! 2145: The interface module keeps a `soft-up' state for each <struct/iface/ which
! 2146: is a conjunction of link being up, the interface being of a `sane'
! 2147: type and at least one IP address assigned to it.
! 2148:
! 2149:
! 2150: <function><p><type>void</type>
! 2151: <funcdef>ifa_dump</funcdef>
! 2152: (<type>struct ifa *</type> <param>a</param>) -- dump interface address
! 2153:
! 2154: <funcsect>Arguments
! 2155: <p><descrip>
! 2156: <tagp><type>struct ifa *</type> <param>a</param></tagp>
! 2157: interface address descriptor
! 2158: </descrip>
! 2159: <funcsect>Description
! 2160: <p>
! 2161: This function dumps contents of an <struct/ifa/ to the debug output.
! 2162: </function>
! 2163: <function><p><type>void</type>
! 2164: <funcdef>if_dump</funcdef>
! 2165: (<type>struct iface *</type> <param>i</param>) -- dump interface
! 2166:
! 2167: <funcsect>Arguments
! 2168: <p><descrip>
! 2169: <tagp><type>struct iface *</type> <param>i</param></tagp>
! 2170: interface to dump
! 2171: </descrip>
! 2172: <funcsect>Description
! 2173: <p>
! 2174: This function dumps all information associated with a given
! 2175: network interface to the debug output.
! 2176: </function>
! 2177: <function><p><type>void</type>
! 2178: <funcdef>if_dump_all</funcdef>
! 2179: (<param>void</param>) -- dump all interfaces
! 2180:
! 2181: <funcsect>Description
! 2182: <p>
! 2183: <p>
! 2184: This function dumps information about all known network
! 2185: interfaces to the debug output.
! 2186: </function>
! 2187: <function><p><type>void</type>
! 2188: <funcdef>if_delete</funcdef>
! 2189: (<type>struct iface *</type> <param>old</param>) -- remove interface
! 2190:
! 2191: <funcsect>Arguments
! 2192: <p><descrip>
! 2193: <tagp><type>struct iface *</type> <param>old</param></tagp>
! 2194: interface
! 2195: </descrip>
! 2196: <funcsect>Description
! 2197: <p>
! 2198: This function is called by the low-level platform dependent code
! 2199: whenever it notices an interface disappears. It is just a shorthand
! 2200: for <func/if_update()/.
! 2201: </function>
! 2202: <function><p><type>struct iface *</type>
! 2203: <funcdef>if_update</funcdef>
! 2204: (<type>struct iface *</type> <param>new</param>) -- update interface status
! 2205:
! 2206: <funcsect>Arguments
! 2207: <p><descrip>
! 2208: <tagp><type>struct iface *</type> <param>new</param></tagp>
! 2209: new interface status
! 2210: </descrip>
! 2211: <funcsect>Description
! 2212: <p>
! 2213: <func/if_update()/ is called by the low-level platform dependent code
! 2214: whenever it notices an interface change.
! 2215: <p>
! 2216: There exist two types of interface updates -- synchronous and asynchronous
! 2217: ones. In the synchronous case, the low-level code calls <func/if_start_update()/,
! 2218: scans all interfaces reported by the OS, uses <func/if_update()/ and <func/ifa_update()/
! 2219: to pass them to the core and then it finishes the update sequence by
! 2220: calling <func/if_end_update()/. When working asynchronously, the sysdep code
! 2221: calls <func/if_update()/ and <func/ifa_update()/ whenever it notices a change.
! 2222: <p>
! 2223: <func/if_update()/ will automatically notify all other modules about the change.
! 2224: </function>
! 2225: <function><p><type>void</type>
! 2226: <funcdef>if_feed_baby</funcdef>
! 2227: (<type>struct proto *</type> <param>p</param>) -- advertise interfaces to a new protocol
! 2228:
! 2229: <funcsect>Arguments
! 2230: <p><descrip>
! 2231: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 2232: protocol to feed
! 2233: </descrip>
! 2234: <funcsect>Description
! 2235: <p>
! 2236: When a new protocol starts, this function sends it a series
! 2237: of notifications about all existing interfaces.
! 2238: </function>
! 2239: <function><p><type>struct iface *</type>
! 2240: <funcdef>if_find_by_index</funcdef>
! 2241: (<type>unsigned</type> <param>idx</param>) -- find interface by ifindex
! 2242:
! 2243: <funcsect>Arguments
! 2244: <p><descrip>
! 2245: <tagp><type>unsigned</type> <param>idx</param></tagp>
! 2246: ifindex
! 2247: </descrip>
! 2248: <funcsect>Description
! 2249: <p>
! 2250: This function finds an <struct/iface/ structure corresponding to an interface
! 2251: of the given index <param/idx/. Returns a pointer to the structure or <const/NULL/
! 2252: if no such structure exists.
! 2253: </function>
! 2254: <function><p><type>struct iface *</type>
! 2255: <funcdef>if_find_by_name</funcdef>
! 2256: (<type>char *</type> <param>name</param>) -- find interface by name
! 2257:
! 2258: <funcsect>Arguments
! 2259: <p><descrip>
! 2260: <tagp><type>char *</type> <param>name</param></tagp>
! 2261: interface name
! 2262: </descrip>
! 2263: <funcsect>Description
! 2264: <p>
! 2265: This function finds an <struct/iface/ structure corresponding to an interface
! 2266: of the given name <param/name/. Returns a pointer to the structure or <const/NULL/
! 2267: if no such structure exists.
! 2268: </function>
! 2269: <function><p><type>struct ifa *</type>
! 2270: <funcdef>ifa_update</funcdef>
! 2271: (<type>struct ifa *</type> <param>a</param>) -- update interface address
! 2272:
! 2273: <funcsect>Arguments
! 2274: <p><descrip>
! 2275: <tagp><type>struct ifa *</type> <param>a</param></tagp>
! 2276: new interface address
! 2277: </descrip>
! 2278: <funcsect>Description
! 2279: <p>
! 2280: This function adds address information to a network
! 2281: interface. It's called by the platform dependent code during
! 2282: the interface update process described under <func/if_update()/.
! 2283: </function>
! 2284: <function><p><type>void</type>
! 2285: <funcdef>ifa_delete</funcdef>
! 2286: (<type>struct ifa *</type> <param>a</param>) -- remove interface address
! 2287:
! 2288: <funcsect>Arguments
! 2289: <p><descrip>
! 2290: <tagp><type>struct ifa *</type> <param>a</param></tagp>
! 2291: interface address
! 2292: </descrip>
! 2293: <funcsect>Description
! 2294: <p>
! 2295: This function removes address information from a network
! 2296: interface. It's called by the platform dependent code during
! 2297: the interface update process described under <func/if_update()/.
! 2298: </function>
! 2299: <function><p><type>void</type>
! 2300: <funcdef>if_init</funcdef>
! 2301: (<param>void</param>) -- initialize interface module
! 2302:
! 2303: <funcsect>Description
! 2304: <p>
! 2305: <p>
! 2306: This function is called during BIRD startup to initialize
! 2307: all data structures of the interface module.
! 2308: </function>
! 2309: <sect>Neighbor cache
! 2310: <p>
! 2311: <p>
! 2312: Most routing protocols need to associate their internal state data with
! 2313: neighboring routers, check whether an address given as the next hop
! 2314: attribute of a route is really an address of a directly connected host
! 2315: and which interface is it connected through. Also, they often need to
! 2316: be notified when a neighbor ceases to exist or when their long awaited
! 2317: neighbor becomes connected. The neighbor cache is there to solve all
! 2318: these problems.
! 2319: <p>
! 2320: The neighbor cache maintains a collection of neighbor entries. Each
! 2321: entry represents one IP address corresponding to either our directly
! 2322: connected neighbor or our own end of the link (when the scope of the
! 2323: address is set to <const/SCOPE_HOST/) together with per-neighbor data belonging to a
! 2324: single protocol.
! 2325: <p>
! 2326: Active entries represent known neighbors and are stored in a hash
! 2327: table (to allow fast retrieval based on the IP address of the node) and
! 2328: two linked lists: one global and one per-interface (allowing quick
! 2329: processing of interface change events). Inactive entries exist only
! 2330: when the protocol has explicitly requested it via the <const/NEF_STICKY/
! 2331: flag because it wishes to be notified when the node will again become
! 2332: a neighbor. Such entries are enqueued in a special list which is walked
! 2333: whenever an interface changes its state to up. Neighbor entry VRF
! 2334: association is implied by respective protocol.
! 2335: <p>
! 2336: When a neighbor event occurs (a neighbor gets disconnected or a sticky
! 2337: inactive neighbor becomes connected), the protocol hook <func/neigh_notify()/
! 2338: is called to advertise the change.
! 2339:
! 2340:
! 2341: <function><p><type>neighbor *</type>
! 2342: <funcdef>neigh_find</funcdef>
! 2343: (<type>struct proto *</type> <param>p</param>, <type>ip_addr *</type> <param>a</param>, <type>unsigned</type> <param>flags</param>) -- find or create a neighbor entry.
! 2344:
! 2345: <funcsect>Arguments
! 2346: <p><descrip>
! 2347: <tagp><type>struct proto *</type> <param>p</param></tagp>
! 2348: protocol which asks for the entry.
! 2349: <tagp><type>ip_addr *</type> <param>a</param></tagp>
! 2350: pointer to IP address of the node to be searched for.
! 2351: <tagp><type>unsigned</type> <param>flags</param></tagp>
! 2352: 0 or <const/NEF_STICKY/ if you want to create a sticky entry.
! 2353: </descrip>
! 2354: <funcsect>Description
! 2355: <p>
! 2356: Search the neighbor cache for a node with given IP address. If
! 2357: it's found, a pointer to the neighbor entry is returned. If no
! 2358: such entry exists and the node is directly connected on
! 2359: one of our active interfaces, a new entry is created and returned
! 2360: to the caller with protocol-dependent fields initialized to zero.
! 2361: If the node is not connected directly or *<param/a/ is not a valid unicast
! 2362: IP address, <func/neigh_find()/ returns <const/NULL/.
! 2363: </function>
! 2364: <function><p><type>void</type>
! 2365: <funcdef>neigh_dump</funcdef>
! 2366: (<type>neighbor *</type> <param>n</param>) -- dump specified neighbor entry.
! 2367:
! 2368: <funcsect>Arguments
! 2369: <p><descrip>
! 2370: <tagp><type>neighbor *</type> <param>n</param></tagp>
! 2371: the entry to dump
! 2372: </descrip>
! 2373: <funcsect>Description
! 2374: <p>
! 2375: This functions dumps the contents of a given neighbor entry
! 2376: to debug output.
! 2377: </function>
! 2378: <function><p><type>void</type>
! 2379: <funcdef>neigh_dump_all</funcdef>
! 2380: (<param>void</param>) -- dump all neighbor entries.
! 2381:
! 2382: <funcsect>Description
! 2383: <p>
! 2384: <p>
! 2385: This function dumps the contents of the neighbor cache to
! 2386: debug output.
! 2387: </function>
! 2388: <function><p><type>void</type>
! 2389: <funcdef>neigh_if_up</funcdef>
! 2390: (<type>struct iface *</type> <param>i</param>)
! 2391: <funcsect>Arguments
! 2392: <p><descrip>
! 2393: <tagp><type>struct iface *</type> <param>i</param></tagp>
! 2394: interface in question
! 2395: </descrip>
! 2396: <funcsect>Description
! 2397: <p>
! 2398: Tell the neighbor cache that a new interface became up.
! 2399: <p>
! 2400: The neighbor cache wakes up all inactive sticky neighbors with
! 2401: addresses belonging to prefixes of the interface <param/i/.
! 2402: </function>
! 2403: <function><p><type>void</type>
! 2404: <funcdef>neigh_if_down</funcdef>
! 2405: (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface down event
! 2406:
! 2407: <funcsect>Arguments
! 2408: <p><descrip>
! 2409: <tagp><type>struct iface *</type> <param>i</param></tagp>
! 2410: the interface in question
! 2411: </descrip>
! 2412: <funcsect>Description
! 2413: <p>
! 2414: Notify the neighbor cache that an interface has ceased to exist.
! 2415: <p>
! 2416: It causes all entries belonging to neighbors connected to this interface
! 2417: to be flushed.
! 2418: </function>
! 2419: <function><p><type>void</type>
! 2420: <funcdef>neigh_if_link</funcdef>
! 2421: (<type>struct iface *</type> <param>i</param>) -- notify neighbor cache about interface link change
! 2422:
! 2423: <funcsect>Arguments
! 2424: <p><descrip>
! 2425: <tagp><type>struct iface *</type> <param>i</param></tagp>
! 2426: the interface in question
! 2427: </descrip>
! 2428: <funcsect>Description
! 2429: <p>
! 2430: Notify the neighbor cache that an interface changed link state.
! 2431: All owners of neighbor entries connected to this interface are
! 2432: notified.
! 2433: </function>
! 2434: <function><p><type>void</type>
! 2435: <funcdef>neigh_ifa_update</funcdef>
! 2436: (<type>struct ifa *</type> <param>a</param>)
! 2437: <funcsect>Arguments
! 2438: <p><descrip>
! 2439: <tagp><type>struct ifa *</type> <param>a</param></tagp>
! 2440: interface address in question
! 2441: </descrip>
! 2442: <funcsect>Description
! 2443: <p>
! 2444: Tell the neighbor cache that an address was added or removed.
! 2445: <p>
! 2446: The neighbor cache wakes up all inactive sticky neighbors with
! 2447: addresses belonging to prefixes of the interface belonging to <param/ifa/
! 2448: and causes all unreachable neighbors to be flushed.
! 2449: </function>
! 2450: <function><p><type>void</type>
! 2451: <funcdef>neigh_prune</funcdef>
! 2452: (<param>void</param>) -- prune neighbor cache
! 2453:
! 2454: <funcsect>Description
! 2455: <p>
! 2456: <p>
! 2457: <func/neigh_prune()/ examines all neighbor entries cached and removes those
! 2458: corresponding to inactive protocols. It's called whenever a protocol
! 2459: is shut down to get rid of all its heritage.
! 2460: </function>
! 2461: <function><p><type>void</type>
! 2462: <funcdef>neigh_init</funcdef>
! 2463: (<type>pool *</type> <param>if_pool</param>) -- initialize the neighbor cache.
! 2464:
! 2465: <funcsect>Arguments
! 2466: <p><descrip>
! 2467: <tagp><type>pool *</type> <param>if_pool</param></tagp>
! 2468: resource pool to be used for neighbor entries.
! 2469: </descrip>
! 2470: <funcsect>Description
! 2471: <p>
! 2472: This function is called during BIRD startup to initialize
! 2473: the neighbor cache module.
! 2474: </function>
! 2475: <sect>Command line interface
! 2476: <p>
! 2477: <p>
! 2478: This module takes care of the BIRD's command-line interface (CLI).
! 2479: The CLI exists to provide a way to control BIRD remotely and to inspect
! 2480: its status. It uses a very simple textual protocol over a stream
! 2481: connection provided by the platform dependent code (on UNIX systems,
! 2482: it's a UNIX domain socket).
! 2483: <p>
! 2484: Each session of the CLI consists of a sequence of request and replies,
! 2485: slightly resembling the FTP and SMTP protocols.
! 2486: Requests are commands encoded as a single line of text, replies are
! 2487: sequences of lines starting with a four-digit code followed by either
! 2488: a space (if it's the last line of the reply) or a minus sign (when the
! 2489: reply is going to continue with the next line), the rest of the line
! 2490: contains a textual message semantics of which depends on the numeric
! 2491: code. If a reply line has the same code as the previous one and it's
! 2492: a continuation line, the whole prefix can be replaced by a single
! 2493: white space character.
! 2494: <p>
! 2495: Reply codes starting with 0 stand for `action successfully completed' messages,
! 2496: 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
! 2497: <p>
! 2498: Each CLI session is internally represented by a <struct/cli/ structure and a
! 2499: resource pool containing all resources associated with the connection,
! 2500: so that it can be easily freed whenever the connection gets closed, not depending
! 2501: on the current state of command processing.
! 2502: <p>
! 2503: The CLI commands are declared as a part of the configuration grammar
! 2504: by using the <tt>CF_CLI</tt> macro. When a command is received, it is processed
! 2505: by the same lexical analyzer and parser as used for the configuration, but
! 2506: it's switched to a special mode by prepending a fake token to the text,
! 2507: so that it uses only the CLI command rules. Then the parser invokes
! 2508: an execution routine corresponding to the command, which either constructs
! 2509: the whole reply and returns it back or (in case it expects the reply will be long)
! 2510: it prints a partial reply and asks the CLI module (using the <param/cont/ hook)
! 2511: to call it again when the output is transferred to the user.
! 2512: <p>
! 2513: The <param/this_cli/ variable points to a <struct/cli/ structure of the session being
! 2514: currently parsed, but it's of course available only in command handlers
! 2515: not entered using the <param/cont/ hook.
! 2516: <p>
! 2517: TX buffer management works as follows: At cli.tx_buf there is a
! 2518: list of TX buffers (struct cli_out), cli.tx_write is the buffer
! 2519: currently used by the producer (<func/cli_printf()/, <func/cli_alloc_out()/) and
! 2520: cli.tx_pos is the buffer currently used by the consumer
! 2521: (<func/cli_write()/, in system dependent code). The producer uses
! 2522: cli_out.wpos ptr as the current write position and the consumer
! 2523: uses cli_out.outpos ptr as the current read position. When the
! 2524: producer produces something, it calls <func/cli_write_trigger()/. If there
! 2525: is not enough space in the current buffer, the producer allocates
! 2526: the new one. When the consumer processes everything in the buffer
! 2527: queue, it calls <func/cli_written()/, tha frees all buffers (except the
! 2528: first one) and schedules cli.event .
! 2529:
! 2530:
! 2531: <function><p><type>void</type>
! 2532: <funcdef>cli_printf</funcdef>
! 2533: (<type>cli *</type> <param>c</param>, <type>int</type> <param>code</param>, <type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- send reply to a CLI connection
! 2534:
! 2535: <funcsect>Arguments
! 2536: <p><descrip>
! 2537: <tagp><type>cli *</type> <param>c</param></tagp>
! 2538: CLI connection
! 2539: <tagp><type>int</type> <param>code</param></tagp>
! 2540: numeric code of the reply, negative for continuation lines
! 2541: <tagp><type>char *</type> <param>msg</param></tagp>
! 2542: a <func/printf()/-like formatting string.
! 2543: <tagp><type>...</type> <param>...</param></tagp>
! 2544: variable arguments
! 2545: </descrip>
! 2546: <funcsect>Description
! 2547: <p>
! 2548: This function send a single line of reply to a given CLI connection.
! 2549: In works in all aspects like <func/bsprintf()/ except that it automatically
! 2550: prepends the reply line prefix.
! 2551: <p>
! 2552: Please note that if the connection can be already busy sending some
! 2553: data in which case <func/cli_printf()/ stores the output to a temporary buffer,
! 2554: so please avoid sending a large batch of replies without waiting
! 2555: for the buffers to be flushed.
! 2556: <p>
! 2557: If you want to write to the current CLI output, you can use the <func/cli_msg()/
! 2558: macro instead.
! 2559: </function>
! 2560: <function><p><type>void</type>
! 2561: <funcdef>cli_init</funcdef>
! 2562: (<param>void</param>) -- initialize the CLI module
! 2563:
! 2564: <funcsect>Description
! 2565: <p>
! 2566: <p>
! 2567: This function is called during BIRD startup to initialize
! 2568: the internal data structures of the CLI module.
! 2569: </function>
! 2570: <sect>Object locks
! 2571: <p>
! 2572: <p>
! 2573: The lock module provides a simple mechanism for avoiding conflicts between
! 2574: various protocols which would like to use a single physical resource (for
! 2575: example a network port). It would be easy to say that such collisions can
! 2576: occur only when the user specifies an invalid configuration and therefore
! 2577: he deserves to get what he has asked for, but unfortunately they can also
! 2578: arise legitimately when the daemon is reconfigured and there exists (although
! 2579: for a short time period only) an old protocol instance being shut down and a new one
! 2580: willing to start up on the same interface.
! 2581: <p>
! 2582: The solution is very simple: when any protocol wishes to use a network port
! 2583: or some other non-shareable resource, it asks the core to lock it and it doesn't
! 2584: use the resource until it's notified that it has acquired the lock.
! 2585: <p>
! 2586: Object locks are represented by <struct/object_lock/ structures which are in turn a
! 2587: kind of resource. Lockable resources are uniquely determined by resource type
! 2588: (<const/OBJLOCK_UDP/ for a UDP port etc.), IP address (usually a broadcast or
! 2589: multicast address the port is bound to), port number, interface and optional
! 2590: instance ID.
! 2591:
! 2592:
! 2593: <function><p><type>struct object_lock *</type>
! 2594: <funcdef>olock_new</funcdef>
! 2595: (<type>pool *</type> <param>p</param>) -- create an object lock
! 2596:
! 2597: <funcsect>Arguments
! 2598: <p><descrip>
! 2599: <tagp><type>pool *</type> <param>p</param></tagp>
! 2600: resource pool to create the lock in.
! 2601: </descrip>
! 2602: <funcsect>Description
! 2603: <p>
! 2604: The <func/olock_new()/ function creates a new resource of type <struct/object_lock/
! 2605: and returns a pointer to it. After filling in the structure, the caller
! 2606: should call <func/olock_acquire()/ to do the real locking.
! 2607: </function>
! 2608: <function><p><type>void</type>
! 2609: <funcdef>olock_acquire</funcdef>
! 2610: (<type>struct object_lock *</type> <param>l</param>) -- acquire a lock
! 2611:
! 2612: <funcsect>Arguments
! 2613: <p><descrip>
! 2614: <tagp><type>struct object_lock *</type> <param>l</param></tagp>
! 2615: the lock to acquire
! 2616: </descrip>
! 2617: <funcsect>Description
! 2618: <p>
! 2619: This function attempts to acquire exclusive access to the non-shareable
! 2620: resource described by the lock <param/l/. It returns immediately, but as soon
! 2621: as the resource becomes available, it calls the <func/hook()/ function set up
! 2622: by the caller.
! 2623: <p>
! 2624: When you want to release the resource, just <func/rfree()/ the lock.
! 2625: </function>
! 2626: <function><p><type>void</type>
! 2627: <funcdef>olock_init</funcdef>
! 2628: (<param>void</param>) -- initialize the object lock mechanism
! 2629:
! 2630: <funcsect>Description
! 2631: <p>
! 2632: <p>
! 2633: This function is called during BIRD startup. It initializes
! 2634: all the internal data structures of the lock module.
! 2635: </function>
! 2636: <chapt>Configuration
! 2637: <sect>Configuration manager
! 2638: <p>
! 2639: <p>
! 2640: Configuration of BIRD is complex, yet straightforward. There are three
! 2641: modules taking care of the configuration: config manager (which takes care
! 2642: of storage of the config information and controls switching between configs),
! 2643: lexical analyzer and parser.
! 2644: <p>
! 2645: The configuration manager stores each config as a <struct/config/ structure
! 2646: accompanied by a linear pool from which all information associated
! 2647: with the config and pointed to by the <struct/config/ structure is allocated.
! 2648: <p>
! 2649: There can exist up to four different configurations at one time: an active
! 2650: one (pointed to by <param/config/), configuration we are just switching from
! 2651: (<param/old_config/), one queued for the next reconfiguration (<param/future_config/; if
! 2652: there is one and the user wants to reconfigure once again, we just free the
! 2653: previous queued config and replace it with the new one) and finally a config
! 2654: being parsed (<param/new_config/). The stored <param/old_config/ is also used for undo
! 2655: reconfiguration, which works in a similar way. Reconfiguration could also
! 2656: have timeout (using <param/config_timer/) and undo is automatically called if the
! 2657: new configuration is not confirmed later. The new config (<param/new_config/) and
! 2658: associated linear pool (<param/cfg_mem/) is non-NULL only during parsing.
! 2659: <p>
! 2660: Loading of new configuration is very simple: just call <func/config_alloc()/ to get
! 2661: a new <struct/config/ structure, then use <func/config_parse()/ to parse a configuration
! 2662: file and fill all fields of the structure and finally ask the config manager
! 2663: to switch to the new config by calling <func/config_commit()/.
! 2664: <p>
! 2665: CLI commands are parsed in a very similar way -- there is also a stripped-down
! 2666: <struct/config/ structure associated with them and they are lex-ed and parsed by the
! 2667: same functions, only a special fake token is prepended before the command
! 2668: text to make the parser recognize only the rules corresponding to CLI commands.
! 2669:
! 2670:
! 2671: <function><p><type>struct config *</type>
! 2672: <funcdef>config_alloc</funcdef>
! 2673: (<type>const byte *</type> <param>name</param>) -- allocate a new configuration
! 2674:
! 2675: <funcsect>Arguments
! 2676: <p><descrip>
! 2677: <tagp><type>const byte *</type> <param>name</param></tagp>
! 2678: name of the config
! 2679: </descrip>
! 2680: <funcsect>Description
! 2681: <p>
! 2682: This function creates new <struct/config/ structure, attaches a resource
! 2683: pool and a linear memory pool to it and makes it available for
! 2684: further use. Returns a pointer to the structure.
! 2685: </function>
! 2686: <function><p><type>int</type>
! 2687: <funcdef>config_parse</funcdef>
! 2688: (<type>struct config *</type> <param>c</param>) -- parse a configuration
! 2689:
! 2690: <funcsect>Arguments
! 2691: <p><descrip>
! 2692: <tagp><type>struct config *</type> <param>c</param></tagp>
! 2693: configuration
! 2694: </descrip>
! 2695: <funcsect>Description
! 2696: <p>
! 2697: <func/config_parse()/ reads input by calling a hook function pointed to
! 2698: by <param/cf_read_hook/ and parses it according to the configuration
! 2699: grammar. It also calls all the preconfig and postconfig hooks
! 2700: before, resp. after parsing.
! 2701: <funcsect>Result
! 2702: <p>
! 2703: 1 if the config has been parsed successfully, 0 if any
! 2704: error has occurred (such as anybody calling <func/cf_error()/) and
! 2705: the <param/err_msg/ field has been set to the error message.
! 2706: </function>
! 2707: <function><p><type>int</type>
! 2708: <funcdef>cli_parse</funcdef>
! 2709: (<type>struct config *</type> <param>c</param>) -- parse a CLI command
! 2710:
! 2711: <funcsect>Arguments
! 2712: <p><descrip>
! 2713: <tagp><type>struct config *</type> <param>c</param></tagp>
! 2714: temporary config structure
! 2715: </descrip>
! 2716: <funcsect>Description
! 2717: <p>
! 2718: <func/cli_parse()/ is similar to <func/config_parse()/, but instead of a configuration,
! 2719: it parses a CLI command. See the CLI module for more information.
! 2720: </function>
! 2721: <function><p><type>void</type>
! 2722: <funcdef>config_free</funcdef>
! 2723: (<type>struct config *</type> <param>c</param>) -- free a configuration
! 2724:
! 2725: <funcsect>Arguments
! 2726: <p><descrip>
! 2727: <tagp><type>struct config *</type> <param>c</param></tagp>
! 2728: configuration to be freed
! 2729: </descrip>
! 2730: <funcsect>Description
! 2731: <p>
! 2732: This function takes a <struct/config/ structure and frees all resources
! 2733: associated with it.
! 2734: </function>
! 2735: <function><p><type>int</type>
! 2736: <funcdef>config_commit</funcdef>
! 2737: (<type>struct config *</type> <param>c</param>, <type>int</type> <param>type</param>, <type>int</type> <param>timeout</param>) -- commit a configuration
! 2738:
! 2739: <funcsect>Arguments
! 2740: <p><descrip>
! 2741: <tagp><type>struct config *</type> <param>c</param></tagp>
! 2742: new configuration
! 2743: <tagp><type>int</type> <param>type</param></tagp>
! 2744: type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
! 2745: <tagp><type>int</type> <param>timeout</param></tagp>
! 2746: timeout for undo (or 0 for no timeout)
! 2747: </descrip>
! 2748: <funcsect>Description
! 2749: <p>
! 2750: When a configuration is parsed and prepared for use, the
! 2751: <func/config_commit()/ function starts the process of reconfiguration.
! 2752: It checks whether there is already a reconfiguration in progress
! 2753: in which case it just queues the new config for later processing.
! 2754: Else it notifies all modules about the new configuration by calling
! 2755: their <func/commit()/ functions which can either accept it immediately
! 2756: or call <func/config_add_obstacle()/ to report that they need some time
! 2757: to complete the reconfiguration. After all such obstacles are removed
! 2758: using <func/config_del_obstacle()/, the old configuration is freed and
! 2759: everything runs according to the new one.
! 2760: <p>
! 2761: When <param/timeout/ is nonzero, the undo timer is activated with given
! 2762: timeout. The timer is deactivated when <func/config_commit()/,
! 2763: <func/config_confirm()/ or <func/config_undo()/ is called.
! 2764: <funcsect>Result
! 2765: <p>
! 2766: <const/CONF_DONE/ if the configuration has been accepted immediately,
! 2767: <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/
! 2768: if it's been queued due to another reconfiguration being in progress now
! 2769: or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and no new configurations
! 2770: are accepted.
! 2771: </function>
! 2772: <function><p><type>int</type>
! 2773: <funcdef>config_confirm</funcdef>
! 2774: (<param>void</param>) -- confirm a commited configuration
! 2775:
! 2776: <funcsect>Description
! 2777: <p>
! 2778: <p>
! 2779: When the undo timer is activated by <func/config_commit()/ with nonzero timeout,
! 2780: this function can be used to deactivate it and therefore confirm
! 2781: the current configuration.
! 2782: <funcsect>Result
! 2783: <p>
! 2784: <const/CONF_CONFIRM/ when the current configuration is confirmed,
! 2785: <const/CONF_NONE/ when there is nothing to confirm (i.e. undo timer is not active).
! 2786: </function>
! 2787: <function><p><type>int</type>
! 2788: <funcdef>config_undo</funcdef>
! 2789: (<param>void</param>) -- undo a configuration
! 2790:
! 2791: <funcsect>Description
! 2792: <p>
! 2793: <p>
! 2794: Function <func/config_undo()/ can be used to change the current
! 2795: configuration back to stored <const/old_config/. If no reconfiguration is
! 2796: running, this stored configuration is commited in the same way as a
! 2797: new configuration in <func/config_commit()/. If there is already a
! 2798: reconfiguration in progress and no next reconfiguration is
! 2799: scheduled, then the undo is scheduled for later processing as
! 2800: usual, but if another reconfiguration is already scheduled, then
! 2801: such reconfiguration is removed instead (i.e. undo is applied on
! 2802: the last commit that scheduled it).
! 2803: <funcsect>Result
! 2804: <p>
! 2805: <const/CONF_DONE/ if the configuration has been accepted immediately,
! 2806: <const/CONF_PROGRESS/ if it will take some time to switch to it, <const/CONF_QUEUED/
! 2807: if it's been queued due to another reconfiguration being in progress now,
! 2808: <const/CONF_UNQUEUED/ if a scheduled reconfiguration is removed, <const/CONF_NOTHING/
! 2809: if there is no relevant configuration to undo (the previous config request
! 2810: was <func/config_undo()/ too) or <const/CONF_SHUTDOWN/ if BIRD is in shutdown mode and
! 2811: no new configuration changes are accepted.
! 2812: </function>
! 2813: <function><p><type>void</type>
! 2814: <funcdef>order_shutdown</funcdef>
! 2815: (<param>void</param>) -- order BIRD shutdown
! 2816:
! 2817: <funcsect>Description
! 2818: <p>
! 2819: <p>
! 2820: This function initiates shutdown of BIRD. It's accomplished by asking
! 2821: for switching to an empty configuration.
! 2822: </function>
! 2823: <function><p><type>void</type>
! 2824: <funcdef>cf_error</funcdef>
! 2825: (<type>char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a configuration error
! 2826:
! 2827: <funcsect>Arguments
! 2828: <p><descrip>
! 2829: <tagp><type>char *</type> <param>msg</param></tagp>
! 2830: printf-like format string
! 2831: <tagp><type>...</type> <param>...</param></tagp>
! 2832: variable arguments
! 2833: </descrip>
! 2834: <funcsect>Description
! 2835: <p>
! 2836: <func/cf_error()/ can be called during execution of <func/config_parse()/, that is
! 2837: from the parser, a preconfig hook or a postconfig hook, to report an
! 2838: error in the configuration.
! 2839: </function>
! 2840: <function><p><type>char *</type>
! 2841: <funcdef>cfg_strdup</funcdef>
! 2842: (<type>const char *</type> <param>c</param>) -- copy a string to config memory
! 2843:
! 2844: <funcsect>Arguments
! 2845: <p><descrip>
! 2846: <tagp><type>const char *</type> <param>c</param></tagp>
! 2847: string to copy
! 2848: </descrip>
! 2849: <funcsect>Description
! 2850: <p>
! 2851: <func/cfg_strdup()/ creates a new copy of the string in the memory
! 2852: pool associated with the configuration being currently parsed.
! 2853: It's often used when a string literal occurs in the configuration
! 2854: and we want to preserve it for further use.
! 2855: </function>
! 2856: <sect>Lexical analyzer
! 2857: <p>
! 2858: <p>
! 2859: The lexical analyzer used for configuration files and CLI commands
! 2860: is generated using the <tt>flex</tt> tool accompanied by a couple of
! 2861: functions maintaining the hash tables containing information about
! 2862: symbols and keywords.
! 2863: <p>
! 2864: Each symbol is represented by a <struct/symbol/ structure containing name
! 2865: of the symbol, its lexical scope, symbol class (<const/SYM_PROTO/ for a
! 2866: name of a protocol, <const/SYM_CONSTANT/ for a constant etc.) and class
! 2867: dependent data. When an unknown symbol is encountered, it's
! 2868: automatically added to the symbol table with class <const/SYM_VOID/.
! 2869: <p>
! 2870: The keyword tables are generated from the grammar templates
! 2871: using the <tt>gen_keywords.m4</tt> script.
! 2872:
! 2873:
! 2874: <function><p><type>void</type>
! 2875: <funcdef>cf_lex_unwind</funcdef>
! 2876: (<param>void</param>) -- unwind lexer state during error
! 2877:
! 2878: <funcsect>Lexical analyzer
! 2879: <p>
! 2880: <p>
! 2881: <func/cf_lex_unwind()/ frees the internal state on IFS stack when the lexical
! 2882: analyzer is terminated by <func/cf_error()/.
! 2883: </function>
! 2884: <function><p><type>struct symbol *</type>
! 2885: <funcdef>cf_find_symbol</funcdef>
! 2886: (<type>struct config *</type> <param>cfg</param>, <type>byte *</type> <param>c</param>) -- find a symbol by name
! 2887:
! 2888: <funcsect>Arguments
! 2889: <p><descrip>
! 2890: <tagp><type>struct config *</type> <param>cfg</param></tagp>
! 2891: specificed config
! 2892: <tagp><type>byte *</type> <param>c</param></tagp>
! 2893: symbol name
! 2894: </descrip>
! 2895: <funcsect>Description
! 2896: <p>
! 2897: This functions searches the symbol table in the config <param/cfg/ for a symbol of
! 2898: given name. First it examines the current scope, then the second recent one
! 2899: and so on until it either finds the symbol and returns a pointer to its
! 2900: <struct/symbol/ structure or reaches the end of the scope chain and returns <const/NULL/ to
! 2901: signify no match.
! 2902: </function>
! 2903: <function><p><type>struct symbol *</type>
! 2904: <funcdef>cf_get_symbol</funcdef>
! 2905: (<type>byte *</type> <param>c</param>) -- get a symbol by name
! 2906:
! 2907: <funcsect>Arguments
! 2908: <p><descrip>
! 2909: <tagp><type>byte *</type> <param>c</param></tagp>
! 2910: symbol name
! 2911: </descrip>
! 2912: <funcsect>Description
! 2913: <p>
! 2914: This functions searches the symbol table of the currently parsed config
! 2915: (<param/new_config/) for a symbol of given name. It returns either the already
! 2916: existing symbol or a newly allocated undefined (<const/SYM_VOID/) symbol if no
! 2917: existing symbol is found.
! 2918: </function>
! 2919: <function><p><type>struct symbol *</type>
! 2920: <funcdef>cf_define_symbol</funcdef>
! 2921: (<type>struct symbol *</type> <param>sym</param>, <type>int</type> <param>type</param>, <type>void *</type> <param>def</param>) -- define meaning of a symbol
! 2922:
! 2923: <funcsect>Arguments
! 2924: <p><descrip>
! 2925: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
! 2926: symbol to be defined
! 2927: <tagp><type>int</type> <param>type</param></tagp>
! 2928: symbol class to assign
! 2929: <tagp><type>void *</type> <param>def</param></tagp>
! 2930: class dependent data
! 2931: </descrip>
! 2932: <funcsect>Description
! 2933: <p>
! 2934: Defines new meaning of a symbol. If the symbol is an undefined
! 2935: one (<const/SYM_VOID/), it's just re-defined to the new type. If it's defined
! 2936: in different scope, a new symbol in current scope is created and the
! 2937: meaning is assigned to it. If it's already defined in the current scope,
! 2938: an error is reported via <func/cf_error()/.
! 2939: <funcsect>Result
! 2940: <p>
! 2941: Pointer to the newly defined symbol. If we are in the top-level
! 2942: scope, it's the same <param/sym/ as passed to the function.
! 2943: </function>
! 2944: <function><p><type>void</type>
! 2945: <funcdef>cf_lex_init</funcdef>
! 2946: (<type>int</type> <param>is_cli</param>, <type>struct config *</type> <param>c</param>) -- initialize the lexer
! 2947:
! 2948: <funcsect>Arguments
! 2949: <p><descrip>
! 2950: <tagp><type>int</type> <param>is_cli</param></tagp>
! 2951: true if we're going to parse CLI command, false for configuration
! 2952: <tagp><type>struct config *</type> <param>c</param></tagp>
! 2953: configuration structure
! 2954: </descrip>
! 2955: <funcsect>Description
! 2956: <p>
! 2957: <func/cf_lex_init()/ initializes the lexical analyzer and prepares it for
! 2958: parsing of a new input.
! 2959: </function>
! 2960: <function><p><type>void</type>
! 2961: <funcdef>cf_push_scope</funcdef>
! 2962: (<type>struct symbol *</type> <param>sym</param>) -- enter new scope
! 2963:
! 2964: <funcsect>Arguments
! 2965: <p><descrip>
! 2966: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
! 2967: symbol representing scope name
! 2968: </descrip>
! 2969: <funcsect>Description
! 2970: <p>
! 2971: If we want to enter a new scope to process declarations inside
! 2972: a nested block, we can just call <func/cf_push_scope()/ to push a new
! 2973: scope onto the scope stack which will cause all new symbols to be
! 2974: defined in this scope and all existing symbols to be sought for
! 2975: in all scopes stored on the stack.
! 2976: </function>
! 2977: <function><p><type>void</type>
! 2978: <funcdef>cf_pop_scope</funcdef>
! 2979: (<param>void</param>) -- leave a scope
! 2980:
! 2981: <funcsect>Description
! 2982: <p>
! 2983: <p>
! 2984: <func/cf_pop_scope()/ pops the topmost scope from the scope stack,
! 2985: leaving all its symbols in the symbol table, but making them
! 2986: invisible to the rest of the config.
! 2987: </function>
! 2988: <function><p><type>char *</type>
! 2989: <funcdef>cf_symbol_class_name</funcdef>
! 2990: (<type>struct symbol *</type> <param>sym</param>) -- get name of a symbol class
! 2991:
! 2992: <funcsect>Arguments
! 2993: <p><descrip>
! 2994: <tagp><type>struct symbol *</type> <param>sym</param></tagp>
! 2995: symbol
! 2996: </descrip>
! 2997: <funcsect>Description
! 2998: <p>
! 2999: This function returns a string representing the class
! 3000: of the given symbol.
! 3001: </function>
! 3002: <sect>Parser
! 3003: <p>
! 3004: <p>
! 3005: Both the configuration and CLI commands are analyzed using a syntax
! 3006: driven parser generated by the <tt>bison</tt> tool from a grammar which
! 3007: is constructed from information gathered from grammar snippets by
! 3008: the <tt>gen_parser.m4</tt> script.
! 3009: <p>
! 3010: Grammar snippets are files (usually with extension <tt>.Y</tt>) contributed
! 3011: by various BIRD modules in order to provide information about syntax of their
! 3012: configuration and their CLI commands. Each snipped consists of several
! 3013: sections, each of them starting with a special keyword: <tt>CF_HDR</tt> for
! 3014: a list of <tt>#include</tt> directives needed by the C code, <tt>CF_DEFINES</tt>
! 3015: for a list of C declarations, <tt>CF_DECLS</tt> for <tt>bison</tt> declarations
! 3016: including keyword definitions specified as <tt>CF_KEYWORDS</tt>, <tt>CF_GRAMMAR</tt>
! 3017: for the grammar rules, <tt>CF_CODE</tt> for auxiliary C code and finally
! 3018: <tt>CF_END</tt> at the end of the snippet.
! 3019: <p>
! 3020: To create references between the snippets, it's possible to define
! 3021: multi-part rules by utilizing the <tt>CF_ADDTO</tt> macro which adds a new
! 3022: alternative to a multi-part rule.
! 3023: <p>
! 3024: CLI commands are defined using a <tt>CF_CLI</tt> macro. Its parameters are:
! 3025: the list of keywords determining the command, the list of parameters,
! 3026: help text for the parameters and help text for the command.
! 3027: <p>
! 3028: Values of <tt>enum</tt> filter types can be defined using <tt>CF_ENUM</tt> with
! 3029: the following parameters: name of filter type, prefix common for all
! 3030: literals of this type and names of all the possible values.
! 3031:
! 3032:
! 3033: <chapt>Filters
! 3034: <sect>Filters
! 3035: <p>
! 3036: <p>
! 3037: You can find sources of the filter language in <tt>filter/</tt>
! 3038: directory. File <tt>filter/config.Y</tt> contains filter grammar and basically translates
! 3039: the source from user into a tree of <struct/f_inst/ structures. These trees are
! 3040: later interpreted using code in <tt>filter/filter.c</tt>.
! 3041: <p>
! 3042: A filter is represented by a tree of <struct/f_inst/ structures, one structure per
! 3043: "instruction". Each <struct/f_inst/ contains <param/code/, <param/aux/ value which is
! 3044: usually the data type this instruction operates on and two generic
! 3045: arguments (<param/a1/, <param/a2/). Some instructions contain pointer(s) to other
! 3046: instructions in their (<param/a1/, <param/a2/) fields.
! 3047: <p>
! 3048: Filters use a <struct/f_val/ structure for their data. Each <struct/f_val/
! 3049: contains type and value (types are constants prefixed with <const/T_/). Few
! 3050: of the types are special; <const/T_RETURN/ can be or-ed with a type to indicate
! 3051: that return from a function or from the whole filter should be
! 3052: forced. Important thing about <struct/f_val/'s is that they may be copied
! 3053: with a simple <tt>=</tt>. That's fine for all currently defined types: strings
! 3054: are read-only (and therefore okay), paths are copied for each
! 3055: operation (okay too).
! 3056:
! 3057:
! 3058: <function><p><type>int</type>
! 3059: <funcdef>val_compare</funcdef>
! 3060: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values
! 3061:
! 3062: <funcsect>Arguments
! 3063: <p><descrip>
! 3064: <tagp><type>struct f_val</type> <param>v1</param></tagp>
! 3065: first value
! 3066: <tagp><type>struct f_val</type> <param>v2</param></tagp>
! 3067: second value
! 3068: </descrip>
! 3069: <funcsect>Description
! 3070: <p>
! 3071: Compares two values and returns -1, 0, 1 on <, =, > or CMP_ERROR on
! 3072: error. Tree module relies on this giving consistent results so
! 3073: that it can be used for building balanced trees.
! 3074: </function>
! 3075: <function><p><type>int</type>
! 3076: <funcdef>val_same</funcdef>
! 3077: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- compare two values
! 3078:
! 3079: <funcsect>Arguments
! 3080: <p><descrip>
! 3081: <tagp><type>struct f_val</type> <param>v1</param></tagp>
! 3082: first value
! 3083: <tagp><type>struct f_val</type> <param>v2</param></tagp>
! 3084: second value
! 3085: </descrip>
! 3086: <funcsect>Description
! 3087: <p>
! 3088: Compares two values and returns 1 if they are same and 0 if not.
! 3089: Comparison of values of different types is valid and returns 0.
! 3090: </function>
! 3091: <function><p><type>int</type>
! 3092: <funcdef>val_in_range</funcdef>
! 3093: (<type>struct f_val</type> <param>v1</param>, <type>struct f_val</type> <param>v2</param>) -- implement <tt>~</tt> operator
! 3094:
! 3095: <funcsect>Arguments
! 3096: <p><descrip>
! 3097: <tagp><type>struct f_val</type> <param>v1</param></tagp>
! 3098: element
! 3099: <tagp><type>struct f_val</type> <param>v2</param></tagp>
! 3100: set
! 3101: </descrip>
! 3102: <funcsect>Description
! 3103: <p>
! 3104: Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/.
! 3105: </function>
! 3106: <function><p><type>struct f_val</type>
! 3107: <funcdef>interpret</funcdef>
! 3108: (<type>struct f_inst *</type> <param>what</param>)
! 3109: <funcsect>Arguments
! 3110: <p><descrip>
! 3111: <tagp><type>struct f_inst *</type> <param>what</param></tagp>
! 3112: filter to interpret
! 3113: </descrip>
! 3114: <funcsect>Description
! 3115: <p>
! 3116: Interpret given tree of filter instructions. This is core function
! 3117: of filter system and does all the hard work.
! 3118: <funcsect>Each instruction has 4 fields
! 3119: <p>
! 3120: code (which is instruction code),
! 3121: aux (which is extension to instruction code, typically type),
! 3122: arg1 and arg2 - arguments. Depending on instruction, arguments
! 3123: are either integers, or pointers to instruction trees. Common
! 3124: instructions like +, that have two expressions as arguments use
! 3125: TWOARGS macro to get both of them evaluated.
! 3126: <p>
! 3127: <struct/f_val/ structures are copied around, so there are no problems with
! 3128: memory managment.
! 3129: </function>
! 3130: <function><p><type>int</type>
! 3131: <funcdef>f_run</funcdef>
! 3132: (<type>struct filter *</type> <param>filter</param>, <type>struct rte **</type> <param>rte</param>, <type>struct ea_list **</type> <param>tmp_attrs</param>, <type>struct linpool *</type> <param>tmp_pool</param>, <type>int</type> <param>flags</param>) -- run a filter for a route
! 3133:
! 3134: <funcsect>Arguments
! 3135: <p><descrip>
! 3136: <tagp><type>struct filter *</type> <param>filter</param></tagp>
! 3137: filter to run
! 3138: <tagp><type>struct rte **</type> <param>rte</param></tagp>
! 3139: route being filtered, may be modified
! 3140: <tagp><type>struct ea_list **</type> <param>tmp_attrs</param></tagp>
! 3141: temporary attributes, prepared by caller or generated by <func/f_run()/
! 3142: <tagp><type>struct linpool *</type> <param>tmp_pool</param></tagp>
! 3143: all filter allocations go from this pool
! 3144: <tagp><type>int</type> <param>flags</param></tagp>
! 3145: flags
! 3146: </descrip>
! 3147: <funcsect>Description
! 3148: <p>
! 3149: If filter needs to modify the route, there are several
! 3150: posibilities. <param/rte/ might be read-only (with REF_COW flag), in that
! 3151: case rw copy is obtained by <func/rte_cow()/ and <param/rte/ is replaced. If
! 3152: <param/rte/ is originally rw, it may be directly modified (and it is never
! 3153: copied).
! 3154: <p>
! 3155: The returned rte may reuse the (possibly cached, cloned) rta, or
! 3156: (if rta was modificied) contains a modified uncached rta, which
! 3157: uses parts allocated from <param/tmp_pool/ and parts shared from original
! 3158: rta. There is one exception - if <param/rte/ is rw but contains a cached
! 3159: rta and that is modified, rta in returned rte is also cached.
! 3160: <p>
! 3161: Ownership of cached rtas is consistent with rte, i.e.
! 3162: if a new rte is returned, it has its own clone of cached rta
! 3163: (and cached rta of read-only source rte is intact), if rte is
! 3164: modified in place, old cached rta is possibly freed.
! 3165: </function>
! 3166: <function><p><type>int</type>
! 3167: <funcdef>filter_same</funcdef>
! 3168: (<type>struct filter *</type> <param>new</param>, <type>struct filter *</type> <param>old</param>) -- compare two filters
! 3169:
! 3170: <funcsect>Arguments
! 3171: <p><descrip>
! 3172: <tagp><type>struct filter *</type> <param>new</param></tagp>
! 3173: first filter to be compared
! 3174: <tagp><type>struct filter *</type> <param>old</param></tagp>
! 3175: second filter to be compared, notice that this filter is
! 3176: damaged while comparing.
! 3177: </descrip>
! 3178: <funcsect>Description
! 3179: <p>
! 3180: Returns 1 in case filters are same, otherwise 0. If there are
! 3181: underlying bugs, it will rather say 0 on same filters than say
! 3182: 1 on different.
! 3183: </function>
! 3184: <function><p><type>struct f_tree *</type>
! 3185: <funcdef>find_tree</funcdef>
! 3186: (<type>struct f_tree *</type> <param>t</param>, <type>struct f_val</type> <param>val</param>)
! 3187: <funcsect>Arguments
! 3188: <p><descrip>
! 3189: <tagp><type>struct f_tree *</type> <param>t</param></tagp>
! 3190: tree to search in
! 3191: <tagp><type>struct f_val</type> <param>val</param></tagp>
! 3192: value to find
! 3193: </descrip>
! 3194: <funcsect>Description
! 3195: <p>
! 3196: Search for given value in the tree. I relies on fact that sorted tree is populated
! 3197: by <struct/f_val/ structures (that can be compared by <func/val_compare()/). In each node of tree,
! 3198: either single value (then t->from==t->to) or range is present.
! 3199: <p>
! 3200: Both set matching and <tt><func/switch()/ { }</tt> construction is implemented using this function,
! 3201: thus both are as fast as they can be.
! 3202: </function>
! 3203: <function><p><type>struct f_tree *</type>
! 3204: <funcdef>build_tree</funcdef>
! 3205: (<type>struct f_tree *</type> <param>from</param>)
! 3206: <funcsect>Arguments
! 3207: <p><descrip>
! 3208: <tagp><type>struct f_tree *</type> <param>from</param></tagp>
! 3209: degenerated tree (linked by <param/tree/->left) to be transformed into form suitable for <func/find_tree()/
! 3210: </descrip>
! 3211: <funcsect>Description
! 3212: <p>
! 3213: Transforms degenerated tree into balanced tree.
! 3214: </function>
! 3215: <function><p><type>int</type>
! 3216: <funcdef>same_tree</funcdef>
! 3217: (<type>struct f_tree *</type> <param>t1</param>, <type>struct f_tree *</type> <param>t2</param>)
! 3218: <funcsect>Arguments
! 3219: <p><descrip>
! 3220: <tagp><type>struct f_tree *</type> <param>t1</param></tagp>
! 3221: first tree to be compared
! 3222: <tagp><type>struct f_tree *</type> <param>t2</param></tagp>
! 3223: second one
! 3224: </descrip>
! 3225: <funcsect>Description
! 3226: <p>
! 3227: Compares two trees and returns 1 if they are same
! 3228: </function>
! 3229: <sect>Trie for prefix sets
! 3230: <p>
! 3231: <p>
! 3232: We use a (compressed) trie to represent prefix sets. Every node
! 3233: in the trie represents one prefix (<struct/addr//<struct/plen/) and <struct/plen/ also
! 3234: indicates the index of the bit in the address that is used to
! 3235: branch at the node. If we need to represent just a set of
! 3236: prefixes, it would be simple, but we have to represent a
! 3237: set of prefix patterns. Each prefix pattern consists of
! 3238: <struct/ppaddr//<struct/pplen/ and two integers: <struct/low/ and <struct/high/, and a prefix
! 3239: <struct/paddr//<struct/plen/ matches that pattern if the first MIN(<struct/plen/, <struct/pplen/)
! 3240: bits of <struct/paddr/ and <struct/ppaddr/ are the same and <struct/low/ <= <struct/plen/ <= <struct/high/.
! 3241: <p>
! 3242: We use a bitmask (<struct/accept/) to represent accepted prefix lengths
! 3243: at a node. As there are 33 prefix lengths (0..32 for IPv4), but
! 3244: there is just one prefix of zero length in the whole trie so we
! 3245: have <struct/zero/ flag in <struct/f_trie/ (indicating whether the trie accepts
! 3246: prefix 0.0.0.0/0) as a special case, and <struct/accept/ bitmask
! 3247: represents accepted prefix lengths from 1 to 32.
! 3248: <p>
! 3249: There are two cases in prefix matching - a match when the length
! 3250: of the prefix is smaller that the length of the prefix pattern,
! 3251: (<struct/plen/ < <struct/pplen/) and otherwise. The second case is simple - we
! 3252: just walk through the trie and look at every visited node
! 3253: whether that prefix accepts our prefix length (<struct/plen/). The
! 3254: first case is tricky - we don't want to examine every descendant
! 3255: of a final node, so (when we create the trie) we have to propagate
! 3256: that information from nodes to their ascendants.
! 3257: <p>
! 3258: Suppose that we have two masks (M1 and M2) for a node. Mask M1
! 3259: represents accepted prefix lengths by just the node and mask M2
! 3260: represents accepted prefix lengths by the node or any of its
! 3261: descendants. Therefore M2 is a bitwise or of M1 and children's
! 3262: M2 and this is a maintained invariant during trie building.
! 3263: Basically, when we want to match a prefix, we walk through the trie,
! 3264: check mask M1 for our prefix length and when we came to
! 3265: final node, we check mask M2.
! 3266: <p>
! 3267: There are two differences in the real implementation. First,
! 3268: we use a compressed trie so there is a case that we skip our
! 3269: final node (if it is not in the trie) and we came to node that
! 3270: is either extension of our prefix, or completely out of path
! 3271: In the first case, we also have to check M2.
! 3272: <p>
! 3273: Second, we really need not to maintain two separate bitmasks.
! 3274: Checks for mask M1 are always larger than <struct/applen/ and we need
! 3275: just the first <struct/pplen/ bits of mask M2 (if trie compression
! 3276: hadn't been used it would suffice to know just $applen-th bit),
! 3277: so we have to store them together in <struct/accept/ mask - the first
! 3278: <struct/pplen/ bits of mask M2 and then mask M1.
! 3279: <p>
! 3280: There are four cases when we walk through a trie:
! 3281: <p>
! 3282: - we are in NULL
! 3283: - we are out of path (prefixes are inconsistent)
! 3284: - we are in the wanted (final) node (node length == <struct/plen/)
! 3285: - we are beyond the end of path (node length > <struct/plen/)
! 3286: - we are still on path and keep walking (node length < <struct/plen/)
! 3287: <p>
! 3288: The walking code in <func/trie_match_prefix()/ is structured according to
! 3289: these cases.
! 3290:
! 3291:
! 3292: <function><p><type>struct f_trie *</type>
! 3293: <funcdef>f_new_trie</funcdef>
! 3294: (<type>linpool *</type> <param>lp</param>, <type>uint</type> <param>node_size</param>) -- allocates and returns a new empty trie
! 3295:
! 3296: <funcsect>Arguments
! 3297: <p><descrip>
! 3298: <tagp><type>linpool *</type> <param>lp</param></tagp>
! 3299: linear pool to allocate items from
! 3300: <tagp><type>uint</type> <param>node_size</param></tagp>
! 3301: node size to be used (<struct/f_trie_node/ and user data)
! 3302: </descrip>
! 3303: </function>
! 3304: <function><p><type>void *</type>
! 3305: <funcdef>trie_add_prefix</funcdef>
! 3306: (<type>struct f_trie *</type> <param>t</param>, <type>ip_addr</type> <param>px</param>, <type>int</type> <param>plen</param>, <type>int</type> <param>l</param>, <type>int</type> <param>h</param>)
! 3307: <funcsect>Arguments
! 3308: <p><descrip>
! 3309: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
! 3310: trie to add to
! 3311: <tagp><type>ip_addr</type> <param>px</param></tagp>
! 3312: prefix address
! 3313: <tagp><type>int</type> <param>plen</param></tagp>
! 3314: prefix length
! 3315: <tagp><type>int</type> <param>l</param></tagp>
! 3316: prefix lower bound
! 3317: <tagp><type>int</type> <param>h</param></tagp>
! 3318: prefix upper bound
! 3319: </descrip>
! 3320: <funcsect>Description
! 3321: <p>
! 3322: Adds prefix (prefix pattern) <param/px//<param/plen/ to trie <param/t/. <param/l/ and <param/h/ are lower
! 3323: and upper bounds on accepted prefix lengths, both inclusive.
! 3324: 0 <= l, h <= 32 (128 for IPv6).
! 3325: <p>
! 3326: Returns a pointer to the allocated node. The function can return a pointer to
! 3327: an existing node if <param/px/ and <param/plen/ are the same. If px/plen == 0/0 (or ::/0),
! 3328: a pointer to the root node is returned.
! 3329: </function>
! 3330: <function><p><type>int</type>
! 3331: <funcdef>trie_match_prefix</funcdef>
! 3332: (<type>struct f_trie *</type> <param>t</param>, <type>ip_addr</type> <param>px</param>, <type>int</type> <param>plen</param>)
! 3333: <funcsect>Arguments
! 3334: <p><descrip>
! 3335: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
! 3336: trie
! 3337: <tagp><type>ip_addr</type> <param>px</param></tagp>
! 3338: prefix address
! 3339: <tagp><type>int</type> <param>plen</param></tagp>
! 3340: prefix length
! 3341: </descrip>
! 3342: <funcsect>Description
! 3343: <p>
! 3344: Tries to find a matching prefix pattern in the trie such that
! 3345: prefix <param/px//<param/plen/ matches that prefix pattern. Returns 1 if there
! 3346: is such prefix pattern in the trie.
! 3347: </function>
! 3348: <function><p><type>int</type>
! 3349: <funcdef>trie_same</funcdef>
! 3350: (<type>struct f_trie *</type> <param>t1</param>, <type>struct f_trie *</type> <param>t2</param>)
! 3351: <funcsect>Arguments
! 3352: <p><descrip>
! 3353: <tagp><type>struct f_trie *</type> <param>t1</param></tagp>
! 3354: first trie to be compared
! 3355: <tagp><type>struct f_trie *</type> <param>t2</param></tagp>
! 3356: second one
! 3357: </descrip>
! 3358: <funcsect>Description
! 3359: <p>
! 3360: Compares two tries and returns 1 if they are same
! 3361: </function>
! 3362: <function><p><type>void</type>
! 3363: <funcdef>trie_format</funcdef>
! 3364: (<type>struct f_trie *</type> <param>t</param>, <type>buffer *</type> <param>buf</param>)
! 3365: <funcsect>Arguments
! 3366: <p><descrip>
! 3367: <tagp><type>struct f_trie *</type> <param>t</param></tagp>
! 3368: trie to be formatted
! 3369: <tagp><type>buffer *</type> <param>buf</param></tagp>
! 3370: destination buffer
! 3371: </descrip>
! 3372: <funcsect>Description
! 3373: <p>
! 3374: Prints the trie to the supplied buffer.
! 3375: </function>
! 3376: <chapt>Protocols
! 3377: <sect>The Babel protocol
! 3378: <p>
! 3379: <p>
! 3380: Babel (RFC6126) is a loop-avoiding distance-vector routing protocol that is
! 3381: robust and efficient both in ordinary wired networks and in wireless mesh
! 3382: networks.
! 3383: <p>
! 3384: The Babel protocol keeps state for each neighbour in a <struct/babel_neighbor/
! 3385: struct, tracking received Hello and I Heard You (IHU) messages. A
! 3386: <struct/babel_interface/ struct keeps hello and update times for each interface, and
! 3387: a separate hello seqno is maintained for each interface.
! 3388: <p>
! 3389: For each prefix, Babel keeps track of both the possible routes (with next hop
! 3390: and router IDs), as well as the feasibility distance for each prefix and
! 3391: router id. The prefix itself is tracked in a <struct/babel_entry/ struct, while the
! 3392: possible routes for the prefix are tracked as <struct/babel_route/ entries and the
! 3393: feasibility distance is maintained through <struct/babel_source/ structures.
! 3394: <p>
! 3395: The main route selection is done in <func/babel_select_route()/. This is called when
! 3396: an entry is updated by receiving updates from the network or when modified by
! 3397: internal timers. It performs feasibility checks on the available routes for
! 3398: the prefix and selects the one with the lowest metric to be announced to the
! 3399: core.
! 3400:
! 3401:
! 3402: <function><p><type>void</type>
! 3403: <funcdef>babel_announce_rte</funcdef>
! 3404: (<type>struct babel_proto *</type> <param>p</param>, <type>struct babel_entry *</type> <param>e</param>) -- announce selected route to the core
! 3405:
! 3406: <funcsect>Arguments
! 3407: <p><descrip>
! 3408: <tagp><type>struct babel_proto *</type> <param>p</param></tagp>
! 3409: Babel protocol instance
! 3410: <tagp><type>struct babel_entry *</type> <param>e</param></tagp>
! 3411: Babel route entry to announce
! 3412: </descrip>
! 3413: <funcsect>Description
! 3414: <p>
! 3415: This function announces a Babel entry to the core if it has a selected
! 3416: incoming path, and retracts it otherwise. If the selected entry has infinite
! 3417: metric, the route is announced as unreachable.
! 3418: </function>
! 3419: <function><p><type>void</type>
! 3420: <funcdef>babel_select_route</funcdef>
! 3421: (<type>struct babel_entry *</type> <param>e</param>) -- select best route for given route entry
! 3422:
! 3423: <funcsect>Arguments
! 3424: <p><descrip>
! 3425: <tagp><type>struct babel_entry *</type> <param>e</param></tagp>
! 3426: Babel entry to select the best route for
! 3427: </descrip>
! 3428: <funcsect>Description
! 3429: <p>
! 3430: Select the best feasible route for a given prefix among the routes received
! 3431: from peers, and propagate it to the nest. This just selects the feasible
! 3432: route with the lowest metric.
! 3433: <p>
! 3434: If no feasible route is available for a prefix that previously had a route
! 3435: selected, a seqno request is sent to try to get a valid route. In the
! 3436: meantime, the route is marked as infeasible in the nest (to blackhole packets
! 3437: going to it, as per the RFC).
! 3438: <p>
! 3439: If no feasible route is available, and no previous route is selected, the
! 3440: route is removed from the nest entirely.
! 3441: </function>
! 3442: <function><p><type>void</type>
! 3443: <funcdef>babel_send_update</funcdef>
! 3444: (<type>struct babel_iface *</type> <param>ifa</param>, <type>bird_clock_t</type> <param>changed</param>) -- send route table updates
! 3445:
! 3446: <funcsect>Arguments
! 3447: <p><descrip>
! 3448: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3449: Interface to transmit on
! 3450: <tagp><type>bird_clock_t</type> <param>changed</param></tagp>
! 3451: Only send entries changed since this time
! 3452: </descrip>
! 3453: <funcsect>Description
! 3454: <p>
! 3455: This function produces update TLVs for all entries changed since the time
! 3456: indicated by the <struct/changed/ parameter and queues them for transmission on the
! 3457: selected interface. During the process, the feasibility distance for each
! 3458: transmitted entry is updated.
! 3459: </function>
! 3460: <function><p><type>void</type>
! 3461: <funcdef>babel_handle_update</funcdef>
! 3462: (<type>union babel_msg *</type> <param>m</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- handle incoming route updates
! 3463:
! 3464: <funcsect>Arguments
! 3465: <p><descrip>
! 3466: <tagp><type>union babel_msg *</type> <param>m</param></tagp>
! 3467: Incoming update TLV
! 3468: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3469: Interface the update was received on
! 3470: </descrip>
! 3471: <funcsect>Description
! 3472: <p>
! 3473: This function is called as a handler for update TLVs and handles the updating
! 3474: and maintenance of route entries in Babel's internal routing cache. The
! 3475: handling follows the actions described in the Babel RFC, and at the end of
! 3476: each update handling, <func/babel_select_route()/ is called on the affected entry to
! 3477: optionally update the selected routes and propagate them to the core.
! 3478: </function>
! 3479: <function><p><type>void</type>
! 3480: <funcdef>babel_iface_timer</funcdef>
! 3481: (<type>timer *</type> <param>t</param>) -- Babel interface timer handler
! 3482:
! 3483: <funcsect>Arguments
! 3484: <p><descrip>
! 3485: <tagp><type>timer *</type> <param>t</param></tagp>
! 3486: Timer
! 3487: </descrip>
! 3488: <funcsect>Description
! 3489: <p>
! 3490: This function is called by the per-interface timer and triggers sending of
! 3491: periodic Hello's and both triggered and periodic updates. Periodic Hello's
! 3492: and updates are simply handled by setting the next_{hello,regular} variables
! 3493: on the interface, and triggering an update (and resetting the variable)
! 3494: whenever 'now' exceeds that value.
! 3495: <p>
! 3496: For triggered updates, <func/babel_trigger_iface_update()/ will set the
! 3497: want_triggered field on the interface to a timestamp value. If this is set
! 3498: (and the next_triggered time has passed; this is a rate limiting mechanism),
! 3499: <func/babel_send_update()/ will be called with this timestamp as the second
! 3500: parameter. This causes updates to be send consisting of only the routes that
! 3501: have changed since the time saved in want_triggered.
! 3502: <p>
! 3503: Mostly when an update is triggered, the route being modified will be set to
! 3504: the value of 'now' at the time of the trigger; the >= comparison for
! 3505: selecting which routes to send in the update will make sure this is included.
! 3506: </function>
! 3507: <function><p><type>void</type>
! 3508: <funcdef>babel_timer</funcdef>
! 3509: (<type>timer *</type> <param>t</param>) -- global timer hook
! 3510:
! 3511: <funcsect>Arguments
! 3512: <p><descrip>
! 3513: <tagp><type>timer *</type> <param>t</param></tagp>
! 3514: Timer
! 3515: </descrip>
! 3516: <funcsect>Description
! 3517: <p>
! 3518: This function is called by the global protocol instance timer and handles
! 3519: expiration of routes and neighbours as well as pruning of the seqno request
! 3520: cache.
! 3521: </function>
! 3522: <function><p><type>uint</type>
! 3523: <funcdef>babel_write_queue</funcdef>
! 3524: (<type>struct babel_iface *</type> <param>ifa</param>, <type>list *</type> <param>queue</param>) -- Write a TLV queue to a transmission buffer
! 3525:
! 3526: <funcsect>Arguments
! 3527: <p><descrip>
! 3528: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3529: Interface holding the transmission buffer
! 3530: <tagp><type>list *</type> <param>queue</param></tagp>
! 3531: TLV queue to write (containing internal-format TLVs)
! 3532: </descrip>
! 3533: <funcsect>Description
! 3534: <p>
! 3535: This function writes a packet to the interface transmission buffer with as
! 3536: many TLVs from the <struct/queue/ as will fit in the buffer. It returns the number of
! 3537: bytes written (NOT counting the packet header). The function is called by
! 3538: <func/babel_send_queue()/ and <func/babel_send_unicast()/ to construct packets for
! 3539: transmission, and uses per-TLV helper functions to convert the
! 3540: internal-format TLVs to their wire representations.
! 3541: <p>
! 3542: The TLVs in the queue are freed after they are written to the buffer.
! 3543: </function>
! 3544: <function><p><type>void</type>
! 3545: <funcdef>babel_send_unicast</funcdef>
! 3546: (<type>union babel_msg *</type> <param>msg</param>, <type>struct babel_iface *</type> <param>ifa</param>, <type>ip_addr</type> <param>dest</param>) -- send a single TLV via unicast to a destination
! 3547:
! 3548: <funcsect>Arguments
! 3549: <p><descrip>
! 3550: <tagp><type>union babel_msg *</type> <param>msg</param></tagp>
! 3551: TLV to send
! 3552: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3553: Interface to send via
! 3554: <tagp><type>ip_addr</type> <param>dest</param></tagp>
! 3555: Destination of the TLV
! 3556: </descrip>
! 3557: <funcsect>Description
! 3558: <p>
! 3559: This function is used to send a single TLV via unicast to a designated
! 3560: receiver. This is used for replying to certain incoming requests, and for
! 3561: sending unicast requests to refresh routes before they expire.
! 3562: </function>
! 3563: <function><p><type>void</type>
! 3564: <funcdef>babel_enqueue</funcdef>
! 3565: (<type>union babel_msg *</type> <param>msg</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- enqueue a TLV for transmission on an interface
! 3566:
! 3567: <funcsect>Arguments
! 3568: <p><descrip>
! 3569: <tagp><type>union babel_msg *</type> <param>msg</param></tagp>
! 3570: TLV to enqueue (in internal TLV format)
! 3571: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3572: Interface to enqueue to
! 3573: </descrip>
! 3574: <funcsect>Description
! 3575: <p>
! 3576: This function is called to enqueue a TLV for subsequent transmission on an
! 3577: interface. The transmission event is triggered whenever a TLV is enqueued;
! 3578: this ensures that TLVs will be transmitted in a timely manner, but that TLVs
! 3579: which are enqueued in rapid succession can be transmitted together in one
! 3580: packet.
! 3581: </function>
! 3582: <function><p><type>void</type>
! 3583: <funcdef>babel_process_packet</funcdef>
! 3584: (<type>struct babel_pkt_header *</type> <param>pkt</param>, <type>int</type> <param>len</param>, <type>ip_addr</type> <param>saddr</param>, <type>struct babel_iface *</type> <param>ifa</param>) -- process incoming data packet
! 3585:
! 3586: <funcsect>Arguments
! 3587: <p><descrip>
! 3588: <tagp><type>struct babel_pkt_header *</type> <param>pkt</param></tagp>
! 3589: Pointer to the packet data
! 3590: <tagp><type>int</type> <param>len</param></tagp>
! 3591: Length of received packet
! 3592: <tagp><type>ip_addr</type> <param>saddr</param></tagp>
! 3593: Address of packet sender
! 3594: <tagp><type>struct babel_iface *</type> <param>ifa</param></tagp>
! 3595: Interface packet was received on.
! 3596: </descrip>
! 3597: <funcsect>Description
! 3598: <p>
! 3599: This function is the main processing hook of incoming Babel packets. It
! 3600: checks that the packet header is well-formed, then processes the TLVs
! 3601: contained in the packet. This is done in two passes: First all TLVs are
! 3602: parsed into the internal TLV format. If a TLV parser fails, processing of the
! 3603: rest of the packet is aborted.
! 3604: <p>
! 3605: After the parsing step, the TLV handlers are called for each parsed TLV in
! 3606: order.
! 3607: </function>
! 3608: <sect>Bidirectional Forwarding Detection
! 3609: <p>
! 3610: <p>
! 3611: The BFD protocol is implemented in three files: <tt>bfd.c</tt> containing the
! 3612: protocol logic and the protocol glue with BIRD core, <tt>packets.c</tt> handling BFD
! 3613: packet processing, RX, TX and protocol sockets. <tt>io.c</tt> then contains generic
! 3614: code for the event loop, threads and event sources (sockets, microsecond
! 3615: timers). This generic code will be merged to the main BIRD I/O code in the
! 3616: future.
! 3617: <p>
! 3618: The BFD implementation uses a separate thread with an internal event loop for
! 3619: handling the protocol logic, which requires high-res and low-latency timing,
! 3620: so it is not affected by the rest of BIRD, which has several low-granularity
! 3621: hooks in the main loop, uses second-based timers and cannot offer good
! 3622: latency. The core of BFD protocol (the code related to BFD sessions,
! 3623: interfaces and packets) runs in the BFD thread, while the rest (the code
! 3624: related to BFD requests, BFD neighbors and the protocol glue) runs in the
! 3625: main thread.
! 3626: <p>
! 3627: BFD sessions are represented by structure <struct/bfd_session/ that contains a state
! 3628: related to the session and two timers (TX timer for periodic packets and hold
! 3629: timer for session timeout). These sessions are allocated from <param/session_slab/
! 3630: and are accessible by two hash tables, <param/session_hash_id/ (by session ID) and
! 3631: <param/session_hash_ip/ (by IP addresses of neighbors). Slab and both hashes are in
! 3632: the main protocol structure <struct/bfd_proto/. The protocol logic related to BFD
! 3633: sessions is implemented in internal functions bfd_session_*(), which are
! 3634: expected to be called from the context of BFD thread, and external functions
! 3635: <func/bfd_add_session()/, <func/bfd_remove_session()/ and <func/bfd_reconfigure_session()/, which
! 3636: form an interface to the BFD core for the rest and are expected to be called
! 3637: from the context of main thread.
! 3638: <p>
! 3639: Each BFD session has an associated BFD interface, represented by structure
! 3640: <struct/bfd_iface/. A BFD interface contains a socket used for TX (the one for RX is
! 3641: shared in <struct/bfd_proto/), an interface configuration and reference counter.
! 3642: Compared to interface structures of other protocols, these structures are not
! 3643: created and removed based on interface notification events, but according to
! 3644: the needs of BFD sessions. When a new session is created, it requests a
! 3645: proper BFD interface by function <func/bfd_get_iface()/, which either finds an
! 3646: existing one in <struct/iface_list/ (from <struct/bfd_proto/) or allocates a new one. When a
! 3647: session is removed, an associated iface is discharged by <func/bfd_free_iface()/.
! 3648: <p>
! 3649: BFD requests are the external API for the other protocols. When a protocol
! 3650: wants a BFD session, it calls <func/bfd_request_session()/, which creates a
! 3651: structure <struct/bfd_request/ containing approprite information and an notify hook.
! 3652: This structure is a resource associated with the caller's resource pool. When
! 3653: a BFD protocol is available, a BFD request is submitted to the protocol, an
! 3654: appropriate BFD session is found or created and the request is attached to
! 3655: the session. When a session changes state, all attached requests (and related
! 3656: protocols) are notified. Note that BFD requests do not depend on BFD protocol
! 3657: running. When the BFD protocol is stopped or removed (or not available from
! 3658: beginning), related BFD requests are stored in <param/bfd_wait_list/, where waits
! 3659: for a new protocol.
! 3660: <p>
! 3661: BFD neighbors are just a way to statically configure BFD sessions without
! 3662: requests from other protocol. Structures <struct/bfd_neighbor/ are part of BFD
! 3663: configuration (like static routes in the static protocol). BFD neighbors are
! 3664: handled by BFD protocol like it is a BFD client -- when a BFD neighbor is
! 3665: ready, the protocol just creates a BFD request like any other protocol.
! 3666: <p>
! 3667: The protocol uses a new generic event loop (structure <struct/birdloop/) from <tt>io.c</tt>,
! 3668: which supports sockets, timers and events like the main loop. Timers
! 3669: (structure <struct/timer2/) are new microsecond based timers, while sockets and
! 3670: events are the same. A birdloop is associated with a thread (field <param/thread/)
! 3671: in which event hooks are executed. Most functions for setting event sources
! 3672: (like <func/sk_start()/ or <func/tm2_start()/) must be called from the context of that
! 3673: thread. Birdloop allows to temporarily acquire the context of that thread for
! 3674: the main thread by calling <func/birdloop_enter()/ and then <func/birdloop_leave()/, which
! 3675: also ensures mutual exclusion with all event hooks. Note that resources
! 3676: associated with a birdloop (like timers) should be attached to the
! 3677: independent resource pool, detached from the main resource tree.
! 3678: <p>
! 3679: There are two kinds of interaction between the BFD core (running in the BFD
! 3680: thread) and the rest of BFD (running in the main thread). The first kind are
! 3681: configuration calls from main thread to the BFD thread (like <func/bfd_add_session()/).
! 3682: These calls are synchronous and use <func/birdloop_enter()/ mechanism for mutual
! 3683: exclusion. The second kind is a notification about session changes from the
! 3684: BFD thread to the main thread. This is done in an asynchronous way, sesions
! 3685: with pending notifications are linked (in the BFD thread) to <param/notify_list/ in
! 3686: <struct/bfd_proto/, and then <func/bfd_notify_hook()/ in the main thread is activated using
! 3687: <func/bfd_notify_kick()/ and a pipe. The hook then processes scheduled sessions and
! 3688: calls hooks from associated BFD requests. This <param/notify_list/ (and state fields
! 3689: in structure <struct/bfd_session/) is protected by a spinlock in <struct/bfd_proto/ and
! 3690: functions <func/bfd_lock_sessions()/ / <func/bfd_unlock_sessions()/.
! 3691: <p>
! 3692: There are few data races (accessing <param/p/->p.debug from <func/TRACE()/ from the BFD
! 3693: thread and accessing some some private fields of <const/bfd_session/ from
! 3694: <func/bfd_show_sessions()/ from the main thread, but these are harmless (i hope).
! 3695: <p>
! 3696: TODO: document functions and access restrictions for fields in BFD structures.
! 3697: <p>
! 3698: Supported standards:
! 3699: - RFC 5880 - main BFD standard
! 3700: - RFC 5881 - BFD for IP links
! 3701: - RFC 5882 - generic application of BFD
! 3702: - RFC 5883 - BFD for multihop paths
! 3703:
! 3704:
! 3705: <sect>Border Gateway Protocol
! 3706: <p>
! 3707: <p>
! 3708: The BGP protocol is implemented in three parts: <tt>bgp.c</tt> which takes care of the
! 3709: connection and most of the interface with BIRD core, <tt>packets.c</tt> handling
! 3710: both incoming and outgoing BGP packets and <tt>attrs.c</tt> containing functions for
! 3711: manipulation with BGP attribute lists.
! 3712: <p>
! 3713: As opposed to the other existing routing daemons, BIRD has a sophisticated core
! 3714: architecture which is able to keep all the information needed by BGP in the
! 3715: primary routing table, therefore no complex data structures like a central
! 3716: BGP table are needed. This increases memory footprint of a BGP router with
! 3717: many connections, but not too much and, which is more important, it makes
! 3718: BGP much easier to implement.
! 3719: <p>
! 3720: Each instance of BGP (corresponding to a single BGP peer) is described by a <struct/bgp_proto/
! 3721: structure to which are attached individual connections represented by <struct/bgp_connection/
! 3722: (usually, there exists only one connection, but during BGP session setup, there
! 3723: can be more of them). The connections are handled according to the BGP state machine
! 3724: defined in the RFC with all the timers and all the parameters configurable.
! 3725: <p>
! 3726: In incoming direction, we listen on the connection's socket and each time we receive
! 3727: some input, we pass it to <func/bgp_rx()/. It decodes packet headers and the markers and
! 3728: passes complete packets to <func/bgp_rx_packet()/ which distributes the packet according
! 3729: to its type.
! 3730: <p>
! 3731: In outgoing direction, we gather all the routing updates and sort them to buckets
! 3732: (<struct/bgp_bucket/) according to their attributes (we keep a hash table for fast comparison
! 3733: of <struct/rta/'s and a <struct/fib/ which helps us to find if we already have another route for
! 3734: the same destination queued for sending, so that we can replace it with the new one
! 3735: immediately instead of sending both updates). There also exists a special bucket holding
! 3736: all the route withdrawals which cannot be queued anywhere else as they don't have any
! 3737: attributes. If we have any packet to send (due to either new routes or the connection
! 3738: tracking code wanting to send a Open, Keepalive or Notification message), we call
! 3739: <func/bgp_schedule_packet()/ which sets the corresponding bit in a <param/packet_to_send/
! 3740: bit field in <struct/bgp_conn/ and as soon as the transmit socket buffer becomes empty,
! 3741: we call <func/bgp_fire_tx()/. It inspects state of all the packet type bits and calls
! 3742: the corresponding <func/bgp_create_xx()/ functions, eventually rescheduling the same packet
! 3743: type if we have more data of the same type to send.
! 3744: <p>
! 3745: The processing of attributes consists of two functions: <func/bgp_decode_attrs()/ for checking
! 3746: of the attribute blocks and translating them to the language of BIRD's extended attributes
! 3747: and <func/bgp_encode_attrs()/ which does the converse. Both functions are built around a
! 3748: <param/bgp_attr_table/ array describing all important characteristics of all known attributes.
! 3749: Unknown transitive attributes are attached to the route as <const/EAF_TYPE_OPAQUE/ byte streams.
! 3750: <p>
! 3751: BGP protocol implements graceful restart in both restarting (local restart)
! 3752: and receiving (neighbor restart) roles. The first is handled mostly by the
! 3753: graceful restart code in the nest, BGP protocol just handles capabilities,
! 3754: sets <param/gr_wait/ and locks graceful restart until end-of-RIB mark is received.
! 3755: The second is implemented by internal restart of the BGP state to <const/BS_IDLE/
! 3756: and protocol state to <const/PS_START/, but keeping the protocol up from the core
! 3757: point of view and therefore maintaining received routes. Routing table
! 3758: refresh cycle (<func/rt_refresh_begin()/, <func/rt_refresh_end()/) is used for removing
! 3759: stale routes after reestablishment of BGP session during graceful restart.
! 3760:
! 3761:
! 3762: <function><p><type>int</type>
! 3763: <funcdef>bgp_open</funcdef>
! 3764: (<type>struct bgp_proto *</type> <param>p</param>) -- open a BGP instance
! 3765:
! 3766: <funcsect>Arguments
! 3767: <p><descrip>
! 3768: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3769: BGP instance
! 3770: </descrip>
! 3771: <funcsect>Description
! 3772: <p>
! 3773: This function allocates and configures shared BGP resources.
! 3774: Should be called as the last step during initialization
! 3775: (when lock is acquired and neighbor is ready).
! 3776: When error, state changed to PS_DOWN, -1 is returned and caller
! 3777: should return immediately.
! 3778: </function>
! 3779: <function><p><type>void</type>
! 3780: <funcdef>bgp_close</funcdef>
! 3781: (<type>struct bgp_proto *</type> <param>p</param>, <type>int</type> <param>apply_md5</param>) -- close a BGP instance
! 3782:
! 3783: <funcsect>Arguments
! 3784: <p><descrip>
! 3785: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3786: BGP instance
! 3787: <tagp><type>int</type> <param>apply_md5</param></tagp>
! 3788: 0 to disable unsetting MD5 auth
! 3789: </descrip>
! 3790: <funcsect>Description
! 3791: <p>
! 3792: This function frees and deconfigures shared BGP resources.
! 3793: <param/apply_md5/ is set to 0 when bgp_close is called as a cleanup
! 3794: from failed <func/bgp_open()/.
! 3795: </function>
! 3796: <function><p><type>void</type>
! 3797: <funcdef>bgp_start_timer</funcdef>
! 3798: (<type>timer *</type> <param>t</param>, <type>int</type> <param>value</param>) -- start a BGP timer
! 3799:
! 3800: <funcsect>Arguments
! 3801: <p><descrip>
! 3802: <tagp><type>timer *</type> <param>t</param></tagp>
! 3803: timer
! 3804: <tagp><type>int</type> <param>value</param></tagp>
! 3805: time to fire (0 to disable the timer)
! 3806: </descrip>
! 3807: <funcsect>Description
! 3808: <p>
! 3809: This functions calls <func/tm_start()/ on <param/t/ with time <param/value/ and the
! 3810: amount of randomization suggested by the BGP standard. Please use
! 3811: it for all BGP timers.
! 3812: </function>
! 3813: <function><p><type>void</type>
! 3814: <funcdef>bgp_close_conn</funcdef>
! 3815: (<type>struct bgp_conn *</type> <param>conn</param>) -- close a BGP connection
! 3816:
! 3817: <funcsect>Arguments
! 3818: <p><descrip>
! 3819: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
! 3820: connection to close
! 3821: </descrip>
! 3822: <funcsect>Description
! 3823: <p>
! 3824: This function takes a connection described by the <struct/bgp_conn/ structure,
! 3825: closes its socket and frees all resources associated with it.
! 3826: </function>
! 3827: <function><p><type>void</type>
! 3828: <funcdef>bgp_update_startup_delay</funcdef>
! 3829: (<type>struct bgp_proto *</type> <param>p</param>) -- update a startup delay
! 3830:
! 3831: <funcsect>Arguments
! 3832: <p><descrip>
! 3833: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3834: BGP instance
! 3835: </descrip>
! 3836: <funcsect>Description
! 3837: <p>
! 3838: This function updates a startup delay that is used to postpone next BGP connect.
! 3839: It also handles disable_after_error and might stop BGP instance when error
! 3840: happened and disable_after_error is on.
! 3841: <p>
! 3842: It should be called when BGP protocol error happened.
! 3843: </function>
! 3844: <function><p><type>void</type>
! 3845: <funcdef>bgp_handle_graceful_restart</funcdef>
! 3846: (<type>struct bgp_proto *</type> <param>p</param>) -- handle detected BGP graceful restart
! 3847:
! 3848: <funcsect>Arguments
! 3849: <p><descrip>
! 3850: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3851: BGP instance
! 3852: </descrip>
! 3853: <funcsect>Description
! 3854: <p>
! 3855: This function is called when a BGP graceful restart of the neighbor is
! 3856: detected (when the TCP connection fails or when a new TCP connection
! 3857: appears). The function activates processing of the restart - starts routing
! 3858: table refresh cycle and activates BGP restart timer. The protocol state goes
! 3859: back to <const/PS_START/, but changing BGP state back to <const/BS_IDLE/ is left for the
! 3860: caller.
! 3861: </function>
! 3862: <function><p><type>void</type>
! 3863: <funcdef>bgp_graceful_restart_done</funcdef>
! 3864: (<type>struct bgp_proto *</type> <param>p</param>) -- finish active BGP graceful restart
! 3865:
! 3866: <funcsect>Arguments
! 3867: <p><descrip>
! 3868: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3869: BGP instance
! 3870: </descrip>
! 3871: <funcsect>Description
! 3872: <p>
! 3873: This function is called when the active BGP graceful restart of the neighbor
! 3874: should be finished - either successfully (the neighbor sends all paths and
! 3875: reports end-of-RIB on the new session) or unsuccessfully (the neighbor does
! 3876: not support BGP graceful restart on the new session). The function ends
! 3877: routing table refresh cycle and stops BGP restart timer.
! 3878: </function>
! 3879: <function><p><type>void</type>
! 3880: <funcdef>bgp_graceful_restart_timeout</funcdef>
! 3881: (<type>timer *</type> <param>t</param>) -- timeout of graceful restart 'restart timer'
! 3882:
! 3883: <funcsect>Arguments
! 3884: <p><descrip>
! 3885: <tagp><type>timer *</type> <param>t</param></tagp>
! 3886: timer
! 3887: </descrip>
! 3888: <funcsect>Description
! 3889: <p>
! 3890: This function is a timeout hook for <param/gr_timer/, implementing BGP restart time
! 3891: limit for reestablisment of the BGP session after the graceful restart. When
! 3892: fired, we just proceed with the usual protocol restart.
! 3893: </function>
! 3894: <function><p><type>void</type>
! 3895: <funcdef>bgp_refresh_begin</funcdef>
! 3896: (<type>struct bgp_proto *</type> <param>p</param>) -- start incoming enhanced route refresh sequence
! 3897:
! 3898: <funcsect>Arguments
! 3899: <p><descrip>
! 3900: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3901: BGP instance
! 3902: </descrip>
! 3903: <funcsect>Description
! 3904: <p>
! 3905: This function is called when an incoming enhanced route refresh sequence is
! 3906: started by the neighbor, demarcated by the BoRR packet. The function updates
! 3907: the load state and starts the routing table refresh cycle. Note that graceful
! 3908: restart also uses routing table refresh cycle, but RFC 7313 and load states
! 3909: ensure that these two sequences do not overlap.
! 3910: </function>
! 3911: <function><p><type>void</type>
! 3912: <funcdef>bgp_refresh_end</funcdef>
! 3913: (<type>struct bgp_proto *</type> <param>p</param>) -- finish incoming enhanced route refresh sequence
! 3914:
! 3915: <funcsect>Arguments
! 3916: <p><descrip>
! 3917: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3918: BGP instance
! 3919: </descrip>
! 3920: <funcsect>Description
! 3921: <p>
! 3922: This function is called when an incoming enhanced route refresh sequence is
! 3923: finished by the neighbor, demarcated by the EoRR packet. The function updates
! 3924: the load state and ends the routing table refresh cycle. Routes not received
! 3925: during the sequence are removed by the nest.
! 3926: </function>
! 3927: <function><p><type>void</type>
! 3928: <funcdef>bgp_connect</funcdef>
! 3929: (<type>struct bgp_proto *</type> <param>p</param>) -- initiate an outgoing connection
! 3930:
! 3931: <funcsect>Arguments
! 3932: <p><descrip>
! 3933: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 3934: BGP instance
! 3935: </descrip>
! 3936: <funcsect>Description
! 3937: <p>
! 3938: The <func/bgp_connect()/ function creates a new <struct/bgp_conn/ and initiates
! 3939: a TCP connection to the peer. The rest of connection setup is governed
! 3940: by the BGP state machine as described in the standard.
! 3941: </function>
! 3942: <function><p><type>struct bgp_proto *</type>
! 3943: <funcdef>bgp_find_proto</funcdef>
! 3944: (<type>sock *</type> <param>sk</param>) -- find existing proto for incoming connection
! 3945:
! 3946: <funcsect>Arguments
! 3947: <p><descrip>
! 3948: <tagp><type>sock *</type> <param>sk</param></tagp>
! 3949: TCP socket
! 3950: </descrip>
! 3951: </function>
! 3952: <function><p><type>int</type>
! 3953: <funcdef>bgp_incoming_connection</funcdef>
! 3954: (<type>sock *</type> <param>sk</param>, <type>uint dummy</type> <param>UNUSED</param>) -- handle an incoming connection
! 3955:
! 3956: <funcsect>Arguments
! 3957: <p><descrip>
! 3958: <tagp><type>sock *</type> <param>sk</param></tagp>
! 3959: TCP socket
! 3960: <tagp><type>uint dummy</type> <param>UNUSED</param></tagp>
! 3961: -- undescribed --
! 3962: </descrip>
! 3963: <funcsect>Description
! 3964: <p>
! 3965: This function serves as a socket hook for accepting of new BGP
! 3966: connections. It searches a BGP instance corresponding to the peer
! 3967: which has connected and if such an instance exists, it creates a
! 3968: <struct/bgp_conn/ structure, attaches it to the instance and either sends
! 3969: an Open message or (if there already is an active connection) it
! 3970: closes the new connection by sending a Notification message.
! 3971: </function>
! 3972: <function><p><type>void</type>
! 3973: <funcdef>bgp_error</funcdef>
! 3974: (<type>struct bgp_conn *</type> <param>c</param>, <type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>, <type>byte *</type> <param>data</param>, <type>int</type> <param>len</param>) -- report a protocol error
! 3975:
! 3976: <funcsect>Arguments
! 3977: <p><descrip>
! 3978: <tagp><type>struct bgp_conn *</type> <param>c</param></tagp>
! 3979: connection
! 3980: <tagp><type>unsigned</type> <param>code</param></tagp>
! 3981: error code (according to the RFC)
! 3982: <tagp><type>unsigned</type> <param>subcode</param></tagp>
! 3983: error sub-code
! 3984: <tagp><type>byte *</type> <param>data</param></tagp>
! 3985: data to be passed in the Notification message
! 3986: <tagp><type>int</type> <param>len</param></tagp>
! 3987: length of the data
! 3988: </descrip>
! 3989: <funcsect>Description
! 3990: <p>
! 3991: <func/bgp_error()/ sends a notification packet to tell the other side that a protocol
! 3992: error has occurred (including the data considered erroneous if possible) and
! 3993: closes the connection.
! 3994: </function>
! 3995: <function><p><type>void</type>
! 3996: <funcdef>bgp_store_error</funcdef>
! 3997: (<type>struct bgp_proto *</type> <param>p</param>, <type>struct bgp_conn *</type> <param>c</param>, <type>u8</type> <param>class</param>, <type>u32</type> <param>code</param>) -- store last error for status report
! 3998:
! 3999: <funcsect>Arguments
! 4000: <p><descrip>
! 4001: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 4002: BGP instance
! 4003: <tagp><type>struct bgp_conn *</type> <param>c</param></tagp>
! 4004: connection
! 4005: <tagp><type>u8</type> <param>class</param></tagp>
! 4006: error class (BE_xxx constants)
! 4007: <tagp><type>u32</type> <param>code</param></tagp>
! 4008: error code (class specific)
! 4009: </descrip>
! 4010: <funcsect>Description
! 4011: <p>
! 4012: <func/bgp_store_error()/ decides whether given error is interesting enough
! 4013: and store that error to last_error variables of <param/p/
! 4014: </function>
! 4015: <function><p><type>int</type>
! 4016: <funcdef>bgp_fire_tx</funcdef>
! 4017: (<type>struct bgp_conn *</type> <param>conn</param>) -- transmit packets
! 4018:
! 4019: <funcsect>Arguments
! 4020: <p><descrip>
! 4021: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
! 4022: connection
! 4023: </descrip>
! 4024: <funcsect>Description
! 4025: <p>
! 4026: Whenever the transmit buffers of the underlying TCP connection
! 4027: are free and we have any packets queued for sending, the socket functions
! 4028: call <func/bgp_fire_tx()/ which takes care of selecting the highest priority packet
! 4029: queued (Notification > Keepalive > Open > Update), assembling its header
! 4030: and body and sending it to the connection.
! 4031: </function>
! 4032: <function><p><type>void</type>
! 4033: <funcdef>bgp_schedule_packet</funcdef>
! 4034: (<type>struct bgp_conn *</type> <param>conn</param>, <type>int</type> <param>type</param>) -- schedule a packet for transmission
! 4035:
! 4036: <funcsect>Arguments
! 4037: <p><descrip>
! 4038: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
! 4039: connection
! 4040: <tagp><type>int</type> <param>type</param></tagp>
! 4041: packet type
! 4042: </descrip>
! 4043: <funcsect>Description
! 4044: <p>
! 4045: Schedule a packet of type <param/type/ to be sent as soon as possible.
! 4046: </function>
! 4047: <function><p><type>const char *</type>
! 4048: <funcdef>bgp_error_dsc</funcdef>
! 4049: (<type>unsigned</type> <param>code</param>, <type>unsigned</type> <param>subcode</param>) -- return BGP error description
! 4050:
! 4051: <funcsect>Arguments
! 4052: <p><descrip>
! 4053: <tagp><type>unsigned</type> <param>code</param></tagp>
! 4054: BGP error code
! 4055: <tagp><type>unsigned</type> <param>subcode</param></tagp>
! 4056: BGP error subcode
! 4057: </descrip>
! 4058: <funcsect>Description
! 4059: <p>
! 4060: <func/bgp_error_dsc()/ returns error description for BGP errors
! 4061: which might be static string or given temporary buffer.
! 4062: </function>
! 4063: <function><p><type>void</type>
! 4064: <funcdef>bgp_rx_packet</funcdef>
! 4065: (<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>pkt</param>, <type>unsigned</type> <param>len</param>) -- handle a received packet
! 4066:
! 4067: <funcsect>Arguments
! 4068: <p><descrip>
! 4069: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
! 4070: BGP connection
! 4071: <tagp><type>byte *</type> <param>pkt</param></tagp>
! 4072: start of the packet
! 4073: <tagp><type>unsigned</type> <param>len</param></tagp>
! 4074: packet size
! 4075: </descrip>
! 4076: <funcsect>Description
! 4077: <p>
! 4078: <func/bgp_rx_packet()/ takes a newly received packet and calls the corresponding
! 4079: packet handler according to the packet type.
! 4080: </function>
! 4081: <function><p><type>int</type>
! 4082: <funcdef>bgp_rx</funcdef>
! 4083: (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>size</param>) -- handle received data
! 4084:
! 4085: <funcsect>Arguments
! 4086: <p><descrip>
! 4087: <tagp><type>sock *</type> <param>sk</param></tagp>
! 4088: socket
! 4089: <tagp><type>uint</type> <param>size</param></tagp>
! 4090: amount of data received
! 4091: </descrip>
! 4092: <funcsect>Description
! 4093: <p>
! 4094: <func/bgp_rx()/ is called by the socket layer whenever new data arrive from
! 4095: the underlying TCP connection. It assembles the data fragments to packets,
! 4096: checks their headers and framing and passes complete packets to
! 4097: <func/bgp_rx_packet()/.
! 4098: </function>
! 4099: <function><p><type>uint</type>
! 4100: <funcdef>bgp_encode_attrs</funcdef>
! 4101: (<type>struct bgp_proto *</type> <param>p</param>, <type>byte *</type> <param>w</param>, <type>ea_list *</type> <param>attrs</param>, <type>int</type> <param>remains</param>) -- encode BGP attributes
! 4102:
! 4103: <funcsect>Arguments
! 4104: <p><descrip>
! 4105: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp>
! 4106: BGP instance (or NULL)
! 4107: <tagp><type>byte *</type> <param>w</param></tagp>
! 4108: buffer
! 4109: <tagp><type>ea_list *</type> <param>attrs</param></tagp>
! 4110: a list of extended attributes
! 4111: <tagp><type>int</type> <param>remains</param></tagp>
! 4112: remaining space in the buffer
! 4113: </descrip>
! 4114: <funcsect>Description
! 4115: <p>
! 4116: The <func/bgp_encode_attrs()/ function takes a list of extended attributes
! 4117: and converts it to its BGP representation (a part of an Update message).
! 4118: <funcsect>Result
! 4119: <p>
! 4120: Length of the attribute block generated or -1 if not enough space.
! 4121: </function>
! 4122: <function><p><type>struct rta *</type>
! 4123: <funcdef>bgp_decode_attrs</funcdef>
! 4124: (<type>struct bgp_conn *</type> <param>conn</param>, <type>byte *</type> <param>attr</param>, <type>uint</type> <param>len</param>, <type>struct linpool *</type> <param>pool</param>, <type>int</type> <param>mandatory</param>) -- check and decode BGP attributes
! 4125:
! 4126: <funcsect>Arguments
! 4127: <p><descrip>
! 4128: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp>
! 4129: connection
! 4130: <tagp><type>byte *</type> <param>attr</param></tagp>
! 4131: start of attribute block
! 4132: <tagp><type>uint</type> <param>len</param></tagp>
! 4133: length of attribute block
! 4134: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
! 4135: linear pool to make all the allocations in
! 4136: <tagp><type>int</type> <param>mandatory</param></tagp>
! 4137: 1 iff presence of mandatory attributes has to be checked
! 4138: </descrip>
! 4139: <funcsect>Description
! 4140: <p>
! 4141: This function takes a BGP attribute block (a part of an Update message), checks
! 4142: its consistency and converts it to a list of BIRD route attributes represented
! 4143: by a <struct/rta/.
! 4144: </function>
! 4145: <sect>Multi-Threaded Routing Toolkit (MRT) protocol
! 4146: <p>
! 4147: <p>
! 4148: The MRT protocol is implemented in just one file: <tt>mrt.c</tt>. It contains of
! 4149: several parts: Generic functions for preparing MRT messages in a buffer,
! 4150: functions for MRT table dump (called from timer or CLI), functions for MRT
! 4151: BGP4MP dump (called from BGP), and the usual protocol glue. For the MRT table
! 4152: dump, the key structure is struct mrt_table_dump_state, which contains all
! 4153: necessary data and created when the MRT dump cycle is started for the
! 4154: duration of the MRT dump. The MBGP4MP dump is currently not bound to MRT
! 4155: protocol instance and uses the config->mrtdump_file fd.
! 4156: <p>
! 4157: The protocol is simple, just periodically scans routing table and export it
! 4158: to a file. It does not use the regular update mechanism, but a direct access
! 4159: in order to handle iteration through multiple routing tables. The table dump
! 4160: needs to dump all peers first and then use indexes to address the peers, we
! 4161: use a hash table (<param/peer_hash/) to find peer index based on BGP protocol key
! 4162: attributes.
! 4163: <p>
! 4164: One thing worth documenting is the locking. During processing, the currently
! 4165: processed table (<param/table/ field in the state structure) is locked and also the
! 4166: explicitly named table is locked (<param/table_ptr/ field in the state structure) if
! 4167: specified. Between dumps no table is locked. Also the current config is
! 4168: locked (by <func/config_add_obstacle()/) during table dumps as some data (strings,
! 4169: filters) are shared from the config and the running table dump may be
! 4170: interrupted by reconfiguration.
! 4171: <p>
! 4172: Supported standards:
! 4173: - RFC 6396 - MRT format standard
! 4174: - RFC 8050 - ADD_PATH extension
! 4175:
! 4176:
! 4177: <sect>Open Shortest Path First (OSPF)
! 4178: <p>
! 4179: <p>
! 4180: The OSPF protocol is quite complicated and its complex implemenation is split
! 4181: to many files. In <tt>ospf.c</tt>, you will find mainly the interface for
! 4182: communication with the core (e.g., reconfiguration hooks, shutdown and
! 4183: initialisation and so on). File <tt>iface.c</tt> contains the interface state
! 4184: machine and functions for allocation and deallocation of OSPF's interface
! 4185: data structures. Source <tt>neighbor.c</tt> includes the neighbor state machine and
! 4186: functions for election of Designated Router and Backup Designated router. In
! 4187: <tt>packet.c</tt>, you will find various functions for sending and receiving generic
! 4188: OSPF packets. There are also routines for authentication and checksumming.
! 4189: In <tt>hello.c</tt>, there are routines for sending and receiving of hello packets
! 4190: as well as functions for maintaining wait times and the inactivity timer.
! 4191: Files <tt>lsreq.c</tt>, <tt>lsack.c</tt>, <tt>dbdes.c</tt> contain functions for sending and
! 4192: receiving of link-state requests, link-state acknowledgements and database
! 4193: descriptions respectively. In <tt>lsupd.c</tt>, there are functions for sending and
! 4194: receiving of link-state updates and also the flooding algorithm. Source
! 4195: <tt>topology.c</tt> is a place where routines for searching LSAs in the link-state
! 4196: database, adding and deleting them reside, there also are functions for
! 4197: originating of various types of LSAs (router LSA, net LSA, external LSA).
! 4198: File <tt>rt.c</tt> contains routines for calculating the routing table. <tt>lsalib.c</tt>
! 4199: is a set of various functions for working with the LSAs (endianity
! 4200: conversions, calculation of checksum etc.).
! 4201: <p>
! 4202: One instance of the protocol is able to hold LSA databases for multiple OSPF
! 4203: areas, to exchange routing information between multiple neighbors and to
! 4204: calculate the routing tables. The core structure is <struct/ospf_proto/ to which
! 4205: multiple <struct/ospf_area/ and <struct/ospf_iface/ structures are connected. <struct/ospf_proto/ is
! 4206: also connected to <struct/top_hash_graph/ which is a dynamic hashing structure that
! 4207: describes the link-state database. It allows fast search, addition and
! 4208: deletion. Each LSA is kept in two pieces: header and body. Both of them are
! 4209: kept in the endianity of the CPU.
! 4210: <p>
! 4211: In OSPFv2 specification, it is implied that there is one IP prefix for each
! 4212: physical network/interface (unless it is an ptp link). But in modern systems,
! 4213: there might be more independent IP prefixes associated with an interface. To
! 4214: handle this situation, we have one <struct/ospf_iface/ for each active IP prefix
! 4215: (instead for each active iface); This behaves like virtual interface for the
! 4216: purpose of OSPF. If we receive packet, we associate it with a proper virtual
! 4217: interface mainly according to its source address.
! 4218: <p>
! 4219: OSPF keeps one socket per <struct/ospf_iface/. This allows us (compared to one socket
! 4220: approach) to evade problems with a limit of multicast groups per socket and
! 4221: with sending multicast packets to appropriate interface in a portable way.
! 4222: The socket is associated with underlying physical iface and should not
! 4223: receive packets received on other ifaces (unfortunately, this is not true on
! 4224: BSD). Generally, one packet can be received by more sockets (for example, if
! 4225: there are more <struct/ospf_iface/ on one physical iface), therefore we explicitly
! 4226: filter received packets according to src/dst IP address and received iface.
! 4227: <p>
! 4228: Vlinks are implemented using particularly degenerate form of <struct/ospf_iface/,
! 4229: which has several exceptions: it does not have its iface or socket (it copies
! 4230: these from 'parent' <struct/ospf_iface/) and it is present in iface list even when
! 4231: down (it is not freed in <func/ospf_iface_down()/).
! 4232: <p>
! 4233: The heart beat of ospf is <func/ospf_disp()/. It is called at regular intervals
! 4234: (<struct/ospf_proto/->tick). It is responsible for aging and flushing of LSAs in the
! 4235: database, updating topology information in LSAs and for routing table
! 4236: calculation.
! 4237: <p>
! 4238: To every <struct/ospf_iface/, we connect one or more <struct/ospf_neighbor/'s -- a structure
! 4239: containing many timers and queues for building adjacency and for exchange of
! 4240: routing messages.
! 4241: <p>
! 4242: BIRD's OSPF implementation respects RFC2328 in every detail, but some of
! 4243: internal algorithms do differ. The RFC recommends making a snapshot of the
! 4244: link-state database when a new adjacency is forming and sending the database
! 4245: description packets based on the information in this snapshot. The database
! 4246: can be quite large in some networks, so rather we walk through a <struct/slist/
! 4247: structure which allows us to continue even if the actual LSA we were working
! 4248: with is deleted. New LSAs are added at the tail of this <struct/slist/.
! 4249: <p>
! 4250: We also do not keep a separate OSPF routing table, because the core helps us
! 4251: by being able to recognize when a route is updated to an identical one and it
! 4252: suppresses the update automatically. Due to this, we can flush all the routes
! 4253: we have recalculated and also those we have deleted to the core's routing
! 4254: table and the core will take care of the rest. This simplifies the process
! 4255: and conserves memory.
! 4256: <p>
! 4257: Supported standards:
! 4258: - RFC 2328 - main OSPFv2 standard
! 4259: - RFC 5340 - main OSPFv3 standard
! 4260: - RFC 3101 - OSPFv2 NSSA areas
! 4261: - RFC 6549 - OSPFv2 multi-instance extensions
! 4262: - RFC 6987 - OSPF stub router advertisement
! 4263:
! 4264:
! 4265: <function><p><type>void</type>
! 4266: <funcdef>ospf_disp</funcdef>
! 4267: (<type>timer *</type> <param>timer</param>) -- invokes routing table calculation, aging and also <func/area_disp()/
! 4268:
! 4269: <funcsect>Arguments
! 4270: <p><descrip>
! 4271: <tagp><type>timer *</type> <param>timer</param></tagp>
! 4272: timer usually called every <param/ospf_proto/->tick second, <param/timer/->data
! 4273: point to <param/ospf_proto/
! 4274: </descrip>
! 4275: </function>
! 4276: <function><p><type>int</type>
! 4277: <funcdef>ospf_import_control</funcdef>
! 4278: (<type>struct proto *</type> <param>P</param>, <type>rte **</type> <param>new</param>, <type>ea_list **</type> <param>attrs</param>, <type>struct linpool *</type> <param>pool</param>) -- accept or reject new route from nest's routing table
! 4279:
! 4280: <funcsect>Arguments
! 4281: <p><descrip>
! 4282: <tagp><type>struct proto *</type> <param>P</param></tagp>
! 4283: OSPF protocol instance
! 4284: <tagp><type>rte **</type> <param>new</param></tagp>
! 4285: the new route
! 4286: <tagp><type>ea_list **</type> <param>attrs</param></tagp>
! 4287: list of attributes
! 4288: <tagp><type>struct linpool *</type> <param>pool</param></tagp>
! 4289: pool for allocation of attributes
! 4290: </descrip>
! 4291: <funcsect>Description
! 4292: <p>
! 4293: Its quite simple. It does not accept our own routes and leaves the decision on
! 4294: import to the filters.
! 4295: </function>
! 4296: <function><p><type>int</type>
! 4297: <funcdef>ospf_shutdown</funcdef>
! 4298: (<type>struct proto *</type> <param>P</param>) -- Finish of OSPF instance
! 4299:
! 4300: <funcsect>Arguments
! 4301: <p><descrip>
! 4302: <tagp><type>struct proto *</type> <param>P</param></tagp>
! 4303: OSPF protocol instance
! 4304: </descrip>
! 4305: <funcsect>Description
! 4306: <p>
! 4307: RFC does not define any action that should be taken before router
! 4308: shutdown. To make my neighbors react as fast as possible, I send
! 4309: them hello packet with empty neighbor list. They should start
! 4310: their neighbor state machine with event <const/NEIGHBOR_1WAY/.
! 4311: </function>
! 4312: <function><p><type>int</type>
! 4313: <funcdef>ospf_reconfigure</funcdef>
! 4314: (<type>struct proto *</type> <param>P</param>, <type>struct proto_config *</type> <param>c</param>) -- reconfiguration hook
! 4315:
! 4316: <funcsect>Arguments
! 4317: <p><descrip>
! 4318: <tagp><type>struct proto *</type> <param>P</param></tagp>
! 4319: current instance of protocol (with old configuration)
! 4320: <tagp><type>struct proto_config *</type> <param>c</param></tagp>
! 4321: new configuration requested by user
! 4322: </descrip>
! 4323: <funcsect>Description
! 4324: <p>
! 4325: This hook tries to be a little bit intelligent. Instance of OSPF
! 4326: will survive change of many constants like hello interval,
! 4327: password change, addition or deletion of some neighbor on
! 4328: nonbroadcast network, cost of interface, etc.
! 4329: </function>
! 4330: <function><p><type>struct top_hash_entry *</type>
! 4331: <funcdef>ospf_install_lsa</funcdef>
! 4332: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>type</param>, <type>u32</type> <param>domain</param>, <type>void *</type> <param>body</param>) -- install new LSA into database
! 4333:
! 4334: <funcsect>Arguments
! 4335: <p><descrip>
! 4336: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4337: OSPF protocol instance
! 4338: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
! 4339: LSA header
! 4340: <tagp><type>u32</type> <param>type</param></tagp>
! 4341: type of LSA
! 4342: <tagp><type>u32</type> <param>domain</param></tagp>
! 4343: domain of LSA
! 4344: <tagp><type>void *</type> <param>body</param></tagp>
! 4345: pointer to LSA body
! 4346: </descrip>
! 4347: <funcsect>Description
! 4348: <p>
! 4349: This function ensures installing new LSA received in LS update into LSA
! 4350: database. Old instance is replaced. Several actions are taken to detect if
! 4351: new routing table calculation is necessary. This is described in 13.2 of RFC
! 4352: 2328. This function is for received LSA only, locally originated LSAs are
! 4353: installed by <func/ospf_originate_lsa()/.
! 4354: <p>
! 4355: The LSA body in <param/body/ is expected to be mb_allocated by the caller and its
! 4356: ownership is transferred to the LSA entry structure.
! 4357: </function>
! 4358: <function><p><type>void</type>
! 4359: <funcdef>ospf_advance_lsa</funcdef>
! 4360: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct top_hash_entry *</type> <param>en</param>, <type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>type</param>, <type>u32</type> <param>domain</param>, <type>void *</type> <param>body</param>) -- handle received unexpected self-originated LSA
! 4361:
! 4362: <funcsect>Arguments
! 4363: <p><descrip>
! 4364: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4365: OSPF protocol instance
! 4366: <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp>
! 4367: current LSA entry or NULL
! 4368: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
! 4369: new LSA header
! 4370: <tagp><type>u32</type> <param>type</param></tagp>
! 4371: type of LSA
! 4372: <tagp><type>u32</type> <param>domain</param></tagp>
! 4373: domain of LSA
! 4374: <tagp><type>void *</type> <param>body</param></tagp>
! 4375: pointer to LSA body
! 4376: </descrip>
! 4377: <funcsect>Description
! 4378: <p>
! 4379: This function handles received unexpected self-originated LSA (<param/lsa/, <param/body/)
! 4380: by either advancing sequence number of the local LSA instance (<param/en/) and
! 4381: propagating it, or installing the received LSA and immediately flushing it
! 4382: (if there is no local LSA; i.e., <param/en/ is NULL or MaxAge).
! 4383: <p>
! 4384: The LSA body in <param/body/ is expected to be mb_allocated by the caller and its
! 4385: ownership is transferred to the LSA entry structure or it is freed.
! 4386: </function>
! 4387: <function><p><type>struct top_hash_entry *</type>
! 4388: <funcdef>ospf_originate_lsa</funcdef>
! 4389: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_new_lsa *</type> <param>lsa</param>) -- originate new LSA
! 4390:
! 4391: <funcsect>Arguments
! 4392: <p><descrip>
! 4393: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4394: OSPF protocol instance
! 4395: <tagp><type>struct ospf_new_lsa *</type> <param>lsa</param></tagp>
! 4396: New LSA specification
! 4397: </descrip>
! 4398: <funcsect>Description
! 4399: <p>
! 4400: This function prepares a new LSA, installs it into the LSA database and
! 4401: floods it. If the new LSA cannot be originated now (because the old instance
! 4402: was originated within MinLSInterval, or because the LSA seqnum is currently
! 4403: wrapping), the origination is instead scheduled for later. If the new LSA is
! 4404: equivalent to the current LSA, the origination is skipped. In all cases, the
! 4405: corresponding LSA entry is returned. The new LSA is based on the LSA
! 4406: specification (<param/lsa/) and the LSA body from lsab buffer of <param/p/, which is
! 4407: emptied after the call. The opposite of this function is <func/ospf_flush_lsa()/.
! 4408: </function>
! 4409: <function><p><type>void</type>
! 4410: <funcdef>ospf_flush_lsa</funcdef>
! 4411: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct top_hash_entry *</type> <param>en</param>) -- flush LSA from OSPF domain
! 4412:
! 4413: <funcsect>Arguments
! 4414: <p><descrip>
! 4415: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4416: OSPF protocol instance
! 4417: <tagp><type>struct top_hash_entry *</type> <param>en</param></tagp>
! 4418: LSA entry to flush
! 4419: </descrip>
! 4420: <funcsect>Description
! 4421: <p>
! 4422: This function flushes <param/en/ from the OSPF domain by setting its age to
! 4423: <const/LSA_MAXAGE/ and flooding it. That also triggers subsequent events in LSA
! 4424: lifecycle leading to removal of the LSA from the LSA database (e.g. the LSA
! 4425: content is freed when flushing is acknowledged by neighbors). The function
! 4426: does nothing if the LSA is already being flushed. LSA entries are not
! 4427: immediately removed when being flushed, the caller may assume that <param/en/ still
! 4428: exists after the call. The function is the opposite of <func/ospf_originate_lsa()/
! 4429: and is supposed to do the right thing even in cases of postponed
! 4430: origination.
! 4431: </function>
! 4432: <function><p><type>void</type>
! 4433: <funcdef>ospf_update_lsadb</funcdef>
! 4434: (<type>struct ospf_proto *</type> <param>p</param>) -- update LSA database
! 4435:
! 4436: <funcsect>Arguments
! 4437: <p><descrip>
! 4438: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4439: OSPF protocol instance
! 4440: </descrip>
! 4441: <funcsect>Description
! 4442: <p>
! 4443: This function is periodicaly invoked from <func/ospf_disp()/. It does some periodic
! 4444: or postponed processing related to LSA entries. It originates postponed LSAs
! 4445: scheduled by <func/ospf_originate_lsa()/, It continues in flushing processes started
! 4446: by <func/ospf_flush_lsa()/. It also periodically refreshs locally originated LSAs --
! 4447: when the current instance is older <const/LSREFRESHTIME/, a new instance is originated.
! 4448: Finally, it also ages stored LSAs and flushes ones that reached <const/LSA_MAXAGE/.
! 4449: <p>
! 4450: The RFC 2328 says that a router should periodically check checksums of all
! 4451: stored LSAs to detect hardware problems. This is not implemented.
! 4452: </function>
! 4453: <function><p><type>void</type>
! 4454: <funcdef>ospf_originate_ext_lsa</funcdef>
! 4455: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_area *</type> <param>oa</param>, <type>ort *</type> <param>nf</param>, <type>u8</type> <param>mode</param>, <type>u32</type> <param>metric</param>, <type>u32</type> <param>ebit</param>, <type>ip_addr</type> <param>fwaddr</param>, <type>u32</type> <param>tag</param>, <type>int</type> <param>pbit</param>) -- new route received from nest and filters
! 4456:
! 4457: <funcsect>Arguments
! 4458: <p><descrip>
! 4459: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4460: OSPF protocol instance
! 4461: <tagp><type>struct ospf_area *</type> <param>oa</param></tagp>
! 4462: ospf_area for which LSA is originated
! 4463: <tagp><type>ort *</type> <param>nf</param></tagp>
! 4464: network prefix and mask
! 4465: <tagp><type>u8</type> <param>mode</param></tagp>
! 4466: the mode of the LSA (LSA_M_EXPORT or LSA_M_RTCALC)
! 4467: <tagp><type>u32</type> <param>metric</param></tagp>
! 4468: the metric of a route
! 4469: <tagp><type>u32</type> <param>ebit</param></tagp>
! 4470: E-bit for route metric (bool)
! 4471: <tagp><type>ip_addr</type> <param>fwaddr</param></tagp>
! 4472: the forwarding address
! 4473: <tagp><type>u32</type> <param>tag</param></tagp>
! 4474: the route tag
! 4475: <tagp><type>int</type> <param>pbit</param></tagp>
! 4476: P-bit for NSSA LSAs (bool), ignored for external LSAs
! 4477: </descrip>
! 4478: <funcsect>Description
! 4479: <p>
! 4480: If I receive a message that new route is installed, I try to originate an
! 4481: external LSA. If <param/oa/ is an NSSA area, NSSA-LSA is originated instead.
! 4482: <param/oa/ should not be a stub area. <param/src/ does not specify whether the LSA
! 4483: is external or NSSA, but it specifies the source of origination -
! 4484: the export from <func/ospf_rt_notify()/, or the NSSA-EXT translation.
! 4485: </function>
! 4486: <function><p><type>struct top_graph *</type>
! 4487: <funcdef>ospf_top_new</funcdef>
! 4488: (<type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param>, <type>pool *</type> <param>pool</param>) -- allocated new topology database
! 4489:
! 4490: <funcsect>Arguments
! 4491: <p><descrip>
! 4492: <tagp><type>struct ospf_proto *p UNUSED4</type> <param>UNUSED6</param></tagp>
! 4493: -- undescribed --
! 4494: <tagp><type>pool *</type> <param>pool</param></tagp>
! 4495: pool for allocation
! 4496: </descrip>
! 4497: <funcsect>Description
! 4498: <p>
! 4499: This dynamically hashed structure is used for keeping LSAs. Mainly it is used
! 4500: for the LSA database of the OSPF protocol, but also for LSA retransmission
! 4501: and request lists of OSPF neighbors.
! 4502: </function>
! 4503: <function><p><type>void</type>
! 4504: <funcdef>ospf_neigh_chstate</funcdef>
! 4505: (<type>struct ospf_neighbor *</type> <param>n</param>, <type>u8</type> <param>state</param>) -- handles changes related to new or lod state of neighbor
! 4506:
! 4507: <funcsect>Arguments
! 4508: <p><descrip>
! 4509: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
! 4510: OSPF neighbor
! 4511: <tagp><type>u8</type> <param>state</param></tagp>
! 4512: new state
! 4513: </descrip>
! 4514: <funcsect>Description
! 4515: <p>
! 4516: Many actions have to be taken acording to a change of state of a neighbor. It
! 4517: starts rxmt timers, call interface state machine etc.
! 4518: </function>
! 4519: <function><p><type>void</type>
! 4520: <funcdef>ospf_neigh_sm</funcdef>
! 4521: (<type>struct ospf_neighbor *</type> <param>n</param>, <type>int</type> <param>event</param>) -- ospf neighbor state machine
! 4522:
! 4523: <funcsect>Arguments
! 4524: <p><descrip>
! 4525: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
! 4526: neighor
! 4527: <tagp><type>int</type> <param>event</param></tagp>
! 4528: actual event
! 4529: </descrip>
! 4530: <funcsect>Description
! 4531: <p>
! 4532: This part implements the neighbor state machine as described in 10.3 of
! 4533: RFC 2328. The only difference is that state <const/NEIGHBOR_ATTEMPT/ is not
! 4534: used. We discover neighbors on nonbroadcast networks in the
! 4535: same way as on broadcast networks. The only difference is in
! 4536: sending hello packets. These are sent to IPs listed in
! 4537: <param/ospf_iface/->nbma_list .
! 4538: </function>
! 4539: <function><p><type>void</type>
! 4540: <funcdef>ospf_dr_election</funcdef>
! 4541: (<type>struct ospf_iface *</type> <param>ifa</param>) -- (Backup) Designed Router election
! 4542:
! 4543: <funcsect>Arguments
! 4544: <p><descrip>
! 4545: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
! 4546: actual interface
! 4547: </descrip>
! 4548: <funcsect>Description
! 4549: <p>
! 4550: When the wait timer fires, it is time to elect (Backup) Designated Router.
! 4551: Structure describing me is added to this list so every electing router has
! 4552: the same list. Backup Designated Router is elected before Designated
! 4553: Router. This process is described in 9.4 of RFC 2328. The function is
! 4554: supposed to be called only from <func/ospf_iface_sm()/ as a part of the interface
! 4555: state machine.
! 4556: </function>
! 4557: <function><p><type>void</type>
! 4558: <funcdef>ospf_iface_chstate</funcdef>
! 4559: (<type>struct ospf_iface *</type> <param>ifa</param>, <type>u8</type> <param>state</param>) -- handle changes of interface state
! 4560:
! 4561: <funcsect>Arguments
! 4562: <p><descrip>
! 4563: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
! 4564: OSPF interface
! 4565: <tagp><type>u8</type> <param>state</param></tagp>
! 4566: new state
! 4567: </descrip>
! 4568: <funcsect>Description
! 4569: <p>
! 4570: Many actions must be taken according to interface state changes. New network
! 4571: LSAs must be originated, flushed, new multicast sockets to listen for messages for
! 4572: <const/ALLDROUTERS/ have to be opened, etc.
! 4573: </function>
! 4574: <function><p><type>void</type>
! 4575: <funcdef>ospf_iface_sm</funcdef>
! 4576: (<type>struct ospf_iface *</type> <param>ifa</param>, <type>int</type> <param>event</param>) -- OSPF interface state machine
! 4577:
! 4578: <funcsect>Arguments
! 4579: <p><descrip>
! 4580: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp>
! 4581: OSPF interface
! 4582: <tagp><type>int</type> <param>event</param></tagp>
! 4583: event comming to state machine
! 4584: </descrip>
! 4585: <funcsect>Description
! 4586: <p>
! 4587: This fully respects 9.3 of RFC 2328 except we have slightly
! 4588: different handling of <const/DOWN/ and <const/LOOP/ state. We remove intefaces
! 4589: that are <const/DOWN/. <const/DOWN/ state is used when an interface is waiting
! 4590: for a lock. <const/LOOP/ state is used when an interface does not have a
! 4591: link.
! 4592: </function>
! 4593: <function><p><type>int</type>
! 4594: <funcdef>ospf_rx_hook</funcdef>
! 4595: (<type>sock *</type> <param>sk</param>, <type>uint</type> <param>len</param>)
! 4596: <funcsect>Arguments
! 4597: <p><descrip>
! 4598: <tagp><type>sock *</type> <param>sk</param></tagp>
! 4599: socket we received the packet.
! 4600: <tagp><type>uint</type> <param>len</param></tagp>
! 4601: size of the packet
! 4602: </descrip>
! 4603: <funcsect>Description
! 4604: <p>
! 4605: This is the entry point for messages from neighbors. Many checks (like
! 4606: authentication, checksums, size) are done before the packet is passed to
! 4607: non generic functions.
! 4608: </function>
! 4609: <function><p><type>int</type>
! 4610: <funcdef>lsa_validate</funcdef>
! 4611: (<type>struct ospf_lsa_header *</type> <param>lsa</param>, <type>u32</type> <param>lsa_type</param>, <type>int</type> <param>ospf2</param>, <type>void *</type> <param>body</param>) -- check whether given LSA is valid
! 4612:
! 4613: <funcsect>Arguments
! 4614: <p><descrip>
! 4615: <tagp><type>struct ospf_lsa_header *</type> <param>lsa</param></tagp>
! 4616: LSA header
! 4617: <tagp><type>u32</type> <param>lsa_type</param></tagp>
! 4618: one of <const/LSA_T_xxx/
! 4619: <tagp><type>int</type> <param>ospf2</param></tagp>
! 4620: <const/true/ means OSPF version 2, <const/false/ means OSPF version 3
! 4621: <tagp><type>void *</type> <param>body</param></tagp>
! 4622: pointer to LSA body
! 4623: </descrip>
! 4624: <funcsect>Description
! 4625: <p>
! 4626: Checks internal structure of given LSA body (minimal length,
! 4627: consistency). Returns true if valid.
! 4628: </function>
! 4629: <function><p><type>void</type>
! 4630: <funcdef>ospf_send_dbdes</funcdef>
! 4631: (<type>struct ospf_proto *</type> <param>p</param>, <type>struct ospf_neighbor *</type> <param>n</param>) -- transmit database description packet
! 4632:
! 4633: <funcsect>Arguments
! 4634: <p><descrip>
! 4635: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4636: OSPF protocol instance
! 4637: <tagp><type>struct ospf_neighbor *</type> <param>n</param></tagp>
! 4638: neighbor
! 4639: </descrip>
! 4640: <funcsect>Description
! 4641: <p>
! 4642: Sending of a database description packet is described in 10.8 of RFC 2328.
! 4643: Reception of each packet is acknowledged in the sequence number of another.
! 4644: When I send a packet to a neighbor I keep a copy in a buffer. If the neighbor
! 4645: does not reply, I don't create a new packet but just send the content
! 4646: of the buffer.
! 4647: </function>
! 4648: <function><p><type>void</type>
! 4649: <funcdef>ospf_rt_spf</funcdef>
! 4650: (<type>struct ospf_proto *</type> <param>p</param>) -- calculate internal routes
! 4651:
! 4652: <funcsect>Arguments
! 4653: <p><descrip>
! 4654: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp>
! 4655: OSPF protocol instance
! 4656: </descrip>
! 4657: <funcsect>Description
! 4658: <p>
! 4659: Calculation of internal paths in an area is described in 16.1 of RFC 2328.
! 4660: It's based on Dijkstra's shortest path tree algorithms.
! 4661: This function is invoked from <func/ospf_disp()/.
! 4662: </function>
! 4663: <sect>Pipe
! 4664: <p>
! 4665: <p>
! 4666: The Pipe protocol is very simple. It just connects to two routing tables
! 4667: using <func/proto_add_announce_hook()/ and whenever it receives a <func/rt_notify()/
! 4668: about a change in one of the tables, it converts it to a <func/rte_update()/
! 4669: in the other one.
! 4670: <p>
! 4671: To avoid pipe loops, Pipe keeps a `being updated' flag in each routing
! 4672: table.
! 4673: <p>
! 4674: A pipe has two announce hooks, the first connected to the main
! 4675: table, the second connected to the peer table. When a new route is
! 4676: announced on the main table, it gets checked by an export filter in
! 4677: ahook 1, and, after that, it is announced to the peer table via
! 4678: <func/rte_update()/, an import filter in ahook 2 is called. When a new
! 4679: route is announced in the peer table, an export filter in ahook2
! 4680: and an import filter in ahook 1 are used. Oviously, there is no
! 4681: need in filtering the same route twice, so both import filters are
! 4682: set to accept, while user configured 'import' and 'export' filters
! 4683: are used as export filters in ahooks 2 and 1. Route limits are
! 4684: handled similarly, but on the import side of ahooks.
! 4685:
! 4686:
! 4687: <sect>Routing Information Protocol (RIP)
! 4688: <p>
! 4689: <p>
! 4690: The RIP protocol is implemented in two files: <tt>rip.c</tt> containing the protocol
! 4691: logic, route management and the protocol glue with BIRD core, and <tt>packets.c</tt>
! 4692: handling RIP packet processing, RX, TX and protocol sockets.
! 4693: <p>
! 4694: Each instance of RIP is described by a structure <struct/rip_proto/, which contains
! 4695: an internal RIP routing table, a list of protocol interfaces and the main
! 4696: timer responsible for RIP routing table cleanup.
! 4697: <p>
! 4698: RIP internal routing table contains incoming and outgoing routes. For each
! 4699: network (represented by structure <struct/rip_entry/) there is one outgoing route
! 4700: stored directly in <struct/rip_entry/ and an one-way linked list of incoming routes
! 4701: (structures <struct/rip_rte/). The list contains incoming routes from different RIP
! 4702: neighbors, but only routes with the lowest metric are stored (i.e., all
! 4703: stored incoming routes have the same metric).
! 4704: <p>
! 4705: Note that RIP itself does not select outgoing route, that is done by the core
! 4706: routing table. When a new incoming route is received, it is propagated to the
! 4707: RIP table by <func/rip_update_rte()/ and possibly stored in the list of incoming
! 4708: routes. Then the change may be propagated to the core by <func/rip_announce_rte()/.
! 4709: The core selects the best route and propagate it to RIP by <func/rip_rt_notify()/,
! 4710: which updates outgoing route part of <struct/rip_entry/ and possibly triggers route
! 4711: propagation by <func/rip_trigger_update()/.
! 4712: <p>
! 4713: RIP interfaces are represented by structures <struct/rip_iface/. A RIP interface
! 4714: contains a per-interface socket, a list of associated neighbors, interface
! 4715: configuration, and state information related to scheduled interface events
! 4716: and running update sessions. RIP interfaces are added and removed based on
! 4717: core interface notifications.
! 4718: <p>
! 4719: There are two RIP interface events - regular updates and triggered updates.
! 4720: Both are managed from the RIP interface timer (<func/rip_iface_timer()/). Regular
! 4721: updates are called at fixed interval and propagate the whole routing table,
! 4722: while triggered updates are scheduled by <func/rip_trigger_update()/ due to some
! 4723: routing table change and propagate only the routes modified since the time
! 4724: they were scheduled. There are also unicast-destined requested updates, but
! 4725: these are sent directly as a reaction to received RIP request message. The
! 4726: update session is started by <func/rip_send_table()/. There may be at most one
! 4727: active update session per interface, as the associated state (including the
! 4728: fib iterator) is stored directly in <struct/rip_iface/ structure.
! 4729: <p>
! 4730: RIP neighbors are represented by structures <struct/rip_neighbor/. Compared to
! 4731: neighbor handling in other routing protocols, RIP does not have explicit
! 4732: neighbor discovery and adjacency maintenance, which makes the <struct/rip_neighbor/
! 4733: related code a bit peculiar. RIP neighbors are interlinked with core neighbor
! 4734: structures (<struct/neighbor/) and use core neighbor notifications to ensure that RIP
! 4735: neighbors are timely removed. RIP neighbors are added based on received route
! 4736: notifications and removed based on core neighbor and RIP interface events.
! 4737: <p>
! 4738: RIP neighbors are linked by RIP routes and use counter to track the number of
! 4739: associated routes, but when these RIP routes timeout, associated RIP neighbor
! 4740: is still alive (with zero counter). When RIP neighbor is removed but still
! 4741: has some associated routes, it is not freed, just changed to detached state
! 4742: (core neighbors and RIP ifaces are unlinked), then during the main timer
! 4743: cleanup phase the associated routes are removed and the <struct/rip_neighbor/
! 4744: structure is finally freed.
! 4745: <p>
! 4746: Supported standards:
! 4747: - RFC 1058 - RIPv1
! 4748: - RFC 2453 - RIPv2
! 4749: - RFC 2080 - RIPng
! 4750: - RFC 4822 - RIP cryptographic authentication
! 4751:
! 4752:
! 4753: <function><p><type>void</type>
! 4754: <funcdef>rip_announce_rte</funcdef>
! 4755: (<type>struct rip_proto *</type> <param>p</param>, <type>struct rip_entry *</type> <param>en</param>) -- announce route from RIP routing table to the core
! 4756:
! 4757: <funcsect>Arguments
! 4758: <p><descrip>
! 4759: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
! 4760: RIP instance
! 4761: <tagp><type>struct rip_entry *</type> <param>en</param></tagp>
! 4762: related network
! 4763: </descrip>
! 4764: <funcsect>Description
! 4765: <p>
! 4766: The function takes a list of incoming routes from <param/en/, prepare appropriate
! 4767: <struct/rte/ for the core and propagate it by <func/rte_update()/.
! 4768: </function>
! 4769: <function><p><type>void</type>
! 4770: <funcdef>rip_update_rte</funcdef>
! 4771: (<type>struct rip_proto *</type> <param>p</param>, <type>ip_addr *</type> <param>prefix</param>, <type>int</type> <param>pxlen</param>, <type>struct rip_rte *</type> <param>new</param>) -- enter a route update to RIP routing table
! 4772:
! 4773: <funcsect>Arguments
! 4774: <p><descrip>
! 4775: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
! 4776: RIP instance
! 4777: <tagp><type>ip_addr *</type> <param>prefix</param></tagp>
! 4778: network prefix
! 4779: <tagp><type>int</type> <param>pxlen</param></tagp>
! 4780: network prefix length
! 4781: <tagp><type>struct rip_rte *</type> <param>new</param></tagp>
! 4782: a <struct/rip_rte/ representing the new route
! 4783: </descrip>
! 4784: <funcsect>Description
! 4785: <p>
! 4786: The function is called by the RIP packet processing code whenever it receives
! 4787: a reachable route. The appropriate routing table entry is found and the list
! 4788: of incoming routes is updated. Eventually, the change is also propagated to
! 4789: the core by <func/rip_announce_rte()/. Note that for unreachable routes,
! 4790: <func/rip_withdraw_rte()/ should be called instead of <func/rip_update_rte()/.
! 4791: </function>
! 4792: <function><p><type>void</type>
! 4793: <funcdef>rip_withdraw_rte</funcdef>
! 4794: (<type>struct rip_proto *</type> <param>p</param>, <type>ip_addr *</type> <param>prefix</param>, <type>int</type> <param>pxlen</param>, <type>struct rip_neighbor *</type> <param>from</param>) -- enter a route withdraw to RIP routing table
! 4795:
! 4796: <funcsect>Arguments
! 4797: <p><descrip>
! 4798: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
! 4799: RIP instance
! 4800: <tagp><type>ip_addr *</type> <param>prefix</param></tagp>
! 4801: network prefix
! 4802: <tagp><type>int</type> <param>pxlen</param></tagp>
! 4803: network prefix length
! 4804: <tagp><type>struct rip_neighbor *</type> <param>from</param></tagp>
! 4805: a <struct/rip_neighbor/ propagating the withdraw
! 4806: </descrip>
! 4807: <funcsect>Description
! 4808: <p>
! 4809: The function is called by the RIP packet processing code whenever it receives
! 4810: an unreachable route. The incoming route for given network from nbr <param/from/ is
! 4811: removed. Eventually, the change is also propagated by <func/rip_announce_rte()/.
! 4812: </function>
! 4813: <function><p><type>void</type>
! 4814: <funcdef>rip_timer</funcdef>
! 4815: (<type>timer *</type> <param>t</param>) -- RIP main timer hook
! 4816:
! 4817: <funcsect>Arguments
! 4818: <p><descrip>
! 4819: <tagp><type>timer *</type> <param>t</param></tagp>
! 4820: timer
! 4821: </descrip>
! 4822: <funcsect>Description
! 4823: <p>
! 4824: The RIP main timer is responsible for routing table maintenance. Invalid or
! 4825: expired routes (<struct/rip_rte/) are removed and garbage collection of stale routing
! 4826: table entries (<struct/rip_entry/) is done. Changes are propagated to core tables,
! 4827: route reload is also done here. Note that garbage collection uses a maximal
! 4828: GC time, while interfaces maintain an illusion of per-interface GC times in
! 4829: <func/rip_send_response()/.
! 4830: <p>
! 4831: Keeping incoming routes and the selected outgoing route are two independent
! 4832: functions, therefore after garbage collection some entries now considered
! 4833: invalid (RIP_ENTRY_DUMMY) still may have non-empty list of incoming routes,
! 4834: while some valid entries (representing an outgoing route) may have that list
! 4835: empty.
! 4836: <p>
! 4837: The main timer is not scheduled periodically but it uses the time of the
! 4838: current next event and the minimal interval of any possible event to compute
! 4839: the time of the next run.
! 4840: </function>
! 4841: <function><p><type>void</type>
! 4842: <funcdef>rip_iface_timer</funcdef>
! 4843: (<type>timer *</type> <param>t</param>) -- RIP interface timer hook
! 4844:
! 4845: <funcsect>Arguments
! 4846: <p><descrip>
! 4847: <tagp><type>timer *</type> <param>t</param></tagp>
! 4848: timer
! 4849: </descrip>
! 4850: <funcsect>Description
! 4851: <p>
! 4852: RIP interface timers are responsible for scheduling both regular and
! 4853: triggered updates. Fixed, delay-independent period is used for regular
! 4854: updates, while minimal separating interval is enforced for triggered updates.
! 4855: The function also ensures that a new update is not started when the old one
! 4856: is still running.
! 4857: </function>
! 4858: <function><p><type>void</type>
! 4859: <funcdef>rip_send_table</funcdef>
! 4860: (<type>struct rip_proto *</type> <param>p</param>, <type>struct rip_iface *</type> <param>ifa</param>, <type>ip_addr</type> <param>addr</param>, <type>bird_clock_t</type> <param>changed</param>) -- RIP interface timer hook
! 4861:
! 4862: <funcsect>Arguments
! 4863: <p><descrip>
! 4864: <tagp><type>struct rip_proto *</type> <param>p</param></tagp>
! 4865: RIP instance
! 4866: <tagp><type>struct rip_iface *</type> <param>ifa</param></tagp>
! 4867: RIP interface
! 4868: <tagp><type>ip_addr</type> <param>addr</param></tagp>
! 4869: destination IP address
! 4870: <tagp><type>bird_clock_t</type> <param>changed</param></tagp>
! 4871: time limit for triggered updates
! 4872: </descrip>
! 4873: <funcsect>Description
! 4874: <p>
! 4875: The function activates an update session and starts sending routing update
! 4876: packets (using <func/rip_send_response()/). The session may be finished during the
! 4877: call or may continue in <func/rip_tx_hook()/ until all appropriate routes are
! 4878: transmitted. Note that there may be at most one active update session per
! 4879: interface, the function will terminate the old active session before
! 4880: activating the new one.
! 4881: </function>
! 4882: <sect>Router Advertisements
! 4883: <p>
! 4884: <p>
! 4885: The RAdv protocol is implemented in two files: <tt>radv.c</tt> containing the
! 4886: interface with BIRD core and the protocol logic and <tt>packets.c</tt> handling low
! 4887: level protocol stuff (RX, TX and packet formats). The protocol does not
! 4888: export any routes.
! 4889: <p>
! 4890: The RAdv is structured in the usual way - for each handled interface there is
! 4891: a structure <struct/radv_iface/ that contains a state related to that interface
! 4892: together with its resources (a socket, a timer). There is also a prepared RA
! 4893: stored in a TX buffer of the socket associated with an iface. These iface
! 4894: structures are created and removed according to iface events from BIRD core
! 4895: handled by <func/radv_if_notify()/ callback.
! 4896: <p>
! 4897: The main logic of RAdv consists of two functions: <func/radv_iface_notify()/, which
! 4898: processes asynchronous events (specified by RA_EV_* codes), and <func/radv_timer()/,
! 4899: which triggers sending RAs and computes the next timeout.
! 4900: <p>
! 4901: The RAdv protocol could receive routes (through <func/radv_import_control()/ and
! 4902: <func/radv_rt_notify()/), but only the configured trigger route is tracked (in
! 4903: <struct/active/ var). When a radv protocol is reconfigured, the connected routing
! 4904: table is examined (in <func/radv_check_active()/) to have proper <struct/active/ value in
! 4905: case of the specified trigger prefix was changed.
! 4906: <p>
! 4907: Supported standards:
! 4908: - RFC 4861 - main RA standard
! 4909: - RFC 4191 - Default Router Preferences and More-Specific Routes
! 4910: - RFC 6106 - DNS extensions (RDDNS, DNSSL)
! 4911:
! 4912:
! 4913: <sect>Static
! 4914: <p>
! 4915: <p>
! 4916: The Static protocol is implemented in a straightforward way. It keeps
! 4917: two lists of static routes: one containing interface routes and one
! 4918: holding the remaining ones. Interface routes are inserted and removed according
! 4919: to interface events received from the core via the <func/if_notify()/ hook. Routes
! 4920: pointing to a neighboring router use a sticky node in the neighbor cache
! 4921: to be notified about gaining or losing the neighbor. Special
! 4922: routes like black holes or rejects are inserted all the time.
! 4923: <p>
! 4924: Multipath routes are tricky. Because these routes depends on
! 4925: several neighbors we need to integrate that to the neighbor
! 4926: notification handling, we use dummy static_route nodes, one for
! 4927: each nexthop. Therefore, a multipath route consists of a master
! 4928: static_route node (of dest RTD_MULTIPATH), which specifies prefix
! 4929: and is used in most circumstances, and a list of dummy static_route
! 4930: nodes (of dest RTD_NONE), which stores info about nexthops and are
! 4931: connected to neighbor entries and neighbor notifications. Dummy
! 4932: nodes are chained using mp_next, they aren't in other_routes list,
! 4933: and abuse some fields (masklen, if_name) for other purposes.
! 4934: <p>
! 4935: The only other thing worth mentioning is that when asked for reconfiguration,
! 4936: Static not only compares the two configurations, but it also calculates
! 4937: difference between the lists of static routes and it just inserts the
! 4938: newly added routes and removes the obsolete ones.
! 4939:
! 4940:
! 4941: <sect>Direct
! 4942: <p>
! 4943: <p>
! 4944: The Direct protocol works by converting all <func/ifa_notify()/ events it receives
! 4945: to <func/rte_update()/ calls for the corresponding network.
! 4946:
! 4947:
! 4948: <!--
! 4949: BIRD Programmer's Guide: Sysdeps
! 4950:
! 4951: (c) 2000 Martin Mares <mj@ucw.cz>
! 4952: -->
! 4953:
! 4954: <chapt>System dependent parts
! 4955:
! 4956: <sect>Introduction
! 4957:
! 4958: <p>We've tried to make BIRD as portable as possible, but unfortunately
! 4959: communication with the network stack differs from one OS to another,
! 4960: so we need at least some OS specific code. The good news is that this
! 4961: code is isolated in a small set of modules:
! 4962:
! 4963: <descrip>
! 4964: <tagp><tt/config.h/</tagp> is a header file with configuration information,
! 4965: definition of the standard set of types and so on.
! 4966: <tagp/Startup module/ controls BIRD startup. Common for a family of OS's (e.g.,
! 4967: for all Unices).
! 4968: <tagp/Logging module/ manages the system logs. [per OS family]
! 4969: <tagp/IO module/ gives an implementation of sockets, timers and the
! 4970: global event queue. [per OS family]
! 4971: <tagp/KRT module/ implements the Kernel and Device protocols. This
! 4972: is the most arcane part of the system dependent stuff and some
! 4973: functions differ even between various releases of a single OS.
! 4974: </descrip>
! 4975: <sect>Logging
! 4976: <p>
! 4977: <p>
! 4978: The Logging module offers a simple set of functions for writing
! 4979: messages to system logs and to the debug output. Message classes
! 4980: used by this module are described in <tt>birdlib.h</tt> and also in the
! 4981: user's manual.
! 4982:
! 4983:
! 4984: <function><p><type>void</type>
! 4985: <funcdef>log_commit</funcdef>
! 4986: (<type>int</type> <param>class</param>, <type>buffer *</type> <param>buf</param>) -- commit a log message
! 4987:
! 4988: <funcsect>Arguments
! 4989: <p><descrip>
! 4990: <tagp><type>int</type> <param>class</param></tagp>
! 4991: message class information (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>)
! 4992: <tagp><type>buffer *</type> <param>buf</param></tagp>
! 4993: message to write
! 4994: </descrip>
! 4995: <funcsect>Description
! 4996: <p>
! 4997: This function writes a message prepared in the log buffer to the
! 4998: log file (as specified in the configuration). The log buffer is
! 4999: reset after that. The log message is a full line, <func/log_commit()/
! 5000: terminates it.
! 5001: <p>
! 5002: The message class is an integer, not a first char of a string like
! 5003: in <func/log()/, so it should be written like *L_INFO.
! 5004: </function>
! 5005: <function><p><type>void</type>
! 5006: <funcdef>log_msg</funcdef>
! 5007: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- log a message
! 5008:
! 5009: <funcsect>Arguments
! 5010: <p><descrip>
! 5011: <tagp><type>const char *</type> <param>msg</param></tagp>
! 5012: printf-like formatting string with message class information
! 5013: prepended (<const/L_DEBUG/ to <const/L_BUG/, see <tt>lib/birdlib.h</tt>)
! 5014: <tagp><type>...</type> <param>...</param></tagp>
! 5015: variable arguments
! 5016: </descrip>
! 5017: <funcsect>Description
! 5018: <p>
! 5019: This function formats a message according to the format string <param/msg/
! 5020: and writes it to the corresponding log file (as specified in the
! 5021: configuration). Please note that the message is automatically
! 5022: formatted as a full line, no need to include <tt>\n</tt> inside.
! 5023: It is essentially a sequence of <func/log_reset()/, <func/logn()/ and <func/log_commit()/.
! 5024: </function>
! 5025: <function><p><type>void</type>
! 5026: <funcdef>bug</funcdef>
! 5027: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report an internal error
! 5028:
! 5029: <funcsect>Arguments
! 5030: <p><descrip>
! 5031: <tagp><type>const char *</type> <param>msg</param></tagp>
! 5032: a printf-like error message
! 5033: <tagp><type>...</type> <param>...</param></tagp>
! 5034: variable arguments
! 5035: </descrip>
! 5036: <funcsect>Description
! 5037: <p>
! 5038: This function logs an internal error and aborts execution
! 5039: of the program.
! 5040: </function>
! 5041: <function><p><type>void</type>
! 5042: <funcdef>die</funcdef>
! 5043: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- report a fatal error
! 5044:
! 5045: <funcsect>Arguments
! 5046: <p><descrip>
! 5047: <tagp><type>const char *</type> <param>msg</param></tagp>
! 5048: a printf-like error message
! 5049: <tagp><type>...</type> <param>...</param></tagp>
! 5050: variable arguments
! 5051: </descrip>
! 5052: <funcsect>Description
! 5053: <p>
! 5054: This function logs a fatal error and aborts execution
! 5055: of the program.
! 5056: </function>
! 5057: <function><p><type>void</type>
! 5058: <funcdef>debug</funcdef>
! 5059: (<type>const char *</type> <param>msg</param>, <type>...</type> <param>...</param>) -- write to debug output
! 5060:
! 5061: <funcsect>Arguments
! 5062: <p><descrip>
! 5063: <tagp><type>const char *</type> <param>msg</param></tagp>
! 5064: a printf-like message
! 5065: <tagp><type>...</type> <param>...</param></tagp>
! 5066: variable arguments
! 5067: </descrip>
! 5068: <funcsect>Description
! 5069: <p>
! 5070: This function formats the message <param/msg/ and prints it out
! 5071: to the debugging output. No newline character is appended.
! 5072: </function>
! 5073: <sect>Kernel synchronization
! 5074: <p>
! 5075: <p>
! 5076: This system dependent module implements the Kernel and Device protocol,
! 5077: that is synchronization of interface lists and routing tables with the
! 5078: OS kernel.
! 5079: <p>
! 5080: The whole kernel synchronization is a bit messy and touches some internals
! 5081: of the routing table engine, because routing table maintenance is a typical
! 5082: example of the proverbial compatibility between different Unices and we want
! 5083: to keep the overhead of our KRT business as low as possible and avoid maintaining
! 5084: a local routing table copy.
! 5085: <p>
! 5086: The kernel syncer can work in three different modes (according to system config header):
! 5087: Either with a single routing table and single KRT protocol [traditional UNIX]
! 5088: or with many routing tables and separate KRT protocols for all of them
! 5089: or with many routing tables, but every scan including all tables, so we start
! 5090: separate KRT protocols which cooperate with each other [Linux].
! 5091: In this case, we keep only a single scan timer.
! 5092: <p>
! 5093: We use FIB node flags in the routing table to keep track of route
! 5094: synchronization status. We also attach temporary <struct/rte/'s to the routing table,
! 5095: but it cannot do any harm to the rest of BIRD since table synchronization is
! 5096: an atomic process.
! 5097: <p>
! 5098: When starting up, we cheat by looking if there is another
! 5099: KRT instance to be initialized later and performing table scan
! 5100: only once for all the instances.
! 5101: <p>
! 5102: The code uses OS-dependent parts for kernel updates and scans. These parts are
! 5103: in more specific sysdep directories (e.g. sysdep/linux) in functions krt_sys_*
! 5104: and kif_sys_* (and some others like <func/krt_replace_rte()/) and krt-sys.h header file.
! 5105: This is also used for platform specific protocol options and route attributes.
! 5106: <p>
! 5107: There was also an old code that used traditional UNIX ioctls for these tasks.
! 5108: It was unmaintained and later removed. For reference, see sysdep/krt-* files
! 5109: in commit 396dfa9042305f62da1f56589c4b98fac57fc2f6
! 5110:
! 5111:
! 5112: <chapt>Library functions
! 5113: <sect>IP addresses
! 5114: <p>
! 5115: <p>
! 5116: BIRD uses its own abstraction of IP address in order to share the same
! 5117: code for both IPv4 and IPv6. IP addresses are represented as entities
! 5118: of type <struct/ip_addr/ which are never to be treated as numbers and instead
! 5119: they must be manipulated using the following functions and macros.
! 5120:
! 5121:
! 5122: <function><p><type>char *</type>
! 5123: <funcdef>ip_scope_text</funcdef>
! 5124: (<type>uint</type> <param>scope</param>) -- get textual representation of address scope
! 5125:
! 5126: <funcsect>Arguments
! 5127: <p><descrip>
! 5128: <tagp><type>uint</type> <param>scope</param></tagp>
! 5129: scope (<const/SCOPE_xxx/)
! 5130: </descrip>
! 5131: <funcsect>Description
! 5132: <p>
! 5133: Returns a pointer to a textual name of the scope given.
! 5134: </function>
! 5135: <function><p><type>int</type>
! 5136: <funcdef>ipa_equal</funcdef>
! 5137: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for equality
! 5138:
! 5139: <funcsect>Arguments
! 5140: <p><descrip>
! 5141: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5142: IP address
! 5143: <tagp><type>ip_addr</type> <param>y</param></tagp>
! 5144: IP address
! 5145: </descrip>
! 5146: <funcsect>Description
! 5147: <p>
! 5148: <func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0.
! 5149: </function>
! 5150: <function><p><type>int</type>
! 5151: <funcdef>ipa_nonzero</funcdef>
! 5152: (<type>ip_addr</type> <param>x</param>) -- test if an IP address is defined
! 5153:
! 5154: <funcsect>Arguments
! 5155: <p><descrip>
! 5156: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5157: IP address
! 5158: </descrip>
! 5159: <funcsect>Description
! 5160: <p>
! 5161: ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero),
! 5162: else 0.
! 5163: <p>
! 5164: The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro.
! 5165: </function>
! 5166: <function><p><type>ip_addr</type>
! 5167: <funcdef>ipa_and</funcdef>
! 5168: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise and of two IP addresses
! 5169:
! 5170: <funcsect>Arguments
! 5171: <p><descrip>
! 5172: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5173: IP address
! 5174: <tagp><type>ip_addr</type> <param>y</param></tagp>
! 5175: IP address
! 5176: </descrip>
! 5177: <funcsect>Description
! 5178: <p>
! 5179: This function returns a bitwise and of <param/x/ and <param/y/. It's primarily
! 5180: used for network masking.
! 5181: </function>
! 5182: <function><p><type>ip_addr</type>
! 5183: <funcdef>ipa_or</funcdef>
! 5184: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise or of two IP addresses
! 5185:
! 5186: <funcsect>Arguments
! 5187: <p><descrip>
! 5188: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5189: IP address
! 5190: <tagp><type>ip_addr</type> <param>y</param></tagp>
! 5191: IP address
! 5192: </descrip>
! 5193: <funcsect>Description
! 5194: <p>
! 5195: This function returns a bitwise or of <param/x/ and <param/y/.
! 5196: </function>
! 5197: <function><p><type>ip_addr</type>
! 5198: <funcdef>ipa_xor</funcdef>
! 5199: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compute bitwise xor of two IP addresses
! 5200:
! 5201: <funcsect>Arguments
! 5202: <p><descrip>
! 5203: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5204: IP address
! 5205: <tagp><type>ip_addr</type> <param>y</param></tagp>
! 5206: IP address
! 5207: </descrip>
! 5208: <funcsect>Description
! 5209: <p>
! 5210: This function returns a bitwise xor of <param/x/ and <param/y/.
! 5211: </function>
! 5212: <function><p><type>ip_addr</type>
! 5213: <funcdef>ipa_not</funcdef>
! 5214: (<type>ip_addr</type> <param>x</param>) -- compute bitwise negation of two IP addresses
! 5215:
! 5216: <funcsect>Arguments
! 5217: <p><descrip>
! 5218: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5219: IP address
! 5220: </descrip>
! 5221: <funcsect>Description
! 5222: <p>
! 5223: This function returns a bitwise negation of <param/x/.
! 5224: </function>
! 5225: <function><p><type>ip_addr</type>
! 5226: <funcdef>ipa_mkmask</funcdef>
! 5227: (<type>int</type> <param>x</param>) -- create a netmask
! 5228:
! 5229: <funcsect>Arguments
! 5230: <p><descrip>
! 5231: <tagp><type>int</type> <param>x</param></tagp>
! 5232: prefix length
! 5233: </descrip>
! 5234: <funcsect>Description
! 5235: <p>
! 5236: This function returns an <struct/ip_addr/ corresponding of a netmask
! 5237: of an address prefix of size <param/x/.
! 5238: </function>
! 5239: <function><p><type>int</type>
! 5240: <funcdef>ipa_masklen</funcdef>
! 5241: (<type>ip_addr</type> <param>x</param>) -- calculate netmask length
! 5242:
! 5243: <funcsect>Arguments
! 5244: <p><descrip>
! 5245: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5246: IP address
! 5247: </descrip>
! 5248: <funcsect>Description
! 5249: <p>
! 5250: This function checks whether <param/x/ represents a valid netmask and
! 5251: returns the size of the associate network prefix or -1 for invalid
! 5252: mask.
! 5253: </function>
! 5254: <function><p><type>int</type>
! 5255: <funcdef>ipa_hash</funcdef>
! 5256: (<type>ip_addr</type> <param>x</param>) -- hash IP addresses
! 5257:
! 5258: <funcsect>Arguments
! 5259: <p><descrip>
! 5260: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5261: IP address
! 5262: </descrip>
! 5263: <funcsect>Description
! 5264: <p>
! 5265: <func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/.
! 5266: </function>
! 5267: <function><p><type>void</type>
! 5268: <funcdef>ipa_hton</funcdef>
! 5269: (<type>ip_addr</type> <param>x</param>) -- convert IP address to network order
! 5270:
! 5271: <funcsect>Arguments
! 5272: <p><descrip>
! 5273: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5274: IP address
! 5275: </descrip>
! 5276: <funcsect>Description
! 5277: <p>
! 5278: Converts the IP address <param/x/ to the network byte order.
! 5279: <p>
! 5280: Beware, this is a macro and it alters the argument!
! 5281: </function>
! 5282: <function><p><type>void</type>
! 5283: <funcdef>ipa_ntoh</funcdef>
! 5284: (<type>ip_addr</type> <param>x</param>) -- convert IP address to host order
! 5285:
! 5286: <funcsect>Arguments
! 5287: <p><descrip>
! 5288: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5289: IP address
! 5290: </descrip>
! 5291: <funcsect>Description
! 5292: <p>
! 5293: Converts the IP address <param/x/ from the network byte order.
! 5294: <p>
! 5295: Beware, this is a macro and it alters the argument!
! 5296: </function>
! 5297: <function><p><type>int</type>
! 5298: <funcdef>ipa_classify</funcdef>
! 5299: (<type>ip_addr</type> <param>x</param>) -- classify an IP address
! 5300:
! 5301: <funcsect>Arguments
! 5302: <p><descrip>
! 5303: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5304: IP address
! 5305: </descrip>
! 5306: <funcsect>Description
! 5307: <p>
! 5308: <func/ipa_classify()/ returns an address class of <param/x/, that is a bitwise or
! 5309: of address type (<const/IADDR_INVALID/, <const/IADDR_HOST/, <const/IADDR_BROADCAST/, <const/IADDR_MULTICAST/)
! 5310: with address scope (<const/SCOPE_HOST/ to <const/SCOPE_UNIVERSE/) or -1 (<const/IADDR_INVALID/)
! 5311: for an invalid address.
! 5312: </function>
! 5313: <function><p><type>ip4_addr</type>
! 5314: <funcdef>ip4_class_mask</funcdef>
! 5315: (<type>ip4_addr</type> <param>x</param>) -- guess netmask according to address class
! 5316:
! 5317: <funcsect>Arguments
! 5318: <p><descrip>
! 5319: <tagp><type>ip4_addr</type> <param>x</param></tagp>
! 5320: IPv4 address
! 5321: </descrip>
! 5322: <funcsect>Description
! 5323: <p>
! 5324: This function (available in IPv4 version only) returns a
! 5325: network mask according to the address class of <param/x/. Although
! 5326: classful addressing is nowadays obsolete, there still live
! 5327: routing protocols transferring no prefix lengths nor netmasks
! 5328: and this function could be useful to them.
! 5329: </function>
! 5330: <function><p><type>u32</type>
! 5331: <funcdef>ipa_from_u32</funcdef>
! 5332: (<type>ip_addr</type> <param>x</param>) -- convert IPv4 address to an integer
! 5333:
! 5334: <funcsect>Arguments
! 5335: <p><descrip>
! 5336: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5337: IP address
! 5338: </descrip>
! 5339: <funcsect>Description
! 5340: <p>
! 5341: This function takes an IPv4 address and returns its numeric
! 5342: representation.
! 5343: </function>
! 5344: <function><p><type>ip_addr</type>
! 5345: <funcdef>ipa_to_u32</funcdef>
! 5346: (<type>u32</type> <param>x</param>) -- convert integer to IPv4 address
! 5347:
! 5348: <funcsect>Arguments
! 5349: <p><descrip>
! 5350: <tagp><type>u32</type> <param>x</param></tagp>
! 5351: a 32-bit integer
! 5352: </descrip>
! 5353: <funcsect>Description
! 5354: <p>
! 5355: <func/ipa_to_u32()/ takes a numeric representation of an IPv4 address
! 5356: and converts it to the corresponding <struct/ip_addr/.
! 5357: </function>
! 5358: <function><p><type>int</type>
! 5359: <funcdef>ipa_compare</funcdef>
! 5360: (<type>ip_addr</type> <param>x</param>, <type>ip_addr</type> <param>y</param>) -- compare two IP addresses for order
! 5361:
! 5362: <funcsect>Arguments
! 5363: <p><descrip>
! 5364: <tagp><type>ip_addr</type> <param>x</param></tagp>
! 5365: IP address
! 5366: <tagp><type>ip_addr</type> <param>y</param></tagp>
! 5367: IP address
! 5368: </descrip>
! 5369: <funcsect>Description
! 5370: <p>
! 5371: The <func/ipa_compare()/ function takes two IP addresses and returns
! 5372: -1 if <param/x/ is less than <param/y/ in canonical ordering (lexicographical
! 5373: order of the bit strings), 1 if <param/x/ is greater than <param/y/ and 0
! 5374: if they are the same.
! 5375: </function>
! 5376: <function><p><type>ip_addr</type>
! 5377: <funcdef>ipa_build6</funcdef>
! 5378: (<type>u32</type> <param>a1</param>, <type>u32</type> <param>a2</param>, <type>u32</type> <param>a3</param>, <type>u32</type> <param>a4</param>) -- build an IPv6 address from parts
! 5379:
! 5380: <funcsect>Arguments
! 5381: <p><descrip>
! 5382: <tagp><type>u32</type> <param>a1</param></tagp>
! 5383: part #1
! 5384: <tagp><type>u32</type> <param>a2</param></tagp>
! 5385: part #2
! 5386: <tagp><type>u32</type> <param>a3</param></tagp>
! 5387: part #3
! 5388: <tagp><type>u32</type> <param>a4</param></tagp>
! 5389: part #4
! 5390: </descrip>
! 5391: <funcsect>Description
! 5392: <p>
! 5393: <func/ipa_build()/ takes <param/a1/ to <param/a4/ and assembles them to a single IPv6
! 5394: address. It's used for example when a protocol wants to bind its
! 5395: socket to a hard-wired multicast address.
! 5396: </function>
! 5397: <function><p><type>char *</type>
! 5398: <funcdef>ip_ntop</funcdef>
! 5399: (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to textual representation
! 5400:
! 5401: <funcsect>Arguments
! 5402: <p><descrip>
! 5403: <tagp><type>ip_addr</type> <param>a</param></tagp>
! 5404: IP address
! 5405: <tagp><type>char *</type> <param>buf</param></tagp>
! 5406: buffer of size at least <const/STD_ADDRESS_P_LENGTH/
! 5407: </descrip>
! 5408: <funcsect>Description
! 5409: <p>
! 5410: This function takes an IP address and creates its textual
! 5411: representation for presenting to the user.
! 5412: </function>
! 5413: <function><p><type>char *</type>
! 5414: <funcdef>ip_ntox</funcdef>
! 5415: (<type>ip_addr</type> <param>a</param>, <type>char *</type> <param>buf</param>) -- convert IP address to hexadecimal representation
! 5416:
! 5417: <funcsect>Arguments
! 5418: <p><descrip>
! 5419: <tagp><type>ip_addr</type> <param>a</param></tagp>
! 5420: IP address
! 5421: <tagp><type>char *</type> <param>buf</param></tagp>
! 5422: buffer of size at least <const/STD_ADDRESS_P_LENGTH/
! 5423: </descrip>
! 5424: <funcsect>Description
! 5425: <p>
! 5426: This function takes an IP address and creates its hexadecimal
! 5427: textual representation. Primary use: debugging dumps.
! 5428: </function>
! 5429: <function><p><type>int</type>
! 5430: <funcdef>ip_pton</funcdef>
! 5431: (<type>char *</type> <param>a</param>, <type>ip_addr *</type> <param>o</param>) -- parse textual representation of IP address
! 5432:
! 5433: <funcsect>Arguments
! 5434: <p><descrip>
! 5435: <tagp><type>char *</type> <param>a</param></tagp>
! 5436: textual representation
! 5437: <tagp><type>ip_addr *</type> <param>o</param></tagp>
! 5438: where to put the resulting address
! 5439: </descrip>
! 5440: <funcsect>Description
! 5441: <p>
! 5442: This function parses a textual IP address representation and
! 5443: stores the decoded address to a variable pointed to by <param/o/.
! 5444: Returns 0 if a parse error has occurred, else 0.
! 5445: </function>
! 5446: <sect>Linked lists
! 5447: <p>
! 5448: <p>
! 5449: The BIRD library provides a set of functions for operating on linked
! 5450: lists. The lists are internally represented as standard doubly linked
! 5451: lists with synthetic head and tail which makes all the basic operations
! 5452: run in constant time and contain no extra end-of-list checks. Each list
! 5453: is described by a <struct/list/ structure, nodes can have any format as long
! 5454: as they start with a <struct/node/ structure. If you want your nodes to belong
! 5455: to multiple lists at once, you can embed multiple <struct/node/ structures in them
! 5456: and use the <func/SKIP_BACK()/ macro to calculate a pointer to the start of the
! 5457: structure from a <struct/node/ pointer, but beware of obscurity.
! 5458: <p>
! 5459: There also exist safe linked lists (<struct/slist/, <struct/snode/ and all functions
! 5460: being prefixed with <tt>s_</tt>) which support asynchronous walking very
! 5461: similar to that used in the <struct/fib/ structure.
! 5462:
! 5463:
! 5464: <function><p><type>LIST_INLINE void</type>
! 5465: <funcdef>add_tail</funcdef>
! 5466: (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- append a node to a list
! 5467:
! 5468: <funcsect>Arguments
! 5469: <p><descrip>
! 5470: <tagp><type>list *</type> <param>l</param></tagp>
! 5471: linked list
! 5472: <tagp><type>node *</type> <param>n</param></tagp>
! 5473: list node
! 5474: </descrip>
! 5475: <funcsect>Description
! 5476: <p>
! 5477: <func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/.
! 5478: </function>
! 5479: <function><p><type>LIST_INLINE void</type>
! 5480: <funcdef>add_head</funcdef>
! 5481: (<type>list *</type> <param>l</param>, <type>node *</type> <param>n</param>) -- prepend a node to a list
! 5482:
! 5483: <funcsect>Arguments
! 5484: <p><descrip>
! 5485: <tagp><type>list *</type> <param>l</param></tagp>
! 5486: linked list
! 5487: <tagp><type>node *</type> <param>n</param></tagp>
! 5488: list node
! 5489: </descrip>
! 5490: <funcsect>Description
! 5491: <p>
! 5492: <func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/.
! 5493: </function>
! 5494: <function><p><type>LIST_INLINE void</type>
! 5495: <funcdef>insert_node</funcdef>
! 5496: (<type>node *</type> <param>n</param>, <type>node *</type> <param>after</param>) -- insert a node to a list
! 5497:
! 5498: <funcsect>Arguments
! 5499: <p><descrip>
! 5500: <tagp><type>node *</type> <param>n</param></tagp>
! 5501: a new list node
! 5502: <tagp><type>node *</type> <param>after</param></tagp>
! 5503: a node of a list
! 5504: </descrip>
! 5505: <funcsect>Description
! 5506: <p>
! 5507: Inserts a node <param/n/ to a linked list after an already inserted
! 5508: node <param/after/.
! 5509: </function>
! 5510: <function><p><type>LIST_INLINE void</type>
! 5511: <funcdef>rem_node</funcdef>
! 5512: (<type>node *</type> <param>n</param>) -- remove a node from a list
! 5513:
! 5514: <funcsect>Arguments
! 5515: <p><descrip>
! 5516: <tagp><type>node *</type> <param>n</param></tagp>
! 5517: node to be removed
! 5518: </descrip>
! 5519: <funcsect>Description
! 5520: <p>
! 5521: Removes a node <param/n/ from the list it's linked in. Afterwards, node <param/n/ is cleared.
! 5522: </function>
! 5523: <function><p><type>LIST_INLINE void</type>
! 5524: <funcdef>replace_node</funcdef>
! 5525: (<type>node *</type> <param>old</param>, <type>node *</type> <param>new</param>) -- replace a node in a list with another one
! 5526:
! 5527: <funcsect>Arguments
! 5528: <p><descrip>
! 5529: <tagp><type>node *</type> <param>old</param></tagp>
! 5530: node to be removed
! 5531: <tagp><type>node *</type> <param>new</param></tagp>
! 5532: node to be inserted
! 5533: </descrip>
! 5534: <funcsect>Description
! 5535: <p>
! 5536: Replaces node <param/old/ in the list it's linked in with node <param/new/. Node
! 5537: <param/old/ may be a copy of the original node, which is not accessed
! 5538: through the list. The function could be called with <param/old/ == <param/new/,
! 5539: which just fixes neighbors' pointers in the case that the node
! 5540: was reallocated.
! 5541: </function>
! 5542: <function><p><type>LIST_INLINE void</type>
! 5543: <funcdef>init_list</funcdef>
! 5544: (<type>list *</type> <param>l</param>) -- create an empty list
! 5545:
! 5546: <funcsect>Arguments
! 5547: <p><descrip>
! 5548: <tagp><type>list *</type> <param>l</param></tagp>
! 5549: list
! 5550: </descrip>
! 5551: <funcsect>Description
! 5552: <p>
! 5553: <func/init_list()/ takes a <struct/list/ structure and initializes its
! 5554: fields, so that it represents an empty list.
! 5555: </function>
! 5556: <function><p><type>LIST_INLINE void</type>
! 5557: <funcdef>add_tail_list</funcdef>
! 5558: (<type>list *</type> <param>to</param>, <type>list *</type> <param>l</param>) -- concatenate two lists
! 5559:
! 5560: <funcsect>Arguments
! 5561: <p><descrip>
! 5562: <tagp><type>list *</type> <param>to</param></tagp>
! 5563: destination list
! 5564: <tagp><type>list *</type> <param>l</param></tagp>
! 5565: source list
! 5566: </descrip>
! 5567: <funcsect>Description
! 5568: <p>
! 5569: This function appends all elements of the list <param/l/ to
! 5570: the list <param/to/ in constant time.
! 5571: </function>
! 5572: <sect>Miscellaneous functions.
! 5573: <p>
! 5574:
! 5575:
! 5576: <function><p><type>int</type>
! 5577: <funcdef>ipsum_verify</funcdef>
! 5578: (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- verify an IP checksum
! 5579:
! 5580: <funcsect>Arguments
! 5581: <p><descrip>
! 5582: <tagp><type>void *</type> <param>frag</param></tagp>
! 5583: first packet fragment
! 5584: <tagp><type>uint</type> <param>len</param></tagp>
! 5585: length in bytes
! 5586: <tagp><type>...</type> <param>...</param></tagp>
! 5587: variable arguments
! 5588: </descrip>
! 5589: <funcsect>Description
! 5590: <p>
! 5591: This function verifies whether a given fragmented packet
! 5592: has correct one's complement checksum as used by the IP
! 5593: protocol.
! 5594: <p>
! 5595: It uses all the clever tricks described in RFC 1071 to speed
! 5596: up checksum calculation as much as possible.
! 5597: <funcsect>Result
! 5598: <p>
! 5599: 1 if the checksum is correct, 0 else.
! 5600: </function>
! 5601: <function><p><type>u16</type>
! 5602: <funcdef>ipsum_calculate</funcdef>
! 5603: (<type>void *</type> <param>frag</param>, <type>uint</type> <param>len</param>, <type>...</type> <param>...</param>) -- compute an IP checksum
! 5604:
! 5605: <funcsect>Arguments
! 5606: <p><descrip>
! 5607: <tagp><type>void *</type> <param>frag</param></tagp>
! 5608: first packet fragment
! 5609: <tagp><type>uint</type> <param>len</param></tagp>
! 5610: length in bytes
! 5611: <tagp><type>...</type> <param>...</param></tagp>
! 5612: variable arguments
! 5613: </descrip>
! 5614: <funcsect>Description
! 5615: <p>
! 5616: This function calculates a one's complement checksum of a given fragmented
! 5617: packet.
! 5618: <p>
! 5619: It uses all the clever tricks described in RFC 1071 to speed
! 5620: up checksum calculation as much as possible.
! 5621: </function>
! 5622: <function><p><type>u32</type>
! 5623: <funcdef>u32_mkmask</funcdef>
! 5624: (<type>uint</type> <param>n</param>) -- create a bit mask
! 5625:
! 5626: <funcsect>Arguments
! 5627: <p><descrip>
! 5628: <tagp><type>uint</type> <param>n</param></tagp>
! 5629: number of bits
! 5630: </descrip>
! 5631: <funcsect>Description
! 5632: <p>
! 5633: <func/u32_mkmask()/ returns an unsigned 32-bit integer which binary
! 5634: representation consists of <param/n/ ones followed by zeroes.
! 5635: </function>
! 5636: <function><p><type>int</type>
! 5637: <funcdef>u32_masklen</funcdef>
! 5638: (<type>u32</type> <param>x</param>) -- calculate length of a bit mask
! 5639:
! 5640: <funcsect>Arguments
! 5641: <p><descrip>
! 5642: <tagp><type>u32</type> <param>x</param></tagp>
! 5643: bit mask
! 5644: </descrip>
! 5645: <funcsect>Description
! 5646: <p>
! 5647: This function checks whether the given integer <param/x/ represents
! 5648: a valid bit mask (binary representation contains first ones, then
! 5649: zeroes) and returns the number of ones or -1 if the mask is invalid.
! 5650: </function>
! 5651: <function><p><type>u32</type>
! 5652: <funcdef>u32_log2</funcdef>
! 5653: (<type>u32</type> <param>v</param>) -- compute a binary logarithm.
! 5654:
! 5655: <funcsect>Arguments
! 5656: <p><descrip>
! 5657: <tagp><type>u32</type> <param>v</param></tagp>
! 5658: number
! 5659: </descrip>
! 5660: <funcsect>Description
! 5661: <p>
! 5662: This function computes a integral part of binary logarithm of given
! 5663: integer <param/v/ and returns it. The computed value is also an index of the
! 5664: most significant non-zero bit position.
! 5665: </function>
! 5666: <function><p><type>int</type>
! 5667: <funcdef>patmatch</funcdef>
! 5668: (<type>byte *</type> <param>p</param>, <type>byte *</type> <param>s</param>) -- match shell-like patterns
! 5669:
! 5670: <funcsect>Arguments
! 5671: <p><descrip>
! 5672: <tagp><type>byte *</type> <param>p</param></tagp>
! 5673: pattern
! 5674: <tagp><type>byte *</type> <param>s</param></tagp>
! 5675: string
! 5676: </descrip>
! 5677: <funcsect>Description
! 5678: <p>
! 5679: <func/patmatch()/ returns whether given string <param/s/ matches the given shell-like
! 5680: pattern <param/p/. The patterns consist of characters (which are matched literally),
! 5681: question marks which match any single character, asterisks which match any
! 5682: (possibly empty) string of characters and backslashes which are used to
! 5683: escape any special characters and force them to be treated literally.
! 5684: <p>
! 5685: The matching process is not optimized with respect to time, so please
! 5686: avoid using this function for complex patterns.
! 5687: </function>
! 5688: <function><p><type>int</type>
! 5689: <funcdef>bvsnprintf</funcdef>
! 5690: (<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) -- BIRD's <func/vsnprintf()/
! 5691:
! 5692: <funcsect>Arguments
! 5693: <p><descrip>
! 5694: <tagp><type>char *</type> <param>buf</param></tagp>
! 5695: destination buffer
! 5696: <tagp><type>int</type> <param>size</param></tagp>
! 5697: size of the buffer
! 5698: <tagp><type>const char *</type> <param>fmt</param></tagp>
! 5699: format string
! 5700: <tagp><type>va_list</type> <param>args</param></tagp>
! 5701: a list of arguments to be formatted
! 5702: </descrip>
! 5703: <funcsect>Description
! 5704: <p>
! 5705: This functions acts like ordinary <func/sprintf()/ except that it checks
! 5706: available space to avoid buffer overflows and it allows some more
! 5707: <funcsect>format specifiers
! 5708: <p>
! 5709: <tt><const/I/</tt> for formatting of IP addresses (any non-zero
! 5710: width is automatically replaced by standard IP address width which
! 5711: depends on whether we use IPv4 or IPv6; <tt>%#I</tt> gives hexadecimal format),
! 5712: <tt><const/R/</tt> for Router / Network ID (u32 value printed as IPv4 address)
! 5713: <tt><const/lR/</tt> for 64bit Router / Network ID (u64 value printed as eight :-separated octets)
! 5714: and <tt><const/m/</tt> resp. <tt><const/M/</tt> for error messages (uses <func/strerror()/ to translate <param/errno/ code to
! 5715: message text). On the other hand, it doesn't support floating
! 5716: point numbers.
! 5717: <funcsect>Result
! 5718: <p>
! 5719: number of characters of the output string or -1 if
! 5720: the buffer space was insufficient.
! 5721: </function>
! 5722: <function><p><type>int</type>
! 5723: <funcdef>bvsprintf</funcdef>
! 5724: (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>va_list</type> <param>args</param>) -- BIRD's <func/vsprintf()/
! 5725:
! 5726: <funcsect>Arguments
! 5727: <p><descrip>
! 5728: <tagp><type>char *</type> <param>buf</param></tagp>
! 5729: buffer
! 5730: <tagp><type>const char *</type> <param>fmt</param></tagp>
! 5731: format string
! 5732: <tagp><type>va_list</type> <param>args</param></tagp>
! 5733: a list of arguments to be formatted
! 5734: </descrip>
! 5735: <funcsect>Description
! 5736: <p>
! 5737: This function is equivalent to <func/bvsnprintf()/ with an infinite
! 5738: buffer size. Please use carefully only when you are absolutely
! 5739: sure the buffer won't overflow.
! 5740: </function>
! 5741: <function><p><type>int</type>
! 5742: <funcdef>bsprintf</funcdef>
! 5743: (<type>char *</type> <param>buf</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) -- BIRD's <func/sprintf()/
! 5744:
! 5745: <funcsect>Arguments
! 5746: <p><descrip>
! 5747: <tagp><type>char *</type> <param>buf</param></tagp>
! 5748: buffer
! 5749: <tagp><type>const char *</type> <param>fmt</param></tagp>
! 5750: format string
! 5751: <tagp><type>...</type> <param>...</param></tagp>
! 5752: variable arguments
! 5753: </descrip>
! 5754: <funcsect>Description
! 5755: <p>
! 5756: This function is equivalent to <func/bvsnprintf()/ with an infinite
! 5757: buffer size and variable arguments instead of a <struct/va_list/.
! 5758: Please use carefully only when you are absolutely
! 5759: sure the buffer won't overflow.
! 5760: </function>
! 5761: <function><p><type>int</type>
! 5762: <funcdef>bsnprintf</funcdef>
! 5763: (<type>char *</type> <param>buf</param>, <type>int</type> <param>size</param>, <type>const char *</type> <param>fmt</param>, <type>...</type> <param>...</param>) -- BIRD's <func/snprintf()/
! 5764:
! 5765: <funcsect>Arguments
! 5766: <p><descrip>
! 5767: <tagp><type>char *</type> <param>buf</param></tagp>
! 5768: buffer
! 5769: <tagp><type>int</type> <param>size</param></tagp>
! 5770: buffer size
! 5771: <tagp><type>const char *</type> <param>fmt</param></tagp>
! 5772: format string
! 5773: <tagp><type>...</type> <param>...</param></tagp>
! 5774: variable arguments
! 5775: </descrip>
! 5776: <funcsect>Description
! 5777: <p>
! 5778: This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/.
! 5779: </function>
! 5780: <function><p><type>void *</type>
! 5781: <funcdef>xmalloc</funcdef>
! 5782: (<type>uint</type> <param>size</param>) -- malloc with checking
! 5783:
! 5784: <funcsect>Arguments
! 5785: <p><descrip>
! 5786: <tagp><type>uint</type> <param>size</param></tagp>
! 5787: block size
! 5788: </descrip>
! 5789: <funcsect>Description
! 5790: <p>
! 5791: This function is equivalent to <func/malloc()/ except that in case of
! 5792: failure it calls <func/die()/ to quit the program instead of returning
! 5793: a <const/NULL/ pointer.
! 5794: <p>
! 5795: Wherever possible, please use the memory resources instead.
! 5796: </function>
! 5797: <function><p><type>void *</type>
! 5798: <funcdef>xrealloc</funcdef>
! 5799: (<type>void *</type> <param>ptr</param>, <type>uint</type> <param>size</param>) -- realloc with checking
! 5800:
! 5801: <funcsect>Arguments
! 5802: <p><descrip>
! 5803: <tagp><type>void *</type> <param>ptr</param></tagp>
! 5804: original memory block
! 5805: <tagp><type>uint</type> <param>size</param></tagp>
! 5806: block size
! 5807: </descrip>
! 5808: <funcsect>Description
! 5809: <p>
! 5810: This function is equivalent to <func/realloc()/ except that in case of
! 5811: failure it calls <func/die()/ to quit the program instead of returning
! 5812: a <const/NULL/ pointer.
! 5813: <p>
! 5814: Wherever possible, please use the memory resources instead.
! 5815: </function>
! 5816: <sect>Message authentication codes
! 5817: <p>
! 5818: <p>
! 5819: MAC algorithms are simple cryptographic tools for message authentication.
! 5820: They use shared a secret key a and message text to generate authentication
! 5821: code, which is then passed with the message to the other side, where the code
! 5822: is verified. There are multiple families of MAC algorithms based on different
! 5823: cryptographic primitives, BIRD implements two MAC families which use hash
! 5824: functions.
! 5825: <p>
! 5826: The first family is simply a cryptographic hash camouflaged as MAC algorithm.
! 5827: Originally supposed to be (m|k)-hash (message is concatenated with key, and
! 5828: that is hashed), but later it turned out that a raw hash is more practical.
! 5829: This is used for cryptographic authentication in OSPFv2, RIP and BFD.
! 5830: <p>
! 5831: The second family is the standard HMAC (RFC 2104), using inner and outer hash
! 5832: to process key and message. HMAC (with SHA) is used in advanced OSPF and RIP
! 5833: authentication (RFC 5709, RFC 4822).
! 5834:
! 5835:
! 5836: <function><p><type>void</type>
! 5837: <funcdef>mac_init</funcdef>
! 5838: (<type>struct mac_context *</type> <param>ctx</param>, <type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>) -- initialize MAC algorithm
! 5839:
! 5840: <funcsect>Arguments
! 5841: <p><descrip>
! 5842: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
! 5843: context to initialize
! 5844: <tagp><type>uint</type> <param>id</param></tagp>
! 5845: MAC algorithm ID
! 5846: <tagp><type>const byte *</type> <param>key</param></tagp>
! 5847: MAC key
! 5848: <tagp><type>uint</type> <param>keylen</param></tagp>
! 5849: MAC key length
! 5850: </descrip>
! 5851: <funcsect>Description
! 5852: <p>
! 5853: Initialize MAC context <param/ctx/ for algorithm <param/id/ (e.g., <const/ALG_HMAC_SHA1/), with
! 5854: key <param/key/ of length <param/keylen/. After that, message data could be added using
! 5855: <func/mac_update()/ function.
! 5856: </function>
! 5857: <function><p><type>void</type>
! 5858: <funcdef>mac_update</funcdef>
! 5859: (<type>struct mac_context *</type> <param>ctx</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>) -- add more data to MAC algorithm
! 5860:
! 5861: <funcsect>Arguments
! 5862: <p><descrip>
! 5863: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
! 5864: MAC context
! 5865: <tagp><type>const byte *</type> <param>data</param></tagp>
! 5866: data to add
! 5867: <tagp><type>uint</type> <param>datalen</param></tagp>
! 5868: length of data
! 5869: </descrip>
! 5870: <funcsect>Description
! 5871: <p>
! 5872: Push another <param/datalen/ bytes of data pointed to by <param/data/ into the MAC
! 5873: algorithm currently in <param/ctx/. Can be called multiple times for the same MAC
! 5874: context. It has the same effect as concatenating all the data together and
! 5875: passing them at once.
! 5876: </function>
! 5877: <function><p><type>byte *</type>
! 5878: <funcdef>mac_final</funcdef>
! 5879: (<type>struct mac_context *</type> <param>ctx</param>) -- finalize MAC algorithm
! 5880:
! 5881: <funcsect>Arguments
! 5882: <p><descrip>
! 5883: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
! 5884: MAC context
! 5885: </descrip>
! 5886: <funcsect>Description
! 5887: <p>
! 5888: Finish MAC computation and return a pointer to the result. No more
! 5889: <param/mac_update/() calls could be done, but the context may be reinitialized
! 5890: later.
! 5891: <p>
! 5892: Note that the returned pointer points into data in the <param/ctx/ context. If it
! 5893: ceases to exist, the pointer becomes invalid.
! 5894: </function>
! 5895: <function><p><type>void</type>
! 5896: <funcdef>mac_cleanup</funcdef>
! 5897: (<type>struct mac_context *</type> <param>ctx</param>) -- cleanup MAC context
! 5898:
! 5899: <funcsect>Arguments
! 5900: <p><descrip>
! 5901: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp>
! 5902: MAC context
! 5903: </descrip>
! 5904: <funcsect>Description
! 5905: <p>
! 5906: Cleanup MAC context after computation (by filling with zeros). Not strictly
! 5907: necessary, just to erase sensitive data from stack. This also invalidates the
! 5908: pointer returned by <param/mac_final/().
! 5909: </function>
! 5910: <function><p><type>void</type>
! 5911: <funcdef>mac_fill</funcdef>
! 5912: (<type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>, <type>byte *</type> <param>mac</param>) -- compute and fill MAC
! 5913:
! 5914: <funcsect>Arguments
! 5915: <p><descrip>
! 5916: <tagp><type>uint</type> <param>id</param></tagp>
! 5917: MAC algorithm ID
! 5918: <tagp><type>const byte *</type> <param>key</param></tagp>
! 5919: secret key
! 5920: <tagp><type>uint</type> <param>keylen</param></tagp>
! 5921: key length
! 5922: <tagp><type>const byte *</type> <param>data</param></tagp>
! 5923: message data
! 5924: <tagp><type>uint</type> <param>datalen</param></tagp>
! 5925: message length
! 5926: <tagp><type>byte *</type> <param>mac</param></tagp>
! 5927: place to fill MAC
! 5928: </descrip>
! 5929: <funcsect>Description
! 5930: <p>
! 5931: Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and
! 5932: copy it to buffer <param/mac/. <func/mac_fill()/ is a shortcut function doing all usual
! 5933: steps for transmitted messages.
! 5934: </function>
! 5935: <function><p><type>int</type>
! 5936: <funcdef>mac_verify</funcdef>
! 5937: (<type>uint</type> <param>id</param>, <type>const byte *</type> <param>key</param>, <type>uint</type> <param>keylen</param>, <type>const byte *</type> <param>data</param>, <type>uint</type> <param>datalen</param>, <type>const byte *</type> <param>mac</param>) -- compute and verify MAC
! 5938:
! 5939: <funcsect>Arguments
! 5940: <p><descrip>
! 5941: <tagp><type>uint</type> <param>id</param></tagp>
! 5942: MAC algorithm ID
! 5943: <tagp><type>const byte *</type> <param>key</param></tagp>
! 5944: secret key
! 5945: <tagp><type>uint</type> <param>keylen</param></tagp>
! 5946: key length
! 5947: <tagp><type>const byte *</type> <param>data</param></tagp>
! 5948: message data
! 5949: <tagp><type>uint</type> <param>datalen</param></tagp>
! 5950: message length
! 5951: <tagp><type>const byte *</type> <param>mac</param></tagp>
! 5952: received MAC
! 5953: </descrip>
! 5954: <funcsect>Description
! 5955: <p>
! 5956: Compute MAC for specified key <param/key/ and message <param/data/ using algorithm <param/id/ and
! 5957: compare it with received <param/mac/, return whether they are the same. <func/mac_verify()/
! 5958: is a shortcut function doing all usual steps for received messages.
! 5959: </function>
! 5960: <!--
! 5961: BIRD Programmer's Guide: Resources
! 5962:
! 5963: (c) 2000 Martin Mares <mj@ucw.cz>
! 5964: -->
! 5965:
! 5966: <chapt>Resources
! 5967:
! 5968: <sect>Introduction
! 5969:
! 5970: <p>Most large software projects implemented in classical procedural
! 5971: programming languages usually end up with lots of code taking care
! 5972: of resource allocation and deallocation. Bugs in such code are often
! 5973: very difficult to find, because they cause only `resource leakage',
! 5974: that is keeping a lot of memory and other resources which nobody
! 5975: references to.
! 5976:
! 5977: <p>We've tried to solve this problem by employing a resource tracking
! 5978: system which keeps track of all the resources allocated by all the
! 5979: modules of BIRD, deallocates everything automatically when a module
! 5980: shuts down and it is able to print out the list of resources and
! 5981: the corresponding modules they are allocated by.
! 5982:
! 5983: <p>Each allocated resource (from now we'll speak about allocated
! 5984: resources only) is represented by a structure starting with a standard
! 5985: header (struct <struct/resource/) consisting of a list node (resources are
! 5986: often linked to various lists) and a pointer to <struct/resclass/ -- a resource
! 5987: class structure pointing to functions implementing generic resource
! 5988: operations (such as freeing of the resource) for the particular resource
! 5989: type.
! 5990:
! 5991: <p>There exist the following types of resources:
! 5992:
! 5993: <itemize>
! 5994: <item><it/Resource pools/ (<struct/pool/)
! 5995: <item><it/Memory blocks/
! 5996: <item><it/Linear memory pools/ (<struct/linpool/)
! 5997: <item><it/Slabs/ (<struct/slab/)
! 5998: <item><it/Events/ (<struct/event/)
! 5999: <item><it/Timers/ (<struct/timer/)
! 6000: <item><it/Sockets/ (<struct/socket/)
! 6001: </itemize>
! 6002: <sect>Resource pools
! 6003: <p>
! 6004: <p>
! 6005: Resource pools (<struct/pool/) are just containers holding a list of
! 6006: other resources. Freeing a pool causes all the listed resources
! 6007: to be freed as well. Each existing <struct/resource/ is linked to some pool
! 6008: except for a root pool which isn't linked anywhere, so all the
! 6009: resources form a tree structure with internal nodes corresponding
! 6010: to pools and leaves being the other resources.
! 6011: <p>
! 6012: Example: Almost all modules of BIRD have their private pool which
! 6013: is freed upon shutdown of the module.
! 6014:
! 6015:
! 6016: <function><p><type>pool *</type>
! 6017: <funcdef>rp_new</funcdef>
! 6018: (<type>pool *</type> <param>p</param>, <type>char *</type> <param>name</param>) -- create a resource pool
! 6019:
! 6020: <funcsect>Arguments
! 6021: <p><descrip>
! 6022: <tagp><type>pool *</type> <param>p</param></tagp>
! 6023: parent pool
! 6024: <tagp><type>char *</type> <param>name</param></tagp>
! 6025: pool name (to be included in debugging dumps)
! 6026: </descrip>
! 6027: <funcsect>Description
! 6028: <p>
! 6029: <func/rp_new()/ creates a new resource pool inside the specified
! 6030: parent pool.
! 6031: </function>
! 6032: <function><p><type>void</type>
! 6033: <funcdef>rmove</funcdef>
! 6034: (<type>void *</type> <param>res</param>, <type>pool *</type> <param>p</param>) -- move a resource
! 6035:
! 6036: <funcsect>Arguments
! 6037: <p><descrip>
! 6038: <tagp><type>void *</type> <param>res</param></tagp>
! 6039: resource
! 6040: <tagp><type>pool *</type> <param>p</param></tagp>
! 6041: pool to move the resource to
! 6042: </descrip>
! 6043: <funcsect>Description
! 6044: <p>
! 6045: <func/rmove()/ moves a resource from one pool to another.
! 6046: </function>
! 6047: <function><p><type>void</type>
! 6048: <funcdef>rfree</funcdef>
! 6049: (<type>void *</type> <param>res</param>) -- free a resource
! 6050:
! 6051: <funcsect>Arguments
! 6052: <p><descrip>
! 6053: <tagp><type>void *</type> <param>res</param></tagp>
! 6054: resource
! 6055: </descrip>
! 6056: <funcsect>Description
! 6057: <p>
! 6058: <func/rfree()/ frees the given resource and all information associated
! 6059: with it. In case it's a resource pool, it also frees all the objects
! 6060: living inside the pool.
! 6061: <p>
! 6062: It works by calling a class-specific freeing function.
! 6063: </function>
! 6064: <function><p><type>void</type>
! 6065: <funcdef>rdump</funcdef>
! 6066: (<type>void *</type> <param>res</param>) -- dump a resource
! 6067:
! 6068: <funcsect>Arguments
! 6069: <p><descrip>
! 6070: <tagp><type>void *</type> <param>res</param></tagp>
! 6071: resource
! 6072: </descrip>
! 6073: <funcsect>Description
! 6074: <p>
! 6075: This function prints out all available information about the given
! 6076: resource to the debugging output.
! 6077: <p>
! 6078: It works by calling a class-specific dump function.
! 6079: </function>
! 6080: <function><p><type>void *</type>
! 6081: <funcdef>ralloc</funcdef>
! 6082: (<type>pool *</type> <param>p</param>, <type>struct resclass *</type> <param>c</param>) -- create a resource
! 6083:
! 6084: <funcsect>Arguments
! 6085: <p><descrip>
! 6086: <tagp><type>pool *</type> <param>p</param></tagp>
! 6087: pool to create the resource in
! 6088: <tagp><type>struct resclass *</type> <param>c</param></tagp>
! 6089: class of the new resource
! 6090: </descrip>
! 6091: <funcsect>Description
! 6092: <p>
! 6093: This function is called by the resource classes to create a new
! 6094: resource of the specified class and link it to the given pool.
! 6095: Allocated memory is zeroed. Size of the resource structure is taken
! 6096: from the <param/size/ field of the <struct/resclass/.
! 6097: </function>
! 6098: <function><p><type>void</type>
! 6099: <funcdef>rlookup</funcdef>
! 6100: (<type>unsigned long</type> <param>a</param>) -- look up a memory location
! 6101:
! 6102: <funcsect>Arguments
! 6103: <p><descrip>
! 6104: <tagp><type>unsigned long</type> <param>a</param></tagp>
! 6105: memory address
! 6106: </descrip>
! 6107: <funcsect>Description
! 6108: <p>
! 6109: This function examines all existing resources to see whether
! 6110: the address <param/a/ is inside any resource. It's used for debugging
! 6111: purposes only.
! 6112: <p>
! 6113: It works by calling a class-specific lookup function for each
! 6114: resource.
! 6115: </function>
! 6116: <function><p><type>void</type>
! 6117: <funcdef>resource_init</funcdef>
! 6118: (<param>void</param>) -- initialize the resource manager
! 6119:
! 6120: <funcsect>Description
! 6121: <p>
! 6122: <p>
! 6123: This function is called during BIRD startup. It initializes
! 6124: all data structures of the resource manager and creates the
! 6125: root pool.
! 6126: </function>
! 6127: <sect>Memory blocks
! 6128: <p>
! 6129: <p>
! 6130: Memory blocks are pieces of contiguous allocated memory.
! 6131: They are a bit non-standard since they are represented not by a pointer
! 6132: to <struct/resource/, but by a void pointer to the start of data of the
! 6133: memory block. All memory block functions know how to locate the header
! 6134: given the data pointer.
! 6135: <p>
! 6136: Example: All "unique" data structures such as hash tables are allocated
! 6137: as memory blocks.
! 6138:
! 6139:
! 6140: <function><p><type>void *</type>
! 6141: <funcdef>mb_alloc</funcdef>
! 6142: (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate a memory block
! 6143:
! 6144: <funcsect>Arguments
! 6145: <p><descrip>
! 6146: <tagp><type>pool *</type> <param>p</param></tagp>
! 6147: pool
! 6148: <tagp><type>unsigned</type> <param>size</param></tagp>
! 6149: size of the block
! 6150: </descrip>
! 6151: <funcsect>Description
! 6152: <p>
! 6153: <func/mb_alloc()/ allocates memory of a given size and creates
! 6154: a memory block resource representing this memory chunk
! 6155: in the pool <param/p/.
! 6156: <p>
! 6157: Please note that <func/mb_alloc()/ returns a pointer to the memory
! 6158: chunk, not to the resource, hence you have to free it using
! 6159: <func/mb_free()/, not <func/rfree()/.
! 6160: </function>
! 6161: <function><p><type>void *</type>
! 6162: <funcdef>mb_allocz</funcdef>
! 6163: (<type>pool *</type> <param>p</param>, <type>unsigned</type> <param>size</param>) -- allocate and clear a memory block
! 6164:
! 6165: <funcsect>Arguments
! 6166: <p><descrip>
! 6167: <tagp><type>pool *</type> <param>p</param></tagp>
! 6168: pool
! 6169: <tagp><type>unsigned</type> <param>size</param></tagp>
! 6170: size of the block
! 6171: </descrip>
! 6172: <funcsect>Description
! 6173: <p>
! 6174: <func/mb_allocz()/ allocates memory of a given size, initializes it to
! 6175: zeroes and creates a memory block resource representing this memory
! 6176: chunk in the pool <param/p/.
! 6177: <p>
! 6178: Please note that <func/mb_allocz()/ returns a pointer to the memory
! 6179: chunk, not to the resource, hence you have to free it using
! 6180: <func/mb_free()/, not <func/rfree()/.
! 6181: </function>
! 6182: <function><p><type>void *</type>
! 6183: <funcdef>mb_realloc</funcdef>
! 6184: (<type>void *</type> <param>m</param>, <type>unsigned</type> <param>size</param>) -- reallocate a memory block
! 6185:
! 6186: <funcsect>Arguments
! 6187: <p><descrip>
! 6188: <tagp><type>void *</type> <param>m</param></tagp>
! 6189: memory block
! 6190: <tagp><type>unsigned</type> <param>size</param></tagp>
! 6191: new size of the block
! 6192: </descrip>
! 6193: <funcsect>Description
! 6194: <p>
! 6195: <func/mb_realloc()/ changes the size of the memory block <param/m/ to a given size.
! 6196: The contents will be unchanged to the minimum of the old and new sizes;
! 6197: newly allocated memory will be uninitialized. Contrary to <func/realloc()/
! 6198: behavior, <param/m/ must be non-NULL, because the resource pool is inherited
! 6199: from it.
! 6200: <p>
! 6201: Like <func/mb_alloc()/, <func/mb_realloc()/ also returns a pointer to the memory
! 6202: chunk, not to the resource, hence you have to free it using
! 6203: <func/mb_free()/, not <func/rfree()/.
! 6204: </function>
! 6205: <function><p><type>void</type>
! 6206: <funcdef>mb_free</funcdef>
! 6207: (<type>void *</type> <param>m</param>) -- free a memory block
! 6208:
! 6209: <funcsect>Arguments
! 6210: <p><descrip>
! 6211: <tagp><type>void *</type> <param>m</param></tagp>
! 6212: memory block
! 6213: </descrip>
! 6214: <funcsect>Description
! 6215: <p>
! 6216: <func/mb_free()/ frees all memory associated with the block <param/m/.
! 6217: </function>
! 6218: <sect>Linear memory pools
! 6219: <p>
! 6220: <p>
! 6221: Linear memory pools are collections of memory blocks which
! 6222: support very fast allocation of new blocks, but are able to free only
! 6223: the whole collection at once.
! 6224: <p>
! 6225: Example: Each configuration is described by a complex system of structures,
! 6226: linked lists and function trees which are all allocated from a single linear
! 6227: pool, thus they can be freed at once when the configuration is no longer used.
! 6228:
! 6229:
! 6230: <function><p><type>linpool *</type>
! 6231: <funcdef>lp_new</funcdef>
! 6232: (<type>pool *</type> <param>p</param>, <type>uint</type> <param>blk</param>) -- create a new linear memory pool
! 6233:
! 6234: <funcsect>Arguments
! 6235: <p><descrip>
! 6236: <tagp><type>pool *</type> <param>p</param></tagp>
! 6237: pool
! 6238: <tagp><type>uint</type> <param>blk</param></tagp>
! 6239: block size
! 6240: </descrip>
! 6241: <funcsect>Description
! 6242: <p>
! 6243: <func/lp_new()/ creates a new linear memory pool resource inside the pool <param/p/.
! 6244: The linear pool consists of a list of memory chunks of size at least
! 6245: <param/blk/.
! 6246: </function>
! 6247: <function><p><type>void *</type>
! 6248: <funcdef>lp_alloc</funcdef>
! 6249: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate memory from a <struct/linpool/
! 6250:
! 6251: <funcsect>Arguments
! 6252: <p><descrip>
! 6253: <tagp><type>linpool *</type> <param>m</param></tagp>
! 6254: linear memory pool
! 6255: <tagp><type>uint</type> <param>size</param></tagp>
! 6256: amount of memory
! 6257: </descrip>
! 6258: <funcsect>Description
! 6259: <p>
! 6260: <func/lp_alloc()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
! 6261: and it returns a pointer to the allocated memory.
! 6262: <p>
! 6263: It works by trying to find free space in the last memory chunk
! 6264: associated with the <struct/linpool/ and creating a new chunk of the standard
! 6265: size (as specified during <func/lp_new()/) if the free space is too small
! 6266: to satisfy the allocation. If <param/size/ is too large to fit in a standard
! 6267: size chunk, an "overflow" chunk is created for it instead.
! 6268: </function>
! 6269: <function><p><type>void *</type>
! 6270: <funcdef>lp_allocu</funcdef>
! 6271: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate unaligned memory from a <struct/linpool/
! 6272:
! 6273: <funcsect>Arguments
! 6274: <p><descrip>
! 6275: <tagp><type>linpool *</type> <param>m</param></tagp>
! 6276: linear memory pool
! 6277: <tagp><type>uint</type> <param>size</param></tagp>
! 6278: amount of memory
! 6279: </descrip>
! 6280: <funcsect>Description
! 6281: <p>
! 6282: <func/lp_allocu()/ allocates <param/size/ bytes of memory from a <struct/linpool/ <param/m/
! 6283: and it returns a pointer to the allocated memory. It doesn't
! 6284: attempt to align the memory block, giving a very efficient way
! 6285: how to allocate strings without any space overhead.
! 6286: </function>
! 6287: <function><p><type>void *</type>
! 6288: <funcdef>lp_allocz</funcdef>
! 6289: (<type>linpool *</type> <param>m</param>, <type>uint</type> <param>size</param>) -- allocate cleared memory from a <struct/linpool/
! 6290:
! 6291: <funcsect>Arguments
! 6292: <p><descrip>
! 6293: <tagp><type>linpool *</type> <param>m</param></tagp>
! 6294: linear memory pool
! 6295: <tagp><type>uint</type> <param>size</param></tagp>
! 6296: amount of memory
! 6297: </descrip>
! 6298: <funcsect>Description
! 6299: <p>
! 6300: This function is identical to <func/lp_alloc()/ except that it
! 6301: clears the allocated memory block.
! 6302: </function>
! 6303: <function><p><type>void</type>
! 6304: <funcdef>lp_flush</funcdef>
! 6305: (<type>linpool *</type> <param>m</param>) -- flush a linear memory pool
! 6306:
! 6307: <funcsect>Arguments
! 6308: <p><descrip>
! 6309: <tagp><type>linpool *</type> <param>m</param></tagp>
! 6310: linear memory pool
! 6311: </descrip>
! 6312: <funcsect>Description
! 6313: <p>
! 6314: This function frees the whole contents of the given <struct/linpool/ <param/m/,
! 6315: but leaves the pool itself.
! 6316: </function>
! 6317: <sect>Slabs
! 6318: <p>
! 6319: <p>
! 6320: Slabs are collections of memory blocks of a fixed size.
! 6321: They support very fast allocation and freeing of such blocks, prevent memory
! 6322: fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
! 6323: and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
! 6324: Memory Allocator'. Our implementation follows this article except that we don't use
! 6325: constructors and destructors.
! 6326: <p>
! 6327: When the <tt>DEBUGGING</tt> switch is turned on, we automatically fill all
! 6328: newly allocated and freed blocks with a special pattern to make detection
! 6329: of use of uninitialized or already freed memory easier.
! 6330: <p>
! 6331: Example: Nodes of a FIB are allocated from a per-FIB Slab.
! 6332:
! 6333:
! 6334: <function><p><type>slab *</type>
! 6335: <funcdef>sl_new</funcdef>
! 6336: (<type>pool *</type> <param>p</param>, <type>uint</type> <param>size</param>) -- create a new Slab
! 6337:
! 6338: <funcsect>Arguments
! 6339: <p><descrip>
! 6340: <tagp><type>pool *</type> <param>p</param></tagp>
! 6341: resource pool
! 6342: <tagp><type>uint</type> <param>size</param></tagp>
! 6343: block size
! 6344: </descrip>
! 6345: <funcsect>Description
! 6346: <p>
! 6347: This function creates a new Slab resource from which
! 6348: objects of size <param/size/ can be allocated.
! 6349: </function>
! 6350: <function><p><type>void *</type>
! 6351: <funcdef>sl_alloc</funcdef>
! 6352: (<type>slab *</type> <param>s</param>) -- allocate an object from Slab
! 6353:
! 6354: <funcsect>Arguments
! 6355: <p><descrip>
! 6356: <tagp><type>slab *</type> <param>s</param></tagp>
! 6357: slab
! 6358: </descrip>
! 6359: <funcsect>Description
! 6360: <p>
! 6361: <func/sl_alloc()/ allocates space for a single object from the
! 6362: Slab and returns a pointer to the object.
! 6363: </function>
! 6364: <function><p><type>void</type>
! 6365: <funcdef>sl_free</funcdef>
! 6366: (<type>slab *</type> <param>s</param>, <type>void *</type> <param>oo</param>) -- return a free object back to a Slab
! 6367:
! 6368: <funcsect>Arguments
! 6369: <p><descrip>
! 6370: <tagp><type>slab *</type> <param>s</param></tagp>
! 6371: slab
! 6372: <tagp><type>void *</type> <param>oo</param></tagp>
! 6373: object returned by <func/sl_alloc()/
! 6374: </descrip>
! 6375: <funcsect>Description
! 6376: <p>
! 6377: This function frees memory associated with the object <param/oo/
! 6378: and returns it back to the Slab <param/s/.
! 6379: </function>
! 6380: <sect>Events
! 6381: <p>
! 6382: <p>
! 6383: Events are there to keep track of deferred execution.
! 6384: Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
! 6385: parts, so that no module can monopolize the CPU. To split such a task, just create
! 6386: an <struct/event/ resource, point it to the function you want to have called and call <func/ev_schedule()/
! 6387: to ask the core to run the event when nothing more important requires attention.
! 6388: <p>
! 6389: You can also define your own event lists (the <struct/event_list/ structure), enqueue your
! 6390: events in them and explicitly ask to run them.
! 6391:
! 6392:
! 6393: <function><p><type>event *</type>
! 6394: <funcdef>ev_new</funcdef>
! 6395: (<type>pool *</type> <param>p</param>) -- create a new event
! 6396:
! 6397: <funcsect>Arguments
! 6398: <p><descrip>
! 6399: <tagp><type>pool *</type> <param>p</param></tagp>
! 6400: resource pool
! 6401: </descrip>
! 6402: <funcsect>Description
! 6403: <p>
! 6404: This function creates a new event resource. To use it,
! 6405: you need to fill the structure fields and call <func/ev_schedule()/.
! 6406: </function>
! 6407: <function><p><type>void</type>
! 6408: <funcdef>ev_run</funcdef>
! 6409: (<type>event *</type> <param>e</param>) -- run an event
! 6410:
! 6411: <funcsect>Arguments
! 6412: <p><descrip>
! 6413: <tagp><type>event *</type> <param>e</param></tagp>
! 6414: an event
! 6415: </descrip>
! 6416: <funcsect>Description
! 6417: <p>
! 6418: This function explicitly runs the event <param/e/ (calls its hook
! 6419: function) and removes it from an event list if it's linked to any.
! 6420: <p>
! 6421: From the hook function, you can call <func/ev_enqueue()/ or <func/ev_schedule()/
! 6422: to re-add the event.
! 6423: </function>
! 6424: <function><p><type>void</type>
! 6425: <funcdef>ev_enqueue</funcdef>
! 6426: (<type>event_list *</type> <param>l</param>, <type>event *</type> <param>e</param>) -- enqueue an event
! 6427:
! 6428: <funcsect>Arguments
! 6429: <p><descrip>
! 6430: <tagp><type>event_list *</type> <param>l</param></tagp>
! 6431: an event list
! 6432: <tagp><type>event *</type> <param>e</param></tagp>
! 6433: an event
! 6434: </descrip>
! 6435: <funcsect>Description
! 6436: <p>
! 6437: <func/ev_enqueue()/ stores the event <param/e/ to the specified event
! 6438: list <param/l/ which can be run by calling <func/ev_run_list()/.
! 6439: </function>
! 6440: <function><p><type>void</type>
! 6441: <funcdef>ev_schedule</funcdef>
! 6442: (<type>event *</type> <param>e</param>) -- schedule an event
! 6443:
! 6444: <funcsect>Arguments
! 6445: <p><descrip>
! 6446: <tagp><type>event *</type> <param>e</param></tagp>
! 6447: an event
! 6448: </descrip>
! 6449: <funcsect>Description
! 6450: <p>
! 6451: This function schedules an event by enqueueing it to a system-wide
! 6452: event list which is run by the platform dependent code whenever
! 6453: appropriate.
! 6454: </function>
! 6455: <function><p><type>int</type>
! 6456: <funcdef>ev_run_list</funcdef>
! 6457: (<type>event_list *</type> <param>l</param>) -- run an event list
! 6458:
! 6459: <funcsect>Arguments
! 6460: <p><descrip>
! 6461: <tagp><type>event_list *</type> <param>l</param></tagp>
! 6462: an event list
! 6463: </descrip>
! 6464: <funcsect>Description
! 6465: <p>
! 6466: This function calls <func/ev_run()/ for all events enqueued in the list <param/l/.
! 6467: </function>
! 6468: <sect>Timers
! 6469: <p>
! 6470: <p>
! 6471: Timers are resources which represent a wish of a module to call
! 6472: a function at the specified time. The platform dependent code
! 6473: doesn't guarantee exact timing, only that a timer function
! 6474: won't be called before the requested time.
! 6475: <p>
! 6476: In BIRD, time is represented by values of the <struct/bird_clock_t/ type
! 6477: which are integral numbers interpreted as a relative number of seconds since
! 6478: some fixed time point in past. The current time can be read
! 6479: from variable <param/now/ with reasonable accuracy and is monotonic. There is also
! 6480: a current 'absolute' time in variable <param/now_real/ reported by OS.
! 6481: <p>
! 6482: Each timer is described by a <struct/timer/ structure containing a pointer
! 6483: to the handler function (<param/hook/), data private to this function (<param/data/),
! 6484: time the function should be called at (<param/expires/, 0 for inactive timers),
! 6485: for the other fields see <tt>timer.h</tt>.
! 6486:
! 6487:
! 6488: <function><p><type>timer *</type>
! 6489: <funcdef>tm_new</funcdef>
! 6490: (<type>pool *</type> <param>p</param>) -- create a timer
! 6491:
! 6492: <funcsect>Arguments
! 6493: <p><descrip>
! 6494: <tagp><type>pool *</type> <param>p</param></tagp>
! 6495: pool
! 6496: </descrip>
! 6497: <funcsect>Description
! 6498: <p>
! 6499: This function creates a new timer resource and returns
! 6500: a pointer to it. To use the timer, you need to fill in
! 6501: the structure fields and call <func/tm_start()/ to start timing.
! 6502: </function>
! 6503: <function><p><type>void</type>
! 6504: <funcdef>tm_start</funcdef>
! 6505: (<type>timer *</type> <param>t</param>, <type>unsigned</type> <param>after</param>) -- start a timer
! 6506:
! 6507: <funcsect>Arguments
! 6508: <p><descrip>
! 6509: <tagp><type>timer *</type> <param>t</param></tagp>
! 6510: timer
! 6511: <tagp><type>unsigned</type> <param>after</param></tagp>
! 6512: number of seconds the timer should be run after
! 6513: </descrip>
! 6514: <funcsect>Description
! 6515: <p>
! 6516: This function schedules the hook function of the timer to
! 6517: be called after <param/after/ seconds. If the timer has been already
! 6518: started, it's <param/expire/ time is replaced by the new value.
! 6519: <p>
! 6520: You can have set the <param/randomize/ field of <param/t/, the timeout
! 6521: will be increased by a random number of seconds chosen
! 6522: uniformly from range 0 .. <param/randomize/.
! 6523: <p>
! 6524: You can call <func/tm_start()/ from the handler function of the timer
! 6525: to request another run of the timer. Also, you can set the <param/recurrent/
! 6526: field to have the timer re-added automatically with the same timeout.
! 6527: </function>
! 6528: <function><p><type>void</type>
! 6529: <funcdef>tm_stop</funcdef>
! 6530: (<type>timer *</type> <param>t</param>) -- stop a timer
! 6531:
! 6532: <funcsect>Arguments
! 6533: <p><descrip>
! 6534: <tagp><type>timer *</type> <param>t</param></tagp>
! 6535: timer
! 6536: </descrip>
! 6537: <funcsect>Description
! 6538: <p>
! 6539: This function stops a timer. If the timer is already stopped,
! 6540: nothing happens.
! 6541: </function>
! 6542: <function><p><type>bird_clock_t</type>
! 6543: <funcdef>tm_parse_datetime</funcdef>
! 6544: (<type>char *</type> <param>x</param>) -- parse a date and time
! 6545:
! 6546: <funcsect>Arguments
! 6547: <p><descrip>
! 6548: <tagp><type>char *</type> <param>x</param></tagp>
! 6549: datetime string
! 6550: </descrip>
! 6551: <funcsect>Description
! 6552: <p>
! 6553: <func/tm_parse_datetime()/ takes a textual representation of
! 6554: a date and time (dd-mm-yyyy hh:mm:ss)
! 6555: and converts it to the corresponding value of type <struct/bird_clock_t/.
! 6556: </function>
! 6557: <function><p><type>bird_clock_t</type>
! 6558: <funcdef>tm_parse_date</funcdef>
! 6559: (<type>char *</type> <param>x</param>) -- parse a date
! 6560:
! 6561: <funcsect>Arguments
! 6562: <p><descrip>
! 6563: <tagp><type>char *</type> <param>x</param></tagp>
! 6564: date string
! 6565: </descrip>
! 6566: <funcsect>Description
! 6567: <p>
! 6568: <func/tm_parse_date()/ takes a textual representation of a date (dd-mm-yyyy)
! 6569: and converts it to the corresponding value of type <struct/bird_clock_t/.
! 6570: </function>
! 6571: <function><p><type>void</type>
! 6572: <funcdef>tm_format_datetime</funcdef>
! 6573: (<type>char *</type> <param>x</param>, <type>struct timeformat *</type> <param>fmt_spec</param>, <type>bird_clock_t</type> <param>t</param>) -- convert date and time to textual representation
! 6574:
! 6575: <funcsect>Arguments
! 6576: <p><descrip>
! 6577: <tagp><type>char *</type> <param>x</param></tagp>
! 6578: destination buffer of size <const/TM_DATETIME_BUFFER_SIZE/
! 6579: <tagp><type>struct timeformat *</type> <param>fmt_spec</param></tagp>
! 6580: specification of resulting textual representation of the time
! 6581: <tagp><type>bird_clock_t</type> <param>t</param></tagp>
! 6582: time
! 6583: </descrip>
! 6584: <funcsect>Description
! 6585: <p>
! 6586: This function formats the given relative time value <param/t/ to a textual
! 6587: date/time representation (dd-mm-yyyy hh:mm:ss) in real time.
! 6588: </function>
! 6589: <sect>Sockets
! 6590: <p>
! 6591: <p>
! 6592: Socket resources represent network connections. Their data structure (<struct/socket/)
! 6593: contains a lot of fields defining the exact type of the socket, the local and
! 6594: remote addresses and ports, pointers to socket buffers and finally pointers to
! 6595: hook functions to be called when new data have arrived to the receive buffer
! 6596: (<param/rx_hook/), when the contents of the transmit buffer have been transmitted
! 6597: (<param/tx_hook/) and when an error or connection close occurs (<param/err_hook/).
! 6598: <p>
! 6599: Freeing of sockets from inside socket hooks is perfectly safe.
! 6600:
! 6601:
! 6602: <function><p><type>int</type>
! 6603: <funcdef>sk_setup_multicast</funcdef>
! 6604: (<type>sock *</type> <param>s</param>) -- enable multicast for given socket
! 6605:
! 6606: <funcsect>Arguments
! 6607: <p><descrip>
! 6608: <tagp><type>sock *</type> <param>s</param></tagp>
! 6609: socket
! 6610: </descrip>
! 6611: <funcsect>Description
! 6612: <p>
! 6613: Prepare transmission of multicast packets for given datagram socket.
! 6614: The socket must have defined <param/iface/.
! 6615: <funcsect>Result
! 6616: <p>
! 6617: 0 for success, -1 for an error.
! 6618: </function>
! 6619: <function><p><type>int</type>
! 6620: <funcdef>sk_join_group</funcdef>
! 6621: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- join multicast group for given socket
! 6622:
! 6623: <funcsect>Arguments
! 6624: <p><descrip>
! 6625: <tagp><type>sock *</type> <param>s</param></tagp>
! 6626: socket
! 6627: <tagp><type>ip_addr</type> <param>maddr</param></tagp>
! 6628: multicast address
! 6629: </descrip>
! 6630: <funcsect>Description
! 6631: <p>
! 6632: Join multicast group for given datagram socket and associated interface.
! 6633: The socket must have defined <param/iface/.
! 6634: <funcsect>Result
! 6635: <p>
! 6636: 0 for success, -1 for an error.
! 6637: </function>
! 6638: <function><p><type>int</type>
! 6639: <funcdef>sk_leave_group</funcdef>
! 6640: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>maddr</param>) -- leave multicast group for given socket
! 6641:
! 6642: <funcsect>Arguments
! 6643: <p><descrip>
! 6644: <tagp><type>sock *</type> <param>s</param></tagp>
! 6645: socket
! 6646: <tagp><type>ip_addr</type> <param>maddr</param></tagp>
! 6647: multicast address
! 6648: </descrip>
! 6649: <funcsect>Description
! 6650: <p>
! 6651: Leave multicast group for given datagram socket and associated interface.
! 6652: The socket must have defined <param/iface/.
! 6653: <funcsect>Result
! 6654: <p>
! 6655: 0 for success, -1 for an error.
! 6656: </function>
! 6657: <function><p><type>int</type>
! 6658: <funcdef>sk_setup_broadcast</funcdef>
! 6659: (<type>sock *</type> <param>s</param>) -- enable broadcast for given socket
! 6660:
! 6661: <funcsect>Arguments
! 6662: <p><descrip>
! 6663: <tagp><type>sock *</type> <param>s</param></tagp>
! 6664: socket
! 6665: </descrip>
! 6666: <funcsect>Description
! 6667: <p>
! 6668: Allow reception and transmission of broadcast packets for given datagram
! 6669: socket. The socket must have defined <param/iface/. For transmission, packets should
! 6670: be send to <param/brd/ address of <param/iface/.
! 6671: <funcsect>Result
! 6672: <p>
! 6673: 0 for success, -1 for an error.
! 6674: </function>
! 6675: <function><p><type>int</type>
! 6676: <funcdef>sk_set_ttl</funcdef>
! 6677: (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set transmit TTL for given socket
! 6678:
! 6679: <funcsect>Arguments
! 6680: <p><descrip>
! 6681: <tagp><type>sock *</type> <param>s</param></tagp>
! 6682: socket
! 6683: <tagp><type>int</type> <param>ttl</param></tagp>
! 6684: TTL value
! 6685: </descrip>
! 6686: <funcsect>Description
! 6687: <p>
! 6688: Set TTL for already opened connections when TTL was not set before. Useful
! 6689: for accepted connections when different ones should have different TTL.
! 6690: <funcsect>Result
! 6691: <p>
! 6692: 0 for success, -1 for an error.
! 6693: </function>
! 6694: <function><p><type>int</type>
! 6695: <funcdef>sk_set_min_ttl</funcdef>
! 6696: (<type>sock *</type> <param>s</param>, <type>int</type> <param>ttl</param>) -- set minimal accepted TTL for given socket
! 6697:
! 6698: <funcsect>Arguments
! 6699: <p><descrip>
! 6700: <tagp><type>sock *</type> <param>s</param></tagp>
! 6701: socket
! 6702: <tagp><type>int</type> <param>ttl</param></tagp>
! 6703: TTL value
! 6704: </descrip>
! 6705: <funcsect>Description
! 6706: <p>
! 6707: Set minimal accepted TTL for given socket. Can be used for TTL security.
! 6708: implementations.
! 6709: <funcsect>Result
! 6710: <p>
! 6711: 0 for success, -1 for an error.
! 6712: </function>
! 6713: <function><p><type>int</type>
! 6714: <funcdef>sk_set_md5_auth</funcdef>
! 6715: (<type>sock *</type> <param>s</param>, <type>ip_addr</type> <param>local</param>, <type>ip_addr</type> <param>remote</param>, <type>struct iface *</type> <param>ifa</param>, <type>char *</type> <param>passwd</param>, <type>int</type> <param>setkey</param>) -- add / remove MD5 security association for given socket
! 6716:
! 6717: <funcsect>Arguments
! 6718: <p><descrip>
! 6719: <tagp><type>sock *</type> <param>s</param></tagp>
! 6720: socket
! 6721: <tagp><type>ip_addr</type> <param>local</param></tagp>
! 6722: IP address of local side
! 6723: <tagp><type>ip_addr</type> <param>remote</param></tagp>
! 6724: IP address of remote side
! 6725: <tagp><type>struct iface *</type> <param>ifa</param></tagp>
! 6726: Interface for link-local IP address
! 6727: <tagp><type>char *</type> <param>passwd</param></tagp>
! 6728: Password used for MD5 authentication
! 6729: <tagp><type>int</type> <param>setkey</param></tagp>
! 6730: Update also system SA/SP database
! 6731: </descrip>
! 6732: <funcsect>Description
! 6733: <p>
! 6734: In TCP MD5 handling code in kernel, there is a set of security associations
! 6735: used for choosing password and other authentication parameters according to
! 6736: the local and remote address. This function is useful for listening socket,
! 6737: for active sockets it may be enough to set s->password field.
! 6738: <p>
! 6739: When called with passwd != NULL, the new pair is added,
! 6740: When called with passwd == NULL, the existing pair is removed.
! 6741: <p>
! 6742: Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are
! 6743: stored in global SA/SP database (but the behavior also must be enabled on
! 6744: per-socket basis). In case of multiple sockets to the same neighbor, the
! 6745: socket-specific state must be configured for each socket while global state
! 6746: just once per src-dst pair. The <param/setkey/ argument controls whether the global
! 6747: state (SA/SP database) is also updated.
! 6748: <funcsect>Result
! 6749: <p>
! 6750: 0 for success, -1 for an error.
! 6751: </function>
! 6752: <function><p><type>int</type>
! 6753: <funcdef>sk_set_ipv6_checksum</funcdef>
! 6754: (<type>sock *</type> <param>s</param>, <type>int</type> <param>offset</param>) -- specify IPv6 checksum offset for given socket
! 6755:
! 6756: <funcsect>Arguments
! 6757: <p><descrip>
! 6758: <tagp><type>sock *</type> <param>s</param></tagp>
! 6759: socket
! 6760: <tagp><type>int</type> <param>offset</param></tagp>
! 6761: offset
! 6762: </descrip>
! 6763: <funcsect>Description
! 6764: <p>
! 6765: Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the
! 6766: kernel will automatically fill it for outgoing packets and check it for
! 6767: incoming packets. Should not be used on ICMPv6 sockets, where the position is
! 6768: known to the kernel.
! 6769: <funcsect>Result
! 6770: <p>
! 6771: 0 for success, -1 for an error.
! 6772: </function>
! 6773: <function><p><type>sock *</type>
! 6774: <funcdef>sock_new</funcdef>
! 6775: (<type>pool *</type> <param>p</param>) -- create a socket
! 6776:
! 6777: <funcsect>Arguments
! 6778: <p><descrip>
! 6779: <tagp><type>pool *</type> <param>p</param></tagp>
! 6780: pool
! 6781: </descrip>
! 6782: <funcsect>Description
! 6783: <p>
! 6784: This function creates a new socket resource. If you want to use it,
! 6785: you need to fill in all the required fields of the structure and
! 6786: call <func/sk_open()/ to do the actual opening of the socket.
! 6787: <p>
! 6788: The real function name is <func/sock_new()/, <func/sk_new()/ is a macro wrapper
! 6789: to avoid collision with OpenSSL.
! 6790: </function>
! 6791: <function><p><type>int</type>
! 6792: <funcdef>sk_open</funcdef>
! 6793: (<type>sock *</type> <param>s</param>) -- open a socket
! 6794:
! 6795: <funcsect>Arguments
! 6796: <p><descrip>
! 6797: <tagp><type>sock *</type> <param>s</param></tagp>
! 6798: socket
! 6799: </descrip>
! 6800: <funcsect>Description
! 6801: <p>
! 6802: This function takes a socket resource created by <func/sk_new()/ and
! 6803: initialized by the user and binds a corresponding network connection
! 6804: to it.
! 6805: <funcsect>Result
! 6806: <p>
! 6807: 0 for success, -1 for an error.
! 6808: </function>
! 6809: <function><p><type>int</type>
! 6810: <funcdef>sk_send</funcdef>
! 6811: (<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>) -- send data to a socket
! 6812:
! 6813: <funcsect>Arguments
! 6814: <p><descrip>
! 6815: <tagp><type>sock *</type> <param>s</param></tagp>
! 6816: socket
! 6817: <tagp><type>unsigned</type> <param>len</param></tagp>
! 6818: number of bytes to send
! 6819: </descrip>
! 6820: <funcsect>Description
! 6821: <p>
! 6822: This function sends <param/len/ bytes of data prepared in the
! 6823: transmit buffer of the socket <param/s/ to the network connection.
! 6824: If the packet can be sent immediately, it does so and returns
! 6825: 1, else it queues the packet for later processing, returns 0
! 6826: and calls the <param/tx_hook/ of the socket when the tranmission
! 6827: takes place.
! 6828: </function>
! 6829: <function><p><type>int</type>
! 6830: <funcdef>sk_send_to</funcdef>
! 6831: (<type>sock *</type> <param>s</param>, <type>unsigned</type> <param>len</param>, <type>ip_addr</type> <param>addr</param>, <type>unsigned</type> <param>port</param>) -- send data to a specific destination
! 6832:
! 6833: <funcsect>Arguments
! 6834: <p><descrip>
! 6835: <tagp><type>sock *</type> <param>s</param></tagp>
! 6836: socket
! 6837: <tagp><type>unsigned</type> <param>len</param></tagp>
! 6838: number of bytes to send
! 6839: <tagp><type>ip_addr</type> <param>addr</param></tagp>
! 6840: IP address to send the packet to
! 6841: <tagp><type>unsigned</type> <param>port</param></tagp>
! 6842: port to send the packet to
! 6843: </descrip>
! 6844: <funcsect>Description
! 6845: <p>
! 6846: This is a <func/sk_send()/ replacement for connection-less packet sockets
! 6847: which allows destination of the packet to be chosen dynamically.
! 6848: Raw IP sockets should use 0 for <param/port/.
! 6849: </function>
! 6850: <function><p><type>void</type>
! 6851: <funcdef>io_log_event</funcdef>
! 6852: (<type>void *</type> <param>hook</param>, <type>void *</type> <param>data</param>) -- mark approaching event into event log
! 6853:
! 6854: <funcsect>Arguments
! 6855: <p><descrip>
! 6856: <tagp><type>void *</type> <param>hook</param></tagp>
! 6857: event hook address
! 6858: <tagp><type>void *</type> <param>data</param></tagp>
! 6859: event data address
! 6860: </descrip>
! 6861: <funcsect>Description
! 6862: <p>
! 6863: Store info (hook, data, timestamp) about the following internal event into
! 6864: a circular event log (<param/event_log/). When latency tracking is enabled, the log
! 6865: entry is kept open (in <param/event_open/) so the duration can be filled later.
! 6866: </function>
! 6867:
! 6868: </book>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog.sgml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / doc