embedaddon/bird2/doc/prog.sgml - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird2 / doc / prog.sgml
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Mon Oct 21 16:03:57 2019 UTC (4 years, 8 months ago) by misho
Branches: bird2, MAIN
CVS tags: v2_0_7p0, HEAD

bird2 ver 2.0.7

1: <!doctype birddoc system> 2: 3:  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:  25: <toc> 26: 27:  28: <chapt>BIRD Design 29: 30: <sect>Introduction 31: 32: 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: 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: 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: 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: 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: The modules are statically linked to produce a single executable file 157: (except for the client which stands on its own). 158: 159: The building process is controlled by a set of Makefiles for GNU Make, 160: intermixed with several Perl and shell scripts. 161: 162: 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: The parser of the configuration is generated by the GNU Bison. 168: 169: 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: 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: 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:  188: <chapt>Core 189: <sect>Forwarding Information Base 190: 191: 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: 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: 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: 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: 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: 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: 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><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: <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: 256: This function initializes a newly allocated FIB and prepares it for use. 257: </function> 258: <function><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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><type>void</type> 331: <funcdef>fib_free</funcdef> 332: (<type>struct fib *</type> <param>f</param>) -- delete a FIB 333: 334: <funcsect>Arguments 335: <descrip> 336: <tagp><type>struct fib *</type> <param>f</param></tagp> 337: FIB to be deleted 338: </descrip> 339: <funcsect>Description 340: 341: This function deletes a FIB -- it frees all memory associated 342: with it and all its entries. 343: </function> 344: <function><type>void</type> 345: <funcdef>fib_check</funcdef> 346: (<type>struct fib *</type> <param>f</param>) -- audit a FIB 347: 348: <funcsect>Arguments 349: <descrip> 350: <tagp><type>struct fib *</type> <param>f</param></tagp> 351: FIB to be checked 352: </descrip> 353: <funcsect>Description 354: 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: 360: 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: 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: 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><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: <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: 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><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: <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: 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><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: <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: 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: 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: 438: a pointer to the new writable <struct/rte/ with writable <struct/rta/. 439: </function> 440: <function><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: <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: 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: 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: 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: 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><type>void</type> 487: <funcdef>rte_free</funcdef> 488: (<type>rte *</type> <param>e</param>) -- delete a <struct/rte/ 489: 490: <funcsect>Arguments 491: <descrip> 492: <tagp><type>rte *</type> <param>e</param></tagp> 493: <struct/rte/ to be deleted 494: </descrip> 495: <funcsect>Description 496: 497: <func/rte_free()/ deletes the given <struct/rte/ from the routing table it's linked to. 498: </function> 499: <function><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: <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: 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: 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: 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: 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: 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><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: <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: 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><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: <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: 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><type>void</type> 587: <funcdef>rte_dump</funcdef> 588: (<type>rte *</type> <param>e</param>) -- dump a route 589: 590: <funcsect>Arguments 591: <descrip> 592: <tagp><type>rte *</type> <param>e</param></tagp> 593: <struct/rte/ to be dumped 594: </descrip> 595: <funcsect>Description 596: 597: This functions dumps contents of a <struct/rte/ to debug output. 598: </function> 599: <function><type>void</type> 600: <funcdef>rt_dump</funcdef> 601: (<type>rtable *</type> <param>t</param>) -- dump a routing table 602: 603: <funcsect>Arguments 604: <descrip> 605: <tagp><type>rtable *</type> <param>t</param></tagp> 606: routing table to be dumped 607: </descrip> 608: <funcsect>Description 609: 610: This function dumps contents of a given routing table to debug output. 611: </function> 612: <function><type>void</type> 613: <funcdef>rt_dump_all</funcdef> 614: (<param>void</param>) -- dump all routing tables 615: 616: <funcsect>Description 617: 618: 619: This function dumps contents of all routing tables to debug output. 620: </function> 621: <function><type>void</type> 622: <funcdef>rt_init</funcdef> 623: (<param>void</param>) -- initialize routing tables 624: 625: <funcsect>Description 626: 627: 628: This function is called during BIRD startup. It initializes the 629: routing table module. 630: </function> 631: <function><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: <descrip> 637: <tagp><type>rtable *</type> <param>tab</param></tagp> 638: a routing table for pruning 639: </descrip> 640: <funcsect>Description 641: 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: 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><type>int</type> 653: <funcdef>rt_prune_loop</funcdef> 654: (<param>void</param>) -- prune routing tables 655: 656: <funcsect>Description 657: 658: 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><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: <descrip> 669: <tagp><type>rtable *</type> <param>r</param></tagp> 670: routing table to be locked 671: </descrip> 672: <funcsect>Description 673: 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><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: <descrip> 684: <tagp><type>rtable *</type> <param>r</param></tagp> 685: routing table to be unlocked 686: </descrip> 687: <funcsect>Description 688: 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><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: <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: 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><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: <descrip> 719: <tagp><type>struct proto *</type> <param>p</param></tagp> 720: protocol to be fed 721: </descrip> 722: <funcsect>Description 723: 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><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: <descrip> 735: <tagp><type>struct proto *</type> <param>p</param></tagp> 736: protocol 737: </descrip> 738: <funcsect>Description 739: 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><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: <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: 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><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: <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: 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><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: <descrip> 788: <tagp><type>rte *</type> <param>r</param></tagp> 789: a route entry to be copied 790: </descrip> 791: <funcsect>Description 792: 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: 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: 805: a pointer to the new writable <struct/rte/. 806: </function> 807: <sect>Route attribute cache 808: 809: 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: 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: 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: 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: 842: Routing tables always contain only cached <struct/rta/'s. 843: 844: 845: <function><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: <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: 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: 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><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: <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: 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><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: <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: 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: 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><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: <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: 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><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: <descrip> 947: <tagp><type>ea_list *</type> <param>e</param></tagp> 948: list to be sorted 949: </descrip> 950: <funcsect>Description 951: 952: This function takes a <struct/ea_list/ chain and sorts the attributes 953: within each of its entries. 954: 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><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: <descrip> 964: <tagp><type>ea_list *</type> <param>e</param></tagp> 965: attribute list 966: </descrip> 967: <funcsect>Description 968: 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><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: <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: 985: This function takes a possibly multi-segment attribute list 986: and merges all of its segments to one. 987: 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><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: <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: 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><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: <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: 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: 1026: If the protocol defining the attribute provides its own 1027: <func/get_attr()/ hook, it's consulted first. 1028: </function> 1029: <function><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: <descrip> 1035: <tagp><type>ea_list *</type> <param>e</param></tagp> 1036: attribute to be dumped 1037: </descrip> 1038: <funcsect>Description 1039: 1040: <func/ea_dump()/ dumps contents of the extended attribute given to 1041: the debug output. 1042: </function> 1043: <function><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: <descrip> 1049: <tagp><type>ea_list *</type> <param>e</param></tagp> 1050: attribute list 1051: </descrip> 1052: <funcsect>Description 1053: 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><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: <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: 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><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: <descrip> 1079: <tagp><type>rta *</type> <param>o</param></tagp> 1080: a un-cached <struct/rta/ 1081: </descrip> 1082: <funcsect>Description 1083: 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: 1090: The extended attribute lists attached to the <struct/rta/ are automatically 1091: converted to the normalized form. 1092: </function> 1093: <function><type>void</type> 1094: <funcdef>rta_dump</funcdef> 1095: (<type>rta *</type> <param>a</param>) -- dump route attributes 1096: 1097: <funcsect>Arguments 1098: <descrip> 1099: <tagp><type>rta *</type> <param>a</param></tagp> 1100: attribute structure to dump 1101: </descrip> 1102: <funcsect>Description 1103: 1104: This function takes a <struct/rta/ and dumps its contents to the debug output. 1105: </function> 1106: <function><type>void</type> 1107: <funcdef>rta_dump_all</funcdef> 1108: (<param>void</param>) -- dump attribute cache 1109: 1110: <funcsect>Description 1111: 1112: 1113: This function dumps the whole contents of route attribute cache 1114: to the debug output. 1115: </function> 1116: <function><type>void</type> 1117: <funcdef>rta_init</funcdef> 1118: (<param>void</param>) -- initialize route attribute cache 1119: 1120: <funcsect>Description 1121: 1122: 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><type>rta *</type> 1127: <funcdef>rta_clone</funcdef> 1128: (<type>rta *</type> <param>r</param>) -- clone route attributes 1129: 1130: <funcsect>Arguments 1131: <descrip> 1132: <tagp><type>rta *</type> <param>r</param></tagp> 1133: a <struct/rta/ to be cloned 1134: </descrip> 1135: <funcsect>Description 1136: 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><type>void</type> 1142: <funcdef>rta_free</funcdef> 1143: (<type>rta *</type> <param>r</param>) -- free route attributes 1144: 1145: <funcsect>Arguments 1146: <descrip> 1147: <tagp><type>rta *</type> <param>r</param></tagp> 1148: a <struct/rta/ to be freed 1149: </descrip> 1150: <funcsect>Description 1151: 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:  1162: 1163: <sect>Routing protocols 1164: 1165: <sect1>Introduction 1166: 1167: 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: 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: 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: 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: 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: 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: 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: 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: At any time, the core code can ask the protocol to shut itself down by calling its stop() hook. 1227: 1228: 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: The protocol module provides the following functions: 1248: <function><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: <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: 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><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: <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: 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: 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: 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><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: <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: 1313: Returns pointer to announce hook or NULL 1314: </function> 1315: <function><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: <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: 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: 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><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: <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: 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><type>void</type> 1361: <funcdef>protos_preconfig</funcdef> 1362: (<type>struct config *</type> <param>c</param>) -- pre-configuration processing 1363: 1364: <funcsect>Arguments 1365: <descrip> 1366: <tagp><type>struct config *</type> <param>c</param></tagp> 1367: new configuration 1368: </descrip> 1369: <funcsect>Description 1370: 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><type>void</type> 1376: <funcdef>protos_postconfig</funcdef> 1377: (<type>struct config *</type> <param>c</param>) -- post-configuration processing 1378: 1379: <funcsect>Arguments 1380: <descrip> 1381: <tagp><type>struct config *</type> <param>c</param></tagp> 1382: new configuration 1383: </descrip> 1384: <funcsect>Description 1385: 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><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: <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: 1408: Scan differences between <param/old/ and <param/new/ configuration and adjust all 1409: protocol instances to conform to the new configuration. 1410: 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: 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: 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: 1430: 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: 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: 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: 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><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: 1464: 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><type>void</type> 1470: <funcdef>graceful_restart_init</funcdef> 1471: (<param>void</param>) -- initialize graceful restart 1472: 1473: <funcsect>Description 1474: 1475: 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><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: <descrip> 1486: <tagp><type>struct timer *t</type> <param>UNUSED</param></tagp> 1487: -- undescribed -- 1488: </descrip> 1489: <funcsect>Description 1490: 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><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: <descrip> 1503: <tagp><type>struct proto *</type> <param>p</param></tagp> 1504: protocol instance 1505: </descrip> 1506: <funcsect>Description 1507: 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: 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><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: <descrip> 1523: <tagp><type>struct proto *</type> <param>p</param></tagp> 1524: protocol instance 1525: </descrip> 1526: <funcsect>Description 1527: 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><type>void</type> 1532: <funcdef>protos_dump_all</funcdef> 1533: (<param>void</param>) -- dump status of all protocols 1534: 1535: <funcsect>Description 1536: 1537: 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><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: <descrip> 1550: <tagp><type>struct protocol *</type> <param>p</param></tagp> 1551: the protocol 1552: </descrip> 1553: <funcsect>Description 1554: 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><type>void</type> 1560: <funcdef>protos_build</funcdef> 1561: (<param>void</param>) -- build a protocol list 1562: 1563: <funcsect>Description 1564: 1565: 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><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: <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: 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><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: <descrip> 1600: <tagp><type>struct proto *</type> <param>p</param></tagp> 1601: given protocol 1602: </descrip> 1603: <funcsect>Description 1604: 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><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: <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: 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><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: <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: 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: 1656: 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><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: <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: 1677: The <func/preconfig()/ hook is called before parsing of a new configuration. 1678: </function> 1679: <function><type>void</type> 1680: <funcdef>postconfig</funcdef> 1681: (<type>struct proto_config *</type> <param>c</param>) -- instance post-configuration 1682: 1683: <funcsect>Arguments 1684: <descrip> 1685: <tagp><type>struct proto_config *</type> <param>c</param></tagp> 1686: instance configuration 1687: </descrip> 1688: <funcsect>Description 1689: 1690: The <func/postconfig()/ hook is called for each configured instance after 1691: parsing of the new configuration is finished. 1692: </function> 1693: <function><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: <descrip> 1699: <tagp><type>struct proto_config *</type> <param>c</param></tagp> 1700: instance configuration 1701: </descrip> 1702: <funcsect>Description 1703: 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: 1708: a pointer to the instance created 1709: </function> 1710: <function><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: <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: 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: 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><type>void</type> 1733: <funcdef>dump</funcdef> 1734: (<type>struct proto *</type> <param>p</param>) -- dump protocol state 1735: 1736: <funcsect>Arguments 1737: <descrip> 1738: <tagp><type>struct proto *</type> <param>p</param></tagp> 1739: an instance 1740: </descrip> 1741: <funcsect>Description 1742: 1743: This hook dumps the complete state of the instance to the 1744: debug output. 1745: </function> 1746: <function><type>void</type> 1747: <funcdef>dump_attrs</funcdef> 1748: (<type>rte *</type> <param>e</param>) -- dump protocol-dependent attributes 1749: 1750: <funcsect>Arguments 1751: <descrip> 1752: <tagp><type>rte *</type> <param>e</param></tagp> 1753: a route entry 1754: </descrip> 1755: <funcsect>Description 1756: 1757: This hook dumps all attributes in the <struct/rte/ which belong to this 1758: protocol to the debug output. 1759: </function> 1760: <function><type>int</type> 1761: <funcdef>start</funcdef> 1762: (<type>struct proto *</type> <param>p</param>) -- request instance startup 1763: 1764: <funcsect>Arguments 1765: <descrip> 1766: <tagp><type>struct proto *</type> <param>p</param></tagp> 1767: protocol instance 1768: </descrip> 1769: <funcsect>Description 1770: 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: 1775: new protocol state 1776: </function> 1777: <function><type>int</type> 1778: <funcdef>shutdown</funcdef> 1779: (<type>struct proto *</type> <param>p</param>) -- request instance shutdown 1780: 1781: <funcsect>Arguments 1782: <descrip> 1783: <tagp><type>struct proto *</type> <param>p</param></tagp> 1784: protocol instance 1785: </descrip> 1786: <funcsect>Description 1787: 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: 1792: new protocol state 1793: </function> 1794: <function><type>void</type> 1795: <funcdef>cleanup</funcdef> 1796: (<type>struct proto *</type> <param>p</param>) -- request instance cleanup 1797: 1798: <funcsect>Arguments 1799: <descrip> 1800: <tagp><type>struct proto *</type> <param>p</param></tagp> 1801: protocol instance 1802: </descrip> 1803: <funcsect>Description 1804: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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: 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: 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: 1938: <param/p/->accept_ra_types specifies which kind of route announcements 1939: protocol wants to receive. 1940: </function> 1941: <function><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: <descrip> 1947: <tagp><type>neighbor *</type> <param>neigh</param></tagp> 1948: a neighbor cache entry 1949: </descrip> 1950: <funcsect>Description 1951: 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><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: <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: 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><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: <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: 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: 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><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: <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: 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: 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: 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><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: <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: 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: 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><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: <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: 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: 2074: 1 if <param/new/ is better (more preferred) than <param/old/, 0 otherwise. 2075: </function> 2076: <function><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: <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: 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: 2095: 1 if <param/e1/ is identical to <param/e2/, 0 otherwise. 2096: </function> 2097: <function><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: <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: 2110: This hook is called whenever a <struct/rte/ belonging to the instance 2111: is accepted for insertion to a routing table. 2112: 2113: Please avoid using this function in new protocols. 2114: </function> 2115: <function><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: <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: 2128: This hook is called whenever a <struct/rte/ belonging to the instance 2129: is removed from a routing table. 2130: 2131: Please avoid using this function in new protocols. 2132: </function> 2133: <sect>Interfaces 2134: 2135: 2136: The interface module keeps track of all network interfaces in the 2137: system and their addresses. 2138: 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: 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><type>void</type> 2151: <funcdef>ifa_dump</funcdef> 2152: (<type>struct ifa *</type> <param>a</param>) -- dump interface address 2153: 2154: <funcsect>Arguments 2155: <descrip> 2156: <tagp><type>struct ifa *</type> <param>a</param></tagp> 2157: interface address descriptor 2158: </descrip> 2159: <funcsect>Description 2160: 2161: This function dumps contents of an <struct/ifa/ to the debug output. 2162: </function> 2163: <function><type>void</type> 2164: <funcdef>if_dump</funcdef> 2165: (<type>struct iface *</type> <param>i</param>) -- dump interface 2166: 2167: <funcsect>Arguments 2168: <descrip> 2169: <tagp><type>struct iface *</type> <param>i</param></tagp> 2170: interface to dump 2171: </descrip> 2172: <funcsect>Description 2173: 2174: This function dumps all information associated with a given 2175: network interface to the debug output. 2176: </function> 2177: <function><type>void</type> 2178: <funcdef>if_dump_all</funcdef> 2179: (<param>void</param>) -- dump all interfaces 2180: 2181: <funcsect>Description 2182: 2183: 2184: This function dumps information about all known network 2185: interfaces to the debug output. 2186: </function> 2187: <function><type>void</type> 2188: <funcdef>if_delete</funcdef> 2189: (<type>struct iface *</type> <param>old</param>) -- remove interface 2190: 2191: <funcsect>Arguments 2192: <descrip> 2193: <tagp><type>struct iface *</type> <param>old</param></tagp> 2194: interface 2195: </descrip> 2196: <funcsect>Description 2197: 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><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: <descrip> 2208: <tagp><type>struct iface *</type> <param>new</param></tagp> 2209: new interface status 2210: </descrip> 2211: <funcsect>Description 2212: 2213: <func/if_update()/ is called by the low-level platform dependent code 2214: whenever it notices an interface change. 2215: 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: 2223: <func/if_update()/ will automatically notify all other modules about the change. 2224: </function> 2225: <function><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: <descrip> 2231: <tagp><type>struct proto *</type> <param>p</param></tagp> 2232: protocol to feed 2233: </descrip> 2234: <funcsect>Description 2235: 2236: When a new protocol starts, this function sends it a series 2237: of notifications about all existing interfaces. 2238: </function> 2239: <function><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: <descrip> 2245: <tagp><type>unsigned</type> <param>idx</param></tagp> 2246: ifindex 2247: </descrip> 2248: <funcsect>Description 2249: 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><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: <descrip> 2260: <tagp><type>char *</type> <param>name</param></tagp> 2261: interface name 2262: </descrip> 2263: <funcsect>Description 2264: 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><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: <descrip> 2275: <tagp><type>struct ifa *</type> <param>a</param></tagp> 2276: new interface address 2277: </descrip> 2278: <funcsect>Description 2279: 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><type>void</type> 2285: <funcdef>ifa_delete</funcdef> 2286: (<type>struct ifa *</type> <param>a</param>) -- remove interface address 2287: 2288: <funcsect>Arguments 2289: <descrip> 2290: <tagp><type>struct ifa *</type> <param>a</param></tagp> 2291: interface address 2292: </descrip> 2293: <funcsect>Description 2294: 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><type>void</type> 2300: <funcdef>if_init</funcdef> 2301: (<param>void</param>) -- initialize interface module 2302: 2303: <funcsect>Description 2304: 2305: 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: 2311: 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: 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: 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: 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><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: <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: 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><type>void</type> 2365: <funcdef>neigh_dump</funcdef> 2366: (<type>neighbor *</type> <param>n</param>) -- dump specified neighbor entry. 2367: 2368: <funcsect>Arguments 2369: <descrip> 2370: <tagp><type>neighbor *</type> <param>n</param></tagp> 2371: the entry to dump 2372: </descrip> 2373: <funcsect>Description 2374: 2375: This functions dumps the contents of a given neighbor entry 2376: to debug output. 2377: </function> 2378: <function><type>void</type> 2379: <funcdef>neigh_dump_all</funcdef> 2380: (<param>void</param>) -- dump all neighbor entries. 2381: 2382: <funcsect>Description 2383: 2384: 2385: This function dumps the contents of the neighbor cache to 2386: debug output. 2387: </function> 2388: <function><type>void</type> 2389: <funcdef>neigh_if_up</funcdef> 2390: (<type>struct iface *</type> <param>i</param>) 2391: <funcsect>Arguments 2392: <descrip> 2393: <tagp><type>struct iface *</type> <param>i</param></tagp> 2394: interface in question 2395: </descrip> 2396: <funcsect>Description 2397: 2398: Tell the neighbor cache that a new interface became up. 2399: 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><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: <descrip> 2409: <tagp><type>struct iface *</type> <param>i</param></tagp> 2410: the interface in question 2411: </descrip> 2412: <funcsect>Description 2413: 2414: Notify the neighbor cache that an interface has ceased to exist. 2415: 2416: It causes all entries belonging to neighbors connected to this interface 2417: to be flushed. 2418: </function> 2419: <function><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: <descrip> 2425: <tagp><type>struct iface *</type> <param>i</param></tagp> 2426: the interface in question 2427: </descrip> 2428: <funcsect>Description 2429: 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><type>void</type> 2435: <funcdef>neigh_ifa_update</funcdef> 2436: (<type>struct ifa *</type> <param>a</param>) 2437: <funcsect>Arguments 2438: <descrip> 2439: <tagp><type>struct ifa *</type> <param>a</param></tagp> 2440: interface address in question 2441: </descrip> 2442: <funcsect>Description 2443: 2444: Tell the neighbor cache that an address was added or removed. 2445: 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><type>void</type> 2451: <funcdef>neigh_prune</funcdef> 2452: (<param>void</param>) -- prune neighbor cache 2453: 2454: <funcsect>Description 2455: 2456: 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><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: <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: 2472: This function is called during BIRD startup to initialize 2473: the neighbor cache module. 2474: </function> 2475: <sect>Command line interface 2476: 2477: 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: 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: 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: 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: 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: 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: 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><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: <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: 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: 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: 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><type>void</type> 2561: <funcdef>cli_init</funcdef> 2562: (<param>void</param>) -- initialize the CLI module 2563: 2564: <funcsect>Description 2565: 2566: 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: 2572: 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: 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: 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><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: <descrip> 2599: <tagp><type>pool *</type> <param>p</param></tagp> 2600: resource pool to create the lock in. 2601: </descrip> 2602: <funcsect>Description 2603: 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><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: <descrip> 2614: <tagp><type>struct object_lock *</type> <param>l</param></tagp> 2615: the lock to acquire 2616: </descrip> 2617: <funcsect>Description 2618: 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: 2624: When you want to release the resource, just <func/rfree()/ the lock. 2625: </function> 2626: <function><type>void</type> 2627: <funcdef>olock_init</funcdef> 2628: (<param>void</param>) -- initialize the object lock mechanism 2629: 2630: <funcsect>Description 2631: 2632: 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: 2639: 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: 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: 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: 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: 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><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: <descrip> 2677: <tagp><type>const byte *</type> <param>name</param></tagp> 2678: name of the config 2679: </descrip> 2680: <funcsect>Description 2681: 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><type>int</type> 2687: <funcdef>config_parse</funcdef> 2688: (<type>struct config *</type> <param>c</param>) -- parse a configuration 2689: 2690: <funcsect>Arguments 2691: <descrip> 2692: <tagp><type>struct config *</type> <param>c</param></tagp> 2693: configuration 2694: </descrip> 2695: <funcsect>Description 2696: 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: 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><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: <descrip> 2713: <tagp><type>struct config *</type> <param>c</param></tagp> 2714: temporary config structure 2715: </descrip> 2716: <funcsect>Description 2717: 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><type>void</type> 2722: <funcdef>config_free</funcdef> 2723: (<type>struct config *</type> <param>c</param>) -- free a configuration 2724: 2725: <funcsect>Arguments 2726: <descrip> 2727: <tagp><type>struct config *</type> <param>c</param></tagp> 2728: configuration to be freed 2729: </descrip> 2730: <funcsect>Description 2731: 2732: This function takes a <struct/config/ structure and frees all resources 2733: associated with it. 2734: </function> 2735: <function><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: <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: 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: 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: 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><type>int</type> 2773: <funcdef>config_confirm</funcdef> 2774: (<param>void</param>) -- confirm a commited configuration 2775: 2776: <funcsect>Description 2777: 2778: 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: 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><type>int</type> 2788: <funcdef>config_undo</funcdef> 2789: (<param>void</param>) -- undo a configuration 2790: 2791: <funcsect>Description 2792: 2793: 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: 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><type>void</type> 2814: <funcdef>order_shutdown</funcdef> 2815: (<param>void</param>) -- order BIRD shutdown 2816: 2817: <funcsect>Description 2818: 2819: 2820: This function initiates shutdown of BIRD. It's accomplished by asking 2821: for switching to an empty configuration. 2822: </function> 2823: <function><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: <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: 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><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: <descrip> 2846: <tagp><type>const char *</type> <param>c</param></tagp> 2847: string to copy 2848: </descrip> 2849: <funcsect>Description 2850: 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: 2858: 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: 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: 2870: The keyword tables are generated from the grammar templates 2871: using the <tt>gen_keywords.m4</tt> script. 2872: 2873: 2874: <function><type>void</type> 2875: <funcdef>cf_lex_unwind</funcdef> 2876: (<param>void</param>) -- unwind lexer state during error 2877: 2878: <funcsect>Lexical analyzer 2879: 2880: 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><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: <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: 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><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: <descrip> 2909: <tagp><type>byte *</type> <param>c</param></tagp> 2910: symbol name 2911: </descrip> 2912: <funcsect>Description 2913: 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><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: <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: 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: 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><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: <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: 2957: <func/cf_lex_init()/ initializes the lexical analyzer and prepares it for 2958: parsing of a new input. 2959: </function> 2960: <function><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: <descrip> 2966: <tagp><type>struct symbol *</type> <param>sym</param></tagp> 2967: symbol representing scope name 2968: </descrip> 2969: <funcsect>Description 2970: 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><type>void</type> 2978: <funcdef>cf_pop_scope</funcdef> 2979: (<param>void</param>) -- leave a scope 2980: 2981: <funcsect>Description 2982: 2983: 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><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: <descrip> 2994: <tagp><type>struct symbol *</type> <param>sym</param></tagp> 2995: symbol 2996: </descrip> 2997: <funcsect>Description 2998: 2999: This function returns a string representing the class 3000: of the given symbol. 3001: </function> 3002: <sect>Parser 3003: 3004: 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: 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: 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: 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: 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: 3036: 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: 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: 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><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: <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: 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><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: <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: 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><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: <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: 3104: Checks if <param/v1/ is element (<tt>~</tt> operator) of <param/v2/. 3105: </function> 3106: <function><type>struct f_val</type> 3107: <funcdef>interpret</funcdef> 3108: (<type>struct f_inst *</type> <param>what</param>) 3109: <funcsect>Arguments 3110: <descrip> 3111: <tagp><type>struct f_inst *</type> <param>what</param></tagp> 3112: filter to interpret 3113: </descrip> 3114: <funcsect>Description 3115: 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: 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: 3127: <struct/f_val/ structures are copied around, so there are no problems with 3128: memory managment. 3129: </function> 3130: <function><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: <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: 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: 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: 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><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: <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: 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><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: <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: 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: 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><type>struct f_tree *</type> 3204: <funcdef>build_tree</funcdef> 3205: (<type>struct f_tree *</type> <param>from</param>) 3206: <funcsect>Arguments 3207: <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: 3213: Transforms degenerated tree into balanced tree. 3214: </function> 3215: <function><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: <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: 3227: Compares two trees and returns 1 if they are same 3228: </function> 3229: <sect>Trie for prefix sets 3230: 3231: 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: 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: 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: 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: 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: 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: 3280: There are four cases when we walk through a trie: 3281: 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: 3288: The walking code in <func/trie_match_prefix()/ is structured according to 3289: these cases. 3290: 3291: 3292: <function><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: <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><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: <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: 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: 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><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: <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: 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><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: <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: 3360: Compares two tries and returns 1 if they are same 3361: </function> 3362: <function><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: <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: 3374: Prints the trie to the supplied buffer. 3375: </function> 3376: <chapt>Protocols 3377: <sect>The Babel protocol 3378: 3379: 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: 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: 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: 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><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: <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: 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><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: <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: 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: 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: 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><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: <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: 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><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: <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: 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><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: <descrip> 3485: <tagp><type>timer *</type> <param>t</param></tagp> 3486: Timer 3487: </descrip> 3488: <funcsect>Description 3489: 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: 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: 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><type>void</type> 3508: <funcdef>babel_timer</funcdef> 3509: (<type>timer *</type> <param>t</param>) -- global timer hook 3510: 3511: <funcsect>Arguments 3512: <descrip> 3513: <tagp><type>timer *</type> <param>t</param></tagp> 3514: Timer 3515: </descrip> 3516: <funcsect>Description 3517: 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><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: <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: 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: 3542: The TLVs in the queue are freed after they are written to the buffer. 3543: </function> 3544: <function><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: <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: 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><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: <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: 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><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: <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: 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: 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: 3610: 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: 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: 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: 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: 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: 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: 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: 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: 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: 3696: TODO: document functions and access restrictions for fields in BFD structures. 3697: 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: 3707: 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: 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: 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: 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: 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: 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: 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><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: <descrip> 3768: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3769: BGP instance 3770: </descrip> 3771: <funcsect>Description 3772: 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><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: <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: 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><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: <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: 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><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: <descrip> 3819: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> 3820: connection to close 3821: </descrip> 3822: <funcsect>Description 3823: 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><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: <descrip> 3833: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3834: BGP instance 3835: </descrip> 3836: <funcsect>Description 3837: 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: 3842: It should be called when BGP protocol error happened. 3843: </function> 3844: <function><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: <descrip> 3850: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3851: BGP instance 3852: </descrip> 3853: <funcsect>Description 3854: 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><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: <descrip> 3868: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3869: BGP instance 3870: </descrip> 3871: <funcsect>Description 3872: 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><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: <descrip> 3885: <tagp><type>timer *</type> <param>t</param></tagp> 3886: timer 3887: </descrip> 3888: <funcsect>Description 3889: 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><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: <descrip> 3900: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3901: BGP instance 3902: </descrip> 3903: <funcsect>Description 3904: 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><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: <descrip> 3917: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3918: BGP instance 3919: </descrip> 3920: <funcsect>Description 3921: 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><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: <descrip> 3933: <tagp><type>struct bgp_proto *</type> <param>p</param></tagp> 3934: BGP instance 3935: </descrip> 3936: <funcsect>Description 3937: 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><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: <descrip> 3948: <tagp><type>sock *</type> <param>sk</param></tagp> 3949: TCP socket 3950: </descrip> 3951: </function> 3952: <function><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: <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: 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><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: <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: 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><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: <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: 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><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: <descrip> 4021: <tagp><type>struct bgp_conn *</type> <param>conn</param></tagp> 4022: connection 4023: </descrip> 4024: <funcsect>Description 4025: 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><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: <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: 4045: Schedule a packet of type <param/type/ to be sent as soon as possible. 4046: </function> 4047: <function><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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: 4120: Length of the attribute block generated or -1 if not enough space. 4121: </function> 4122: <function><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: <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: 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: 4147: 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: 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: 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: 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: 4179: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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><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: <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><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: <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: 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><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: <descrip> 4302: <tagp><type>struct proto *</type> <param>P</param></tagp> 4303: OSPF protocol instance 4304: </descrip> 4305: <funcsect>Description 4306: 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><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: <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: 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><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: <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: 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: 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><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: <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: 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: 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><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: <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: 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><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: <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: 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><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: <descrip> 4438: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> 4439: OSPF protocol instance 4440: </descrip> 4441: <funcsect>Description 4442: 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: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <descrip> 4545: <tagp><type>struct ospf_iface *</type> <param>ifa</param></tagp> 4546: actual interface 4547: </descrip> 4548: <funcsect>Description 4549: 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><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: <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: 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><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: <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: 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><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: <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: 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><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: <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: 4626: Checks internal structure of given LSA body (minimal length, 4627: consistency). Returns true if valid. 4628: </function> 4629: <function><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: <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: 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><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: <descrip> 4654: <tagp><type>struct ospf_proto *</type> <param>p</param></tagp> 4655: OSPF protocol instance 4656: </descrip> 4657: <funcsect>Description 4658: 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: 4665: 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: 4671: To avoid pipe loops, Pipe keeps a `being updated' flag in each routing 4672: table. 4673: 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: 4689: 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: 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: 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: 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: 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: 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: 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: 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: 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><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: <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: 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><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: <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: 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><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: <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: 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><type>void</type> 4814: <funcdef>rip_timer</funcdef> 4815: (<type>timer *</type> <param>t</param>) -- RIP main timer hook 4816: 4817: <funcsect>Arguments 4818: <descrip> 4819: <tagp><type>timer *</type> <param>t</param></tagp> 4820: timer 4821: </descrip> 4822: <funcsect>Description 4823: 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: 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: 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><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: <descrip> 4847: <tagp><type>timer *</type> <param>t</param></tagp> 4848: timer 4849: </descrip> 4850: <funcsect>Description 4851: 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><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: <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: 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: 4884: 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: 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: 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: 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: 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: 4915: 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: 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: 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: 4943: 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:  4953: 4954: <chapt>System dependent parts 4955: 4956: <sect>Introduction 4957: 4958: 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: 4977: 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><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: <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: 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: 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><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: <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: 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><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: <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: 5038: This function logs an internal error and aborts execution 5039: of the program. 5040: </function> 5041: <function><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: <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: 5054: This function logs a fatal error and aborts execution 5055: of the program. 5056: </function> 5057: <function><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: <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: 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: 5075: 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: 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: 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: 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: 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: 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: 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: 5115: 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><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: <descrip> 5128: <tagp><type>uint</type> <param>scope</param></tagp> 5129: scope (<const/SCOPE_xxx/) 5130: </descrip> 5131: <funcsect>Description 5132: 5133: Returns a pointer to a textual name of the scope given. 5134: </function> 5135: <function><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: <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: 5148: <func/ipa_equal()/ returns 1 if <param/x/ and <param/y/ represent the same IP address, else 0. 5149: </function> 5150: <function><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: <descrip> 5156: <tagp><type>ip_addr</type> <param>x</param></tagp> 5157: IP address 5158: </descrip> 5159: <funcsect>Description 5160: 5161: ipa_nonzero returns 1 if <param/x/ is a defined IP address (not all bits are zero), 5162: else 0. 5163: 5164: The undefined all-zero address is reachable as a <tt>IPA_NONE</tt> macro. 5165: </function> 5166: <function><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: <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: 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><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: <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: 5195: This function returns a bitwise or of <param/x/ and <param/y/. 5196: </function> 5197: <function><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: <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: 5210: This function returns a bitwise xor of <param/x/ and <param/y/. 5211: </function> 5212: <function><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: <descrip> 5218: <tagp><type>ip_addr</type> <param>x</param></tagp> 5219: IP address 5220: </descrip> 5221: <funcsect>Description 5222: 5223: This function returns a bitwise negation of <param/x/. 5224: </function> 5225: <function><type>ip_addr</type> 5226: <funcdef>ipa_mkmask</funcdef> 5227: (<type>int</type> <param>x</param>) -- create a netmask 5228: 5229: <funcsect>Arguments 5230: <descrip> 5231: <tagp><type>int</type> <param>x</param></tagp> 5232: prefix length 5233: </descrip> 5234: <funcsect>Description 5235: 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><type>int</type> 5240: <funcdef>ipa_masklen</funcdef> 5241: (<type>ip_addr</type> <param>x</param>) -- calculate netmask length 5242: 5243: <funcsect>Arguments 5244: <descrip> 5245: <tagp><type>ip_addr</type> <param>x</param></tagp> 5246: IP address 5247: </descrip> 5248: <funcsect>Description 5249: 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><type>int</type> 5255: <funcdef>ipa_hash</funcdef> 5256: (<type>ip_addr</type> <param>x</param>) -- hash IP addresses 5257: 5258: <funcsect>Arguments 5259: <descrip> 5260: <tagp><type>ip_addr</type> <param>x</param></tagp> 5261: IP address 5262: </descrip> 5263: <funcsect>Description 5264: 5265: <func/ipa_hash()/ returns a 16-bit hash value of the IP address <param/x/. 5266: </function> 5267: <function><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: <descrip> 5273: <tagp><type>ip_addr</type> <param>x</param></tagp> 5274: IP address 5275: </descrip> 5276: <funcsect>Description 5277: 5278: Converts the IP address <param/x/ to the network byte order. 5279: 5280: Beware, this is a macro and it alters the argument! 5281: </function> 5282: <function><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: <descrip> 5288: <tagp><type>ip_addr</type> <param>x</param></tagp> 5289: IP address 5290: </descrip> 5291: <funcsect>Description 5292: 5293: Converts the IP address <param/x/ from the network byte order. 5294: 5295: Beware, this is a macro and it alters the argument! 5296: </function> 5297: <function><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: <descrip> 5303: <tagp><type>ip_addr</type> <param>x</param></tagp> 5304: IP address 5305: </descrip> 5306: <funcsect>Description 5307: 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><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: <descrip> 5319: <tagp><type>ip4_addr</type> <param>x</param></tagp> 5320: IPv4 address 5321: </descrip> 5322: <funcsect>Description 5323: 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><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: <descrip> 5336: <tagp><type>ip_addr</type> <param>x</param></tagp> 5337: IP address 5338: </descrip> 5339: <funcsect>Description 5340: 5341: This function takes an IPv4 address and returns its numeric 5342: representation. 5343: </function> 5344: <function><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: <descrip> 5350: <tagp><type>u32</type> <param>x</param></tagp> 5351: a 32-bit integer 5352: </descrip> 5353: <funcsect>Description 5354: 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><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: <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: 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><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: <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: 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><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: <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: 5410: This function takes an IP address and creates its textual 5411: representation for presenting to the user. 5412: </function> 5413: <function><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: <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: 5426: This function takes an IP address and creates its hexadecimal 5427: textual representation. Primary use: debugging dumps. 5428: </function> 5429: <function><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: <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: 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: 5448: 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: 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><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: <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: 5477: <func/add_tail()/ takes a node <param/n/ and appends it at the end of the list <param/l/. 5478: </function> 5479: <function><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: <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: 5492: <func/add_head()/ takes a node <param/n/ and prepends it at the start of the list <param/l/. 5493: </function> 5494: <function><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: <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: 5507: Inserts a node <param/n/ to a linked list after an already inserted 5508: node <param/after/. 5509: </function> 5510: <function><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: <descrip> 5516: <tagp><type>node *</type> <param>n</param></tagp> 5517: node to be removed 5518: </descrip> 5519: <funcsect>Description 5520: 5521: Removes a node <param/n/ from the list it's linked in. Afterwards, node <param/n/ is cleared. 5522: </function> 5523: <function><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: <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: 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><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: <descrip> 5548: <tagp><type>list *</type> <param>l</param></tagp> 5549: list 5550: </descrip> 5551: <funcsect>Description 5552: 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><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: <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: 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: 5574: 5575: 5576: <function><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: <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: 5591: This function verifies whether a given fragmented packet 5592: has correct one's complement checksum as used by the IP 5593: protocol. 5594: 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: 5599: 1 if the checksum is correct, 0 else. 5600: </function> 5601: <function><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: <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: 5616: This function calculates a one's complement checksum of a given fragmented 5617: packet. 5618: 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><type>u32</type> 5623: <funcdef>u32_mkmask</funcdef> 5624: (<type>uint</type> <param>n</param>) -- create a bit mask 5625: 5626: <funcsect>Arguments 5627: <descrip> 5628: <tagp><type>uint</type> <param>n</param></tagp> 5629: number of bits 5630: </descrip> 5631: <funcsect>Description 5632: 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><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: <descrip> 5642: <tagp><type>u32</type> <param>x</param></tagp> 5643: bit mask 5644: </descrip> 5645: <funcsect>Description 5646: 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><type>u32</type> 5652: <funcdef>u32_log2</funcdef> 5653: (<type>u32</type> <param>v</param>) -- compute a binary logarithm. 5654: 5655: <funcsect>Arguments 5656: <descrip> 5657: <tagp><type>u32</type> <param>v</param></tagp> 5658: number 5659: </descrip> 5660: <funcsect>Description 5661: 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><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: <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: 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: 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><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: <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: 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: 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: 5719: number of characters of the output string or -1 if 5720: the buffer space was insufficient. 5721: </function> 5722: <function><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: <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: 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><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: <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: 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><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: <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: 5778: This function is equivalent to <func/bsnprintf()/ with variable arguments instead of a <struct/va_list/. 5779: </function> 5780: <function><type>void *</type> 5781: <funcdef>xmalloc</funcdef> 5782: (<type>uint</type> <param>size</param>) -- malloc with checking 5783: 5784: <funcsect>Arguments 5785: <descrip> 5786: <tagp><type>uint</type> <param>size</param></tagp> 5787: block size 5788: </descrip> 5789: <funcsect>Description 5790: 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: 5795: Wherever possible, please use the memory resources instead. 5796: </function> 5797: <function><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: <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: 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: 5814: Wherever possible, please use the memory resources instead. 5815: </function> 5816: <sect>Message authentication codes 5817: 5818: 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: 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: 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><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: <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: 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><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: <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: 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><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: <descrip> 5883: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> 5884: MAC context 5885: </descrip> 5886: <funcsect>Description 5887: 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: 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><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: <descrip> 5901: <tagp><type>struct mac_context *</type> <param>ctx</param></tagp> 5902: MAC context 5903: </descrip> 5904: <funcsect>Description 5905: 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><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: <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: 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><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: <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: 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:  5965: 5966: <chapt>Resources 5967: 5968: <sect>Introduction 5969: 5970: 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: 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: 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: 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: 6004: 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: 6012: Example: Almost all modules of BIRD have their private pool which 6013: is freed upon shutdown of the module. 6014: 6015: 6016: <function><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: <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: 6029: <func/rp_new()/ creates a new resource pool inside the specified 6030: parent pool. 6031: </function> 6032: <function><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: <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: 6045: <func/rmove()/ moves a resource from one pool to another. 6046: </function> 6047: <function><type>void</type> 6048: <funcdef>rfree</funcdef> 6049: (<type>void *</type> <param>res</param>) -- free a resource 6050: 6051: <funcsect>Arguments 6052: <descrip> 6053: <tagp><type>void *</type> <param>res</param></tagp> 6054: resource 6055: </descrip> 6056: <funcsect>Description 6057: 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: 6062: It works by calling a class-specific freeing function. 6063: </function> 6064: <function><type>void</type> 6065: <funcdef>rdump</funcdef> 6066: (<type>void *</type> <param>res</param>) -- dump a resource 6067: 6068: <funcsect>Arguments 6069: <descrip> 6070: <tagp><type>void *</type> <param>res</param></tagp> 6071: resource 6072: </descrip> 6073: <funcsect>Description 6074: 6075: This function prints out all available information about the given 6076: resource to the debugging output. 6077: 6078: It works by calling a class-specific dump function. 6079: </function> 6080: <function><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: <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: 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><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: <descrip> 6104: <tagp><type>unsigned long</type> <param>a</param></tagp> 6105: memory address 6106: </descrip> 6107: <funcsect>Description 6108: 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: 6113: It works by calling a class-specific lookup function for each 6114: resource. 6115: </function> 6116: <function><type>void</type> 6117: <funcdef>resource_init</funcdef> 6118: (<param>void</param>) -- initialize the resource manager 6119: 6120: <funcsect>Description 6121: 6122: 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: 6129: 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: 6136: Example: All "unique" data structures such as hash tables are allocated 6137: as memory blocks. 6138: 6139: 6140: <function><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: <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: 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: 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><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: <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: 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: 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><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: <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: 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: 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><type>void</type> 6206: <funcdef>mb_free</funcdef> 6207: (<type>void *</type> <param>m</param>) -- free a memory block 6208: 6209: <funcsect>Arguments 6210: <descrip> 6211: <tagp><type>void *</type> <param>m</param></tagp> 6212: memory block 6213: </descrip> 6214: <funcsect>Description 6215: 6216: <func/mb_free()/ frees all memory associated with the block <param/m/. 6217: </function> 6218: <sect>Linear memory pools 6219: 6220: 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: 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><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: <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: 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><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: <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: 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: 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><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: <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: 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><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: <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: 6300: This function is identical to <func/lp_alloc()/ except that it 6301: clears the allocated memory block. 6302: </function> 6303: <function><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: <descrip> 6309: <tagp><type>linpool *</type> <param>m</param></tagp> 6310: linear memory pool 6311: </descrip> 6312: <funcsect>Description 6313: 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: 6319: 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: 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: 6331: Example: Nodes of a FIB are allocated from a per-FIB Slab. 6332: 6333: 6334: <function><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: <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: 6347: This function creates a new Slab resource from which 6348: objects of size <param/size/ can be allocated. 6349: </function> 6350: <function><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: <descrip> 6356: <tagp><type>slab *</type> <param>s</param></tagp> 6357: slab 6358: </descrip> 6359: <funcsect>Description 6360: 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><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: <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: 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: 6382: 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: 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><type>event *</type> 6394: <funcdef>ev_new</funcdef> 6395: (<type>pool *</type> <param>p</param>) -- create a new event 6396: 6397: <funcsect>Arguments 6398: <descrip> 6399: <tagp><type>pool *</type> <param>p</param></tagp> 6400: resource pool 6401: </descrip> 6402: <funcsect>Description 6403: 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><type>void</type> 6408: <funcdef>ev_run</funcdef> 6409: (<type>event *</type> <param>e</param>) -- run an event 6410: 6411: <funcsect>Arguments 6412: <descrip> 6413: <tagp><type>event *</type> <param>e</param></tagp> 6414: an event 6415: </descrip> 6416: <funcsect>Description 6417: 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: 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><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: <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: 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><type>void</type> 6441: <funcdef>ev_schedule</funcdef> 6442: (<type>event *</type> <param>e</param>) -- schedule an event 6443: 6444: <funcsect>Arguments 6445: <descrip> 6446: <tagp><type>event *</type> <param>e</param></tagp> 6447: an event 6448: </descrip> 6449: <funcsect>Description 6450: 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><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: <descrip> 6461: <tagp><type>event_list *</type> <param>l</param></tagp> 6462: an event list 6463: </descrip> 6464: <funcsect>Description 6465: 6466: This function calls <func/ev_run()/ for all events enqueued in the list <param/l/. 6467: </function> 6468: <sect>Timers 6469: 6470: 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: 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: 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><type>timer *</type> 6489: <funcdef>tm_new</funcdef> 6490: (<type>pool *</type> <param>p</param>) -- create a timer 6491: 6492: <funcsect>Arguments 6493: <descrip> 6494: <tagp><type>pool *</type> <param>p</param></tagp> 6495: pool 6496: </descrip> 6497: <funcsect>Description 6498: 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><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: <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: 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: 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: 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><type>void</type> 6529: <funcdef>tm_stop</funcdef> 6530: (<type>timer *</type> <param>t</param>) -- stop a timer 6531: 6532: <funcsect>Arguments 6533: <descrip> 6534: <tagp><type>timer *</type> <param>t</param></tagp> 6535: timer 6536: </descrip> 6537: <funcsect>Description 6538: 6539: This function stops a timer. If the timer is already stopped, 6540: nothing happens. 6541: </function> 6542: <function><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: <descrip> 6548: <tagp><type>char *</type> <param>x</param></tagp> 6549: datetime string 6550: </descrip> 6551: <funcsect>Description 6552: 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><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: <descrip> 6563: <tagp><type>char *</type> <param>x</param></tagp> 6564: date string 6565: </descrip> 6566: <funcsect>Description 6567: 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><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: <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: 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: 6591: 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: 6599: Freeing of sockets from inside socket hooks is perfectly safe. 6600: 6601: 6602: <function><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: <descrip> 6608: <tagp><type>sock *</type> <param>s</param></tagp> 6609: socket 6610: </descrip> 6611: <funcsect>Description 6612: 6613: Prepare transmission of multicast packets for given datagram socket. 6614: The socket must have defined <param/iface/. 6615: <funcsect>Result 6616: 6617: 0 for success, -1 for an error. 6618: </function> 6619: <function><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: <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: 6632: Join multicast group for given datagram socket and associated interface. 6633: The socket must have defined <param/iface/. 6634: <funcsect>Result 6635: 6636: 0 for success, -1 for an error. 6637: </function> 6638: <function><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: <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: 6651: Leave multicast group for given datagram socket and associated interface. 6652: The socket must have defined <param/iface/. 6653: <funcsect>Result 6654: 6655: 0 for success, -1 for an error. 6656: </function> 6657: <function><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: <descrip> 6663: <tagp><type>sock *</type> <param>s</param></tagp> 6664: socket 6665: </descrip> 6666: <funcsect>Description 6667: 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: 6673: 0 for success, -1 for an error. 6674: </function> 6675: <function><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: <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: 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: 6692: 0 for success, -1 for an error. 6693: </function> 6694: <function><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: <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: 6707: Set minimal accepted TTL for given socket. Can be used for TTL security. 6708: implementations. 6709: <funcsect>Result 6710: 6711: 0 for success, -1 for an error. 6712: </function> 6713: <function><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: <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: 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: 6739: When called with passwd != NULL, the new pair is added, 6740: When called with passwd == NULL, the existing pair is removed. 6741: 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: 6750: 0 for success, -1 for an error. 6751: </function> 6752: <function><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: <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: 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: 6771: 0 for success, -1 for an error. 6772: </function> 6773: <function><type>sock *</type> 6774: <funcdef>sock_new</funcdef> 6775: (<type>pool *</type> <param>p</param>) -- create a socket 6776: 6777: <funcsect>Arguments 6778: <descrip> 6779: <tagp><type>pool *</type> <param>p</param></tagp> 6780: pool 6781: </descrip> 6782: <funcsect>Description 6783: 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: 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><type>int</type> 6792: <funcdef>sk_open</funcdef> 6793: (<type>sock *</type> <param>s</param>) -- open a socket 6794: 6795: <funcsect>Arguments 6796: <descrip> 6797: <tagp><type>sock *</type> <param>s</param></tagp> 6798: socket 6799: </descrip> 6800: <funcsect>Description 6801: 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: 6807: 0 for success, -1 for an error. 6808: </function> 6809: <function><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: <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: 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><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: <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: 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><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: <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: 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>