embedaddon/bird/doc/prog-2.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-2.html
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Wed Mar 17 19:50:23 2021 UTC (3 years, 4 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_8p3, HEAD

bird 1.6.8

1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> 2: <HTML> 3: <HEAD> 4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9"> 5: <TITLE>BIRD Programmer's Documentation: Core</TITLE> 6: <LINK HREF="prog-3.html" REL=next> 7: <LINK HREF="prog-1.html" REL=previous> 8: <LINK HREF="prog.html#toc2" REL=contents> 9: </HEAD> 10: <BODY> 11: <A HREF="prog-3.html">Next</A> 12: <A HREF="prog-1.html">Previous</A> 13: <A HREF="prog.html#toc2">Contents</A> 14: <HR> 15: <H2><A NAME="s2">2.</A> <A HREF="prog.html#toc2">Core</A></H2> 16: 17: <H2><A NAME="ss2.1">2.1</A> <A HREF="prog.html#toc2.1">Forwarding Information Base</A> 18: </H2> 19: 20:  21: FIB is a data structure designed for storage of routes indexed by their 22: network prefixes. It supports insertion, deletion, searching by prefix, 23: `routing' (in CIDR sense, that is searching for a longest prefix matching 24: a given IP address) and (which makes the structure very tricky to implement) 25: asynchronous reading, that is enumerating the contents of a FIB while other 26: modules add, modify or remove entries. 27: Internally, each FIB is represented as a collection of nodes of type fib_node 28: indexed using a sophisticated hashing mechanism. 29: We use two-stage hashing where we calculate a 16-bit primary hash key independent 30: on hash table size and then we just divide the primary keys modulo table size 31: to get a real hash key used for determining the bucket containing the node. 32: The lists of nodes in each bucket are sorted according to the primary hash 33: key, hence if we keep the total number of buckets to be a power of two, 34: re-hashing of the structure keeps the relative order of the nodes. 35: To get the asynchronous reading consistent over node deletions, we need to 36: keep a list of readers for each node. When a node gets deleted, its readers 37: are automatically moved to the next node in the table. 38: Basic FIB operations are performed by functions defined by this module, 39: enumerating of FIB contents is accomplished by using the FIB_WALK() macro 40: or FIB_ITERATE_START() if you want to do it asynchronously. 41: For simple iteration just place the body of the loop between FIB_WALK() and 42: FIB_WALK_END(). You can't modify the FIB during the iteration (you can modify 43: data in the node, but not add or remove nodes). 44: If you need more freedom, you can use the FIB_ITERATE_*() group of macros. 45: First, you initialize an iterator with FIB_ITERATE_INIT(). Then you can put 46: the loop body in between FIB_ITERATE_START() and FIB_ITERATE_END(). In 47: addition, the iteration can be suspended by calling FIB_ITERATE_PUT(). 48: This'll link the iterator inside the FIB. While suspended, you may modify the 49: FIB, exit the current function, etc. To resume the iteration, enter the loop 50: again. You can use FIB_ITERATE_UNLINK() to unlink the iterator (while 51: iteration is suspended) in cases like premature end of FIB iteration. 52: Note that the iterator must not be destroyed when the iteration is suspended, 53: the FIB would then contain a pointer to invalid memory. Therefore, after each 54: FIB_ITERATE_INIT() or FIB_ITERATE_PUT() there must be either 55: FIB_ITERATE_START() or FIB_ITERATE_UNLINK() before the iterator is destroyed. 56:  57: <HR><H3>Function</H3> 58: void 59: fib_init 60: (struct fib * f, pool * p, unsigned node_size, unsigned hash_order, fib_init_func init) -- initialize a new FIB 61:  62: <H3>Arguments</H3> 63:  64: <DL> 65: <DT>struct fib * f<DD>the FIB to be initialized (the structure itself being allocated by the caller) 66: <DT>pool * p<DD>pool to allocate the nodes in 67: <DT>unsigned node_size<DD>node size to be used (each node consists of a standard header fib_node 68: followed by user data) 69: <DT>unsigned hash_order<DD>initial hash order (a binary logarithm of hash table size), 0 to use default order 70: (recommended) 71: <DT>fib_init_func init<DD>pointer a function to be called to initialize a newly created node 72: </DL> 73: <H3>Description</H3> 74: This function initializes a newly allocated FIB and prepares it for use. 75: 76: 77: <HR><H3>Function</H3> 78: void * 79: fib_find 80: (struct fib * f, ip_addr * a, int len) -- search for FIB node by prefix 81:  82: <H3>Arguments</H3> 83:  84: <DL> 85: <DT>struct fib * f<DD>FIB to search in 86: <DT>ip_addr * a<DD>pointer to IP address of the prefix 87: <DT>int len<DD>prefix length 88: </DL> 89: <H3>Description</H3> 90: Search for a FIB node corresponding to the given prefix, return 91: a pointer to it or NULL if no such node exists. 92: 93: 94: <HR><H3>Function</H3> 95: void * 96: fib_get 97: (struct fib * f, ip_addr * a, int len) -- find or create a FIB node 98:  99: <H3>Arguments</H3> 100:  101: <DL> 102: <DT>struct fib * f<DD>FIB to work with 103: <DT>ip_addr * a<DD>pointer to IP address of the prefix 104: <DT>int len<DD>prefix length 105: </DL> 106: <H3>Description</H3> 107: Search for a FIB node corresponding to the given prefix and 108: return a pointer to it. If no such node exists, create it. 109: 110: 111: <HR><H3>Function</H3> 112: void * 113: fib_route 114: (struct fib * f, ip_addr a, int len) -- CIDR routing lookup 115:  116: <H3>Arguments</H3> 117:  118: <DL> 119: <DT>struct fib * f<DD>FIB to search in 120: <DT>ip_addr a<DD>pointer to IP address of the prefix 121: <DT>int len<DD>prefix length 122: </DL> 123: <H3>Description</H3> 124: Search for a FIB node with longest prefix matching the given 125: network, that is a node which a CIDR router would use for routing 126: that network. 127: 128: 129: <HR><H3>Function</H3> 130: void 131: fib_delete 132: (struct fib * f, void * E) -- delete a FIB node 133:  134: <H3>Arguments</H3> 135:  136: <DL> 137: <DT>struct fib * f<DD>FIB to delete from 138: <DT>void * E<DD>entry to delete 139: </DL> 140: <H3>Description</H3> 141: This function removes the given entry from the FIB, 142: taking care of all the asynchronous readers by shifting 143: them to the next node in the canonical reading order. 144: 145: 146: <HR><H3>Function</H3> 147: void 148: fib_free 149: (struct fib * f) -- delete a FIB 150:  151: <H3>Arguments</H3> 152:  153: <DL> 154: <DT>struct fib * f<DD>FIB to be deleted 155: </DL> 156: <H3>Description</H3> 157: This function deletes a FIB -- it frees all memory associated 158: with it and all its entries. 159: 160: 161: <HR><H3>Function</H3> 162: void 163: fib_check 164: (struct fib * f) -- audit a FIB 165:  166: <H3>Arguments</H3> 167:  168: <DL> 169: <DT>struct fib * f<DD>FIB to be checked 170: </DL> 171: <H3>Description</H3> 172: This debugging function audits a FIB by checking its internal consistency. 173: Use when you suspect somebody of corrupting innocent data structures. 174: 175: <H2><A NAME="ss2.2">2.2</A> <A HREF="prog.html#toc2.2">Routing tables</A> 176: </H2> 177: 178:  179: Routing tables are probably the most important structures BIRD uses. They 180: hold all the information about known networks, the associated routes and 181: their attributes. 182: There are multiple routing tables (a primary one together with any 183: number of secondary ones if requested by the configuration). Each table 184: is basically a FIB containing entries describing the individual 185: destination networks. For each network (represented by structure net), 186: there is a one-way linked list of route entries (rte), the first entry 187: on the list being the best one (i.e., the one we currently use 188: for routing), the order of the other ones is undetermined. 189: The rte contains information specific to the route (preference, protocol 190: metrics, time of last modification etc.) and a pointer to a rta structure 191: (see the route attribute module for a precise explanation) holding the 192: remaining route attributes which are expected to be shared by multiple 193: routes in order to conserve memory. 194:  195: <HR><H3>Function</H3> 196: rte * 197: rte_find 198: (net * net, struct rte_src * src) -- find a route 199:  200: <H3>Arguments</H3> 201:  202: <DL> 203: <DT>net * net<DD>network node 204: <DT>struct rte_src * src<DD>route source 205: </DL> 206: <H3>Description</H3> 207: The rte_find() function returns a route for destination net 208: which is from route source src. 209: 210: 211: <HR><H3>Function</H3> 212: rte * 213: rte_get_temp 214: (rta * a) -- get a temporary rte 215:  216: <H3>Arguments</H3> 217:  218: <DL> 219: <DT>rta * a<DD>attributes to assign to the new route (a rta; in case it's 220: un-cached, rte_update() will create a cached copy automatically) 221: </DL> 222: <H3>Description</H3> 223: Create a temporary rte and bind it with the attributes a. 224: Also set route preference to the default preference set for 225: the protocol. 226: 227: 228: <HR><H3>Function</H3> 229: rte * 230: rte_cow_rta 231: (rte * r, linpool * lp) -- get a private writable copy of rte with writable rta 232:  233: <H3>Arguments</H3> 234:  235: <DL> 236: <DT>rte * r<DD>a route entry to be copied 237: <DT>linpool * lp<DD>a linpool from which to allocate rta 238: </DL> 239: <H3>Description</H3> 240: rte_cow_rta() takes a rte and prepares it and associated rta for 241: modification. There are three possibilities: First, both rte and rta are 242: private copies, in that case they are returned unchanged. Second, rte is 243: private copy, but rta is cached, in that case rta is duplicated using 244: rta_do_cow(). Third, both rte is shared and rta is cached, in that case 245: both structures are duplicated by rte_do_cow() and rta_do_cow(). 246: Note that in the second case, cached rta loses one reference, while private 247: copy created by rta_do_cow() is a shallow copy sharing indirect data (eattrs, 248: nexthops, ...) with it. To work properly, original shared rta should have 249: another reference during the life of created private copy. 250: <H3>Result</H3> 251: a pointer to the new writable rte with writable rta. 252: 253: 254: <HR><H3>Function</H3> 255: void 256: rte_announce 257: (rtable * tab, unsigned type, net * net, rte * new, rte * old, rte * new_best, rte * old_best, rte * before_old) -- announce a routing table change 258:  259: <H3>Arguments</H3> 260:  261: <DL> 262: <DT>rtable * tab<DD>table the route has been added to 263: <DT>unsigned type<DD>type of route announcement (RA_OPTIMAL or RA_ANY) 264: <DT>net * net<DD>network in question 265: <DT>rte * new<DD>the new route to be announced 266: <DT>rte * old<DD>the previous route for the same network 267: <DT>rte * new_best<DD>the new best route for the same network 268: <DT>rte * old_best<DD>the previous best route for the same network 269: <DT>rte * before_old<DD>The previous route before old for the same network. 270: If before_old is NULL old was the first. 271: </DL> 272: <H3>Description</H3> 273: This function gets a routing table update and announces it 274: to all protocols that acccepts given type of route announcement 275: and are connected to the same table by their announcement hooks. 276: Route announcement of type RA_OPTIMAL si generated when optimal 277: route (in routing table tab) changes. In that case old stores the 278: old optimal route. 279: Route announcement of type RA_ANY si generated when any route (in 280: routing table tab) changes In that case old stores the old route 281: from the same protocol. 282: For each appropriate protocol, we first call its import_control() 283: hook which performs basic checks on the route (each protocol has a 284: right to veto or force accept of the route before any filter is 285: asked) and adds default values of attributes specific to the new 286: protocol (metrics, tags etc.). Then it consults the protocol's 287: export filter and if it accepts the route, the rt_notify() hook of 288: the protocol gets called. 289: 290: 291: <HR><H3>Function</H3> 292: void 293: rte_free 294: (rte * e) -- delete a rte 295:  296: <H3>Arguments</H3> 297:  298: <DL> 299: <DT>rte * e<DD>rte to be deleted 300: </DL> 301: <H3>Description</H3> 302: rte_free() deletes the given rte from the routing table it's linked to. 303: 304: 305: <HR><H3>Function</H3> 306: void 307: rte_update2 308: (struct announce_hook * ah, net * net, rte * new, struct rte_src * src) -- enter a new update to a routing table 309:  310: <H3>Arguments</H3> 311:  312: <DL> 313: <DT>struct announce_hook * ah<DD>pointer to table announce hook 314: <DT>net * net<DD>network node 315: <DT>rte * new<DD>a rte representing the new route or NULL for route removal. 316: <DT>struct rte_src * src<DD>protocol originating the update 317: </DL> 318: <H3>Description</H3> 319: This function is called by the routing protocols whenever they discover 320: a new route or wish to update/remove an existing route. The right announcement 321: sequence is to build route attributes first (either un-cached with aflags set 322: to zero or a cached one using rta_lookup(); in this case please note that 323: you need to increase the use count of the attributes yourself by calling 324: rta_clone()), call rte_get_temp() to obtain a temporary rte, fill in all 325: the appropriate data and finally submit the new rte by calling rte_update(). 326: src specifies the protocol that originally created the route and the meaning 327: of protocol-dependent data of new. If new is not NULL, src have to be the 328: same value as new->attrs->proto. p specifies the protocol that called 329: rte_update(). In most cases it is the same protocol as src. rte_update() 330: stores p in new->sender; 331: When rte_update() gets any route, it automatically validates it (checks, 332: whether the network and next hop address are valid IP addresses and also 333: whether a normal routing protocol doesn't try to smuggle a host or link 334: scope route to the table), converts all protocol dependent attributes stored 335: in the rte to temporary extended attributes, consults import filters of the 336: protocol to see if the route should be accepted and/or its attributes modified, 337: stores the temporary attributes back to the rte. 338: Now, having a "public" version of the route, we 339: automatically find any old route defined by the protocol src 340: for network n, replace it by the new one (or removing it if new is NULL), 341: recalculate the optimal route for this destination and finally broadcast 342: the change (if any) to all routing protocols by calling rte_announce(). 343: All memory used for attribute lists and other temporary allocations is taken 344: from a special linear pool rte_update_pool and freed when rte_update() 345: finishes. 346: 347: 348: <HR><H3>Function</H3> 349: void 350: rt_refresh_begin 351: (rtable * t, struct announce_hook * ah) -- start a refresh cycle 352:  353: <H3>Arguments</H3> 354:  355: <DL> 356: <DT>rtable * t<DD>related routing table 357: <DT>struct announce_hook * ah<DD>related announce hook 358: </DL> 359: <H3>Description</H3> 360: This function starts a refresh cycle for given routing table and announce 361: hook. The refresh cycle is a sequence where the protocol sends all its valid 362: routes to the routing table (by rte_update()). After that, all protocol 363: routes (more precisely routes with ah as sender) not sent during the 364: refresh cycle but still in the table from the past are pruned. This is 365: implemented by marking all related routes as stale by REF_STALE flag in 366: rt_refresh_begin(), then marking all related stale routes with REF_DISCARD 367: flag in rt_refresh_end() and then removing such routes in the prune loop. 368: 369: 370: <HR><H3>Function</H3> 371: void 372: rt_refresh_end 373: (rtable * t, struct announce_hook * ah) -- end a refresh cycle 374:  375: <H3>Arguments</H3> 376:  377: <DL> 378: <DT>rtable * t<DD>related routing table 379: <DT>struct announce_hook * ah<DD>related announce hook 380: </DL> 381: <H3>Description</H3> 382: This function starts a refresh cycle for given routing table and announce 383: hook. See rt_refresh_begin() for description of refresh cycles. 384: 385: 386: <HR><H3>Function</H3> 387: void 388: rte_dump 389: (rte * e) -- dump a route 390:  391: <H3>Arguments</H3> 392:  393: <DL> 394: <DT>rte * e<DD>rte to be dumped 395: </DL> 396: <H3>Description</H3> 397: This functions dumps contents of a rte to debug output. 398: 399: 400: <HR><H3>Function</H3> 401: void 402: rt_dump 403: (rtable * t) -- dump a routing table 404:  405: <H3>Arguments</H3> 406:  407: <DL> 408: <DT>rtable * t<DD>routing table to be dumped 409: </DL> 410: <H3>Description</H3> 411: This function dumps contents of a given routing table to debug output. 412: 413: 414: <HR><H3>Function</H3> 415: void 416: rt_dump_all 417: (void) -- dump all routing tables 418:  419: <H3>Description</H3> 420:  421: This function dumps contents of all routing tables to debug output. 422: 423: 424: <HR><H3>Function</H3> 425: void 426: rt_init 427: (void) -- initialize routing tables 428:  429: <H3>Description</H3> 430:  431: This function is called during BIRD startup. It initializes the 432: routing table module. 433: 434: 435: <HR><H3>Function</H3> 436: int 437: rt_prune_table 438: (rtable * tab) -- prune a routing table 439:  440: <H3>Arguments</H3> 441:  442: <DL> 443: <DT>rtable * tab<DD>a routing table for pruning 444: </DL> 445: <H3>Description</H3> 446: This function scans the routing table tab and removes routes belonging to 447: flushing protocols, discarded routes and also stale network entries, in a 448: similar fashion like rt_prune_loop(). Returns 1 when all such routes are 449: pruned. Contrary to rt_prune_loop(), this function is not a part of the 450: protocol flushing loop, but it is called from rt_event() for just one routing 451: table. 452: Note that rt_prune_table() and rt_prune_loop() share (for each table) the 453: prune state (prune_state) and also the pruning iterator (prune_fit). 454: 455: 456: <HR><H3>Function</H3> 457: int 458: rt_prune_loop 459: (void) -- prune routing tables 460:  461: <H3>Description</H3> 462:  463: The prune loop scans routing tables and removes routes belonging to flushing 464: protocols, discarded routes and also stale network entries. Returns 1 when 465: all such routes are pruned. It is a part of the protocol flushing loop. 466: 467: 468: <HR><H3>Function</H3> 469: void 470: rt_lock_table 471: (rtable * r) -- lock a routing table 472:  473: <H3>Arguments</H3> 474:  475: <DL> 476: <DT>rtable * r<DD>routing table to be locked 477: </DL> 478: <H3>Description</H3> 479: Lock a routing table, because it's in use by a protocol, 480: preventing it from being freed when it gets undefined in a new 481: configuration. 482: 483: 484: <HR><H3>Function</H3> 485: void 486: rt_unlock_table 487: (rtable * r) -- unlock a routing table 488:  489: <H3>Arguments</H3> 490:  491: <DL> 492: <DT>rtable * r<DD>routing table to be unlocked 493: </DL> 494: <H3>Description</H3> 495: Unlock a routing table formerly locked by rt_lock_table(), 496: that is decrease its use count and delete it if it's scheduled 497: for deletion by configuration changes. 498: 499: 500: <HR><H3>Function</H3> 501: void 502: rt_commit 503: (struct config * new, struct config * old) -- commit new routing table configuration 504:  505: <H3>Arguments</H3> 506:  507: <DL> 508: <DT>struct config * new<DD>new configuration 509: <DT>struct config * old<DD>original configuration or NULL if it's boot time config 510: </DL> 511: <H3>Description</H3> 512: Scan differences between old and new configuration and modify 513: the routing tables according to these changes. If new defines a 514: previously unknown table, create it, if it omits a table existing 515: in old, schedule it for deletion (it gets deleted when all protocols 516: disconnect from it by calling rt_unlock_table()), if it exists 517: in both configurations, leave it unchanged. 518: 519: 520: <HR><H3>Function</H3> 521: int 522: rt_feed_baby 523: (struct proto * p) -- advertise routes to a new protocol 524:  525: <H3>Arguments</H3> 526:  527: <DL> 528: <DT>struct proto * p<DD>protocol to be fed 529: </DL> 530: <H3>Description</H3> 531: This function performs one pass of advertisement of routes to a newly 532: initialized protocol. It's called by the protocol code as long as it 533: has something to do. (We avoid transferring all the routes in single 534: pass in order not to monopolize CPU time.) 535: 536: 537: <HR><H3>Function</H3> 538: void 539: rt_feed_baby_abort 540: (struct proto * p) -- abort protocol feeding 541:  542: <H3>Arguments</H3> 543:  544: <DL> 545: <DT>struct proto * p<DD>protocol 546: </DL> 547: <H3>Description</H3> 548: This function is called by the protocol code when the protocol 549: stops or ceases to exist before the last iteration of rt_feed_baby() 550: has finished. 551: 552: 553: <HR><H3>Function</H3> 554: net * 555: net_find 556: (rtable * tab, ip_addr addr, unsigned len) -- find a network entry 557:  558: <H3>Arguments</H3> 559:  560: <DL> 561: <DT>rtable * tab<DD>a routing table 562: <DT>ip_addr addr<DD>address of the network 563: <DT>unsigned len<DD>length of the network prefix 564: </DL> 565: <H3>Description</H3> 566: net_find() looks up the given network in routing table tab and 567: returns a pointer to its net entry or NULL if no such network 568: exists. 569: 570: 571: <HR><H3>Function</H3> 572: net * 573: net_get 574: (rtable * tab, ip_addr addr, unsigned len) -- obtain a network entry 575:  576: <H3>Arguments</H3> 577:  578: <DL> 579: <DT>rtable * tab<DD>a routing table 580: <DT>ip_addr addr<DD>address of the network 581: <DT>unsigned len<DD>length of the network prefix 582: </DL> 583: <H3>Description</H3> 584: net_get() looks up the given network in routing table tab and 585: returns a pointer to its net entry. If no such entry exists, it's 586: created. 587: 588: 589: <HR><H3>Function</H3> 590: rte * 591: rte_cow 592: (rte * r) -- copy a route for writing 593:  594: <H3>Arguments</H3> 595:  596: <DL> 597: <DT>rte * r<DD>a route entry to be copied 598: </DL> 599: <H3>Description</H3> 600: rte_cow() takes a rte and prepares it for modification. The exact action 601: taken depends on the flags of the rte -- if it's a temporary entry, it's 602: just returned unchanged, else a new temporary entry with the same contents 603: is created. 604: The primary use of this function is inside the filter machinery -- when 605: a filter wants to modify rte contents (to change the preference or to 606: attach another set of attributes), it must ensure that the rte is not 607: shared with anyone else (and especially that it isn't stored in any routing 608: table). 609: <H3>Result</H3> 610: a pointer to the new writable rte. 611: 612: <H2><A NAME="ss2.3">2.3</A> <A HREF="prog.html#toc2.3">Route attribute cache</A> 613: </H2> 614: 615:  616: Each route entry carries a set of route attributes. Several of them 617: vary from route to route, but most attributes are usually common 618: for a large number of routes. To conserve memory, we've decided to 619: store only the varying ones directly in the rte and hold the rest 620: in a special structure called rta which is shared among all the 621: rte's with these attributes. 622: Each rta contains all the static attributes of the route (i.e., 623: those which are always present) as structure members and a list of 624: dynamic attributes represented by a linked list of ea_list 625: structures, each of them consisting of an array of eattr's containing 626: the individual attributes. An attribute can be specified more than once 627: in the ea_list chain and in such case the first occurrence overrides 628: the others. This semantics is used especially when someone (for example 629: a filter) wishes to alter values of several dynamic attributes, but 630: it wants to preserve the original attribute lists maintained by 631: another module. 632: Each eattr contains an attribute identifier (split to protocol ID and 633: per-protocol attribute ID), protocol dependent flags, a type code (consisting 634: of several bit fields describing attribute characteristics) and either an 635: embedded 32-bit value or a pointer to a adata structure holding attribute 636: contents. 637: There exist two variants of rta's -- cached and un-cached ones. Un-cached 638: rta's can have arbitrarily complex structure of ea_list's and they 639: can be modified by any module in the route processing chain. Cached 640: rta's have their attribute lists normalized (that means at most one 641: ea_list is present and its values are sorted in order to speed up 642: searching), they are stored in a hash table to make fast lookup possible 643: and they are provided with a use count to allow sharing. 644: Routing tables always contain only cached rta's. 645:  646: <HR><H3>Function</H3> 647: struct mpnh * 648: mpnh_merge 649: (struct mpnh * x, struct mpnh * y, int rx, int ry, int max, linpool * lp) -- merge nexthop lists 650:  651: <H3>Arguments</H3> 652:  653: <DL> 654: <DT>struct mpnh * x<DD>list 1 655: <DT>struct mpnh * y<DD>list 2 656: <DT>int rx<DD>reusability of list x 657: <DT>int ry<DD>reusability of list y 658: <DT>int max<DD>max number of nexthops 659: <DT>linpool * lp<DD>linpool for allocating nexthops 660: </DL> 661: <H3>Description</H3> 662: The mpnh_merge() function takes two nexthop lists x and y and merges them, 663: eliminating possible duplicates. The input lists must be sorted and the 664: result is sorted too. The number of nexthops in result is limited by max. 665: New nodes are allocated from linpool lp. 666: The arguments rx and ry specify whether corresponding input lists may be 667: consumed by the function (i.e. their nodes reused in the resulting list), in 668: that case the caller should not access these lists after that. To eliminate 669: issues with deallocation of these lists, the caller should use some form of 670: bulk deallocation (e.g. stack or linpool) to free these nodes when the 671: resulting list is no longer needed. When reusability is not set, the 672: corresponding lists are not modified nor linked from the resulting list. 673: 674: 675: <HR><H3>Function</H3> 676: eattr * 677: ea_find 678: (ea_list * e, unsigned id) -- find an extended attribute 679:  680: <H3>Arguments</H3> 681:  682: <DL> 683: <DT>ea_list * e<DD>attribute list to search in 684: <DT>unsigned id<DD>attribute ID to search for 685: </DL> 686: <H3>Description</H3> 687: Given an extended attribute list, ea_find() searches for a first 688: occurrence of an attribute with specified ID, returning either a pointer 689: to its eattr structure or NULL if no such attribute exists. 690: 691: 692: <HR><H3>Function</H3> 693: eattr * 694: ea_walk 695: (struct ea_walk_state * s, uint id, uint max) -- walk through extended attributes 696:  697: <H3>Arguments</H3> 698:  699: <DL> 700: <DT>struct ea_walk_state * s<DD>walk state structure 701: <DT>uint id<DD>start of attribute ID interval 702: <DT>uint max<DD>length of attribute ID interval 703: </DL> 704: <H3>Description</H3> 705: Given an extended attribute list, ea_walk() walks through the list looking 706: for first occurrences of attributes with ID in specified interval from id to 707: (id + max - 1), returning pointers to found eattr structures, storing its 708: walk state in s for subsequent calls. 709: The function ea_walk() is supposed to be called in a loop, with initially 710: zeroed walk state structure s with filled the initial extended attribute 711: list, returning one found attribute in each call or NULL when no other 712: attribute exists. The extended attribute list or the arguments should not be 713: modified between calls. The maximum value of max is 128. 714: 715: 716: <HR><H3>Function</H3> 717: int 718: ea_get_int 719: (ea_list * e, unsigned id, int def) -- fetch an integer attribute 720:  721: <H3>Arguments</H3> 722:  723: <DL> 724: <DT>ea_list * e<DD>attribute list 725: <DT>unsigned id<DD>attribute ID 726: <DT>int def<DD>default value 727: </DL> 728: <H3>Description</H3> 729: This function is a shortcut for retrieving a value of an integer attribute 730: by calling ea_find() to find the attribute, extracting its value or returning 731: a provided default if no such attribute is present. 732: 733: 734: <HR><H3>Function</H3> 735: void 736: ea_sort 737: (ea_list * e) -- sort an attribute list 738:  739: <H3>Arguments</H3> 740:  741: <DL> 742: <DT>ea_list * e<DD>list to be sorted 743: </DL> 744: <H3>Description</H3> 745: This function takes a ea_list chain and sorts the attributes 746: within each of its entries. 747: If an attribute occurs multiple times in a single ea_list, 748: ea_sort() leaves only the first (the only significant) occurrence. 749: 750: 751: <HR><H3>Function</H3> 752: unsigned 753: ea_scan 754: (ea_list * e) -- estimate attribute list size 755:  756: <H3>Arguments</H3> 757:  758: <DL> 759: <DT>ea_list * e<DD>attribute list 760: </DL> 761: <H3>Description</H3> 762: This function calculates an upper bound of the size of 763: a given ea_list after merging with ea_merge(). 764: 765: 766: <HR><H3>Function</H3> 767: void 768: ea_merge 769: (ea_list * e, ea_list * t) -- merge segments of an attribute list 770:  771: <H3>Arguments</H3> 772:  773: <DL> 774: <DT>ea_list * e<DD>attribute list 775: <DT>ea_list * t<DD>buffer to store the result to 776: </DL> 777: <H3>Description</H3> 778: This function takes a possibly multi-segment attribute list 779: and merges all of its segments to one. 780: The primary use of this function is for ea_list normalization: 781: first call ea_scan() to determine how much memory will the result 782: take, then allocate a buffer (usually using alloca()), merge the 783: segments with ea_merge() and finally sort and prune the result 784: by calling ea_sort(). 785: 786: 787: <HR><H3>Function</H3> 788: int 789: ea_same 790: (ea_list * x, ea_list * y) -- compare two ea_list's 791:  792: <H3>Arguments</H3> 793:  794: <DL> 795: <DT>ea_list * x<DD>attribute list 796: <DT>ea_list * y<DD>attribute list 797: </DL> 798: <H3>Description</H3> 799: ea_same() compares two normalized attribute lists x and y and returns 800: 1 if they contain the same attributes, 0 otherwise. 801: 802: 803: <HR><H3>Function</H3> 804: void 805: ea_show 806: (struct cli * c, eattr * e) -- print an eattr to CLI 807:  808: <H3>Arguments</H3> 809:  810: <DL> 811: <DT>struct cli * c<DD>destination CLI 812: <DT>eattr * e<DD>attribute to be printed 813: </DL> 814: <H3>Description</H3> 815: This function takes an extended attribute represented by its eattr 816: structure and prints it to the CLI according to the type information. 817: If the protocol defining the attribute provides its own 818: get_attr() hook, it's consulted first. 819: 820: 821: <HR><H3>Function</H3> 822: void 823: ea_dump 824: (ea_list * e) -- dump an extended attribute 825:  826: <H3>Arguments</H3> 827:  828: <DL> 829: <DT>ea_list * e<DD>attribute to be dumped 830: </DL> 831: <H3>Description</H3> 832: ea_dump() dumps contents of the extended attribute given to 833: the debug output. 834: 835: 836: <HR><H3>Function</H3> 837: uint 838: ea_hash 839: (ea_list * e) -- calculate an ea_list hash key 840:  841: <H3>Arguments</H3> 842:  843: <DL> 844: <DT>ea_list * e<DD>attribute list 845: </DL> 846: <H3>Description</H3> 847: ea_hash() takes an extended attribute list and calculated a hopefully 848: uniformly distributed hash value from its contents. 849: 850: 851: <HR><H3>Function</H3> 852: ea_list * 853: ea_append 854: (ea_list * to, ea_list * what) -- concatenate ea_list's 855:  856: <H3>Arguments</H3> 857:  858: <DL> 859: <DT>ea_list * to<DD>destination list (can be NULL) 860: <DT>ea_list * what<DD>list to be appended (can be NULL) 861: </DL> 862: <H3>Description</H3> 863: This function appends the ea_list what at the end of 864: ea_list to and returns a pointer to the resulting list. 865: 866: 867: <HR><H3>Function</H3> 868: rta * 869: rta_lookup 870: (rta * o) -- look up a rta in attribute cache 871:  872: <H3>Arguments</H3> 873:  874: <DL> 875: <DT>rta * o<DD>a un-cached rta 876: </DL> 877: <H3>Description</H3> 878: rta_lookup() gets an un-cached rta structure and returns its cached 879: counterpart. It starts with examining the attribute cache to see whether 880: there exists a matching entry. If such an entry exists, it's returned and 881: its use count is incremented, else a new entry is created with use count 882: set to 1. 883: The extended attribute lists attached to the rta are automatically 884: converted to the normalized form. 885: 886: 887: <HR><H3>Function</H3> 888: void 889: rta_dump 890: (rta * a) -- dump route attributes 891:  892: <H3>Arguments</H3> 893:  894: <DL> 895: <DT>rta * a<DD>attribute structure to dump 896: </DL> 897: <H3>Description</H3> 898: This function takes a rta and dumps its contents to the debug output. 899: 900: 901: <HR><H3>Function</H3> 902: void 903: rta_dump_all 904: (void) -- dump attribute cache 905:  906: <H3>Description</H3> 907:  908: This function dumps the whole contents of route attribute cache 909: to the debug output. 910: 911: 912: <HR><H3>Function</H3> 913: void 914: rta_init 915: (void) -- initialize route attribute cache 916:  917: <H3>Description</H3> 918:  919: This function is called during initialization of the routing 920: table module to set up the internals of the attribute cache. 921: 922: 923: <HR><H3>Function</H3> 924: rta * 925: rta_clone 926: (rta * r) -- clone route attributes 927:  928: <H3>Arguments</H3> 929:  930: <DL> 931: <DT>rta * r<DD>a rta to be cloned 932: </DL> 933: <H3>Description</H3> 934: rta_clone() takes a cached rta and returns its identical cached 935: copy. Currently it works by just returning the original rta with 936: its use count incremented. 937: 938: 939: <HR><H3>Function</H3> 940: void 941: rta_free 942: (rta * r) -- free route attributes 943:  944: <H3>Arguments</H3> 945:  946: <DL> 947: <DT>rta * r<DD>a rta to be freed 948: </DL> 949: <H3>Description</H3> 950: If you stop using a rta (for example when deleting a route which uses 951: it), you need to call rta_free() to notify the attribute cache the 952: attribute is no longer in use and can be freed if you were the last 953: user (which rta_free() tests by inspecting the use count). 954: 955:  956: <H2><A NAME="ss2.4">2.4</A> <A HREF="prog.html#toc2.4">Routing protocols</A> 957: </H2> 958: 959: <H3>Introduction</H3> 960: 961: The routing protocols are the bird's heart and a fine amount of code 962: is dedicated to their management and for providing support functions to them. 963: (-: Actually, this is the reason why the directory with sources of the core 964: code is called <CODE>nest</CODE> :-). 965:  966: When talking about protocols, one need to distinguish between protocols 967: and protocol instances. A protocol exists exactly once, not depending on whether 968: it's configured or not and it can have an arbitrary number of instances corresponding 969: to its "incarnations" requested by the configuration file. Each instance is completely 970: autonomous, has its own configuration, its own status, its own set of routes and its 971: own set of interfaces it works on. 972:  973: A protocol is represented by a protocol structure containing all the basic 974: information (protocol name, default settings and pointers to most of the protocol 975: hooks). All these structures are linked in the protocol_list list. 976:  977: Each instance has its own proto structure describing all its properties: protocol 978: type, configuration, a resource pool where all resources belonging to the instance 979: live, various protocol attributes (take a look at the declaration of proto in 980: <CODE>protocol.h</CODE>), protocol states (see below for what do they mean), connections 981: to routing tables, filters attached to the protocol 982: and finally a set of pointers to the rest of protocol hooks (they 983: are the same for all instances of the protocol, but in order to avoid extra 984: indirections when calling the hooks from the fast path, they are stored directly 985: in proto). The instance is always linked in both the global instance list 986: (proto_list) and a per-status list (either active_proto_list for 987: running protocols, initial_proto_list for protocols being initialized or 988: flush_proto_list when the protocol is being shut down). 989:  990: The protocol hooks are described in the next chapter, for more information about 991: configuration of protocols, please refer to the configuration chapter and also 992: to the description of the proto_commit function. 993:  994: <H3>Protocol states</H3> 995: 996: As startup and shutdown of each protocol are complex processes which can be affected 997: by lots of external events (user's actions, reconfigurations, behavior of neighboring routers etc.), 998: we have decided to supervise them by a pair of simple state machines -- the protocol 999: state machine and a core state machine. 1000:  1001: The protocol state machine corresponds to internal state of the protocol 1002: and the protocol can alter its state whenever it wants to. There are 1003: the following states: 1004:  1005: <DL> 1006: <DT><CODE>PS_DOWN</CODE><DD>The protocol is down and waits for being woken up by calling its 1007: start() hook. 1008: <DT><CODE>PS_START</CODE><DD>The protocol is waiting for connection with the rest of the 1009: network. It's active, it has resources allocated, but it still doesn't want 1010: any routes since it doesn't know what to do with them. 1011: <DT><CODE>PS_UP</CODE><DD>The protocol is up and running. It communicates with the core, 1012: delivers routes to tables and wants to hear announcement about route changes. 1013: <DT><CODE>PS_STOP</CODE><DD>The protocol has been shut down (either by being asked by the 1014: core code to do so or due to having encountered a protocol error). 1015: </DL> 1016:  1017: Unless the protocol is in the <CODE>PS_DOWN</CODE> state, it can decide to change 1018: its state by calling the proto_notify_state function. 1019:  1020: At any time, the core code can ask the protocol to shut itself down by calling its stop() hook. 1021:  1022: The core state machine takes care of the core view of protocol state. 1023: The states are traversed according to changes of the protocol state machine, but 1024: sometimes the transitions are delayed if the core needs to finish some actions 1025: (for example sending of new routes to the protocol) before proceeding to the 1026: new state. There are the following core states: 1027:  1028: <DL> 1029: <DT><CODE>FS_HUNGRY</CODE><DD>The protocol is down, it doesn't have any routes and 1030: doesn't want them. 1031: <DT><CODE>FS_FEEDING</CODE><DD>The protocol has reached the <CODE>PS_UP</CODE> state, but 1032: we are still busy sending the initial set of routes to it. 1033: <DT><CODE>FS_HAPPY</CODE><DD>The protocol is up and has complete routing information. 1034: <DT><CODE>FS_FLUSHING</CODE><DD>The protocol is shutting down (it's in either <CODE>PS_STOP</CODE> 1035: or <CODE>PS_DOWN</CODE> state) and we're flushing all of its routes from the 1036: routing tables. 1037: </DL> 1038:  1039: <H3>Functions of the protocol module</H3> 1040: 1041: The protocol module provides the following functions: 1042: <HR><H3>Function</H3> 1043: void * 1044: proto_new 1045: (struct proto_config * c, unsigned size) -- create a new protocol instance 1046:  1047: <H3>Arguments</H3> 1048:  1049: <DL> 1050: <DT>struct proto_config * c<DD>protocol configuration 1051: <DT>unsigned size<DD>size of protocol data structure (each protocol instance is represented by 1052: a structure starting with generic part [struct proto] and continued 1053: with data specific to the protocol) 1054: </DL> 1055: <H3>Description</H3> 1056: When a new configuration has been read in, the core code starts 1057: initializing all the protocol instances configured by calling their 1058: init() hooks with the corresponding instance configuration. The initialization 1059: code of the protocol is expected to create a new instance according to the 1060: configuration by calling this function and then modifying the default settings 1061: to values wanted by the protocol. 1062: 1063: 1064: <HR><H3>Function</H3> 1065: struct announce_hook * 1066: proto_add_announce_hook 1067: (struct proto * p, struct rtable * t, struct proto_stats * stats) -- connect protocol to a routing table 1068:  1069: <H3>Arguments</H3> 1070:  1071: <DL> 1072: <DT>struct proto * p<DD>protocol instance 1073: <DT>struct rtable * t<DD>routing table to connect to 1074: <DT>struct proto_stats * stats<DD>per-table protocol statistics 1075: </DL> 1076: <H3>Description</H3> 1077: This function creates a connection between the protocol instance p and the 1078: routing table t, making the protocol hear all changes in the table. 1079: The announce hook is linked in the protocol ahook list. Announce hooks are 1080: allocated from the routing table resource pool and when protocol accepts 1081: routes also in the table ahook list. The are linked to the table ahook list 1082: and unlinked from it depending on export_state (in proto_want_export_up() and 1083: proto_want_export_down()) and they are automatically freed after the protocol 1084: is flushed (in proto_fell_down()). 1085: Unless you want to listen to multiple routing tables (as the Pipe protocol 1086: does), you needn't to worry about this function since the connection to the 1087: protocol's primary routing table is initialized automatically by the core 1088: code. 1089: 1090: 1091: <HR><H3>Function</H3> 1092: struct announce_hook * 1093: proto_find_announce_hook 1094: (struct proto * p, struct rtable * t) -- find announce hooks 1095:  1096: <H3>Arguments</H3> 1097:  1098: <DL> 1099: <DT>struct proto * p<DD>protocol instance 1100: <DT>struct rtable * t<DD>routing table 1101: </DL> 1102: <H3>Description</H3> 1103: Returns pointer to announce hook or NULL 1104: 1105: 1106: <HR><H3>Function</H3> 1107: void * 1108: proto_config_new 1109: (struct protocol * pr, int class) -- create a new protocol configuration 1110:  1111: <H3>Arguments</H3> 1112:  1113: <DL> 1114: <DT>struct protocol * pr<DD>protocol the configuration will belong to 1115: <DT>int class<DD>SYM_PROTO or SYM_TEMPLATE 1116: </DL> 1117: <H3>Description</H3> 1118: Whenever the configuration file says that a new instance 1119: of a routing protocol should be created, the parser calls 1120: proto_config_new() to create a configuration entry for this 1121: instance (a structure staring with the proto_config header 1122: containing all the generic items followed by protocol-specific 1123: ones). Also, the configuration entry gets added to the list 1124: of protocol instances kept in the configuration. 1125: The function is also used to create protocol templates (when class 1126: SYM_TEMPLATE is specified), the only difference is that templates 1127: are not added to the list of protocol instances and therefore not 1128: initialized during protos_commit()). 1129: 1130: 1131: <HR><H3>Function</H3> 1132: void 1133: proto_copy_config 1134: (struct proto_config * dest, struct proto_config * src) -- copy a protocol configuration 1135:  1136: <H3>Arguments</H3> 1137:  1138: <DL> 1139: <DT>struct proto_config * dest<DD>destination protocol configuration 1140: <DT>struct proto_config * src<DD>source protocol configuration 1141: </DL> 1142: <H3>Description</H3> 1143: Whenever a new instance of a routing protocol is created from the 1144: template, proto_copy_config() is called to copy a content of 1145: the source protocol configuration to the new protocol configuration. 1146: Name, class and a node in protos list of dest are kept intact. 1147: copy_config() protocol hook is used to copy protocol-specific data. 1148: 1149: 1150: <HR><H3>Function</H3> 1151: void 1152: protos_preconfig 1153: (struct config * c) -- pre-configuration processing 1154:  1155: <H3>Arguments</H3> 1156:  1157: <DL> 1158: <DT>struct config * c<DD>new configuration 1159: </DL> 1160: <H3>Description</H3> 1161: This function calls the preconfig() hooks of all routing 1162: protocols available to prepare them for reading of the new 1163: configuration. 1164: 1165: 1166: <HR><H3>Function</H3> 1167: void 1168: protos_postconfig 1169: (struct config * c) -- post-configuration processing 1170:  1171: <H3>Arguments</H3> 1172:  1173: <DL> 1174: <DT>struct config * c<DD>new configuration 1175: </DL> 1176: <H3>Description</H3> 1177: This function calls the postconfig() hooks of all protocol 1178: instances specified in configuration c. The hooks are not 1179: called for protocol templates. 1180: 1181: 1182: <HR><H3>Function</H3> 1183: void 1184: protos_commit 1185: (struct config * new, struct config * old, int force_reconfig, int type) -- commit new protocol configuration 1186:  1187: <H3>Arguments</H3> 1188:  1189: <DL> 1190: <DT>struct config * new<DD>new configuration 1191: <DT>struct config * old<DD>old configuration or NULL if it's boot time config 1192: <DT>int force_reconfig<DD>force restart of all protocols (used for example 1193: when the router ID changes) 1194: <DT>int type<DD>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD) 1195: </DL> 1196: <H3>Description</H3> 1197: Scan differences between old and new configuration and adjust all 1198: protocol instances to conform to the new configuration. 1199: When a protocol exists in the new configuration, but it doesn't in the 1200: original one, it's immediately started. When a collision with the other 1201: running protocol would arise, the new protocol will be temporarily stopped 1202: by the locking mechanism. 1203: When a protocol exists in the old configuration, but it doesn't in the 1204: new one, it's shut down and deleted after the shutdown completes. 1205: When a protocol exists in both configurations, the core decides 1206: whether it's possible to reconfigure it dynamically - it checks all 1207: the core properties of the protocol (changes in filters are ignored 1208: if type is RECONFIG_SOFT) and if they match, it asks the 1209: reconfigure() hook of the protocol to see if the protocol is able 1210: to switch to the new configuration. If it isn't possible, the 1211: protocol is shut down and a new instance is started with the new 1212: configuration after the shutdown is completed. 1213: 1214: <H2><A NAME="ss2.5">2.5</A> <A HREF="prog.html#toc2.5">Graceful restart recovery</A> 1215: </H2> 1216: 1217:  1218: Graceful restart of a router is a process when the routing plane (e.g. BIRD) 1219: restarts but both the forwarding plane (e.g kernel routing table) and routing 1220: neighbors keep proper routes, and therefore uninterrupted packet forwarding 1221: is maintained. 1222: BIRD implements graceful restart recovery by deferring export of routes to 1223: protocols until routing tables are refilled with the expected content. After 1224: start, protocols generate routes as usual, but routes are not propagated to 1225: them, until protocols report that they generated all routes. After that, 1226: graceful restart recovery is finished and the export (and the initial feed) 1227: to protocols is enabled. 1228: When graceful restart recovery need is detected during initialization, then 1229: enabled protocols are marked with gr_recovery flag before start. Such 1230: protocols then decide how to proceed with graceful restart, participation is 1231: voluntary. Protocols could lock the recovery by proto_graceful_restart_lock() 1232: (stored in gr_lock flag), which means that they want to postpone the end of 1233: the recovery until they converge and then unlock it. They also could set 1234: gr_wait before advancing to PS_UP, which means that the core should defer 1235: route export to that protocol until the end of the recovery. This should be 1236: done by protocols that expect their neigbors to keep the proper routes 1237: (kernel table, BGP sessions with BGP graceful restart capability). 1238: The graceful restart recovery is finished when either all graceful restart 1239: locks are unlocked or when graceful restart wait timer fires. 1240:  1241: <HR><H3>Function</H3> 1242: void 1243: graceful_restart_recovery 1244: (void) -- request initial graceful restart recovery 1245:  1246: <H3>Graceful restart recovery</H3> 1247:  1248: Called by the platform initialization code if the need for recovery 1249: after graceful restart is detected during boot. Have to be called 1250: before protos_commit(). 1251: 1252: 1253: <HR><H3>Function</H3> 1254: void 1255: graceful_restart_init 1256: (void) -- initialize graceful restart 1257:  1258: <H3>Description</H3> 1259:  1260: When graceful restart recovery was requested, the function starts an active 1261: phase of the recovery and initializes graceful restart wait timer. The 1262: function have to be called after protos_commit(). 1263: 1264: 1265: <HR><H3>Function</H3> 1266: void 1267: graceful_restart_done 1268: (struct timer *t UNUSED) -- finalize graceful restart 1269:  1270: <H3>Arguments</H3> 1271:  1272: <DL> 1273: <DT>struct timer *t UNUSED<DD>-- undescribed -- 1274: </DL> 1275: <H3>Description</H3> 1276: When there are no locks on graceful restart, the functions finalizes the 1277: graceful restart recovery. Protocols postponing route export until the end of 1278: the recovery are awakened and the export to them is enabled. All other 1279: related state is cleared. The function is also called when the graceful 1280: restart wait timer fires (but there are still some locks). 1281: 1282: 1283: <HR><H3>Function</H3> 1284: void 1285: proto_graceful_restart_lock 1286: (struct proto * p) -- lock graceful restart by protocol 1287:  1288: <H3>Arguments</H3> 1289:  1290: <DL> 1291: <DT>struct proto * p<DD>protocol instance 1292: </DL> 1293: <H3>Description</H3> 1294: This function allows a protocol to postpone the end of graceful restart 1295: recovery until it converges. The lock is removed when the protocol calls 1296: proto_graceful_restart_unlock() or when the protocol is stopped. 1297: The function have to be called during the initial phase of graceful restart 1298: recovery and only for protocols that are part of graceful restart (i.e. their 1299: gr_recovery is set), which means it should be called from protocol start 1300: hooks. 1301: 1302: 1303: <HR><H3>Function</H3> 1304: void 1305: proto_graceful_restart_unlock 1306: (struct proto * p) -- unlock graceful restart by protocol 1307:  1308: <H3>Arguments</H3> 1309:  1310: <DL> 1311: <DT>struct proto * p<DD>protocol instance 1312: </DL> 1313: <H3>Description</H3> 1314: This function unlocks a lock from proto_graceful_restart_lock(). It is also 1315: automatically called when the lock holding protocol went down. 1316: 1317: 1318: <HR><H3>Function</H3> 1319: void 1320: protos_dump_all 1321: (void) -- dump status of all protocols 1322:  1323: <H3>Description</H3> 1324:  1325: This function dumps status of all existing protocol instances to the 1326: debug output. It involves printing of general status information 1327: such as protocol states, its position on the protocol lists 1328: and also calling of a dump() hook of the protocol to print 1329: the internals. 1330: 1331: 1332: <HR><H3>Function</H3> 1333: void 1334: proto_build 1335: (struct protocol * p) -- make a single protocol available 1336:  1337: <H3>Arguments</H3> 1338:  1339: <DL> 1340: <DT>struct protocol * p<DD>the protocol 1341: </DL> 1342: <H3>Description</H3> 1343: After the platform specific initialization code uses protos_build() 1344: to add all the standard protocols, it should call proto_build() for 1345: all platform specific protocols to inform the core that they exist. 1346: 1347: 1348: <HR><H3>Function</H3> 1349: void 1350: protos_build 1351: (void) -- build a protocol list 1352:  1353: <H3>Description</H3> 1354:  1355: This function is called during BIRD startup to insert 1356: all standard protocols to the global protocol list. Insertion 1357: of platform specific protocols (such as the kernel syncer) 1358: is in the domain of competence of the platform dependent 1359: startup code. 1360: 1361: 1362: <HR><H3>Function</H3> 1363: void 1364: proto_set_message 1365: (struct proto * p, char * msg, int len) -- set administrative message to protocol 1366:  1367: <H3>Arguments</H3> 1368:  1369: <DL> 1370: <DT>struct proto * p<DD>protocol 1371: <DT>char * msg<DD>message 1372: <DT>int len<DD>message length (-1 for NULL-terminated string) 1373: </DL> 1374: <H3>Description</H3> 1375: The function sets administrative message (string) related to protocol state 1376: change. It is called by the nest code for manual enable/disable/restart 1377: commands all routes to the protocol, and by protocol-specific code when the 1378: protocol state change is initiated by the protocol. Using NULL message clears 1379: the last message. The message string may be either NULL-terminated or with an 1380: explicit length. 1381: 1382: 1383: <HR><H3>Function</H3> 1384: void 1385: proto_request_feeding 1386: (struct proto * p) -- request feeding routes to the protocol 1387:  1388: <H3>Arguments</H3> 1389:  1390: <DL> 1391: <DT>struct proto * p<DD>given protocol 1392: </DL> 1393: <H3>Description</H3> 1394: Sometimes it is needed to send again all routes to the 1395: protocol. This is called feeding and can be requested by this 1396: function. This would cause protocol export state transition 1397: to ES_FEEDING (during feeding) and when completed, it will 1398: switch back to ES_READY. This function can be called even 1399: when feeding is already running, in that case it is restarted. 1400: 1401: 1402: <HR><H3>Function</H3> 1403: void 1404: proto_notify_limit 1405: (struct announce_hook * ah, struct proto_limit * l, int dir, u32 rt_count) 1406: <H3>Arguments</H3> 1407:  1408: <DL> 1409: <DT>struct announce_hook * ah<DD>announce hook 1410: <DT>struct proto_limit * l<DD>limit being hit 1411: <DT>int dir<DD>limit direction (PLD_*) 1412: <DT>u32 rt_count<DD>the number of routes 1413: </DL> 1414: <H3>Description</H3> 1415: The function is called by the route processing core when limit l 1416: is breached. It activates the limit and tooks appropriate action 1417: according to l->action. 1418: 1419: 1420: <HR><H3>Function</H3> 1421: void 1422: proto_notify_state 1423: (struct proto * p, unsigned ps) -- notify core about protocol state change 1424:  1425: <H3>Arguments</H3> 1426:  1427: <DL> 1428: <DT>struct proto * p<DD>protocol the state of which has changed 1429: <DT>unsigned ps<DD>the new status 1430: </DL> 1431: <H3>Description</H3> 1432: Whenever a state of a protocol changes due to some event internal 1433: to the protocol (i.e., not inside a start() or shutdown() hook), 1434: it should immediately notify the core about the change by calling 1435: proto_notify_state() which will write the new state to the proto 1436: structure and take all the actions necessary to adapt to the new 1437: state. State change to PS_DOWN immediately frees resources of protocol 1438: and might execute start callback of protocol; therefore, 1439: it should be used at tail positions of protocol callbacks. 1440: 1441: <H2><A NAME="ss2.6">2.6</A> <A HREF="prog.html#toc2.6">Protocol hooks</A> 1442: </H2> 1443: 1444:  1445: Each protocol can provide a rich set of hook functions referred to by pointers 1446: in either the proto or protocol structure. They are called by the core whenever 1447: it wants the protocol to perform some action or to notify the protocol about 1448: any change of its environment. All of the hooks can be set to NULL which means 1449: to ignore the change or to take a default action. 1450:  1451: <HR><H3>Function</H3> 1452: void 1453: preconfig 1454: (struct protocol * p, struct config * c) -- protocol preconfiguration 1455:  1456: <H3>Arguments</H3> 1457:  1458: <DL> 1459: <DT>struct protocol * p<DD>a routing protocol 1460: <DT>struct config * c<DD>new configuration 1461: </DL> 1462: <H3>Description</H3> 1463: The preconfig() hook is called before parsing of a new configuration. 1464: 1465: 1466: <HR><H3>Function</H3> 1467: void 1468: postconfig 1469: (struct proto_config * c) -- instance post-configuration 1470:  1471: <H3>Arguments</H3> 1472:  1473: <DL> 1474: <DT>struct proto_config * c<DD>instance configuration 1475: </DL> 1476: <H3>Description</H3> 1477: The postconfig() hook is called for each configured instance after 1478: parsing of the new configuration is finished. 1479: 1480: 1481: <HR><H3>Function</H3> 1482: struct proto * 1483: init 1484: (struct proto_config * c) -- initialize an instance 1485:  1486: <H3>Arguments</H3> 1487:  1488: <DL> 1489: <DT>struct proto_config * c<DD>instance configuration 1490: </DL> 1491: <H3>Description</H3> 1492: The init() hook is called by the core to create a protocol instance 1493: according to supplied protocol configuration. 1494: <H3>Result</H3> 1495: a pointer to the instance created 1496: 1497: 1498: <HR><H3>Function</H3> 1499: int 1500: reconfigure 1501: (struct proto * p, struct proto_config * c) -- request instance reconfiguration 1502:  1503: <H3>Arguments</H3> 1504:  1505: <DL> 1506: <DT>struct proto * p<DD>an instance 1507: <DT>struct proto_config * c<DD>new configuration 1508: </DL> 1509: <H3>Description</H3> 1510: The core calls the reconfigure() hook whenever it wants to ask the 1511: protocol for switching to a new configuration. If the reconfiguration 1512: is possible, the hook returns 1. Otherwise, it returns 0 and the core 1513: will shut down the instance and start a new one with the new configuration. 1514: After the protocol confirms reconfiguration, it must no longer keep any 1515: references to the old configuration since the memory it's stored in can 1516: be re-used at any time. 1517: 1518: 1519: <HR><H3>Function</H3> 1520: void 1521: dump 1522: (struct proto * p) -- dump protocol state 1523:  1524: <H3>Arguments</H3> 1525:  1526: <DL> 1527: <DT>struct proto * p<DD>an instance 1528: </DL> 1529: <H3>Description</H3> 1530: This hook dumps the complete state of the instance to the 1531: debug output. 1532: 1533: 1534: <HR><H3>Function</H3> 1535: void 1536: dump_attrs 1537: (rte * e) -- dump protocol-dependent attributes 1538:  1539: <H3>Arguments</H3> 1540:  1541: <DL> 1542: <DT>rte * e<DD>a route entry 1543: </DL> 1544: <H3>Description</H3> 1545: This hook dumps all attributes in the rte which belong to this 1546: protocol to the debug output. 1547: 1548: 1549: <HR><H3>Function</H3> 1550: int 1551: start 1552: (struct proto * p) -- request instance startup 1553:  1554: <H3>Arguments</H3> 1555:  1556: <DL> 1557: <DT>struct proto * p<DD>protocol instance 1558: </DL> 1559: <H3>Description</H3> 1560: The start() hook is called by the core when it wishes to start 1561: the instance. Multitable protocols should lock their tables here. 1562: <H3>Result</H3> 1563: new protocol state 1564: 1565: 1566: <HR><H3>Function</H3> 1567: int 1568: shutdown 1569: (struct proto * p) -- request instance shutdown 1570:  1571: <H3>Arguments</H3> 1572:  1573: <DL> 1574: <DT>struct proto * p<DD>protocol instance 1575: </DL> 1576: <H3>Description</H3> 1577: The stop() hook is called by the core when it wishes to shut 1578: the instance down for some reason. 1579: <H3>Returns</H3> 1580: new protocol state 1581: 1582: 1583: <HR><H3>Function</H3> 1584: void 1585: cleanup 1586: (struct proto * p) -- request instance cleanup 1587:  1588: <H3>Arguments</H3> 1589:  1590: <DL> 1591: <DT>struct proto * p<DD>protocol instance 1592: </DL> 1593: <H3>Description</H3> 1594: The cleanup() hook is called by the core when the protocol became 1595: hungry/down, i.e. all protocol ahooks and routes are flushed. 1596: Multitable protocols should unlock their tables here. 1597: 1598: 1599: <HR><H3>Function</H3> 1600: void 1601: get_status 1602: (struct proto * p, byte * buf) -- get instance status 1603:  1604: <H3>Arguments</H3> 1605:  1606: <DL> 1607: <DT>struct proto * p<DD>protocol instance 1608: <DT>byte * buf<DD>buffer to be filled with the status string 1609: </DL> 1610: <H3>Description</H3> 1611: This hook is called by the core if it wishes to obtain an brief one-line user friendly 1612: representation of the status of the instance to be printed by the <cf/show protocols/ 1613: command. 1614: 1615: 1616: <HR><H3>Function</H3> 1617: void 1618: get_route_info 1619: (rte * e, byte * buf, ea_list * attrs) -- get route information 1620:  1621: <H3>Arguments</H3> 1622:  1623: <DL> 1624: <DT>rte * e<DD>a route entry 1625: <DT>byte * buf<DD>buffer to be filled with the resulting string 1626: <DT>ea_list * attrs<DD>extended attributes of the route 1627: </DL> 1628: <H3>Description</H3> 1629: This hook is called to fill the buffer buf with a brief user friendly 1630: representation of metrics of a route belonging to this protocol. 1631: 1632: 1633: <HR><H3>Function</H3> 1634: int 1635: get_attr 1636: (eattr * a, byte * buf, int buflen) -- get attribute information 1637:  1638: <H3>Arguments</H3> 1639:  1640: <DL> 1641: <DT>eattr * a<DD>an extended attribute 1642: <DT>byte * buf<DD>buffer to be filled with attribute information 1643: <DT>int buflen<DD>a length of the buf parameter 1644: </DL> 1645: <H3>Description</H3> 1646: The get_attr() hook is called by the core to obtain a user friendly 1647: representation of an extended route attribute. It can either leave 1648: the whole conversion to the core (by returning GA_UNKNOWN), fill 1649: in only attribute name (and let the core format the attribute value 1650: automatically according to the type field; by returning GA_NAME) 1651: or doing the whole conversion (used in case the value requires extra 1652: care; return GA_FULL). 1653: 1654: 1655: <HR><H3>Function</H3> 1656: void 1657: if_notify 1658: (struct proto * p, unsigned flags, struct iface * i) -- notify instance about interface changes 1659:  1660: <H3>Arguments</H3> 1661:  1662: <DL> 1663: <DT>struct proto * p<DD>protocol instance 1664: <DT>unsigned flags<DD>interface change flags 1665: <DT>struct iface * i<DD>the interface in question 1666: </DL> 1667: <H3>Description</H3> 1668: This hook is called whenever any network interface changes its status. 1669: The change is described by a combination of status bits (IF_CHANGE_xxx) 1670: in the flags parameter. 1671: 1672: 1673: <HR><H3>Function</H3> 1674: void 1675: ifa_notify 1676: (struct proto * p, unsigned flags, struct ifa * a) -- notify instance about interface address changes 1677:  1678: <H3>Arguments</H3> 1679:  1680: <DL> 1681: <DT>struct proto * p<DD>protocol instance 1682: <DT>unsigned flags<DD>address change flags 1683: <DT>struct ifa * a<DD>the interface address 1684: </DL> 1685: <H3>Description</H3> 1686: This hook is called to notify the protocol instance about an interface 1687: acquiring or losing one of its addresses. The change is described by 1688: a combination of status bits (IF_CHANGE_xxx) in the flags parameter. 1689: 1690: 1691: <HR><H3>Function</H3> 1692: void 1693: rt_notify 1694: (struct proto * p, net * net, rte * new, rte * old, ea_list * attrs) -- notify instance about routing table change 1695:  1696: <H3>Arguments</H3> 1697:  1698: <DL> 1699: <DT>struct proto * p<DD>protocol instance 1700: <DT>net * net<DD>a network entry 1701: <DT>rte * new<DD>new route for the network 1702: <DT>rte * old<DD>old route for the network 1703: <DT>ea_list * attrs<DD>extended attributes associated with the new entry 1704: </DL> 1705: <H3>Description</H3> 1706: The rt_notify() hook is called to inform the protocol instance about 1707: changes in the connected routing table table, that is a route old 1708: belonging to network net being replaced by a new route new with 1709: extended attributes attrs. Either new or old or both can be NULL 1710: if the corresponding route doesn't exist. 1711: If the type of route announcement is RA_OPTIMAL, it is an 1712: announcement of optimal route change, new stores the new optimal 1713: route and old stores the old optimal route. 1714: If the type of route announcement is RA_ANY, it is an announcement 1715: of any route change, new stores the new route and old stores the 1716: old route from the same protocol. 1717: p->accept_ra_types specifies which kind of route announcements 1718: protocol wants to receive. 1719: 1720: 1721: <HR><H3>Function</H3> 1722: void 1723: neigh_notify 1724: (neighbor * neigh) -- notify instance about neighbor status change 1725:  1726: <H3>Arguments</H3> 1727:  1728: <DL> 1729: <DT>neighbor * neigh<DD>a neighbor cache entry 1730: </DL> 1731: <H3>Description</H3> 1732: The neigh_notify() hook is called by the neighbor cache whenever 1733: a neighbor changes its state, that is it gets disconnected or a 1734: sticky neighbor gets connected. 1735: 1736: 1737: <HR><H3>Function</H3> 1738: ea_list * 1739: make_tmp_attrs 1740: (rte * e, struct linpool * pool) -- convert embedded attributes to temporary ones 1741:  1742: <H3>Arguments</H3> 1743:  1744: <DL> 1745: <DT>rte * e<DD>route entry 1746: <DT>struct linpool * pool<DD>linear pool to allocate attribute memory in 1747: </DL> 1748: <H3>Description</H3> 1749: This hook is called by the routing table functions if they need 1750: to convert the protocol attributes embedded directly in the rte 1751: to temporary extended attributes in order to distribute them 1752: to other protocols or to filters. make_tmp_attrs() creates 1753: an ea_list in the linear pool pool, fills it with values of the 1754: temporary attributes and returns a pointer to it. 1755: 1756: 1757: <HR><H3>Function</H3> 1758: void 1759: store_tmp_attrs 1760: (rte * e, ea_list * attrs) -- convert temporary attributes to embedded ones 1761:  1762: <H3>Arguments</H3> 1763:  1764: <DL> 1765: <DT>rte * e<DD>route entry 1766: <DT>ea_list * attrs<DD>temporary attributes to be converted 1767: </DL> 1768: <H3>Description</H3> 1769: This hook is an exact opposite of make_tmp_attrs() -- it takes 1770: a list of extended attributes and converts them to attributes 1771: embedded in the rte corresponding to this protocol. 1772: You must be prepared for any of the attributes being missing 1773: from the list and use default values instead. 1774: 1775: 1776: <HR><H3>Function</H3> 1777: int 1778: import_control 1779: (struct proto * p, rte ** e, ea_list ** attrs, struct linpool * pool) -- pre-filtering decisions on route import 1780:  1781: <H3>Arguments</H3> 1782:  1783: <DL> 1784: <DT>struct proto * p<DD>protocol instance the route is going to be imported to 1785: <DT>rte ** e<DD>the route in question 1786: <DT>ea_list ** attrs<DD>extended attributes of the route 1787: <DT>struct linpool * pool<DD>linear pool for allocation of all temporary data 1788: </DL> 1789: <H3>Description</H3> 1790: The import_control() hook is called as the first step of a exporting 1791: a route from a routing table to the protocol instance. It can modify 1792: route attributes and force acceptance or rejection of the route regardless 1793: of user-specified filters. See rte_announce() for a complete description 1794: of the route distribution process. 1795: The standard use of this hook is to reject routes having originated 1796: from the same instance and to set default values of the protocol's metrics. 1797: <H3>Result</H3> 1798: 1 if the route has to be accepted, -1 if rejected and 0 if it 1799: should be passed to the filters. 1800: 1801: 1802: <HR><H3>Function</H3> 1803: int 1804: rte_recalculate 1805: (struct rtable * table, struct network * net, struct rte * new, struct rte * old, struct rte * old_best) -- prepare routes for comparison 1806:  1807: <H3>Arguments</H3> 1808:  1809: <DL> 1810: <DT>struct rtable * table<DD>a routing table 1811: <DT>struct network * net<DD>a network entry 1812: <DT>struct rte * new<DD>new route for the network 1813: <DT>struct rte * old<DD>old route for the network 1814: <DT>struct rte * old_best<DD>old best route for the network (may be NULL) 1815: </DL> 1816: <H3>Description</H3> 1817: This hook is called when a route change (from old to new for a 1818: net entry) is propagated to a table. It may be used to prepare 1819: routes for comparison by rte_better() in the best route 1820: selection. new may or may not be in net->routes list, 1821: old is not there. 1822: <H3>Result</H3> 1823: 1 if the ordering implied by rte_better() changes enough 1824: that full best route calculation have to be done, 0 otherwise. 1825: 1826: 1827: <HR><H3>Function</H3> 1828: int 1829: rte_better 1830: (rte * new, rte * old) -- compare metrics of two routes 1831:  1832: <H3>Arguments</H3> 1833:  1834: <DL> 1835: <DT>rte * new<DD>the new route 1836: <DT>rte * old<DD>the original route 1837: </DL> 1838: <H3>Description</H3> 1839: This hook gets called when the routing table contains two routes 1840: for the same network which have originated from different instances 1841: of a single protocol and it wants to select which one is preferred 1842: over the other one. Protocols usually decide according to route metrics. 1843: <H3>Result</H3> 1844: 1 if new is better (more preferred) than old, 0 otherwise. 1845: 1846: 1847: <HR><H3>Function</H3> 1848: int 1849: rte_same 1850: (rte * e1, rte * e2) -- compare two routes 1851:  1852: <H3>Arguments</H3> 1853:  1854: <DL> 1855: <DT>rte * e1<DD>route 1856: <DT>rte * e2<DD>route 1857: </DL> 1858: <H3>Description</H3> 1859: The rte_same() hook tests whether the routes e1 and e2 belonging 1860: to the same protocol instance have identical contents. Contents of 1861: rta, all the extended attributes and rte preference are checked 1862: by the core code, no need to take care of them here. 1863: <H3>Result</H3> 1864: 1 if e1 is identical to e2, 0 otherwise. 1865: 1866: 1867: <HR><H3>Function</H3> 1868: void 1869: rte_insert 1870: (net * n, rte * e) -- notify instance about route insertion 1871:  1872: <H3>Arguments</H3> 1873:  1874: <DL> 1875: <DT>net * n<DD>network 1876: <DT>rte * e<DD>route 1877: </DL> 1878: <H3>Description</H3> 1879: This hook is called whenever a rte belonging to the instance 1880: is accepted for insertion to a routing table. 1881: Please avoid using this function in new protocols. 1882: 1883: 1884: <HR><H3>Function</H3> 1885: void 1886: rte_remove 1887: (net * n, rte * e) -- notify instance about route removal 1888:  1889: <H3>Arguments</H3> 1890:  1891: <DL> 1892: <DT>net * n<DD>network 1893: <DT>rte * e<DD>route 1894: </DL> 1895: <H3>Description</H3> 1896: This hook is called whenever a rte belonging to the instance 1897: is removed from a routing table. 1898: Please avoid using this function in new protocols. 1899: 1900: <H2><A NAME="ss2.7">2.7</A> <A HREF="prog.html#toc2.7">Interfaces</A> 1901: </H2> 1902: 1903:  1904: The interface module keeps track of all network interfaces in the 1905: system and their addresses. 1906: Each interface is represented by an iface structure which carries 1907: interface capability flags (IF_MULTIACCESS, IF_BROADCAST etc.), 1908: MTU, interface name and index and finally a linked list of network 1909: prefixes assigned to the interface, each one represented by 1910: struct ifa. 1911: The interface module keeps a `soft-up' state for each iface which 1912: is a conjunction of link being up, the interface being of a `sane' 1913: type and at least one IP address assigned to it. 1914:  1915: <HR><H3>Function</H3> 1916: void 1917: ifa_dump 1918: (struct ifa * a) -- dump interface address 1919:  1920: <H3>Arguments</H3> 1921:  1922: <DL> 1923: <DT>struct ifa * a<DD>interface address descriptor 1924: </DL> 1925: <H3>Description</H3> 1926: This function dumps contents of an ifa to the debug output. 1927: 1928: 1929: <HR><H3>Function</H3> 1930: void 1931: if_dump 1932: (struct iface * i) -- dump interface 1933:  1934: <H3>Arguments</H3> 1935:  1936: <DL> 1937: <DT>struct iface * i<DD>interface to dump 1938: </DL> 1939: <H3>Description</H3> 1940: This function dumps all information associated with a given 1941: network interface to the debug output. 1942: 1943: 1944: <HR><H3>Function</H3> 1945: void 1946: if_dump_all 1947: (void) -- dump all interfaces 1948:  1949: <H3>Description</H3> 1950:  1951: This function dumps information about all known network 1952: interfaces to the debug output. 1953: 1954: 1955: <HR><H3>Function</H3> 1956: void 1957: if_delete 1958: (struct iface * old) -- remove interface 1959:  1960: <H3>Arguments</H3> 1961:  1962: <DL> 1963: <DT>struct iface * old<DD>interface 1964: </DL> 1965: <H3>Description</H3> 1966: This function is called by the low-level platform dependent code 1967: whenever it notices an interface disappears. It is just a shorthand 1968: for if_update(). 1969: 1970: 1971: <HR><H3>Function</H3> 1972: struct iface * 1973: if_update 1974: (struct iface * new) -- update interface status 1975:  1976: <H3>Arguments</H3> 1977:  1978: <DL> 1979: <DT>struct iface * new<DD>new interface status 1980: </DL> 1981: <H3>Description</H3> 1982: if_update() is called by the low-level platform dependent code 1983: whenever it notices an interface change. 1984: There exist two types of interface updates -- synchronous and asynchronous 1985: ones. In the synchronous case, the low-level code calls if_start_update(), 1986: scans all interfaces reported by the OS, uses if_update() and ifa_update() 1987: to pass them to the core and then it finishes the update sequence by 1988: calling if_end_update(). When working asynchronously, the sysdep code 1989: calls if_update() and ifa_update() whenever it notices a change. 1990: if_update() will automatically notify all other modules about the change. 1991: 1992: 1993: <HR><H3>Function</H3> 1994: void 1995: if_feed_baby 1996: (struct proto * p) -- advertise interfaces to a new protocol 1997:  1998: <H3>Arguments</H3> 1999:  2000: <DL> 2001: <DT>struct proto * p<DD>protocol to feed 2002: </DL> 2003: <H3>Description</H3> 2004: When a new protocol starts, this function sends it a series 2005: of notifications about all existing interfaces. 2006: 2007: 2008: <HR><H3>Function</H3> 2009: struct iface * 2010: if_find_by_index 2011: (unsigned idx) -- find interface by ifindex 2012:  2013: <H3>Arguments</H3> 2014:  2015: <DL> 2016: <DT>unsigned idx<DD>ifindex 2017: </DL> 2018: <H3>Description</H3> 2019: This function finds an iface structure corresponding to an interface 2020: of the given index idx. Returns a pointer to the structure or NULL 2021: if no such structure exists. 2022: 2023: 2024: <HR><H3>Function</H3> 2025: struct iface * 2026: if_find_by_name 2027: (char * name) -- find interface by name 2028:  2029: <H3>Arguments</H3> 2030:  2031: <DL> 2032: <DT>char * name<DD>interface name 2033: </DL> 2034: <H3>Description</H3> 2035: This function finds an iface structure corresponding to an interface 2036: of the given name name. Returns a pointer to the structure or NULL 2037: if no such structure exists. 2038: 2039: 2040: <HR><H3>Function</H3> 2041: struct ifa * 2042: ifa_update 2043: (struct ifa * a) -- update interface address 2044:  2045: <H3>Arguments</H3> 2046:  2047: <DL> 2048: <DT>struct ifa * a<DD>new interface address 2049: </DL> 2050: <H3>Description</H3> 2051: This function adds address information to a network 2052: interface. It's called by the platform dependent code during 2053: the interface update process described under if_update(). 2054: 2055: 2056: <HR><H3>Function</H3> 2057: void 2058: ifa_delete 2059: (struct ifa * a) -- remove interface address 2060:  2061: <H3>Arguments</H3> 2062:  2063: <DL> 2064: <DT>struct ifa * a<DD>interface address 2065: </DL> 2066: <H3>Description</H3> 2067: This function removes address information from a network 2068: interface. It's called by the platform dependent code during 2069: the interface update process described under if_update(). 2070: 2071: 2072: <HR><H3>Function</H3> 2073: void 2074: if_init 2075: (void) -- initialize interface module 2076:  2077: <H3>Description</H3> 2078:  2079: This function is called during BIRD startup to initialize 2080: all data structures of the interface module. 2081: 2082: <H2><A NAME="ss2.8">2.8</A> <A HREF="prog.html#toc2.8">Neighbor cache</A> 2083: </H2> 2084: 2085:  2086: Most routing protocols need to associate their internal state data with 2087: neighboring routers, check whether an address given as the next hop 2088: attribute of a route is really an address of a directly connected host 2089: and which interface is it connected through. Also, they often need to 2090: be notified when a neighbor ceases to exist or when their long awaited 2091: neighbor becomes connected. The neighbor cache is there to solve all 2092: these problems. 2093: The neighbor cache maintains a collection of neighbor entries. Each 2094: entry represents one IP address corresponding to either our directly 2095: connected neighbor or our own end of the link (when the scope of the 2096: address is set to SCOPE_HOST) together with per-neighbor data belonging to a 2097: single protocol. 2098: Active entries represent known neighbors and are stored in a hash 2099: table (to allow fast retrieval based on the IP address of the node) and 2100: two linked lists: one global and one per-interface (allowing quick 2101: processing of interface change events). Inactive entries exist only 2102: when the protocol has explicitly requested it via the NEF_STICKY 2103: flag because it wishes to be notified when the node will again become 2104: a neighbor. Such entries are enqueued in a special list which is walked 2105: whenever an interface changes its state to up. Neighbor entry VRF 2106: association is implied by respective protocol. 2107: When a neighbor event occurs (a neighbor gets disconnected or a sticky 2108: inactive neighbor becomes connected), the protocol hook neigh_notify() 2109: is called to advertise the change. 2110:  2111: <HR><H3>Function</H3> 2112: neighbor * 2113: neigh_find 2114: (struct proto * p, ip_addr * a, unsigned flags) -- find or create a neighbor entry. 2115:  2116: <H3>Arguments</H3> 2117:  2118: <DL> 2119: <DT>struct proto * p<DD>protocol which asks for the entry. 2120: <DT>ip_addr * a<DD>pointer to IP address of the node to be searched for. 2121: <DT>unsigned flags<DD>0 or NEF_STICKY if you want to create a sticky entry. 2122: </DL> 2123: <H3>Description</H3> 2124: Search the neighbor cache for a node with given IP address. If 2125: it's found, a pointer to the neighbor entry is returned. If no 2126: such entry exists and the node is directly connected on 2127: one of our active interfaces, a new entry is created and returned 2128: to the caller with protocol-dependent fields initialized to zero. 2129: If the node is not connected directly or *a is not a valid unicast 2130: IP address, neigh_find() returns NULL. 2131: 2132: 2133: <HR><H3>Function</H3> 2134: void 2135: neigh_dump 2136: (neighbor * n) -- dump specified neighbor entry. 2137:  2138: <H3>Arguments</H3> 2139:  2140: <DL> 2141: <DT>neighbor * n<DD>the entry to dump 2142: </DL> 2143: <H3>Description</H3> 2144: This functions dumps the contents of a given neighbor entry 2145: to debug output. 2146: 2147: 2148: <HR><H3>Function</H3> 2149: void 2150: neigh_dump_all 2151: (void) -- dump all neighbor entries. 2152:  2153: <H3>Description</H3> 2154:  2155: This function dumps the contents of the neighbor cache to 2156: debug output. 2157: 2158: 2159: <HR><H3>Function</H3> 2160: void 2161: neigh_if_up 2162: (struct iface * i) 2163: <H3>Arguments</H3> 2164:  2165: <DL> 2166: <DT>struct iface * i<DD>interface in question 2167: </DL> 2168: <H3>Description</H3> 2169: Tell the neighbor cache that a new interface became up. 2170: The neighbor cache wakes up all inactive sticky neighbors with 2171: addresses belonging to prefixes of the interface i. 2172: 2173: 2174: <HR><H3>Function</H3> 2175: void 2176: neigh_if_down 2177: (struct iface * i) -- notify neighbor cache about interface down event 2178:  2179: <H3>Arguments</H3> 2180:  2181: <DL> 2182: <DT>struct iface * i<DD>the interface in question 2183: </DL> 2184: <H3>Description</H3> 2185: Notify the neighbor cache that an interface has ceased to exist. 2186: It causes all entries belonging to neighbors connected to this interface 2187: to be flushed. 2188: 2189: 2190: <HR><H3>Function</H3> 2191: void 2192: neigh_if_link 2193: (struct iface * i) -- notify neighbor cache about interface link change 2194:  2195: <H3>Arguments</H3> 2196:  2197: <DL> 2198: <DT>struct iface * i<DD>the interface in question 2199: </DL> 2200: <H3>Description</H3> 2201: Notify the neighbor cache that an interface changed link state. 2202: All owners of neighbor entries connected to this interface are 2203: notified. 2204: 2205: 2206: <HR><H3>Function</H3> 2207: void 2208: neigh_ifa_update 2209: (struct ifa * a) 2210: <H3>Arguments</H3> 2211:  2212: <DL> 2213: <DT>struct ifa * a<DD>interface address in question 2214: </DL> 2215: <H3>Description</H3> 2216: Tell the neighbor cache that an address was added or removed. 2217: The neighbor cache wakes up all inactive sticky neighbors with 2218: addresses belonging to prefixes of the interface belonging to ifa 2219: and causes all unreachable neighbors to be flushed. 2220: 2221: 2222: <HR><H3>Function</H3> 2223: void 2224: neigh_prune 2225: (void) -- prune neighbor cache 2226:  2227: <H3>Description</H3> 2228:  2229: neigh_prune() examines all neighbor entries cached and removes those 2230: corresponding to inactive protocols. It's called whenever a protocol 2231: is shut down to get rid of all its heritage. 2232: 2233: 2234: <HR><H3>Function</H3> 2235: void 2236: neigh_init 2237: (pool * if_pool) -- initialize the neighbor cache. 2238:  2239: <H3>Arguments</H3> 2240:  2241: <DL> 2242: <DT>pool * if_pool<DD>resource pool to be used for neighbor entries. 2243: </DL> 2244: <H3>Description</H3> 2245: This function is called during BIRD startup to initialize 2246: the neighbor cache module. 2247: 2248: <H2><A NAME="ss2.9">2.9</A> <A HREF="prog.html#toc2.9">Command line interface</A> 2249: </H2> 2250: 2251:  2252: This module takes care of the BIRD's command-line interface (CLI). 2253: The CLI exists to provide a way to control BIRD remotely and to inspect 2254: its status. It uses a very simple textual protocol over a stream 2255: connection provided by the platform dependent code (on UNIX systems, 2256: it's a UNIX domain socket). 2257: Each session of the CLI consists of a sequence of request and replies, 2258: slightly resembling the FTP and SMTP protocols. 2259: Requests are commands encoded as a single line of text, replies are 2260: sequences of lines starting with a four-digit code followed by either 2261: a space (if it's the last line of the reply) or a minus sign (when the 2262: reply is going to continue with the next line), the rest of the line 2263: contains a textual message semantics of which depends on the numeric 2264: code. If a reply line has the same code as the previous one and it's 2265: a continuation line, the whole prefix can be replaced by a single 2266: white space character. 2267: Reply codes starting with 0 stand for `action successfully completed' messages, 2268: 1 means `table entry', 8 `runtime error' and 9 `syntax error'. 2269: Each CLI session is internally represented by a cli structure and a 2270: resource pool containing all resources associated with the connection, 2271: so that it can be easily freed whenever the connection gets closed, not depending 2272: on the current state of command processing. 2273: The CLI commands are declared as a part of the configuration grammar 2274: by using the <CODE>CF_CLI</CODE> macro. When a command is received, it is processed 2275: by the same lexical analyzer and parser as used for the configuration, but 2276: it's switched to a special mode by prepending a fake token to the text, 2277: so that it uses only the CLI command rules. Then the parser invokes 2278: an execution routine corresponding to the command, which either constructs 2279: the whole reply and returns it back or (in case it expects the reply will be long) 2280: it prints a partial reply and asks the CLI module (using the cont hook) 2281: to call it again when the output is transferred to the user. 2282: The this_cli variable points to a cli structure of the session being 2283: currently parsed, but it's of course available only in command handlers 2284: not entered using the cont hook. 2285: TX buffer management works as follows: At cli.tx_buf there is a 2286: list of TX buffers (struct cli_out), cli.tx_write is the buffer 2287: currently used by the producer (cli_printf(), cli_alloc_out()) and 2288: cli.tx_pos is the buffer currently used by the consumer 2289: (cli_write(), in system dependent code). The producer uses 2290: cli_out.wpos ptr as the current write position and the consumer 2291: uses cli_out.outpos ptr as the current read position. When the 2292: producer produces something, it calls cli_write_trigger(). If there 2293: is not enough space in the current buffer, the producer allocates 2294: the new one. When the consumer processes everything in the buffer 2295: queue, it calls cli_written(), tha frees all buffers (except the 2296: first one) and schedules cli.event . 2297:  2298: <HR><H3>Function</H3> 2299: void 2300: cli_printf 2301: (cli * c, int code, char * msg, ... ...) -- send reply to a CLI connection 2302:  2303: <H3>Arguments</H3> 2304:  2305: <DL> 2306: <DT>cli * c<DD>CLI connection 2307: <DT>int code<DD>numeric code of the reply, negative for continuation lines 2308: <DT>char * msg<DD>a printf()-like formatting string. 2309: <DT>... ...<DD>variable arguments 2310: </DL> 2311: <H3>Description</H3> 2312: This function send a single line of reply to a given CLI connection. 2313: In works in all aspects like bsprintf() except that it automatically 2314: prepends the reply line prefix. 2315: Please note that if the connection can be already busy sending some 2316: data in which case cli_printf() stores the output to a temporary buffer, 2317: so please avoid sending a large batch of replies without waiting 2318: for the buffers to be flushed. 2319: If you want to write to the current CLI output, you can use the cli_msg() 2320: macro instead. 2321: 2322: 2323: <HR><H3>Function</H3> 2324: void 2325: cli_init 2326: (void) -- initialize the CLI module 2327:  2328: <H3>Description</H3> 2329:  2330: This function is called during BIRD startup to initialize 2331: the internal data structures of the CLI module. 2332: 2333: <H2><A NAME="ss2.10">2.10</A> <A HREF="prog.html#toc2.10">Object locks</A> 2334: </H2> 2335: 2336:  2337: The lock module provides a simple mechanism for avoiding conflicts between 2338: various protocols which would like to use a single physical resource (for 2339: example a network port). It would be easy to say that such collisions can 2340: occur only when the user specifies an invalid configuration and therefore 2341: he deserves to get what he has asked for, but unfortunately they can also 2342: arise legitimately when the daemon is reconfigured and there exists (although 2343: for a short time period only) an old protocol instance being shut down and a new one 2344: willing to start up on the same interface. 2345: The solution is very simple: when any protocol wishes to use a network port 2346: or some other non-shareable resource, it asks the core to lock it and it doesn't 2347: use the resource until it's notified that it has acquired the lock. 2348: Object locks are represented by object_lock structures which are in turn a 2349: kind of resource. Lockable resources are uniquely determined by resource type 2350: (OBJLOCK_UDP for a UDP port etc.), IP address (usually a broadcast or 2351: multicast address the port is bound to), port number, interface and optional 2352: instance ID. 2353:  2354: <HR><H3>Function</H3> 2355: struct object_lock * 2356: olock_new 2357: (pool * p) -- create an object lock 2358:  2359: <H3>Arguments</H3> 2360:  2361: <DL> 2362: <DT>pool * p<DD>resource pool to create the lock in. 2363: </DL> 2364: <H3>Description</H3> 2365: The olock_new() function creates a new resource of type object_lock 2366: and returns a pointer to it. After filling in the structure, the caller 2367: should call olock_acquire() to do the real locking. 2368: 2369: 2370: <HR><H3>Function</H3> 2371: void 2372: olock_acquire 2373: (struct object_lock * l) -- acquire a lock 2374:  2375: <H3>Arguments</H3> 2376:  2377: <DL> 2378: <DT>struct object_lock * l<DD>the lock to acquire 2379: </DL> 2380: <H3>Description</H3> 2381: This function attempts to acquire exclusive access to the non-shareable 2382: resource described by the lock l. It returns immediately, but as soon 2383: as the resource becomes available, it calls the hook() function set up 2384: by the caller. 2385: When you want to release the resource, just rfree() the lock. 2386: 2387: 2388: <HR><H3>Function</H3> 2389: void 2390: olock_init 2391: (void) -- initialize the object lock mechanism 2392:  2393: <H3>Description</H3> 2394:  2395: This function is called during BIRD startup. It initializes 2396: all the internal data structures of the lock module. 2397: 2398: <HR> 2399: <A HREF="prog-3.html">Next</A> 2400: <A HREF="prog-1.html">Previous</A> 2401: <A HREF="prog.html#toc2">Contents</A> 2402: </BODY> 2403: </HTML>