Annotation of embedaddon/bird/doc/prog-3.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: Configuration</TITLE>
! 6: <LINK HREF="prog-4.html" REL=next>
! 7: <LINK HREF="prog-2.html" REL=previous>
! 8: <LINK HREF="prog.html#toc3" REL=contents>
! 9: </HEAD>
! 10: <BODY>
! 11: <A HREF="prog-4.html">Next</A>
! 12: <A HREF="prog-2.html">Previous</A>
! 13: <A HREF="prog.html#toc3">Contents</A>
! 14: <HR>
! 15: <H2><A NAME="s3">3.</A> <A HREF="prog.html#toc3">Configuration</A></H2>
! 16:
! 17: <H2><A NAME="ss3.1">3.1</A> <A HREF="prog.html#toc3.1">Configuration manager</A>
! 18: </H2>
! 19:
! 20: <P>
! 21: <P>Configuration of BIRD is complex, yet straightforward. There are three
! 22: modules taking care of the configuration: config manager (which takes care
! 23: of storage of the config information and controls switching between configs),
! 24: lexical analyzer and parser.
! 25: <P>The configuration manager stores each config as a <I>config</I> structure
! 26: accompanied by a linear pool from which all information associated
! 27: with the config and pointed to by the <I>config</I> structure is allocated.
! 28: <P>There can exist up to four different configurations at one time: an active
! 29: one (pointed to by <B>config</B>), configuration we are just switching from
! 30: (<B>old_config</B>), one queued for the next reconfiguration (<B>future_config</B>; if
! 31: there is one and the user wants to reconfigure once again, we just free the
! 32: previous queued config and replace it with the new one) and finally a config
! 33: being parsed (<B>new_config</B>). The stored <B>old_config</B> is also used for undo
! 34: reconfiguration, which works in a similar way. Reconfiguration could also
! 35: have timeout (using <B>config_timer</B>) and undo is automatically called if the
! 36: new configuration is not confirmed later. The new config (<B>new_config</B>) and
! 37: associated linear pool (<B>cfg_mem</B>) is non-NULL only during parsing.
! 38: <P>Loading of new configuration is very simple: just call <B>config_alloc()</B> to get
! 39: a new <I>config</I> structure, then use <B>config_parse()</B> to parse a configuration
! 40: file and fill all fields of the structure and finally ask the config manager
! 41: to switch to the new config by calling <B>config_commit()</B>.
! 42: <P>CLI commands are parsed in a very similar way -- there is also a stripped-down
! 43: <I>config</I> structure associated with them and they are lex-ed and parsed by the
! 44: same functions, only a special fake token is prepended before the command
! 45: text to make the parser recognize only the rules corresponding to CLI commands.
! 46: <P>
! 47: <P><HR><H3>Function</H3>
! 48: <P><I>struct config *</I>
! 49: <B>config_alloc</B>
! 50: (<I>const byte *</I> <B>name</B>) -- allocate a new configuration
! 51: <P>
! 52: <H3>Arguments</H3>
! 53: <P>
! 54: <DL>
! 55: <DT><I>const byte *</I> <B>name</B><DD><P>name of the config
! 56: </DL>
! 57: <H3>Description</H3>
! 58: <P>This function creates new <I>config</I> structure, attaches a resource
! 59: pool and a linear memory pool to it and makes it available for
! 60: further use. Returns a pointer to the structure.
! 61:
! 62:
! 63: <HR><H3>Function</H3>
! 64: <P><I>int</I>
! 65: <B>config_parse</B>
! 66: (<I>struct config *</I> <B>c</B>) -- parse a configuration
! 67: <P>
! 68: <H3>Arguments</H3>
! 69: <P>
! 70: <DL>
! 71: <DT><I>struct config *</I> <B>c</B><DD><P>configuration
! 72: </DL>
! 73: <H3>Description</H3>
! 74: <P><B>config_parse()</B> reads input by calling a hook function pointed to
! 75: by <B>cf_read_hook</B> and parses it according to the configuration
! 76: grammar. It also calls all the preconfig and postconfig hooks
! 77: before, resp. after parsing.
! 78: <H3>Result</H3>
! 79: <P>1 if the config has been parsed successfully, 0 if any
! 80: error has occurred (such as anybody calling <B>cf_error()</B>) and
! 81: the <B>err_msg</B> field has been set to the error message.
! 82:
! 83:
! 84: <HR><H3>Function</H3>
! 85: <P><I>int</I>
! 86: <B>cli_parse</B>
! 87: (<I>struct config *</I> <B>c</B>) -- parse a CLI command
! 88: <P>
! 89: <H3>Arguments</H3>
! 90: <P>
! 91: <DL>
! 92: <DT><I>struct config *</I> <B>c</B><DD><P>temporary config structure
! 93: </DL>
! 94: <H3>Description</H3>
! 95: <P><B>cli_parse()</B> is similar to <B>config_parse()</B>, but instead of a configuration,
! 96: it parses a CLI command. See the CLI module for more information.
! 97:
! 98:
! 99: <HR><H3>Function</H3>
! 100: <P><I>void</I>
! 101: <B>config_free</B>
! 102: (<I>struct config *</I> <B>c</B>) -- free a configuration
! 103: <P>
! 104: <H3>Arguments</H3>
! 105: <P>
! 106: <DL>
! 107: <DT><I>struct config *</I> <B>c</B><DD><P>configuration to be freed
! 108: </DL>
! 109: <H3>Description</H3>
! 110: <P>This function takes a <I>config</I> structure and frees all resources
! 111: associated with it.
! 112:
! 113:
! 114: <HR><H3>Function</H3>
! 115: <P><I>int</I>
! 116: <B>config_commit</B>
! 117: (<I>struct config *</I> <B>c</B>, <I>int</I> <B>type</B>, <I>int</I> <B>timeout</B>) -- commit a configuration
! 118: <P>
! 119: <H3>Arguments</H3>
! 120: <P>
! 121: <DL>
! 122: <DT><I>struct config *</I> <B>c</B><DD><P>new configuration
! 123: <DT><I>int</I> <B>type</B><DD><P>type of reconfiguration (RECONFIG_SOFT or RECONFIG_HARD)
! 124: <DT><I>int</I> <B>timeout</B><DD><P>timeout for undo (or 0 for no timeout)
! 125: </DL>
! 126: <H3>Description</H3>
! 127: <P>When a configuration is parsed and prepared for use, the
! 128: <B>config_commit()</B> function starts the process of reconfiguration.
! 129: It checks whether there is already a reconfiguration in progress
! 130: in which case it just queues the new config for later processing.
! 131: Else it notifies all modules about the new configuration by calling
! 132: their <B>commit()</B> functions which can either accept it immediately
! 133: or call <B>config_add_obstacle()</B> to report that they need some time
! 134: to complete the reconfiguration. After all such obstacles are removed
! 135: using <B>config_del_obstacle()</B>, the old configuration is freed and
! 136: everything runs according to the new one.
! 137: <P>When <B>timeout</B> is nonzero, the undo timer is activated with given
! 138: timeout. The timer is deactivated when <B>config_commit()</B>,
! 139: <B>config_confirm()</B> or <B>config_undo()</B> is called.
! 140: <H3>Result</H3>
! 141: <P><I>CONF_DONE</I> if the configuration has been accepted immediately,
! 142: <I>CONF_PROGRESS</I> if it will take some time to switch to it, <I>CONF_QUEUED</I>
! 143: if it's been queued due to another reconfiguration being in progress now
! 144: or <I>CONF_SHUTDOWN</I> if BIRD is in shutdown mode and no new configurations
! 145: are accepted.
! 146:
! 147:
! 148: <HR><H3>Function</H3>
! 149: <P><I>int</I>
! 150: <B>config_confirm</B>
! 151: (<B>void</B>) -- confirm a commited configuration
! 152: <P>
! 153: <H3>Description</H3>
! 154: <P>
! 155: <P>When the undo timer is activated by <B>config_commit()</B> with nonzero timeout,
! 156: this function can be used to deactivate it and therefore confirm
! 157: the current configuration.
! 158: <H3>Result</H3>
! 159: <P><I>CONF_CONFIRM</I> when the current configuration is confirmed,
! 160: <I>CONF_NONE</I> when there is nothing to confirm (i.e. undo timer is not active).
! 161:
! 162:
! 163: <HR><H3>Function</H3>
! 164: <P><I>int</I>
! 165: <B>config_undo</B>
! 166: (<B>void</B>) -- undo a configuration
! 167: <P>
! 168: <H3>Description</H3>
! 169: <P>
! 170: <P>Function <B>config_undo()</B> can be used to change the current
! 171: configuration back to stored <I>old_config</I>. If no reconfiguration is
! 172: running, this stored configuration is commited in the same way as a
! 173: new configuration in <B>config_commit()</B>. If there is already a
! 174: reconfiguration in progress and no next reconfiguration is
! 175: scheduled, then the undo is scheduled for later processing as
! 176: usual, but if another reconfiguration is already scheduled, then
! 177: such reconfiguration is removed instead (i.e. undo is applied on
! 178: the last commit that scheduled it).
! 179: <H3>Result</H3>
! 180: <P><I>CONF_DONE</I> if the configuration has been accepted immediately,
! 181: <I>CONF_PROGRESS</I> if it will take some time to switch to it, <I>CONF_QUEUED</I>
! 182: if it's been queued due to another reconfiguration being in progress now,
! 183: <I>CONF_UNQUEUED</I> if a scheduled reconfiguration is removed, <I>CONF_NOTHING</I>
! 184: if there is no relevant configuration to undo (the previous config request
! 185: was <B>config_undo()</B> too) or <I>CONF_SHUTDOWN</I> if BIRD is in shutdown mode and
! 186: no new configuration changes are accepted.
! 187:
! 188:
! 189: <HR><H3>Function</H3>
! 190: <P><I>void</I>
! 191: <B>order_shutdown</B>
! 192: (<B>void</B>) -- order BIRD shutdown
! 193: <P>
! 194: <H3>Description</H3>
! 195: <P>
! 196: <P>This function initiates shutdown of BIRD. It's accomplished by asking
! 197: for switching to an empty configuration.
! 198:
! 199:
! 200: <HR><H3>Function</H3>
! 201: <P><I>void</I>
! 202: <B>cf_error</B>
! 203: (<I>char *</I> <B>msg</B>, <I>...</I> <B>...</B>) -- report a configuration error
! 204: <P>
! 205: <H3>Arguments</H3>
! 206: <P>
! 207: <DL>
! 208: <DT><I>char *</I> <B>msg</B><DD><P>printf-like format string
! 209: <DT><I>...</I> <B>...</B><DD><P>variable arguments
! 210: </DL>
! 211: <H3>Description</H3>
! 212: <P><B>cf_error()</B> can be called during execution of <B>config_parse()</B>, that is
! 213: from the parser, a preconfig hook or a postconfig hook, to report an
! 214: error in the configuration.
! 215:
! 216:
! 217: <HR><H3>Function</H3>
! 218: <P><I>char *</I>
! 219: <B>cfg_strdup</B>
! 220: (<I>const char *</I> <B>c</B>) -- copy a string to config memory
! 221: <P>
! 222: <H3>Arguments</H3>
! 223: <P>
! 224: <DL>
! 225: <DT><I>const char *</I> <B>c</B><DD><P>string to copy
! 226: </DL>
! 227: <H3>Description</H3>
! 228: <P><B>cfg_strdup()</B> creates a new copy of the string in the memory
! 229: pool associated with the configuration being currently parsed.
! 230: It's often used when a string literal occurs in the configuration
! 231: and we want to preserve it for further use.
! 232:
! 233: <H2><A NAME="ss3.2">3.2</A> <A HREF="prog.html#toc3.2">Lexical analyzer</A>
! 234: </H2>
! 235:
! 236: <P>
! 237: <P>The lexical analyzer used for configuration files and CLI commands
! 238: is generated using the <CODE>flex</CODE> tool accompanied by a couple of
! 239: functions maintaining the hash tables containing information about
! 240: symbols and keywords.
! 241: <P>Each symbol is represented by a <I>symbol</I> structure containing name
! 242: of the symbol, its lexical scope, symbol class (<I>SYM_PROTO</I> for a
! 243: name of a protocol, <I>SYM_CONSTANT</I> for a constant etc.) and class
! 244: dependent data. When an unknown symbol is encountered, it's
! 245: automatically added to the symbol table with class <I>SYM_VOID</I>.
! 246: <P>The keyword tables are generated from the grammar templates
! 247: using the <CODE>gen_keywords.m4</CODE> script.
! 248: <P>
! 249: <P><HR><H3>Function</H3>
! 250: <P><I>void</I>
! 251: <B>cf_lex_unwind</B>
! 252: (<B>void</B>) -- unwind lexer state during error
! 253: <P>
! 254: <H3>Lexical analyzer</H3>
! 255: <P>
! 256: <P><B>cf_lex_unwind()</B> frees the internal state on IFS stack when the lexical
! 257: analyzer is terminated by <B>cf_error()</B>.
! 258:
! 259:
! 260: <HR><H3>Function</H3>
! 261: <P><I>struct symbol *</I>
! 262: <B>cf_find_symbol</B>
! 263: (<I>struct config *</I> <B>cfg</B>, <I>byte *</I> <B>c</B>) -- find a symbol by name
! 264: <P>
! 265: <H3>Arguments</H3>
! 266: <P>
! 267: <DL>
! 268: <DT><I>struct config *</I> <B>cfg</B><DD><P>specificed config
! 269: <DT><I>byte *</I> <B>c</B><DD><P>symbol name
! 270: </DL>
! 271: <H3>Description</H3>
! 272: <P>This functions searches the symbol table in the config <B>cfg</B> for a symbol of
! 273: given name. First it examines the current scope, then the second recent one
! 274: and so on until it either finds the symbol and returns a pointer to its
! 275: <I>symbol</I> structure or reaches the end of the scope chain and returns <I>NULL</I> to
! 276: signify no match.
! 277:
! 278:
! 279: <HR><H3>Function</H3>
! 280: <P><I>struct symbol *</I>
! 281: <B>cf_get_symbol</B>
! 282: (<I>byte *</I> <B>c</B>) -- get a symbol by name
! 283: <P>
! 284: <H3>Arguments</H3>
! 285: <P>
! 286: <DL>
! 287: <DT><I>byte *</I> <B>c</B><DD><P>symbol name
! 288: </DL>
! 289: <H3>Description</H3>
! 290: <P>This functions searches the symbol table of the currently parsed config
! 291: (<B>new_config</B>) for a symbol of given name. It returns either the already
! 292: existing symbol or a newly allocated undefined (<I>SYM_VOID</I>) symbol if no
! 293: existing symbol is found.
! 294:
! 295:
! 296: <HR><H3>Function</H3>
! 297: <P><I>struct symbol *</I>
! 298: <B>cf_define_symbol</B>
! 299: (<I>struct symbol *</I> <B>sym</B>, <I>int</I> <B>type</B>, <I>void *</I> <B>def</B>) -- define meaning of a symbol
! 300: <P>
! 301: <H3>Arguments</H3>
! 302: <P>
! 303: <DL>
! 304: <DT><I>struct symbol *</I> <B>sym</B><DD><P>symbol to be defined
! 305: <DT><I>int</I> <B>type</B><DD><P>symbol class to assign
! 306: <DT><I>void *</I> <B>def</B><DD><P>class dependent data
! 307: </DL>
! 308: <H3>Description</H3>
! 309: <P>Defines new meaning of a symbol. If the symbol is an undefined
! 310: one (<I>SYM_VOID</I>), it's just re-defined to the new type. If it's defined
! 311: in different scope, a new symbol in current scope is created and the
! 312: meaning is assigned to it. If it's already defined in the current scope,
! 313: an error is reported via <B>cf_error()</B>.
! 314: <H3>Result</H3>
! 315: <P>Pointer to the newly defined symbol. If we are in the top-level
! 316: scope, it's the same <B>sym</B> as passed to the function.
! 317:
! 318:
! 319: <HR><H3>Function</H3>
! 320: <P><I>void</I>
! 321: <B>cf_lex_init</B>
! 322: (<I>int</I> <B>is_cli</B>, <I>struct config *</I> <B>c</B>) -- initialize the lexer
! 323: <P>
! 324: <H3>Arguments</H3>
! 325: <P>
! 326: <DL>
! 327: <DT><I>int</I> <B>is_cli</B><DD><P>true if we're going to parse CLI command, false for configuration
! 328: <DT><I>struct config *</I> <B>c</B><DD><P>configuration structure
! 329: </DL>
! 330: <H3>Description</H3>
! 331: <P><B>cf_lex_init()</B> initializes the lexical analyzer and prepares it for
! 332: parsing of a new input.
! 333:
! 334:
! 335: <HR><H3>Function</H3>
! 336: <P><I>void</I>
! 337: <B>cf_push_scope</B>
! 338: (<I>struct symbol *</I> <B>sym</B>) -- enter new scope
! 339: <P>
! 340: <H3>Arguments</H3>
! 341: <P>
! 342: <DL>
! 343: <DT><I>struct symbol *</I> <B>sym</B><DD><P>symbol representing scope name
! 344: </DL>
! 345: <H3>Description</H3>
! 346: <P>If we want to enter a new scope to process declarations inside
! 347: a nested block, we can just call <B>cf_push_scope()</B> to push a new
! 348: scope onto the scope stack which will cause all new symbols to be
! 349: defined in this scope and all existing symbols to be sought for
! 350: in all scopes stored on the stack.
! 351:
! 352:
! 353: <HR><H3>Function</H3>
! 354: <P><I>void</I>
! 355: <B>cf_pop_scope</B>
! 356: (<B>void</B>) -- leave a scope
! 357: <P>
! 358: <H3>Description</H3>
! 359: <P>
! 360: <P><B>cf_pop_scope()</B> pops the topmost scope from the scope stack,
! 361: leaving all its symbols in the symbol table, but making them
! 362: invisible to the rest of the config.
! 363:
! 364:
! 365: <HR><H3>Function</H3>
! 366: <P><I>char *</I>
! 367: <B>cf_symbol_class_name</B>
! 368: (<I>struct symbol *</I> <B>sym</B>) -- get name of a symbol class
! 369: <P>
! 370: <H3>Arguments</H3>
! 371: <P>
! 372: <DL>
! 373: <DT><I>struct symbol *</I> <B>sym</B><DD><P>symbol
! 374: </DL>
! 375: <H3>Description</H3>
! 376: <P>This function returns a string representing the class
! 377: of the given symbol.
! 378:
! 379: <H2><A NAME="ss3.3">3.3</A> <A HREF="prog.html#toc3.3">Parser</A>
! 380: </H2>
! 381:
! 382: <P>
! 383: <P>Both the configuration and CLI commands are analyzed using a syntax
! 384: driven parser generated by the <CODE>bison</CODE> tool from a grammar which
! 385: is constructed from information gathered from grammar snippets by
! 386: the <CODE>gen_parser.m4</CODE> script.
! 387: <P>Grammar snippets are files (usually with extension <CODE>.Y</CODE>) contributed
! 388: by various BIRD modules in order to provide information about syntax of their
! 389: configuration and their CLI commands. Each snipped consists of several
! 390: sections, each of them starting with a special keyword: <CODE>CF_HDR</CODE> for
! 391: a list of <CODE>#include</CODE> directives needed by the C code, <CODE>CF_DEFINES</CODE>
! 392: for a list of C declarations, <CODE>CF_DECLS</CODE> for <CODE>bison</CODE> declarations
! 393: including keyword definitions specified as <CODE>CF_KEYWORDS</CODE>, <CODE>CF_GRAMMAR</CODE>
! 394: for the grammar rules, <CODE>CF_CODE</CODE> for auxiliary C code and finally
! 395: <CODE>CF_END</CODE> at the end of the snippet.
! 396: <P>To create references between the snippets, it's possible to define
! 397: multi-part rules by utilizing the <CODE>CF_ADDTO</CODE> macro which adds a new
! 398: alternative to a multi-part rule.
! 399: <P>CLI commands are defined using a <CODE>CF_CLI</CODE> macro. Its parameters are:
! 400: the list of keywords determining the command, the list of parameters,
! 401: help text for the parameters and help text for the command.
! 402: <P>Values of <CODE>enum</CODE> filter types can be defined using <CODE>CF_ENUM</CODE> with
! 403: the following parameters: name of filter type, prefix common for all
! 404: literals of this type and names of all the possible values.
! 405: <P>
! 406: <P>
! 407: <HR>
! 408: <A HREF="prog-4.html">Next</A>
! 409: <A HREF="prog-2.html">Previous</A>
! 410: <A HREF="prog.html#toc3">Contents</A>
! 411: </BODY>
! 412: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-3.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