Annotation of embedaddon/bird/doc/prog-2.html, revision 1.1
1.1 ! misho 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: <P>
! 21: <P>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: <P>Internally, each FIB is represented as a collection of nodes of type <I>fib_node</I>
! 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: <P>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: <P>Basic FIB operations are performed by functions defined by this module,
! 39: enumerating of FIB contents is accomplished by using the <B>FIB_WALK()</B> macro
! 40: or <B>FIB_ITERATE_START()</B> if you want to do it asynchronously.
! 41: <P>
! 42: <P><HR><H3>Function</H3>
! 43: <P><I>void</I>
! 44: <B>fib_init</B>
! 45: (<I>struct fib *</I> <B>f</B>, <I>pool *</I> <B>p</B>, <I>unsigned</I> <B>node_size</B>, <I>unsigned</I> <B>hash_order</B>, <I>fib_init_func</I> <B>init</B>) -- initialize a new FIB
! 46: <P>
! 47: <H3>Arguments</H3>
! 48: <P>
! 49: <DL>
! 50: <DT><I>struct fib *</I> <B>f</B><DD><P>the FIB to be initialized (the structure itself being allocated by the caller)
! 51: <DT><I>pool *</I> <B>p</B><DD><P>pool to allocate the nodes in
! 52: <DT><I>unsigned</I> <B>node_size</B><DD><P>node size to be used (each node consists of a standard header <I>fib_node</I>
! 53: followed by user data)
! 54: <DT><I>unsigned</I> <B>hash_order</B><DD><P>initial hash order (a binary logarithm of hash table size), 0 to use default order
! 55: (recommended)
! 56: <DT><I>fib_init_func</I> <B>init</B><DD><P>pointer a function to be called to initialize a newly created node
! 57: </DL>
! 58: <H3>Description</H3>
! 59: <P>This function initializes a newly allocated FIB and prepares it for use.
! 60:
! 61:
! 62: <HR><H3>Function</H3>
! 63: <P><I>void *</I>
! 64: <B>fib_find</B>
! 65: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- search for FIB node by prefix
! 66: <P>
! 67: <H3>Arguments</H3>
! 68: <P>
! 69: <DL>
! 70: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
! 71: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
! 72: <DT><I>int</I> <B>len</B><DD><P>prefix length
! 73: </DL>
! 74: <H3>Description</H3>
! 75: <P>Search for a FIB node corresponding to the given prefix, return
! 76: a pointer to it or <I>NULL</I> if no such node exists.
! 77:
! 78:
! 79: <HR><H3>Function</H3>
! 80: <P><I>void *</I>
! 81: <B>fib_get</B>
! 82: (<I>struct fib *</I> <B>f</B>, <I>ip_addr *</I> <B>a</B>, <I>int</I> <B>len</B>) -- find or create a FIB node
! 83: <P>
! 84: <H3>Arguments</H3>
! 85: <P>
! 86: <DL>
! 87: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to work with
! 88: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the prefix
! 89: <DT><I>int</I> <B>len</B><DD><P>prefix length
! 90: </DL>
! 91: <H3>Description</H3>
! 92: <P>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: <P><I>void *</I>
! 98: <B>fib_route</B>
! 99: (<I>struct fib *</I> <B>f</B>, <I>ip_addr</I> <B>a</B>, <I>int</I> <B>len</B>) -- CIDR routing lookup
! 100: <P>
! 101: <H3>Arguments</H3>
! 102: <P>
! 103: <DL>
! 104: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to search in
! 105: <DT><I>ip_addr</I> <B>a</B><DD><P>pointer to IP address of the prefix
! 106: <DT><I>int</I> <B>len</B><DD><P>prefix length
! 107: </DL>
! 108: <H3>Description</H3>
! 109: <P>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: <P><I>void</I>
! 116: <B>fib_delete</B>
! 117: (<I>struct fib *</I> <B>f</B>, <I>void *</I> <B>E</B>) -- delete a FIB node
! 118: <P>
! 119: <H3>Arguments</H3>
! 120: <P>
! 121: <DL>
! 122: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to delete from
! 123: <DT><I>void *</I> <B>E</B><DD><P>entry to delete
! 124: </DL>
! 125: <H3>Description</H3>
! 126: <P>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: <P><I>void</I>
! 133: <B>fib_free</B>
! 134: (<I>struct fib *</I> <B>f</B>) -- delete a FIB
! 135: <P>
! 136: <H3>Arguments</H3>
! 137: <P>
! 138: <DL>
! 139: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be deleted
! 140: </DL>
! 141: <H3>Description</H3>
! 142: <P>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: <P><I>void</I>
! 148: <B>fib_check</B>
! 149: (<I>struct fib *</I> <B>f</B>) -- audit a FIB
! 150: <P>
! 151: <H3>Arguments</H3>
! 152: <P>
! 153: <DL>
! 154: <DT><I>struct fib *</I> <B>f</B><DD><P>FIB to be checked
! 155: </DL>
! 156: <H3>Description</H3>
! 157: <P>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: <P>
! 164: <P>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: <P>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 <I>net</I>),
! 171: there is a one-way linked list of route entries (<I>rte</I>), 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: <P>The <I>rte</I> contains information specific to the route (preference, protocol
! 175: metrics, time of last modification etc.) and a pointer to a <I>rta</I> 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: <P>
! 180: <P><HR><H3>Function</H3>
! 181: <P><I>rte *</I>
! 182: <B>rte_find</B>
! 183: (<I>net *</I> <B>net</B>, <I>struct rte_src *</I> <B>src</B>) -- find a route
! 184: <P>
! 185: <H3>Arguments</H3>
! 186: <P>
! 187: <DL>
! 188: <DT><I>net *</I> <B>net</B><DD><P>network node
! 189: <DT><I>struct rte_src *</I> <B>src</B><DD><P>route source
! 190: </DL>
! 191: <H3>Description</H3>
! 192: <P>The <B>rte_find()</B> function returns a route for destination <B>net</B>
! 193: which is from route source <B>src</B>.
! 194:
! 195:
! 196: <HR><H3>Function</H3>
! 197: <P><I>rte *</I>
! 198: <B>rte_get_temp</B>
! 199: (<I>rta *</I> <B>a</B>) -- get a temporary <I>rte</I>
! 200: <P>
! 201: <H3>Arguments</H3>
! 202: <P>
! 203: <DL>
! 204: <DT><I>rta *</I> <B>a</B><DD><P>attributes to assign to the new route (a <I>rta</I>; in case it's
! 205: un-cached, <B>rte_update()</B> will create a cached copy automatically)
! 206: </DL>
! 207: <H3>Description</H3>
! 208: <P>Create a temporary <I>rte</I> and bind it with the attributes <B>a</B>.
! 209: Also set route preference to the default preference set for
! 210: the protocol.
! 211:
! 212:
! 213: <HR><H3>Function</H3>
! 214: <P><I>rte *</I>
! 215: <B>rte_cow_rta</B>
! 216: (<I>rte *</I> <B>r</B>, <I>linpool *</I> <B>lp</B>) -- get a private writable copy of <I>rte</I> with writable <I>rta</I>
! 217: <P>
! 218: <H3>Arguments</H3>
! 219: <P>
! 220: <DL>
! 221: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
! 222: <DT><I>linpool *</I> <B>lp</B><DD><P>a linpool from which to allocate <I>rta</I>
! 223: </DL>
! 224: <H3>Description</H3>
! 225: <P><B>rte_cow_rta()</B> takes a <I>rte</I> and prepares it and associated <I>rta</I> for
! 226: modification. There are three possibilities: First, both <I>rte</I> and <I>rta</I> are
! 227: private copies, in that case they are returned unchanged. Second, <I>rte</I> is
! 228: private copy, but <I>rta</I> is cached, in that case <I>rta</I> is duplicated using
! 229: <B>rta_do_cow()</B>. Third, both <I>rte</I> is shared and <I>rta</I> is cached, in that case
! 230: both structures are duplicated by <B>rte_do_cow()</B> and <B>rta_do_cow()</B>.
! 231: <P>Note that in the second case, cached <I>rta</I> loses one reference, while private
! 232: copy created by <B>rta_do_cow()</B> is a shallow copy sharing indirect data (eattrs,
! 233: nexthops, ...) with it. To work properly, original shared <I>rta</I> should have
! 234: another reference during the life of created private copy.
! 235: <H3>Result</H3>
! 236: <P>a pointer to the new writable <I>rte</I> with writable <I>rta</I>.
! 237:
! 238:
! 239: <HR><H3>Function</H3>
! 240: <P><I>void</I>
! 241: <B>rte_announce</B>
! 242: (<I>rtable *</I> <B>tab</B>, <I>unsigned</I> <B>type</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>rte *</I> <B>new_best</B>, <I>rte *</I> <B>old_best</B>, <I>rte *</I> <B>before_old</B>) -- announce a routing table change
! 243: <P>
! 244: <H3>Arguments</H3>
! 245: <P>
! 246: <DL>
! 247: <DT><I>rtable *</I> <B>tab</B><DD><P>table the route has been added to
! 248: <DT><I>unsigned</I> <B>type</B><DD><P>type of route announcement (RA_OPTIMAL or RA_ANY)
! 249: <DT><I>net *</I> <B>net</B><DD><P>network in question
! 250: <DT><I>rte *</I> <B>new</B><DD><P>the new route to be announced
! 251: <DT><I>rte *</I> <B>old</B><DD><P>the previous route for the same network
! 252: <DT><I>rte *</I> <B>new_best</B><DD><P>the new best route for the same network
! 253: <DT><I>rte *</I> <B>old_best</B><DD><P>the previous best route for the same network
! 254: <DT><I>rte *</I> <B>before_old</B><DD><P>The previous route before <B>old</B> for the same network.
! 255: If <B>before_old</B> is NULL <B>old</B> was the first.
! 256: </DL>
! 257: <H3>Description</H3>
! 258: <P>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: <P>Route announcement of type <I>RA_OPTIMAL</I> si generated when optimal
! 262: route (in routing table <B>tab</B>) changes. In that case <B>old</B> stores the
! 263: old optimal route.
! 264: <P>Route announcement of type <I>RA_ANY</I> si generated when any route (in
! 265: routing table <B>tab</B>) changes In that case <B>old</B> stores the old route
! 266: from the same protocol.
! 267: <P>For each appropriate protocol, we first call its <B>import_control()</B>
! 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 <B>rt_notify()</B> hook of
! 273: the protocol gets called.
! 274:
! 275:
! 276: <HR><H3>Function</H3>
! 277: <P><I>void</I>
! 278: <B>rte_free</B>
! 279: (<I>rte *</I> <B>e</B>) -- delete a <I>rte</I>
! 280: <P>
! 281: <H3>Arguments</H3>
! 282: <P>
! 283: <DL>
! 284: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be deleted
! 285: </DL>
! 286: <H3>Description</H3>
! 287: <P><B>rte_free()</B> deletes the given <I>rte</I> from the routing table it's linked to.
! 288:
! 289:
! 290: <HR><H3>Function</H3>
! 291: <P><I>void</I>
! 292: <B>rte_update2</B>
! 293: (<I>struct announce_hook *</I> <B>ah</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>struct rte_src *</I> <B>src</B>) -- enter a new update to a routing table
! 294: <P>
! 295: <H3>Arguments</H3>
! 296: <P>
! 297: <DL>
! 298: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>pointer to table announce hook
! 299: <DT><I>net *</I> <B>net</B><DD><P>network node
! 300: <DT><I>rte *</I> <B>new</B><DD><P>a <I>rte</I> representing the new route or <I>NULL</I> for route removal.
! 301: <DT><I>struct rte_src *</I> <B>src</B><DD><P>protocol originating the update
! 302: </DL>
! 303: <H3>Description</H3>
! 304: <P>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 <B>aflags</B> set
! 307: to zero or a cached one using <B>rta_lookup()</B>; in this case please note that
! 308: you need to increase the use count of the attributes yourself by calling
! 309: <B>rta_clone()</B>), call <B>rte_get_temp()</B> to obtain a temporary <I>rte</I>, fill in all
! 310: the appropriate data and finally submit the new <I>rte</I> by calling <B>rte_update()</B>.
! 311: <P><B>src</B> specifies the protocol that originally created the route and the meaning
! 312: of protocol-dependent data of <B>new</B>. If <B>new</B> is not <I>NULL</I>, <B>src</B> have to be the
! 313: same value as <B>new</B>->attrs->proto. <B>p</B> specifies the protocol that called
! 314: <B>rte_update()</B>. In most cases it is the same protocol as <B>src</B>. <B>rte_update()</B>
! 315: stores <B>p</B> in <B>new</B>->sender;
! 316: <P>When <B>rte_update()</B> 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 <I>rte</I> 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 <I>rte</I>.
! 323: <P>Now, having a "public" version of the route, we
! 324: automatically find any old route defined by the protocol <B>src</B>
! 325: for network <B>n</B>, replace it by the new one (or removing it if <B>new</B> is <I>NULL</I>),
! 326: recalculate the optimal route for this destination and finally broadcast
! 327: the change (if any) to all routing protocols by calling <B>rte_announce()</B>.
! 328: <P>All memory used for attribute lists and other temporary allocations is taken
! 329: from a special linear pool <B>rte_update_pool</B> and freed when <B>rte_update()</B>
! 330: finishes.
! 331:
! 332:
! 333: <HR><H3>Function</H3>
! 334: <P><I>void</I>
! 335: <B>rt_refresh_begin</B>
! 336: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) -- start a refresh cycle
! 337: <P>
! 338: <H3>Arguments</H3>
! 339: <P>
! 340: <DL>
! 341: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
! 342: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook
! 343: </DL>
! 344: <H3>Description</H3>
! 345: <P>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 <B>rte_update()</B>). After that, all protocol
! 348: routes (more precisely routes with <B>ah</B> as <B>sender</B>) 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: <B>rt_refresh_begin()</B>, then marking all related stale routes with REF_DISCARD
! 352: flag in <B>rt_refresh_end()</B> and then removing such routes in the prune loop.
! 353:
! 354:
! 355: <HR><H3>Function</H3>
! 356: <P><I>void</I>
! 357: <B>rt_refresh_end</B>
! 358: (<I>rtable *</I> <B>t</B>, <I>struct announce_hook *</I> <B>ah</B>) -- end a refresh cycle
! 359: <P>
! 360: <H3>Arguments</H3>
! 361: <P>
! 362: <DL>
! 363: <DT><I>rtable *</I> <B>t</B><DD><P>related routing table
! 364: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>related announce hook
! 365: </DL>
! 366: <H3>Description</H3>
! 367: <P>This function starts a refresh cycle for given routing table and announce
! 368: hook. See <B>rt_refresh_begin()</B> for description of refresh cycles.
! 369:
! 370:
! 371: <HR><H3>Function</H3>
! 372: <P><I>void</I>
! 373: <B>rte_dump</B>
! 374: (<I>rte *</I> <B>e</B>) -- dump a route
! 375: <P>
! 376: <H3>Arguments</H3>
! 377: <P>
! 378: <DL>
! 379: <DT><I>rte *</I> <B>e</B><DD><P><I>rte</I> to be dumped
! 380: </DL>
! 381: <H3>Description</H3>
! 382: <P>This functions dumps contents of a <I>rte</I> to debug output.
! 383:
! 384:
! 385: <HR><H3>Function</H3>
! 386: <P><I>void</I>
! 387: <B>rt_dump</B>
! 388: (<I>rtable *</I> <B>t</B>) -- dump a routing table
! 389: <P>
! 390: <H3>Arguments</H3>
! 391: <P>
! 392: <DL>
! 393: <DT><I>rtable *</I> <B>t</B><DD><P>routing table to be dumped
! 394: </DL>
! 395: <H3>Description</H3>
! 396: <P>This function dumps contents of a given routing table to debug output.
! 397:
! 398:
! 399: <HR><H3>Function</H3>
! 400: <P><I>void</I>
! 401: <B>rt_dump_all</B>
! 402: (<B>void</B>) -- dump all routing tables
! 403: <P>
! 404: <H3>Description</H3>
! 405: <P>
! 406: <P>This function dumps contents of all routing tables to debug output.
! 407:
! 408:
! 409: <HR><H3>Function</H3>
! 410: <P><I>void</I>
! 411: <B>rt_init</B>
! 412: (<B>void</B>) -- initialize routing tables
! 413: <P>
! 414: <H3>Description</H3>
! 415: <P>
! 416: <P>This function is called during BIRD startup. It initializes the
! 417: routing table module.
! 418:
! 419:
! 420: <HR><H3>Function</H3>
! 421: <P><I>int</I>
! 422: <B>rt_prune_table</B>
! 423: (<I>rtable *</I> <B>tab</B>) -- prune a routing table
! 424: <P>
! 425: <H3>Arguments</H3>
! 426: <P>
! 427: <DL>
! 428: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table for pruning
! 429: </DL>
! 430: <H3>Description</H3>
! 431: <P>This function scans the routing table <B>tab</B> and removes routes belonging to
! 432: flushing protocols, discarded routes and also stale network entries, in a
! 433: similar fashion like <B>rt_prune_loop()</B>. Returns 1 when all such routes are
! 434: pruned. Contrary to <B>rt_prune_loop()</B>, this function is not a part of the
! 435: protocol flushing loop, but it is called from <B>rt_event()</B> for just one routing
! 436: table.
! 437: <P>Note that <B>rt_prune_table()</B> and <B>rt_prune_loop()</B> share (for each table) the
! 438: prune state (<B>prune_state</B>) and also the pruning iterator (<B>prune_fit</B>).
! 439:
! 440:
! 441: <HR><H3>Function</H3>
! 442: <P><I>int</I>
! 443: <B>rt_prune_loop</B>
! 444: (<B>void</B>) -- prune routing tables
! 445: <P>
! 446: <H3>Description</H3>
! 447: <P>
! 448: <P>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: <P><I>void</I>
! 455: <B>rt_lock_table</B>
! 456: (<I>rtable *</I> <B>r</B>) -- lock a routing table
! 457: <P>
! 458: <H3>Arguments</H3>
! 459: <P>
! 460: <DL>
! 461: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be locked
! 462: </DL>
! 463: <H3>Description</H3>
! 464: <P>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: <P><I>void</I>
! 471: <B>rt_unlock_table</B>
! 472: (<I>rtable *</I> <B>r</B>) -- unlock a routing table
! 473: <P>
! 474: <H3>Arguments</H3>
! 475: <P>
! 476: <DL>
! 477: <DT><I>rtable *</I> <B>r</B><DD><P>routing table to be unlocked
! 478: </DL>
! 479: <H3>Description</H3>
! 480: <P>Unlock a routing table formerly locked by <B>rt_lock_table()</B>,
! 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: <P><I>void</I>
! 487: <B>rt_commit</B>
! 488: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>) -- commit new routing table configuration
! 489: <P>
! 490: <H3>Arguments</H3>
! 491: <P>
! 492: <DL>
! 493: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
! 494: <DT><I>struct config *</I> <B>old</B><DD><P>original configuration or <I>NULL</I> if it's boot time config
! 495: </DL>
! 496: <H3>Description</H3>
! 497: <P>Scan differences between <B>old</B> and <B>new</B> configuration and modify
! 498: the routing tables according to these changes. If <B>new</B> defines a
! 499: previously unknown table, create it, if it omits a table existing
! 500: in <B>old</B>, schedule it for deletion (it gets deleted when all protocols
! 501: disconnect from it by calling <B>rt_unlock_table()</B>), if it exists
! 502: in both configurations, leave it unchanged.
! 503:
! 504:
! 505: <HR><H3>Function</H3>
! 506: <P><I>int</I>
! 507: <B>rt_feed_baby</B>
! 508: (<I>struct proto *</I> <B>p</B>) -- advertise routes to a new protocol
! 509: <P>
! 510: <H3>Arguments</H3>
! 511: <P>
! 512: <DL>
! 513: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to be fed
! 514: </DL>
! 515: <H3>Description</H3>
! 516: <P>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: <P><I>void</I>
! 524: <B>rt_feed_baby_abort</B>
! 525: (<I>struct proto *</I> <B>p</B>) -- abort protocol feeding
! 526: <P>
! 527: <H3>Arguments</H3>
! 528: <P>
! 529: <DL>
! 530: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol
! 531: </DL>
! 532: <H3>Description</H3>
! 533: <P>This function is called by the protocol code when the protocol
! 534: stops or ceases to exist before the last iteration of <B>rt_feed_baby()</B>
! 535: has finished.
! 536:
! 537:
! 538: <HR><H3>Function</H3>
! 539: <P><I>net *</I>
! 540: <B>net_find</B>
! 541: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- find a network entry
! 542: <P>
! 543: <H3>Arguments</H3>
! 544: <P>
! 545: <DL>
! 546: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
! 547: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
! 548: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
! 549: </DL>
! 550: <H3>Description</H3>
! 551: <P><B>net_find()</B> looks up the given network in routing table <B>tab</B> and
! 552: returns a pointer to its <I>net</I> entry or <I>NULL</I> if no such network
! 553: exists.
! 554:
! 555:
! 556: <HR><H3>Function</H3>
! 557: <P><I>net *</I>
! 558: <B>net_get</B>
! 559: (<I>rtable *</I> <B>tab</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>len</B>) -- obtain a network entry
! 560: <P>
! 561: <H3>Arguments</H3>
! 562: <P>
! 563: <DL>
! 564: <DT><I>rtable *</I> <B>tab</B><DD><P>a routing table
! 565: <DT><I>ip_addr</I> <B>addr</B><DD><P>address of the network
! 566: <DT><I>unsigned</I> <B>len</B><DD><P>length of the network prefix
! 567: </DL>
! 568: <H3>Description</H3>
! 569: <P><B>net_get()</B> looks up the given network in routing table <B>tab</B> and
! 570: returns a pointer to its <I>net</I> entry. If no such entry exists, it's
! 571: created.
! 572:
! 573:
! 574: <HR><H3>Function</H3>
! 575: <P><I>rte *</I>
! 576: <B>rte_cow</B>
! 577: (<I>rte *</I> <B>r</B>) -- copy a route for writing
! 578: <P>
! 579: <H3>Arguments</H3>
! 580: <P>
! 581: <DL>
! 582: <DT><I>rte *</I> <B>r</B><DD><P>a route entry to be copied
! 583: </DL>
! 584: <H3>Description</H3>
! 585: <P><B>rte_cow()</B> takes a <I>rte</I> and prepares it for modification. The exact action
! 586: taken depends on the flags of the <I>rte</I> -- 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: <P>The primary use of this function is inside the filter machinery -- when
! 590: a filter wants to modify <I>rte</I> contents (to change the preference or to
! 591: attach another set of attributes), it must ensure that the <I>rte</I> is not
! 592: shared with anyone else (and especially that it isn't stored in any routing
! 593: table).
! 594: <H3>Result</H3>
! 595: <P>a pointer to the new writable <I>rte</I>.
! 596:
! 597: <H2><A NAME="ss2.3">2.3</A> <A HREF="prog.html#toc2.3">Route attribute cache</A>
! 598: </H2>
! 599:
! 600: <P>
! 601: <P>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 <I>rte</I> and hold the rest
! 605: in a special structure called <I>rta</I> which is shared among all the
! 606: <I>rte</I>'s with these attributes.
! 607: <P>Each <I>rta</I> 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 <I>ea_list</I>
! 610: structures, each of them consisting of an array of <I>eattr</I>'s containing
! 611: the individual attributes. An attribute can be specified more than once
! 612: in the <I>ea_list</I> 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: <P>Each <I>eattr</I> 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 <I>adata</I> structure holding attribute
! 621: contents.
! 622: <P>There exist two variants of <I>rta</I>'s -- cached and un-cached ones. Un-cached
! 623: <I>rta</I>'s can have arbitrarily complex structure of <I>ea_list</I>'s and they
! 624: can be modified by any module in the route processing chain. Cached
! 625: <I>rta</I>'s have their attribute lists normalized (that means at most one
! 626: <I>ea_list</I> 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: <P>Routing tables always contain only cached <I>rta</I>'s.
! 630: <P>
! 631: <P><HR><H3>Function</H3>
! 632: <P><I>struct mpnh *</I>
! 633: <B>mpnh_merge</B>
! 634: (<I>struct mpnh *</I> <B>x</B>, <I>struct mpnh *</I> <B>y</B>, <I>int</I> <B>rx</B>, <I>int</I> <B>ry</B>, <I>int</I> <B>max</B>, <I>linpool *</I> <B>lp</B>) -- merge nexthop lists
! 635: <P>
! 636: <H3>Arguments</H3>
! 637: <P>
! 638: <DL>
! 639: <DT><I>struct mpnh *</I> <B>x</B><DD><P>list 1
! 640: <DT><I>struct mpnh *</I> <B>y</B><DD><P>list 2
! 641: <DT><I>int</I> <B>rx</B><DD><P>reusability of list <B>x</B>
! 642: <DT><I>int</I> <B>ry</B><DD><P>reusability of list <B>y</B>
! 643: <DT><I>int</I> <B>max</B><DD><P>max number of nexthops
! 644: <DT><I>linpool *</I> <B>lp</B><DD><P>linpool for allocating nexthops
! 645: </DL>
! 646: <H3>Description</H3>
! 647: <P>The <B>mpnh_merge()</B> function takes two nexthop lists <B>x</B> and <B>y</B> 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 <B>max</B>.
! 650: New nodes are allocated from linpool <B>lp</B>.
! 651: <P>The arguments <B>rx</B> and <B>ry</B> 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: <P><I>eattr *</I>
! 662: <B>ea_find</B>
! 663: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>) -- find an extended attribute
! 664: <P>
! 665: <H3>Arguments</H3>
! 666: <P>
! 667: <DL>
! 668: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list to search in
! 669: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID to search for
! 670: </DL>
! 671: <H3>Description</H3>
! 672: <P>Given an extended attribute list, <B>ea_find()</B> searches for a first
! 673: occurrence of an attribute with specified ID, returning either a pointer
! 674: to its <I>eattr</I> structure or <I>NULL</I> if no such attribute exists.
! 675:
! 676:
! 677: <HR><H3>Function</H3>
! 678: <P><I>eattr *</I>
! 679: <B>ea_walk</B>
! 680: (<I>struct ea_walk_state *</I> <B>s</B>, <I>uint</I> <B>id</B>, <I>uint</I> <B>max</B>) -- walk through extended attributes
! 681: <P>
! 682: <H3>Arguments</H3>
! 683: <P>
! 684: <DL>
! 685: <DT><I>struct ea_walk_state *</I> <B>s</B><DD><P>walk state structure
! 686: <DT><I>uint</I> <B>id</B><DD><P>start of attribute ID interval
! 687: <DT><I>uint</I> <B>max</B><DD><P>length of attribute ID interval
! 688: </DL>
! 689: <H3>Description</H3>
! 690: <P>Given an extended attribute list, <B>ea_walk()</B> walks through the list looking
! 691: for first occurrences of attributes with ID in specified interval from <B>id</B> to
! 692: (<B>id</B> + <B>max</B> - 1), returning pointers to found <I>eattr</I> structures, storing its
! 693: walk state in <B>s</B> for subsequent calls.
! 694: <P>The function <B>ea_walk()</B> is supposed to be called in a loop, with initially
! 695: zeroed walk state structure <B>s</B> with filled the initial extended attribute
! 696: list, returning one found attribute in each call or <I>NULL</I> when no other
! 697: attribute exists. The extended attribute list or the arguments should not be
! 698: modified between calls. The maximum value of <B>max</B> is 128.
! 699:
! 700:
! 701: <HR><H3>Function</H3>
! 702: <P><I>int</I>
! 703: <B>ea_get_int</B>
! 704: (<I>ea_list *</I> <B>e</B>, <I>unsigned</I> <B>id</B>, <I>int</I> <B>def</B>) -- fetch an integer attribute
! 705: <P>
! 706: <H3>Arguments</H3>
! 707: <P>
! 708: <DL>
! 709: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
! 710: <DT><I>unsigned</I> <B>id</B><DD><P>attribute ID
! 711: <DT><I>int</I> <B>def</B><DD><P>default value
! 712: </DL>
! 713: <H3>Description</H3>
! 714: <P>This function is a shortcut for retrieving a value of an integer attribute
! 715: by calling <B>ea_find()</B> 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: <P><I>void</I>
! 721: <B>ea_sort</B>
! 722: (<I>ea_list *</I> <B>e</B>) -- sort an attribute list
! 723: <P>
! 724: <H3>Arguments</H3>
! 725: <P>
! 726: <DL>
! 727: <DT><I>ea_list *</I> <B>e</B><DD><P>list to be sorted
! 728: </DL>
! 729: <H3>Description</H3>
! 730: <P>This function takes a <I>ea_list</I> chain and sorts the attributes
! 731: within each of its entries.
! 732: <P>If an attribute occurs multiple times in a single <I>ea_list</I>,
! 733: <B>ea_sort()</B> leaves only the first (the only significant) occurrence.
! 734:
! 735:
! 736: <HR><H3>Function</H3>
! 737: <P><I>unsigned</I>
! 738: <B>ea_scan</B>
! 739: (<I>ea_list *</I> <B>e</B>) -- estimate attribute list size
! 740: <P>
! 741: <H3>Arguments</H3>
! 742: <P>
! 743: <DL>
! 744: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
! 745: </DL>
! 746: <H3>Description</H3>
! 747: <P>This function calculates an upper bound of the size of
! 748: a given <I>ea_list</I> after merging with <B>ea_merge()</B>.
! 749:
! 750:
! 751: <HR><H3>Function</H3>
! 752: <P><I>void</I>
! 753: <B>ea_merge</B>
! 754: (<I>ea_list *</I> <B>e</B>, <I>ea_list *</I> <B>t</B>) -- merge segments of an attribute list
! 755: <P>
! 756: <H3>Arguments</H3>
! 757: <P>
! 758: <DL>
! 759: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
! 760: <DT><I>ea_list *</I> <B>t</B><DD><P>buffer to store the result to
! 761: </DL>
! 762: <H3>Description</H3>
! 763: <P>This function takes a possibly multi-segment attribute list
! 764: and merges all of its segments to one.
! 765: <P>The primary use of this function is for <I>ea_list</I> normalization:
! 766: first call <B>ea_scan()</B> to determine how much memory will the result
! 767: take, then allocate a buffer (usually using <B>alloca()</B>), merge the
! 768: segments with <B>ea_merge()</B> and finally sort and prune the result
! 769: by calling <B>ea_sort()</B>.
! 770:
! 771:
! 772: <HR><H3>Function</H3>
! 773: <P><I>int</I>
! 774: <B>ea_same</B>
! 775: (<I>ea_list *</I> <B>x</B>, <I>ea_list *</I> <B>y</B>) -- compare two <I>ea_list</I>'s
! 776: <P>
! 777: <H3>Arguments</H3>
! 778: <P>
! 779: <DL>
! 780: <DT><I>ea_list *</I> <B>x</B><DD><P>attribute list
! 781: <DT><I>ea_list *</I> <B>y</B><DD><P>attribute list
! 782: </DL>
! 783: <H3>Description</H3>
! 784: <P><B>ea_same()</B> compares two normalized attribute lists <B>x</B> and <B>y</B> and returns
! 785: 1 if they contain the same attributes, 0 otherwise.
! 786:
! 787:
! 788: <HR><H3>Function</H3>
! 789: <P><I>void</I>
! 790: <B>ea_show</B>
! 791: (<I>struct cli *</I> <B>c</B>, <I>eattr *</I> <B>e</B>) -- print an <I>eattr</I> to CLI
! 792: <P>
! 793: <H3>Arguments</H3>
! 794: <P>
! 795: <DL>
! 796: <DT><I>struct cli *</I> <B>c</B><DD><P>destination CLI
! 797: <DT><I>eattr *</I> <B>e</B><DD><P>attribute to be printed
! 798: </DL>
! 799: <H3>Description</H3>
! 800: <P>This function takes an extended attribute represented by its <I>eattr</I>
! 801: structure and prints it to the CLI according to the type information.
! 802: <P>If the protocol defining the attribute provides its own
! 803: <B>get_attr()</B> hook, it's consulted first.
! 804:
! 805:
! 806: <HR><H3>Function</H3>
! 807: <P><I>void</I>
! 808: <B>ea_dump</B>
! 809: (<I>ea_list *</I> <B>e</B>) -- dump an extended attribute
! 810: <P>
! 811: <H3>Arguments</H3>
! 812: <P>
! 813: <DL>
! 814: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute to be dumped
! 815: </DL>
! 816: <H3>Description</H3>
! 817: <P><B>ea_dump()</B> dumps contents of the extended attribute given to
! 818: the debug output.
! 819:
! 820:
! 821: <HR><H3>Function</H3>
! 822: <P><I>uint</I>
! 823: <B>ea_hash</B>
! 824: (<I>ea_list *</I> <B>e</B>) -- calculate an <I>ea_list</I> hash key
! 825: <P>
! 826: <H3>Arguments</H3>
! 827: <P>
! 828: <DL>
! 829: <DT><I>ea_list *</I> <B>e</B><DD><P>attribute list
! 830: </DL>
! 831: <H3>Description</H3>
! 832: <P><B>ea_hash()</B> 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: <P><I>ea_list *</I>
! 838: <B>ea_append</B>
! 839: (<I>ea_list *</I> <B>to</B>, <I>ea_list *</I> <B>what</B>) -- concatenate <I>ea_list</I>'s
! 840: <P>
! 841: <H3>Arguments</H3>
! 842: <P>
! 843: <DL>
! 844: <DT><I>ea_list *</I> <B>to</B><DD><P>destination list (can be <I>NULL</I>)
! 845: <DT><I>ea_list *</I> <B>what</B><DD><P>list to be appended (can be <I>NULL</I>)
! 846: </DL>
! 847: <H3>Description</H3>
! 848: <P>This function appends the <I>ea_list</I> <B>what</B> at the end of
! 849: <I>ea_list</I> <B>to</B> and returns a pointer to the resulting list.
! 850:
! 851:
! 852: <HR><H3>Function</H3>
! 853: <P><I>rta *</I>
! 854: <B>rta_lookup</B>
! 855: (<I>rta *</I> <B>o</B>) -- look up a <I>rta</I> in attribute cache
! 856: <P>
! 857: <H3>Arguments</H3>
! 858: <P>
! 859: <DL>
! 860: <DT><I>rta *</I> <B>o</B><DD><P>a un-cached <I>rta</I>
! 861: </DL>
! 862: <H3>Description</H3>
! 863: <P><B>rta_lookup()</B> gets an un-cached <I>rta</I> 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: <P>The extended attribute lists attached to the <I>rta</I> are automatically
! 869: converted to the normalized form.
! 870:
! 871:
! 872: <HR><H3>Function</H3>
! 873: <P><I>void</I>
! 874: <B>rta_dump</B>
! 875: (<I>rta *</I> <B>a</B>) -- dump route attributes
! 876: <P>
! 877: <H3>Arguments</H3>
! 878: <P>
! 879: <DL>
! 880: <DT><I>rta *</I> <B>a</B><DD><P>attribute structure to dump
! 881: </DL>
! 882: <H3>Description</H3>
! 883: <P>This function takes a <I>rta</I> and dumps its contents to the debug output.
! 884:
! 885:
! 886: <HR><H3>Function</H3>
! 887: <P><I>void</I>
! 888: <B>rta_dump_all</B>
! 889: (<B>void</B>) -- dump attribute cache
! 890: <P>
! 891: <H3>Description</H3>
! 892: <P>
! 893: <P>This function dumps the whole contents of route attribute cache
! 894: to the debug output.
! 895:
! 896:
! 897: <HR><H3>Function</H3>
! 898: <P><I>void</I>
! 899: <B>rta_init</B>
! 900: (<B>void</B>) -- initialize route attribute cache
! 901: <P>
! 902: <H3>Description</H3>
! 903: <P>
! 904: <P>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: <P><I>rta *</I>
! 910: <B>rta_clone</B>
! 911: (<I>rta *</I> <B>r</B>) -- clone route attributes
! 912: <P>
! 913: <H3>Arguments</H3>
! 914: <P>
! 915: <DL>
! 916: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be cloned
! 917: </DL>
! 918: <H3>Description</H3>
! 919: <P><B>rta_clone()</B> takes a cached <I>rta</I> and returns its identical cached
! 920: copy. Currently it works by just returning the original <I>rta</I> with
! 921: its use count incremented.
! 922:
! 923:
! 924: <HR><H3>Function</H3>
! 925: <P><I>void</I>
! 926: <B>rta_free</B>
! 927: (<I>rta *</I> <B>r</B>) -- free route attributes
! 928: <P>
! 929: <H3>Arguments</H3>
! 930: <P>
! 931: <DL>
! 932: <DT><I>rta *</I> <B>r</B><DD><P>a <I>rta</I> to be freed
! 933: </DL>
! 934: <H3>Description</H3>
! 935: <P>If you stop using a <I>rta</I> (for example when deleting a route which uses
! 936: it), you need to call <B>rta_free()</B> 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 <B>rta_free()</B> tests by inspecting the use count).
! 939:
! 940: <P>
! 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: <P>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: <P>
! 951: <P>When talking about protocols, one need to distinguish between <EM>protocols</EM>
! 952: and protocol <EM>instances</EM>. 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: <P>
! 958: <P>A protocol is represented by a <I>protocol</I> 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 <B>protocol_list</B> list.
! 961: <P>
! 962: <P>Each instance has its own <I>proto</I> 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 <I>proto</I> 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 <I>proto</I>). The instance is always linked in both the global instance list
! 971: (<B>proto_list</B>) and a per-status list (either <B>active_proto_list</B> for
! 972: running protocols, <B>initial_proto_list</B> for protocols being initialized or
! 973: <B>flush_proto_list</B> when the protocol is being shut down).
! 974: <P>
! 975: <P>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 <B>proto_commit</B> function.
! 978: <P>
! 979: <H3>Protocol states</H3>
! 980:
! 981: <P>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: <P>
! 986: <P>The <EM>protocol state machine</EM> 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: <P>
! 990: <DL>
! 991: <DT><CODE>PS_DOWN</CODE><DD><P>The protocol is down and waits for being woken up by calling its
! 992: start() hook.
! 993: <DT><CODE>PS_START</CODE><DD><P>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><P>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><P>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: <P>
! 1002: <P>Unless the protocol is in the <CODE>PS_DOWN</CODE> state, it can decide to change
! 1003: its state by calling the <B>proto_notify_state</B> function.
! 1004: <P>
! 1005: <P>At any time, the core code can ask the protocol to shut itself down by calling its stop() hook.
! 1006: <P>
! 1007: <P>The <EM>core state machine</EM> 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: <P>
! 1013: <DL>
! 1014: <DT><CODE>FS_HUNGRY</CODE><DD><P>The protocol is down, it doesn't have any routes and
! 1015: doesn't want them.
! 1016: <DT><CODE>FS_FEEDING</CODE><DD><P>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><P>The protocol is up and has complete routing information.
! 1019: <DT><CODE>FS_FLUSHING</CODE><DD><P>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: <P>
! 1024: <H3>Functions of the protocol module</H3>
! 1025:
! 1026: <P>The protocol module provides the following functions:
! 1027: <HR><H3>Function</H3>
! 1028: <P><I>void *</I>
! 1029: <B>proto_new</B>
! 1030: (<I>struct proto_config *</I> <B>c</B>, <I>unsigned</I> <B>size</B>) -- create a new protocol instance
! 1031: <P>
! 1032: <H3>Arguments</H3>
! 1033: <P>
! 1034: <DL>
! 1035: <DT><I>struct proto_config *</I> <B>c</B><DD><P>protocol configuration
! 1036: <DT><I>unsigned</I> <B>size</B><DD><P>size of protocol data structure (each protocol instance is represented by
! 1037: a structure starting with generic part [struct <I>proto</I>] and continued
! 1038: with data specific to the protocol)
! 1039: </DL>
! 1040: <H3>Description</H3>
! 1041: <P>When a new configuration has been read in, the core code starts
! 1042: initializing all the protocol instances configured by calling their
! 1043: <B>init()</B> 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: <P><I>struct announce_hook *</I>
! 1051: <B>proto_add_announce_hook</B>
! 1052: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>, <I>struct proto_stats *</I> <B>stats</B>) -- connect protocol to a routing table
! 1053: <P>
! 1054: <H3>Arguments</H3>
! 1055: <P>
! 1056: <DL>
! 1057: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1058: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table to connect to
! 1059: <DT><I>struct proto_stats *</I> <B>stats</B><DD><P>per-table protocol statistics
! 1060: </DL>
! 1061: <H3>Description</H3>
! 1062: <P>This function creates a connection between the protocol instance <B>p</B> and the
! 1063: routing table <B>t</B>, making the protocol hear all changes in the table.
! 1064: <P>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 <B>proto_want_export_up()</B> and
! 1068: <B>proto_want_export_down()</B>) and they are automatically freed after the protocol
! 1069: is flushed (in <B>proto_fell_down()</B>).
! 1070: <P>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: <P><I>struct announce_hook *</I>
! 1078: <B>proto_find_announce_hook</B>
! 1079: (<I>struct proto *</I> <B>p</B>, <I>struct rtable *</I> <B>t</B>) -- find announce hooks
! 1080: <P>
! 1081: <H3>Arguments</H3>
! 1082: <P>
! 1083: <DL>
! 1084: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1085: <DT><I>struct rtable *</I> <B>t</B><DD><P>routing table
! 1086: </DL>
! 1087: <H3>Description</H3>
! 1088: <P>Returns pointer to announce hook or NULL
! 1089:
! 1090:
! 1091: <HR><H3>Function</H3>
! 1092: <P><I>void *</I>
! 1093: <B>proto_config_new</B>
! 1094: (<I>struct protocol *</I> <B>pr</B>, <I>int</I> <B>class</B>) -- create a new protocol configuration
! 1095: <P>
! 1096: <H3>Arguments</H3>
! 1097: <P>
! 1098: <DL>
! 1099: <DT><I>struct protocol *</I> <B>pr</B><DD><P>protocol the configuration will belong to
! 1100: <DT><I>int</I> <B>class</B><DD><P>SYM_PROTO or SYM_TEMPLATE
! 1101: </DL>
! 1102: <H3>Description</H3>
! 1103: <P>Whenever the configuration file says that a new instance
! 1104: of a routing protocol should be created, the parser calls
! 1105: <B>proto_config_new()</B> to create a configuration entry for this
! 1106: instance (a structure staring with the <I>proto_config</I> 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: <P>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 <B>protos_commit()</B>).
! 1114:
! 1115:
! 1116: <HR><H3>Function</H3>
! 1117: <P><I>void</I>
! 1118: <B>proto_copy_config</B>
! 1119: (<I>struct proto_config *</I> <B>dest</B>, <I>struct proto_config *</I> <B>src</B>) -- copy a protocol configuration
! 1120: <P>
! 1121: <H3>Arguments</H3>
! 1122: <P>
! 1123: <DL>
! 1124: <DT><I>struct proto_config *</I> <B>dest</B><DD><P>destination protocol configuration
! 1125: <DT><I>struct proto_config *</I> <B>src</B><DD><P>source protocol configuration
! 1126: </DL>
! 1127: <H3>Description</H3>
! 1128: <P>Whenever a new instance of a routing protocol is created from the
! 1129: template, <B>proto_copy_config()</B> 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 <B>dest</B> are kept intact.
! 1132: <B>copy_config()</B> protocol hook is used to copy protocol-specific data.
! 1133:
! 1134:
! 1135: <HR><H3>Function</H3>
! 1136: <P><I>void</I>
! 1137: <B>protos_preconfig</B>
! 1138: (<I>struct config *</I> <B>c</B>) -- pre-configuration processing
! 1139: <P>
! 1140: <H3>Arguments</H3>
! 1141: <P>
! 1142: <DL>
! 1143: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
! 1144: </DL>
! 1145: <H3>Description</H3>
! 1146: <P>This function calls the <B>preconfig()</B> 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: <P><I>void</I>
! 1153: <B>protos_postconfig</B>
! 1154: (<I>struct config *</I> <B>c</B>) -- post-configuration processing
! 1155: <P>
! 1156: <H3>Arguments</H3>
! 1157: <P>
! 1158: <DL>
! 1159: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
! 1160: </DL>
! 1161: <H3>Description</H3>
! 1162: <P>This function calls the <B>postconfig()</B> hooks of all protocol
! 1163: instances specified in configuration <B>c</B>. The hooks are not
! 1164: called for protocol templates.
! 1165:
! 1166:
! 1167: <HR><H3>Function</H3>
! 1168: <P><I>void</I>
! 1169: <B>protos_commit</B>
! 1170: (<I>struct config *</I> <B>new</B>, <I>struct config *</I> <B>old</B>, <I>int</I> <B>force_reconfig</B>, <I>int</I> <B>type</B>) -- commit new protocol configuration
! 1171: <P>
! 1172: <H3>Arguments</H3>
! 1173: <P>
! 1174: <DL>
! 1175: <DT><I>struct config *</I> <B>new</B><DD><P>new configuration
! 1176: <DT><I>struct config *</I> <B>old</B><DD><P>old configuration or <I>NULL</I> if it's boot time config
! 1177: <DT><I>int</I> <B>force_reconfig</B><DD><P>force restart of all protocols (used for example
! 1178: when the router ID changes)
! 1179: <DT><I>int</I> <B>type</B><DD><P>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
! 1180: </DL>
! 1181: <H3>Description</H3>
! 1182: <P>Scan differences between <B>old</B> and <B>new</B> configuration and adjust all
! 1183: protocol instances to conform to the new configuration.
! 1184: <P>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: <P>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: <P>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: <B>reconfigure()</B> 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: <P>
! 1203: <P>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: <P>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: <P>When graceful restart recovery need is detected during initialization, then
! 1214: enabled protocols are marked with <B>gr_recovery</B> flag before start. Such
! 1215: protocols then decide how to proceed with graceful restart, participation is
! 1216: voluntary. Protocols could lock the recovery by <B>proto_graceful_restart_lock()</B>
! 1217: (stored in <B>gr_lock</B> 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: <B>gr_wait</B> before advancing to <I>PS_UP</I>, 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: <P>The graceful restart recovery is finished when either all graceful restart
! 1224: locks are unlocked or when graceful restart wait timer fires.
! 1225: <P>
! 1226: <P><HR><H3>Function</H3>
! 1227: <P><I>void</I>
! 1228: <B>graceful_restart_recovery</B>
! 1229: (<B>void</B>) -- request initial graceful restart recovery
! 1230: <P>
! 1231: <H3>Graceful restart recovery</H3>
! 1232: <P>
! 1233: <P>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 <B>protos_commit()</B>.
! 1236:
! 1237:
! 1238: <HR><H3>Function</H3>
! 1239: <P><I>void</I>
! 1240: <B>graceful_restart_init</B>
! 1241: (<B>void</B>) -- initialize graceful restart
! 1242: <P>
! 1243: <H3>Description</H3>
! 1244: <P>
! 1245: <P>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 <B>protos_commit()</B>.
! 1248:
! 1249:
! 1250: <HR><H3>Function</H3>
! 1251: <P><I>void</I>
! 1252: <B>graceful_restart_done</B>
! 1253: (<I>struct timer *t</I> <B>UNUSED</B>) -- finalize graceful restart
! 1254: <P>
! 1255: <H3>Arguments</H3>
! 1256: <P>
! 1257: <DL>
! 1258: <DT><I>struct timer *t</I> <B>UNUSED</B><DD><P>-- undescribed --
! 1259: </DL>
! 1260: <H3>Description</H3>
! 1261: <P>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: <P><I>void</I>
! 1270: <B>proto_graceful_restart_lock</B>
! 1271: (<I>struct proto *</I> <B>p</B>) -- lock graceful restart by protocol
! 1272: <P>
! 1273: <H3>Arguments</H3>
! 1274: <P>
! 1275: <DL>
! 1276: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1277: </DL>
! 1278: <H3>Description</H3>
! 1279: <P>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: <B>proto_graceful_restart_unlock()</B> or when the protocol is stopped.
! 1282: <P>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: <B>gr_recovery</B> is set), which means it should be called from protocol start
! 1285: hooks.
! 1286:
! 1287:
! 1288: <HR><H3>Function</H3>
! 1289: <P><I>void</I>
! 1290: <B>proto_graceful_restart_unlock</B>
! 1291: (<I>struct proto *</I> <B>p</B>) -- unlock graceful restart by protocol
! 1292: <P>
! 1293: <H3>Arguments</H3>
! 1294: <P>
! 1295: <DL>
! 1296: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1297: </DL>
! 1298: <H3>Description</H3>
! 1299: <P>This function unlocks a lock from <B>proto_graceful_restart_lock()</B>. It is also
! 1300: automatically called when the lock holding protocol went down.
! 1301:
! 1302:
! 1303: <HR><H3>Function</H3>
! 1304: <P><I>void</I>
! 1305: <B>protos_dump_all</B>
! 1306: (<B>void</B>) -- dump status of all protocols
! 1307: <P>
! 1308: <H3>Description</H3>
! 1309: <P>
! 1310: <P>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 <B>dump()</B> hook of the protocol to print
! 1314: the internals.
! 1315:
! 1316:
! 1317: <HR><H3>Function</H3>
! 1318: <P><I>void</I>
! 1319: <B>proto_build</B>
! 1320: (<I>struct protocol *</I> <B>p</B>) -- make a single protocol available
! 1321: <P>
! 1322: <H3>Arguments</H3>
! 1323: <P>
! 1324: <DL>
! 1325: <DT><I>struct protocol *</I> <B>p</B><DD><P>the protocol
! 1326: </DL>
! 1327: <H3>Description</H3>
! 1328: <P>After the platform specific initialization code uses <B>protos_build()</B>
! 1329: to add all the standard protocols, it should call <B>proto_build()</B> for
! 1330: all platform specific protocols to inform the core that they exist.
! 1331:
! 1332:
! 1333: <HR><H3>Function</H3>
! 1334: <P><I>void</I>
! 1335: <B>protos_build</B>
! 1336: (<B>void</B>) -- build a protocol list
! 1337: <P>
! 1338: <H3>Description</H3>
! 1339: <P>
! 1340: <P>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: <P><I>void</I>
! 1349: <B>proto_request_feeding</B>
! 1350: (<I>struct proto *</I> <B>p</B>) -- request feeding routes to the protocol
! 1351: <P>
! 1352: <H3>Arguments</H3>
! 1353: <P>
! 1354: <DL>
! 1355: <DT><I>struct proto *</I> <B>p</B><DD><P>given protocol
! 1356: </DL>
! 1357: <H3>Description</H3>
! 1358: <P>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: <P><I>void</I>
! 1368: <B>proto_notify_limit</B>
! 1369: (<I>struct announce_hook *</I> <B>ah</B>, <I>struct proto_limit *</I> <B>l</B>, <I>int</I> <B>dir</B>, <I>u32</I> <B>rt_count</B>)
! 1370: <H3>Arguments</H3>
! 1371: <P>
! 1372: <DL>
! 1373: <DT><I>struct announce_hook *</I> <B>ah</B><DD><P>announce hook
! 1374: <DT><I>struct proto_limit *</I> <B>l</B><DD><P>limit being hit
! 1375: <DT><I>int</I> <B>dir</B><DD><P>limit direction (PLD_*)
! 1376: <DT><I>u32</I> <B>rt_count</B><DD><P>the number of routes
! 1377: </DL>
! 1378: <H3>Description</H3>
! 1379: <P>The function is called by the route processing core when limit <B>l</B>
! 1380: is breached. It activates the limit and tooks appropriate action
! 1381: according to <B>l</B>->action.
! 1382:
! 1383:
! 1384: <HR><H3>Function</H3>
! 1385: <P><I>void</I>
! 1386: <B>proto_notify_state</B>
! 1387: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>ps</B>) -- notify core about protocol state change
! 1388: <P>
! 1389: <H3>Arguments</H3>
! 1390: <P>
! 1391: <DL>
! 1392: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol the state of which has changed
! 1393: <DT><I>unsigned</I> <B>ps</B><DD><P>the new status
! 1394: </DL>
! 1395: <H3>Description</H3>
! 1396: <P>Whenever a state of a protocol changes due to some event internal
! 1397: to the protocol (i.e., not inside a <B>start()</B> or <B>shutdown()</B> hook),
! 1398: it should immediately notify the core about the change by calling
! 1399: <B>proto_notify_state()</B> which will write the new state to the <I>proto</I>
! 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: <P>
! 1409: <P>Each protocol can provide a rich set of hook functions referred to by pointers
! 1410: in either the <I>proto</I> or <I>protocol</I> 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 <I>NULL</I> which means
! 1413: to ignore the change or to take a default action.
! 1414: <P>
! 1415: <P><HR><H3>Function</H3>
! 1416: <P><I>void</I>
! 1417: <B>preconfig</B>
! 1418: (<I>struct protocol *</I> <B>p</B>, <I>struct config *</I> <B>c</B>) -- protocol preconfiguration
! 1419: <P>
! 1420: <H3>Arguments</H3>
! 1421: <P>
! 1422: <DL>
! 1423: <DT><I>struct protocol *</I> <B>p</B><DD><P>a routing protocol
! 1424: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
! 1425: </DL>
! 1426: <H3>Description</H3>
! 1427: <P>The <B>preconfig()</B> hook is called before parsing of a new configuration.
! 1428:
! 1429:
! 1430: <HR><H3>Function</H3>
! 1431: <P><I>void</I>
! 1432: <B>postconfig</B>
! 1433: (<I>struct proto_config *</I> <B>c</B>) -- instance post-configuration
! 1434: <P>
! 1435: <H3>Arguments</H3>
! 1436: <P>
! 1437: <DL>
! 1438: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
! 1439: </DL>
! 1440: <H3>Description</H3>
! 1441: <P>The <B>postconfig()</B> hook is called for each configured instance after
! 1442: parsing of the new configuration is finished.
! 1443:
! 1444:
! 1445: <HR><H3>Function</H3>
! 1446: <P><I>struct proto *</I>
! 1447: <B>init</B>
! 1448: (<I>struct proto_config *</I> <B>c</B>) -- initialize an instance
! 1449: <P>
! 1450: <H3>Arguments</H3>
! 1451: <P>
! 1452: <DL>
! 1453: <DT><I>struct proto_config *</I> <B>c</B><DD><P>instance configuration
! 1454: </DL>
! 1455: <H3>Description</H3>
! 1456: <P>The <B>init()</B> hook is called by the core to create a protocol instance
! 1457: according to supplied protocol configuration.
! 1458: <H3>Result</H3>
! 1459: <P>a pointer to the instance created
! 1460:
! 1461:
! 1462: <HR><H3>Function</H3>
! 1463: <P><I>int</I>
! 1464: <B>reconfigure</B>
! 1465: (<I>struct proto *</I> <B>p</B>, <I>struct proto_config *</I> <B>c</B>) -- request instance reconfiguration
! 1466: <P>
! 1467: <H3>Arguments</H3>
! 1468: <P>
! 1469: <DL>
! 1470: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
! 1471: <DT><I>struct proto_config *</I> <B>c</B><DD><P>new configuration
! 1472: </DL>
! 1473: <H3>Description</H3>
! 1474: <P>The core calls the <B>reconfigure()</B> 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: <P>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: <P><I>void</I>
! 1485: <B>dump</B>
! 1486: (<I>struct proto *</I> <B>p</B>) -- dump protocol state
! 1487: <P>
! 1488: <H3>Arguments</H3>
! 1489: <P>
! 1490: <DL>
! 1491: <DT><I>struct proto *</I> <B>p</B><DD><P>an instance
! 1492: </DL>
! 1493: <H3>Description</H3>
! 1494: <P>This hook dumps the complete state of the instance to the
! 1495: debug output.
! 1496:
! 1497:
! 1498: <HR><H3>Function</H3>
! 1499: <P><I>void</I>
! 1500: <B>dump_attrs</B>
! 1501: (<I>rte *</I> <B>e</B>) -- dump protocol-dependent attributes
! 1502: <P>
! 1503: <H3>Arguments</H3>
! 1504: <P>
! 1505: <DL>
! 1506: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
! 1507: </DL>
! 1508: <H3>Description</H3>
! 1509: <P>This hook dumps all attributes in the <I>rte</I> which belong to this
! 1510: protocol to the debug output.
! 1511:
! 1512:
! 1513: <HR><H3>Function</H3>
! 1514: <P><I>int</I>
! 1515: <B>start</B>
! 1516: (<I>struct proto *</I> <B>p</B>) -- request instance startup
! 1517: <P>
! 1518: <H3>Arguments</H3>
! 1519: <P>
! 1520: <DL>
! 1521: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1522: </DL>
! 1523: <H3>Description</H3>
! 1524: <P>The <B>start()</B> 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: <P>new protocol state
! 1528:
! 1529:
! 1530: <HR><H3>Function</H3>
! 1531: <P><I>int</I>
! 1532: <B>shutdown</B>
! 1533: (<I>struct proto *</I> <B>p</B>) -- request instance shutdown
! 1534: <P>
! 1535: <H3>Arguments</H3>
! 1536: <P>
! 1537: <DL>
! 1538: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1539: </DL>
! 1540: <H3>Description</H3>
! 1541: <P>The <B>stop()</B> hook is called by the core when it wishes to shut
! 1542: the instance down for some reason.
! 1543: <H3>Returns</H3>
! 1544: <P>new protocol state
! 1545:
! 1546:
! 1547: <HR><H3>Function</H3>
! 1548: <P><I>void</I>
! 1549: <B>cleanup</B>
! 1550: (<I>struct proto *</I> <B>p</B>) -- request instance cleanup
! 1551: <P>
! 1552: <H3>Arguments</H3>
! 1553: <P>
! 1554: <DL>
! 1555: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1556: </DL>
! 1557: <H3>Description</H3>
! 1558: <P>The <B>cleanup()</B> 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: <P><I>void</I>
! 1565: <B>get_status</B>
! 1566: (<I>struct proto *</I> <B>p</B>, <I>byte *</I> <B>buf</B>) -- get instance status
! 1567: <P>
! 1568: <H3>Arguments</H3>
! 1569: <P>
! 1570: <DL>
! 1571: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1572: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the status string
! 1573: </DL>
! 1574: <H3>Description</H3>
! 1575: <P>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: <P><I>void</I>
! 1582: <B>get_route_info</B>
! 1583: (<I>rte *</I> <B>e</B>, <I>byte *</I> <B>buf</B>, <I>ea_list *</I> <B>attrs</B>) -- get route information
! 1584: <P>
! 1585: <H3>Arguments</H3>
! 1586: <P>
! 1587: <DL>
! 1588: <DT><I>rte *</I> <B>e</B><DD><P>a route entry
! 1589: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with the resulting string
! 1590: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes of the route
! 1591: </DL>
! 1592: <H3>Description</H3>
! 1593: <P>This hook is called to fill the buffer <B>buf</B> with a brief user friendly
! 1594: representation of metrics of a route belonging to this protocol.
! 1595:
! 1596:
! 1597: <HR><H3>Function</H3>
! 1598: <P><I>int</I>
! 1599: <B>get_attr</B>
! 1600: (<I>eattr *</I> <B>a</B>, <I>byte *</I> <B>buf</B>, <I>int</I> <B>buflen</B>) -- get attribute information
! 1601: <P>
! 1602: <H3>Arguments</H3>
! 1603: <P>
! 1604: <DL>
! 1605: <DT><I>eattr *</I> <B>a</B><DD><P>an extended attribute
! 1606: <DT><I>byte *</I> <B>buf</B><DD><P>buffer to be filled with attribute information
! 1607: <DT><I>int</I> <B>buflen</B><DD><P>a length of the <B>buf</B> parameter
! 1608: </DL>
! 1609: <H3>Description</H3>
! 1610: <P>The <B>get_attr()</B> 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 <I>GA_UNKNOWN</I>), fill
! 1613: in only attribute name (and let the core format the attribute value
! 1614: automatically according to the type field; by returning <I>GA_NAME</I>)
! 1615: or doing the whole conversion (used in case the value requires extra
! 1616: care; return <I>GA_FULL</I>).
! 1617:
! 1618:
! 1619: <HR><H3>Function</H3>
! 1620: <P><I>void</I>
! 1621: <B>if_notify</B>
! 1622: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct iface *</I> <B>i</B>) -- notify instance about interface changes
! 1623: <P>
! 1624: <H3>Arguments</H3>
! 1625: <P>
! 1626: <DL>
! 1627: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1628: <DT><I>unsigned</I> <B>flags</B><DD><P>interface change flags
! 1629: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
! 1630: </DL>
! 1631: <H3>Description</H3>
! 1632: <P>This hook is called whenever any network interface changes its status.
! 1633: The change is described by a combination of status bits (<I>IF_CHANGE_xxx</I>)
! 1634: in the <B>flags</B> parameter.
! 1635:
! 1636:
! 1637: <HR><H3>Function</H3>
! 1638: <P><I>void</I>
! 1639: <B>ifa_notify</B>
! 1640: (<I>struct proto *</I> <B>p</B>, <I>unsigned</I> <B>flags</B>, <I>struct ifa *</I> <B>a</B>) -- notify instance about interface address changes
! 1641: <P>
! 1642: <H3>Arguments</H3>
! 1643: <P>
! 1644: <DL>
! 1645: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1646: <DT><I>unsigned</I> <B>flags</B><DD><P>address change flags
! 1647: <DT><I>struct ifa *</I> <B>a</B><DD><P>the interface address
! 1648: </DL>
! 1649: <H3>Description</H3>
! 1650: <P>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 (<I>IF_CHANGE_xxx</I>) in the <B>flags</B> parameter.
! 1653:
! 1654:
! 1655: <HR><H3>Function</H3>
! 1656: <P><I>void</I>
! 1657: <B>rt_notify</B>
! 1658: (<I>struct proto *</I> <B>p</B>, <I>net *</I> <B>net</B>, <I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>, <I>ea_list *</I> <B>attrs</B>) -- notify instance about routing table change
! 1659: <P>
! 1660: <H3>Arguments</H3>
! 1661: <P>
! 1662: <DL>
! 1663: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance
! 1664: <DT><I>net *</I> <B>net</B><DD><P>a network entry
! 1665: <DT><I>rte *</I> <B>new</B><DD><P>new route for the network
! 1666: <DT><I>rte *</I> <B>old</B><DD><P>old route for the network
! 1667: <DT><I>ea_list *</I> <B>attrs</B><DD><P>extended attributes associated with the <B>new</B> entry
! 1668: </DL>
! 1669: <H3>Description</H3>
! 1670: <P>The <B>rt_notify()</B> hook is called to inform the protocol instance about
! 1671: changes in the connected routing table <B>table</B>, that is a route <B>old</B>
! 1672: belonging to network <B>net</B> being replaced by a new route <B>new</B> with
! 1673: extended attributes <B>attrs</B>. Either <B>new</B> or <B>old</B> or both can be <I>NULL</I>
! 1674: if the corresponding route doesn't exist.
! 1675: <P>If the type of route announcement is RA_OPTIMAL, it is an
! 1676: announcement of optimal route change, <B>new</B> stores the new optimal
! 1677: route and <B>old</B> stores the old optimal route.
! 1678: <P>If the type of route announcement is RA_ANY, it is an announcement
! 1679: of any route change, <B>new</B> stores the new route and <B>old</B> stores the
! 1680: old route from the same protocol.
! 1681: <P><B>p</B>->accept_ra_types specifies which kind of route announcements
! 1682: protocol wants to receive.
! 1683:
! 1684:
! 1685: <HR><H3>Function</H3>
! 1686: <P><I>void</I>
! 1687: <B>neigh_notify</B>
! 1688: (<I>neighbor *</I> <B>neigh</B>) -- notify instance about neighbor status change
! 1689: <P>
! 1690: <H3>Arguments</H3>
! 1691: <P>
! 1692: <DL>
! 1693: <DT><I>neighbor *</I> <B>neigh</B><DD><P>a neighbor cache entry
! 1694: </DL>
! 1695: <H3>Description</H3>
! 1696: <P>The <B>neigh_notify()</B> 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: <P><I>ea_list *</I>
! 1703: <B>make_tmp_attrs</B>
! 1704: (<I>rte *</I> <B>e</B>, <I>struct linpool *</I> <B>pool</B>) -- convert embedded attributes to temporary ones
! 1705: <P>
! 1706: <H3>Arguments</H3>
! 1707: <P>
! 1708: <DL>
! 1709: <DT><I>rte *</I> <B>e</B><DD><P>route entry
! 1710: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool to allocate attribute memory in
! 1711: </DL>
! 1712: <H3>Description</H3>
! 1713: <P>This hook is called by the routing table functions if they need
! 1714: to convert the protocol attributes embedded directly in the <I>rte</I>
! 1715: to temporary extended attributes in order to distribute them
! 1716: to other protocols or to filters. <B>make_tmp_attrs()</B> creates
! 1717: an <I>ea_list</I> in the linear pool <B>pool</B>, fills it with values of the
! 1718: temporary attributes and returns a pointer to it.
! 1719:
! 1720:
! 1721: <HR><H3>Function</H3>
! 1722: <P><I>void</I>
! 1723: <B>store_tmp_attrs</B>
! 1724: (<I>rte *</I> <B>e</B>, <I>ea_list *</I> <B>attrs</B>) -- convert temporary attributes to embedded ones
! 1725: <P>
! 1726: <H3>Arguments</H3>
! 1727: <P>
! 1728: <DL>
! 1729: <DT><I>rte *</I> <B>e</B><DD><P>route entry
! 1730: <DT><I>ea_list *</I> <B>attrs</B><DD><P>temporary attributes to be converted
! 1731: </DL>
! 1732: <H3>Description</H3>
! 1733: <P>This hook is an exact opposite of <B>make_tmp_attrs()</B> -- it takes
! 1734: a list of extended attributes and converts them to attributes
! 1735: embedded in the <I>rte</I> corresponding to this protocol.
! 1736: <P>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: <P><I>int</I>
! 1742: <B>import_control</B>
! 1743: (<I>struct proto *</I> <B>p</B>, <I>rte **</I> <B>e</B>, <I>ea_list **</I> <B>attrs</B>, <I>struct linpool *</I> <B>pool</B>) -- pre-filtering decisions on route import
! 1744: <P>
! 1745: <H3>Arguments</H3>
! 1746: <P>
! 1747: <DL>
! 1748: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol instance the route is going to be imported to
! 1749: <DT><I>rte **</I> <B>e</B><DD><P>the route in question
! 1750: <DT><I>ea_list **</I> <B>attrs</B><DD><P>extended attributes of the route
! 1751: <DT><I>struct linpool *</I> <B>pool</B><DD><P>linear pool for allocation of all temporary data
! 1752: </DL>
! 1753: <H3>Description</H3>
! 1754: <P>The <B>import_control()</B> 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 <B>rte_announce()</B> for a complete description
! 1758: of the route distribution process.
! 1759: <P>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: <P>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: <P><I>int</I>
! 1768: <B>rte_recalculate</B>
! 1769: (<I>struct rtable *</I> <B>table</B>, <I>struct network *</I> <B>net</B>, <I>struct rte *</I> <B>new</B>, <I>struct rte *</I> <B>old</B>, <I>struct rte *</I> <B>old_best</B>) -- prepare routes for comparison
! 1770: <P>
! 1771: <H3>Arguments</H3>
! 1772: <P>
! 1773: <DL>
! 1774: <DT><I>struct rtable *</I> <B>table</B><DD><P>a routing table
! 1775: <DT><I>struct network *</I> <B>net</B><DD><P>a network entry
! 1776: <DT><I>struct rte *</I> <B>new</B><DD><P>new route for the network
! 1777: <DT><I>struct rte *</I> <B>old</B><DD><P>old route for the network
! 1778: <DT><I>struct rte *</I> <B>old_best</B><DD><P>old best route for the network (may be NULL)
! 1779: </DL>
! 1780: <H3>Description</H3>
! 1781: <P>This hook is called when a route change (from <B>old</B> to <B>new</B> for a
! 1782: <B>net</B> entry) is propagated to a <B>table</B>. It may be used to prepare
! 1783: routes for comparison by <B>rte_better()</B> in the best route
! 1784: selection. <B>new</B> may or may not be in <B>net</B>->routes list,
! 1785: <B>old</B> is not there.
! 1786: <H3>Result</H3>
! 1787: <P>1 if the ordering implied by <B>rte_better()</B> changes enough
! 1788: that full best route calculation have to be done, 0 otherwise.
! 1789:
! 1790:
! 1791: <HR><H3>Function</H3>
! 1792: <P><I>int</I>
! 1793: <B>rte_better</B>
! 1794: (<I>rte *</I> <B>new</B>, <I>rte *</I> <B>old</B>) -- compare metrics of two routes
! 1795: <P>
! 1796: <H3>Arguments</H3>
! 1797: <P>
! 1798: <DL>
! 1799: <DT><I>rte *</I> <B>new</B><DD><P>the new route
! 1800: <DT><I>rte *</I> <B>old</B><DD><P>the original route
! 1801: </DL>
! 1802: <H3>Description</H3>
! 1803: <P>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: <P>1 if <B>new</B> is better (more preferred) than <B>old</B>, 0 otherwise.
! 1809:
! 1810:
! 1811: <HR><H3>Function</H3>
! 1812: <P><I>int</I>
! 1813: <B>rte_same</B>
! 1814: (<I>rte *</I> <B>e1</B>, <I>rte *</I> <B>e2</B>) -- compare two routes
! 1815: <P>
! 1816: <H3>Arguments</H3>
! 1817: <P>
! 1818: <DL>
! 1819: <DT><I>rte *</I> <B>e1</B><DD><P>route
! 1820: <DT><I>rte *</I> <B>e2</B><DD><P>route
! 1821: </DL>
! 1822: <H3>Description</H3>
! 1823: <P>The <B>rte_same()</B> hook tests whether the routes <B>e1</B> and <B>e2</B> belonging
! 1824: to the same protocol instance have identical contents. Contents of
! 1825: <I>rta</I>, all the extended attributes and <I>rte</I> preference are checked
! 1826: by the core code, no need to take care of them here.
! 1827: <H3>Result</H3>
! 1828: <P>1 if <B>e1</B> is identical to <B>e2</B>, 0 otherwise.
! 1829:
! 1830:
! 1831: <HR><H3>Function</H3>
! 1832: <P><I>void</I>
! 1833: <B>rte_insert</B>
! 1834: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route insertion
! 1835: <P>
! 1836: <H3>Arguments</H3>
! 1837: <P>
! 1838: <DL>
! 1839: <DT><I>net *</I> <B>n</B><DD><P>network
! 1840: <DT><I>rte *</I> <B>e</B><DD><P>route
! 1841: </DL>
! 1842: <H3>Description</H3>
! 1843: <P>This hook is called whenever a <I>rte</I> belonging to the instance
! 1844: is accepted for insertion to a routing table.
! 1845: <P>Please avoid using this function in new protocols.
! 1846:
! 1847:
! 1848: <HR><H3>Function</H3>
! 1849: <P><I>void</I>
! 1850: <B>rte_remove</B>
! 1851: (<I>net *</I> <B>n</B>, <I>rte *</I> <B>e</B>) -- notify instance about route removal
! 1852: <P>
! 1853: <H3>Arguments</H3>
! 1854: <P>
! 1855: <DL>
! 1856: <DT><I>net *</I> <B>n</B><DD><P>network
! 1857: <DT><I>rte *</I> <B>e</B><DD><P>route
! 1858: </DL>
! 1859: <H3>Description</H3>
! 1860: <P>This hook is called whenever a <I>rte</I> belonging to the instance
! 1861: is removed from a routing table.
! 1862: <P>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: <P>
! 1868: <P>The interface module keeps track of all network interfaces in the
! 1869: system and their addresses.
! 1870: <P>Each interface is represented by an <I>iface</I> structure which carries
! 1871: interface capability flags (<I>IF_MULTIACCESS</I>, <I>IF_BROADCAST</I> 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 <I>ifa</I>.
! 1875: <P>The interface module keeps a `soft-up' state for each <I>iface</I> 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: <P>
! 1879: <P><HR><H3>Function</H3>
! 1880: <P><I>void</I>
! 1881: <B>ifa_dump</B>
! 1882: (<I>struct ifa *</I> <B>a</B>) -- dump interface address
! 1883: <P>
! 1884: <H3>Arguments</H3>
! 1885: <P>
! 1886: <DL>
! 1887: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address descriptor
! 1888: </DL>
! 1889: <H3>Description</H3>
! 1890: <P>This function dumps contents of an <I>ifa</I> to the debug output.
! 1891:
! 1892:
! 1893: <HR><H3>Function</H3>
! 1894: <P><I>void</I>
! 1895: <B>if_dump</B>
! 1896: (<I>struct iface *</I> <B>i</B>) -- dump interface
! 1897: <P>
! 1898: <H3>Arguments</H3>
! 1899: <P>
! 1900: <DL>
! 1901: <DT><I>struct iface *</I> <B>i</B><DD><P>interface to dump
! 1902: </DL>
! 1903: <H3>Description</H3>
! 1904: <P>This function dumps all information associated with a given
! 1905: network interface to the debug output.
! 1906:
! 1907:
! 1908: <HR><H3>Function</H3>
! 1909: <P><I>void</I>
! 1910: <B>if_dump_all</B>
! 1911: (<B>void</B>) -- dump all interfaces
! 1912: <P>
! 1913: <H3>Description</H3>
! 1914: <P>
! 1915: <P>This function dumps information about all known network
! 1916: interfaces to the debug output.
! 1917:
! 1918:
! 1919: <HR><H3>Function</H3>
! 1920: <P><I>void</I>
! 1921: <B>if_delete</B>
! 1922: (<I>struct iface *</I> <B>old</B>) -- remove interface
! 1923: <P>
! 1924: <H3>Arguments</H3>
! 1925: <P>
! 1926: <DL>
! 1927: <DT><I>struct iface *</I> <B>old</B><DD><P>interface
! 1928: </DL>
! 1929: <H3>Description</H3>
! 1930: <P>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 <B>if_update()</B>.
! 1933:
! 1934:
! 1935: <HR><H3>Function</H3>
! 1936: <P><I>struct iface *</I>
! 1937: <B>if_update</B>
! 1938: (<I>struct iface *</I> <B>new</B>) -- update interface status
! 1939: <P>
! 1940: <H3>Arguments</H3>
! 1941: <P>
! 1942: <DL>
! 1943: <DT><I>struct iface *</I> <B>new</B><DD><P>new interface status
! 1944: </DL>
! 1945: <H3>Description</H3>
! 1946: <P><B>if_update()</B> is called by the low-level platform dependent code
! 1947: whenever it notices an interface change.
! 1948: <P>There exist two types of interface updates -- synchronous and asynchronous
! 1949: ones. In the synchronous case, the low-level code calls <B>if_start_update()</B>,
! 1950: scans all interfaces reported by the OS, uses <B>if_update()</B> and <B>ifa_update()</B>
! 1951: to pass them to the core and then it finishes the update sequence by
! 1952: calling <B>if_end_update()</B>. When working asynchronously, the sysdep code
! 1953: calls <B>if_update()</B> and <B>ifa_update()</B> whenever it notices a change.
! 1954: <P><B>if_update()</B> will automatically notify all other modules about the change.
! 1955:
! 1956:
! 1957: <HR><H3>Function</H3>
! 1958: <P><I>void</I>
! 1959: <B>if_feed_baby</B>
! 1960: (<I>struct proto *</I> <B>p</B>) -- advertise interfaces to a new protocol
! 1961: <P>
! 1962: <H3>Arguments</H3>
! 1963: <P>
! 1964: <DL>
! 1965: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol to feed
! 1966: </DL>
! 1967: <H3>Description</H3>
! 1968: <P>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: <P><I>struct iface *</I>
! 1974: <B>if_find_by_index</B>
! 1975: (<I>unsigned</I> <B>idx</B>) -- find interface by ifindex
! 1976: <P>
! 1977: <H3>Arguments</H3>
! 1978: <P>
! 1979: <DL>
! 1980: <DT><I>unsigned</I> <B>idx</B><DD><P>ifindex
! 1981: </DL>
! 1982: <H3>Description</H3>
! 1983: <P>This function finds an <I>iface</I> structure corresponding to an interface
! 1984: of the given index <B>idx</B>. Returns a pointer to the structure or <I>NULL</I>
! 1985: if no such structure exists.
! 1986:
! 1987:
! 1988: <HR><H3>Function</H3>
! 1989: <P><I>struct iface *</I>
! 1990: <B>if_find_by_name</B>
! 1991: (<I>char *</I> <B>name</B>) -- find interface by name
! 1992: <P>
! 1993: <H3>Arguments</H3>
! 1994: <P>
! 1995: <DL>
! 1996: <DT><I>char *</I> <B>name</B><DD><P>interface name
! 1997: </DL>
! 1998: <H3>Description</H3>
! 1999: <P>This function finds an <I>iface</I> structure corresponding to an interface
! 2000: of the given name <B>name</B>. Returns a pointer to the structure or <I>NULL</I>
! 2001: if no such structure exists.
! 2002:
! 2003:
! 2004: <HR><H3>Function</H3>
! 2005: <P><I>struct ifa *</I>
! 2006: <B>ifa_update</B>
! 2007: (<I>struct ifa *</I> <B>a</B>) -- update interface address
! 2008: <P>
! 2009: <H3>Arguments</H3>
! 2010: <P>
! 2011: <DL>
! 2012: <DT><I>struct ifa *</I> <B>a</B><DD><P>new interface address
! 2013: </DL>
! 2014: <H3>Description</H3>
! 2015: <P>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 <B>if_update()</B>.
! 2018:
! 2019:
! 2020: <HR><H3>Function</H3>
! 2021: <P><I>void</I>
! 2022: <B>ifa_delete</B>
! 2023: (<I>struct ifa *</I> <B>a</B>) -- remove interface address
! 2024: <P>
! 2025: <H3>Arguments</H3>
! 2026: <P>
! 2027: <DL>
! 2028: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address
! 2029: </DL>
! 2030: <H3>Description</H3>
! 2031: <P>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 <B>if_update()</B>.
! 2034:
! 2035:
! 2036: <HR><H3>Function</H3>
! 2037: <P><I>void</I>
! 2038: <B>if_init</B>
! 2039: (<B>void</B>) -- initialize interface module
! 2040: <P>
! 2041: <H3>Description</H3>
! 2042: <P>
! 2043: <P>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: <P>
! 2050: <P>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: <P>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 <I>SCOPE_HOST</I>) together with per-neighbor data belonging to a
! 2061: single protocol.
! 2062: <P>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 <I>NEF_STICKY</I>
! 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: <P>When a neighbor event occurs (a neighbor gets disconnected or a sticky
! 2071: inactive neighbor becomes connected), the protocol hook <B>neigh_notify()</B>
! 2072: is called to advertise the change.
! 2073: <P>
! 2074: <P><HR><H3>Function</H3>
! 2075: <P><I>neighbor *</I>
! 2076: <B>neigh_find</B>
! 2077: (<I>struct proto *</I> <B>p</B>, <I>ip_addr *</I> <B>a</B>, <I>unsigned</I> <B>flags</B>) -- find or create a neighbor entry.
! 2078: <P>
! 2079: <H3>Arguments</H3>
! 2080: <P>
! 2081: <DL>
! 2082: <DT><I>struct proto *</I> <B>p</B><DD><P>protocol which asks for the entry.
! 2083: <DT><I>ip_addr *</I> <B>a</B><DD><P>pointer to IP address of the node to be searched for.
! 2084: <DT><I>unsigned</I> <B>flags</B><DD><P>0 or <I>NEF_STICKY</I> if you want to create a sticky entry.
! 2085: </DL>
! 2086: <H3>Description</H3>
! 2087: <P>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 *<B>a</B> is not a valid unicast
! 2093: IP address, <B>neigh_find()</B> returns <I>NULL</I>.
! 2094:
! 2095:
! 2096: <HR><H3>Function</H3>
! 2097: <P><I>void</I>
! 2098: <B>neigh_dump</B>
! 2099: (<I>neighbor *</I> <B>n</B>) -- dump specified neighbor entry.
! 2100: <P>
! 2101: <H3>Arguments</H3>
! 2102: <P>
! 2103: <DL>
! 2104: <DT><I>neighbor *</I> <B>n</B><DD><P>the entry to dump
! 2105: </DL>
! 2106: <H3>Description</H3>
! 2107: <P>This functions dumps the contents of a given neighbor entry
! 2108: to debug output.
! 2109:
! 2110:
! 2111: <HR><H3>Function</H3>
! 2112: <P><I>void</I>
! 2113: <B>neigh_dump_all</B>
! 2114: (<B>void</B>) -- dump all neighbor entries.
! 2115: <P>
! 2116: <H3>Description</H3>
! 2117: <P>
! 2118: <P>This function dumps the contents of the neighbor cache to
! 2119: debug output.
! 2120:
! 2121:
! 2122: <HR><H3>Function</H3>
! 2123: <P><I>void</I>
! 2124: <B>neigh_if_up</B>
! 2125: (<I>struct iface *</I> <B>i</B>)
! 2126: <H3>Arguments</H3>
! 2127: <P>
! 2128: <DL>
! 2129: <DT><I>struct iface *</I> <B>i</B><DD><P>interface in question
! 2130: </DL>
! 2131: <H3>Description</H3>
! 2132: <P>Tell the neighbor cache that a new interface became up.
! 2133: <P>The neighbor cache wakes up all inactive sticky neighbors with
! 2134: addresses belonging to prefixes of the interface <B>i</B>.
! 2135:
! 2136:
! 2137: <HR><H3>Function</H3>
! 2138: <P><I>void</I>
! 2139: <B>neigh_if_down</B>
! 2140: (<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface down event
! 2141: <P>
! 2142: <H3>Arguments</H3>
! 2143: <P>
! 2144: <DL>
! 2145: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
! 2146: </DL>
! 2147: <H3>Description</H3>
! 2148: <P>Notify the neighbor cache that an interface has ceased to exist.
! 2149: <P>It causes all entries belonging to neighbors connected to this interface
! 2150: to be flushed.
! 2151:
! 2152:
! 2153: <HR><H3>Function</H3>
! 2154: <P><I>void</I>
! 2155: <B>neigh_if_link</B>
! 2156: (<I>struct iface *</I> <B>i</B>) -- notify neighbor cache about interface link change
! 2157: <P>
! 2158: <H3>Arguments</H3>
! 2159: <P>
! 2160: <DL>
! 2161: <DT><I>struct iface *</I> <B>i</B><DD><P>the interface in question
! 2162: </DL>
! 2163: <H3>Description</H3>
! 2164: <P>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: <P><I>void</I>
! 2171: <B>neigh_ifa_update</B>
! 2172: (<I>struct ifa *</I> <B>a</B>)
! 2173: <H3>Arguments</H3>
! 2174: <P>
! 2175: <DL>
! 2176: <DT><I>struct ifa *</I> <B>a</B><DD><P>interface address in question
! 2177: </DL>
! 2178: <H3>Description</H3>
! 2179: <P>Tell the neighbor cache that an address was added or removed.
! 2180: <P>The neighbor cache wakes up all inactive sticky neighbors with
! 2181: addresses belonging to prefixes of the interface belonging to <B>ifa</B>
! 2182: and causes all unreachable neighbors to be flushed.
! 2183:
! 2184:
! 2185: <HR><H3>Function</H3>
! 2186: <P><I>void</I>
! 2187: <B>neigh_prune</B>
! 2188: (<B>void</B>) -- prune neighbor cache
! 2189: <P>
! 2190: <H3>Description</H3>
! 2191: <P>
! 2192: <P><B>neigh_prune()</B> 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: <P><I>void</I>
! 2199: <B>neigh_init</B>
! 2200: (<I>pool *</I> <B>if_pool</B>) -- initialize the neighbor cache.
! 2201: <P>
! 2202: <H3>Arguments</H3>
! 2203: <P>
! 2204: <DL>
! 2205: <DT><I>pool *</I> <B>if_pool</B><DD><P>resource pool to be used for neighbor entries.
! 2206: </DL>
! 2207: <H3>Description</H3>
! 2208: <P>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: <P>
! 2215: <P>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: <P>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: <P>Reply codes starting with 0 stand for `action successfully completed' messages,
! 2231: 1 means `table entry', 8 `runtime error' and 9 `syntax error'.
! 2232: <P>Each CLI session is internally represented by a <I>cli</I> 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: <P>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 <B>cont</B> hook)
! 2244: to call it again when the output is transferred to the user.
! 2245: <P>The <B>this_cli</B> variable points to a <I>cli</I> structure of the session being
! 2246: currently parsed, but it's of course available only in command handlers
! 2247: not entered using the <B>cont</B> hook.
! 2248: <P>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 (<B>cli_printf()</B>, <B>cli_alloc_out()</B>) and
! 2251: cli.tx_pos is the buffer currently used by the consumer
! 2252: (<B>cli_write()</B>, 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 <B>cli_write_trigger()</B>. 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 <B>cli_written()</B>, tha frees all buffers (except the
! 2259: first one) and schedules cli.event .
! 2260: <P>
! 2261: <P><HR><H3>Function</H3>
! 2262: <P><I>void</I>
! 2263: <B>cli_printf</B>
! 2264: (<I>cli *</I> <B>c</B>, <I>int</I> <B>code</B>, <I>char *</I> <B>msg</B>, <I>...</I> <B>...</B>) -- send reply to a CLI connection
! 2265: <P>
! 2266: <H3>Arguments</H3>
! 2267: <P>
! 2268: <DL>
! 2269: <DT><I>cli *</I> <B>c</B><DD><P>CLI connection
! 2270: <DT><I>int</I> <B>code</B><DD><P>numeric code of the reply, negative for continuation lines
! 2271: <DT><I>char *</I> <B>msg</B><DD><P>a <B>printf()</B>-like formatting string.
! 2272: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 2273: </DL>
! 2274: <H3>Description</H3>
! 2275: <P>This function send a single line of reply to a given CLI connection.
! 2276: In works in all aspects like <B>bsprintf()</B> except that it automatically
! 2277: prepends the reply line prefix.
! 2278: <P>Please note that if the connection can be already busy sending some
! 2279: data in which case <B>cli_printf()</B> 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: <P>If you want to write to the current CLI output, you can use the <B>cli_msg()</B>
! 2283: macro instead.
! 2284:
! 2285:
! 2286: <HR><H3>Function</H3>
! 2287: <P><I>void</I>
! 2288: <B>cli_init</B>
! 2289: (<B>void</B>) -- initialize the CLI module
! 2290: <P>
! 2291: <H3>Description</H3>
! 2292: <P>
! 2293: <P>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: <P>
! 2300: <P>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: <P>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: <P>Object locks are represented by <I>object_lock</I> structures which are in turn a
! 2312: kind of resource. Lockable resources are uniquely determined by resource type
! 2313: (<I>OBJLOCK_UDP</I> 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: <P>
! 2317: <P><HR><H3>Function</H3>
! 2318: <P><I>struct object_lock *</I>
! 2319: <B>olock_new</B>
! 2320: (<I>pool *</I> <B>p</B>) -- create an object lock
! 2321: <P>
! 2322: <H3>Arguments</H3>
! 2323: <P>
! 2324: <DL>
! 2325: <DT><I>pool *</I> <B>p</B><DD><P>resource pool to create the lock in.
! 2326: </DL>
! 2327: <H3>Description</H3>
! 2328: <P>The <B>olock_new()</B> function creates a new resource of type <I>object_lock</I>
! 2329: and returns a pointer to it. After filling in the structure, the caller
! 2330: should call <B>olock_acquire()</B> to do the real locking.
! 2331:
! 2332:
! 2333: <HR><H3>Function</H3>
! 2334: <P><I>void</I>
! 2335: <B>olock_acquire</B>
! 2336: (<I>struct object_lock *</I> <B>l</B>) -- acquire a lock
! 2337: <P>
! 2338: <H3>Arguments</H3>
! 2339: <P>
! 2340: <DL>
! 2341: <DT><I>struct object_lock *</I> <B>l</B><DD><P>the lock to acquire
! 2342: </DL>
! 2343: <H3>Description</H3>
! 2344: <P>This function attempts to acquire exclusive access to the non-shareable
! 2345: resource described by the lock <B>l</B>. It returns immediately, but as soon
! 2346: as the resource becomes available, it calls the <B>hook()</B> function set up
! 2347: by the caller.
! 2348: <P>When you want to release the resource, just <B>rfree()</B> the lock.
! 2349:
! 2350:
! 2351: <HR><H3>Function</H3>
! 2352: <P><I>void</I>
! 2353: <B>olock_init</B>
! 2354: (<B>void</B>) -- initialize the object lock mechanism
! 2355: <P>
! 2356: <H3>Description</H3>
! 2357: <P>
! 2358: <P>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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-2.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc