           sid-control-cfgroot (internal :: config_component_library)

Synopsis:

   This component configures and executes a simulation run. This component
   also maintains a mapping of configuration names to configuration strings
   for use by the sid-control-dynamic-configurator components associated with
   each board.

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   This component encapsulates the configuration file parser and the
   simulation main loop. It does not correspond to hardware.

   configuration file format

   The configuration file format is very simple, and the parser/lexer are
   minimal. Each command in the configuration file maps to 1-3 sid::component
   API calls. There is no application- or component-dependent logic.

   Grammar:

 cfg-file ::= cfg-line | cfg-file cfg-line

 cfg-line ::=
   load-cmd | new-cmd | connect-pin-cmd | disconnect-pin-cmd |
   connect-bus-cmd | disconnect-bus-cmd | set-cmd | relate-cmd | unrelate-cmd
      

 load-cmd ::= "load" file-name symbol-name
 file-name ::= string
 symbol-name ::= string
      

   Register a component library. Load the shared library from the file named
   by the first string, or fall back to the sid mainline executable itself.
   Look up a component_library symbol named by the second string. Add all
   component type names to the catalog of types. Its
   sid::component_library::list_component_types hook is called. A
   compatibility magic value in the component library is tested. If a
   filename omits a directory specification, then the installed location and
   a search path held in the SID_LIBRARY_PATH environment variable is
   searched for the library. The library directory under that given by
   SID_EXEC_PREFIX environment variable (optionally set at sid installation
   time), or else the build-time --exec-prefix, is also searched.

 new-cmd ::= "new" type-name comp-name
 type-name ::= string
 comp-name ::= string
      

   Instantiate a new component. The first string is the component type, as
   registered in a prior load-cmd. The second string is the new component
   instance's nick-name. The nicknames must be unique among those built by
   cfgroot. The lucky winner's sid::component_library::create_component hook
   is called.

 connect-pin-cmd ::= "connect-pin" comp-name pin-name dir comp-name pin-name
 dir ::= "->" | "<-" | "<->"
 comp-name ::= string
 pin-name ::= string
      

   Establish a new pin-to-pin connection between two components. The
   component/pin to the left of the -> or right of the <- operator receives
   asid::component::connect_pin call. The other receives a
   sid::component::find_pin call. If the <-> operator is specified, then
   establish two pin-to-pin links in opposite directions.

 disconnect-pin-cmd ::= "disconnect-pin" comp-name pin-name dir comp-name pin-name
 dir ::= "->" | "<-" | "<->"
 comp-name ::= string
 pin-name ::= string

   Break an existing pin-to-pin connection between two components. The
   component/pin to the left of the -> or right of the <- operator receives a
   sid::component::disconnect_pin call. The other receives a
   sid::component::find_pin call. If the <-> operator is specified, then the
   connection will be broken in both directions.

 connect-bus-cmd ::= "connect-bus" comp-name acc-name comp-name bus-name
 comp-name ::= string
 acc-name ::= string
 bus-name ::= string

   Establish a new accessor-to-bus connection between two components. The
   left component receives a sid::component::connect_accessor call; the right
   component receives a sid::component::find_bus call.

 disconnect-bus-cmd ::= "disconnect-bus" comp-name acc-name comp-name bus-name
 comp-name ::= string
 acc-name ::= string
 bus-name ::= string

   Break an existing accessor-to-bus connection between two components. The
   left component recevies a sid::component::disconnect_accessor call; the
   right component receives a sid::component::find_bus call.

 set-cmd ::= "set" comp-name attr-name attr-value
 comp-name ::= string
 attr-name ::= string
 attr-value ::= string

   Set the given attribute of the given component to the given value. The
   component receives a sid::component::set_attribute_value call.

 relate-cmd ::= "relate" comp-name rel-name comp-name
 comp-name ::= string
 rel-name ::= string

   Add the second named component to the named component relationship set for
   the first given component. The first component receives a
   sid::component::relate call.

 unrelate-cmd ::= "unrelate" comp-name rel-name comp-name
 comp-name ::= string
 rel-name ::= string

   Remove the second named component from the named component relationship
   set for the first given component. The first component receives a
   sid::component::unrelate call.

   Lexer issues:

   A string is a white-space-separated sequence of printable ( isprint())
   characters. If started with double-quotes, all characters between opening
   and closing quotes are included in the string. Embedded lexer control
   characters ('\' and '"') may be escaped by a '\' prefix. "\n" is
   interpreted as a C++ \n. (What other escape sequences are worth
   supporting?)

   A "#" character found where a string is expected is interpreted as a
   comment to end-of-line, and the search for the next string found is
   returned instead.

   +-----------------------------------------------------------+
   |                         Behaviors                         |
   |-----------------------------------------------------------|
   |configuration|When the config-file! attribute is written   |
   |             |to, the value is interpreted as a file name, |
   |             |and processed as a configuration file. The   |
   |             |name of the file is appended to a history    |
   |             |list, which is accessible as the read-only   |
   |             |attribute config-file-history.               |
   |             |                                             |
   |             |The format of the configuration file is      |
   |             |described in the APPENDIX below. As each line|
   |             |is read, the appropriate component API       |
   |             |functions are called. In case of any failure,|
   |             |a message is printed to standard error, and a|
   |             |failure result code will be returned from the|
   |             |set_attribute_value call.                    |
   |             |                                             |
   |             |If the auto-print? attribute is set to a true|
   |             |value, then as each component instance is    |
   |             |created, all its attributes in the auto-print|
   |             |category will be queried and printed to      |
   |             |standard output.                             |
   |             |                                             |
   |             |The effects of multiple writes to the        |
   |             |config-file! attribute are cumulative. The   |
   |             |sid-control-cfgroot component is always      |
   |             |implicitly present with the component name   |
   |             |main. If the verbose? attribute is set, some |
   |             |tracing messages are printed during          |
   |             |configuration.                               |
   |             |                                             |
   |             |When the config-line! attribute is written   |
   |             |to, the supplied value is interpreted as a   |
   |             |single configuration command and executed, as|
   |             |if that value was written to a file, and the |
   |             |file's name supplied to the config-file!     |
   |             |attribute.                                   |
   |             |                                             |
   |             |When the dynamic-config! attribute is written|
   |             |to, the value is interpreted as a            |
   |             |configuration spec of the form               |
   |             |NAME:CONFIG_STRING[|NAME:CONFIG_STRING]*.    |
   |             |Each CONFIG_STRING is then associated with   |
   |             |the given NAME.                              |
   |             |                                             |
   |             |When the lookup-dynamic-config! attribute is |
   |             |written to, the value is interpreted as a    |
   |             |name previously associated with a config     |
   |             |string via the dynamic-config! attribute. The|
   |             |associated configuration string is then made |
   |             |available via the found-dynamic-config       |
   |             |attribute.                                   |
   |-------------+---------------------------------------------|
   |      startup|When the run! pin is driven, the simulation  |
   |             |top level loop begins. This process has      |
   |             |several stages.                              |
   |             |                                             |
   |             |First, all components registered in the      |
   |             |component-catalog-informees relationship are |
   |             |given the then-current list of components.   |
   |             |This is done by setting a number of          |
   |             |individual component relationships for every |
   |             |informee. Each relationship contains a single|
   |             |instantiated component pointer, and has the  |
   |             |name constructed as "TYPE NAME", as          |
   |             |appropriate for that component.              |
   |             |                                             |
   |             |Immediately after this, the simulation main  |
   |             |loop behavior takes over. Only after that    |
   |             |main loop is finished will control return to |
   |             |the function that sent the run! signal to    |
   |             |this component.                              |
   |-------------+---------------------------------------------|
   |    main loop|The main loop has two levels. An infinite    |
   |             |outer loop remains active as long as the     |
   |             |persistent? attribute is set to a boolean    |
   |             |true value. The body of this loop performs a |
   |             |sequence of steps. First, it drives the      |
   |             |starting output pin. Then, it enters the     |
   |             |inner main loop. At the start of this loop,  |
   |             |the running attribute is set to boolean true.|
   |             |In the loop, the activity-count attribute is |
   |             |incremented, and the perform-activity output |
   |             |pin is repeatedly driven. This loop runs     |
   |             |until the stop! input pin is driven. (This   |
   |             |could happen during the initial starting     |
   |             |signal, in which case this inner loop will   |
   |             |not be entered at all.) The value driven on  |
   |             |the stop! is stored in the stop-code         |
   |             |attribute. After the inner loop exits, the   |
   |             |stopping output pin is driven.               |
   +-----------------------------------------------------------+

   +----------------------------------------------------+
   |                  SID Conventions                   |
   |----------------------------------------------------|
   |        supervisory|supported  |-                   |
   |-------------------+-----------+--------------------|
   |       save/restore|supported  |-                   |
   |-------------------+-----------+--------------------|
   |      triggerpoints|not        |-                   |
   |                   |supported  |                    |
   |-------------------+-----------+--------------------|
   |  recursion-inhibit|supported  |run!                |
   |-------------------+-----------+--------------------|
   |         categories|supported  |settingpinregister  |
   +----------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

     ----------------------------------------------------------------------

Component Reference:

  Component: sid-control-cfgroot

   +--------------------------------------------------------+
   |                          pins                          |
   |--------------------------------------------------------|
   |       name       | direction | legalvalues | behaviors |
   |------------------+-----------+-------------+-----------|
   |run!              |in         |-            |startup    |
   |------------------+-----------+-------------+-----------|
   |starting          |out        |-            |main loop  |
   |------------------+-----------+-------------+-----------|
   |perform-activity  |out        |-            |main loop  |
   |------------------+-----------+-------------+-----------|
   |stop!             |in         |-            |main loop  |
   |------------------+-----------+-------------+-----------|
   |stopping          |out        |-            |main loop  |
   +--------------------------------------------------------+

   +------------------------------------------------------------------------+
   |                               attributes                               |
   |------------------------------------------------------------------------|
   |         name         |category|legal |default|       behaviors        ||
   |                      |        |values| value |                        ||
   |----------------------+--------+------+-------+------------------------||
   |config-file!          |-       |-     |-      |configuration           ||
   |----------------------+--------+------+-------+------------------------||
   |config-line!          |-       |-     |-      |configuration           ||
   |----------------------+--------+------+-------+------------------------||
   |config-file-history   |register|-     |-      |configuration           ||
   |----------------------+--------+------+-------+------------------------||
   |verbose?              |setting |-     |-      |configuration, main loop||
   |----------------------+--------+------+-------+------------------------||
   |persistent?           |setting |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |auto-print?           |setting |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |state-snapshot        |-       |-     |-      |state save/restore      ||
   |----------------------+--------+------+-------+------------------------||
   |starting              |pin     |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |running               |register|-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |activity-count        |register|-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |stop-code             |register|-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |perform-activity      |pin     |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |stop!                 |pin     |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |stopping              |pin     |-     |-      |main loop               ||
   |----------------------+--------+------+-------+------------------------||
   |dynamic-config!       |-       |-     |-      |configuration           ||
   |----------------------+--------+------+-------+------------------------||
   |lookup-dynamic-config!|-       |-     |-      |configuration           ||
   |----------------------+--------+------+-------+------------------------||
   |found-dynamic-config  |-       |-     |-      |configuration           ||
   +------------------------------------------------------------------------+
