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

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-2.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (6 years, 11 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_3p0, v1_6_3, HEAD

bird 1.6.3

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