sid-control-cfgroot (internal :: config_component_library)

Synopsis:

This component configures and executes a simulation run.

Functionality:

Modelling:

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

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.

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.

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.
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 values	default value	behaviors
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