SID Simulator User's Guide | ||
---|---|---|
<<< Previous | Working with the SID Configuration File | Next >>> |
The syntax for each command type follows.
The syntax is: LIBRARYFILE LIBRARYSYMBOL
where:
The LIBRARYFILE parameter is a file name.
The LIBRARYSYMBOL parameter is a symbol name.
For a list of appropriate LIBRARYFILE and LIBRARYSYMBOL names, refer to the component reference information on each component.
Registers a component library. Loads the shared library from the file named by the first string. Enumerates the available component types by searching the library for the sid::component_library symbol named by the second string. Add all its component type names to the catalog of known types for subsequent new commands. Nearly all SID components are packaged in shared libraries.
The LIBRARYFILE parameter is interpreted as a filename. It may be the name of a Windows DLL or the name UNIX shared object (.so) file, although libtool archives ending with the extension .la are preferred. The file must exist and be loadable on the host platform using normal library loading routines like dlopen(). If the filename is not absolute, several paths are searched. Among these are a colon-separated UNIX-style directory list given in the SID_LIBRARY_PATH environment variable, the PATH environment variable in standard platform notation, and the installation root directory for SID given by the SID_EXEC_PREFIX environment variable.
The LIBRARYSYMBOL parameter is the name of an exported data symbol in the shared library. It must be resolvable using a standard function like dlsym() and refer to an initialized instance of the sid::component_library structure that lists the low-level entry points to the component factory functions.
The load command checks the magic version number in the structure against the number compiled into the sid main-line program. If the shared library is deemed compatible, the list of component types that it contains are obtained, using the sid::component_library::list_component_types() call, and registered internally. From this point, any further request to instantiate a component type whose name is on that list will be directed to this shared library. The special string -static- is also understood as a LIBRARYFILE parameter. It is used in cases where sid::component_library structures are specially linked directly into the SID main-line program. This is an advanced technique and is not discussed further. Referring to an invalid LIBRARYFILE or LIBRARYSYMBOL will cause an error.
The syntax is:
new TYPENAME REFERENCE |
The TYPENAME parameter is the component type.
The REFERENCE parameter is the reference name of the new component instance.
Instantiates a new component. The first string is the component type--one of those made available by a prior load command. The second string is the freely chosen reference name for the new component instance. That name must be unique in a SID run. It is possible to instantiate the same type of component multiple times, but each instance must have a unique reference name. A sid-control-cfgroot type component is automatically instantiated and given the reference name main, so that name is reserved. Do not use an unknown TYPENAME, or a duplicate REFERENCE ; this will cause an error.
If this command is successful, it will cause the sid::component_library::create_component() hook to be called on the component library that has last registered TYPENAME.
The syntax is:
connect-pin COMPONENT1 PIN1 DIRECTION COMPONENT2 PIN2 |
disconnect-pin COMPONENT1 PIN1 DIRECTION COMPONENT2 PIN2 |
The COMPONENT1 and COMPONENT2 parameters are reference names of existing component instances.
The PIN1 and PIN2 parameters are pin names belonging to COMPONENT1 and COMPONENT2, respectively.
The DIRECTION parameter is either " ->", "<-", or "<->", indicating the directionality of the pin connection. The first two establish or destroy a single pin connection in opposite directions, and the last establishes or destroys two independent connections in the opposite directions. The arrow shape suggests the direction of signalling: output to input.
Adds or removes a pin connection between a pair of component instances. Each SID component generally defines its own set of pins. These may be input and/or output. See the reference documentation for the list for any particular component type. It is possible to connect many input pins to a given output pin, and it is also possible to connect many output pins to a given input pin. It is an error to make the same pin-to-pin connection twice, or to connect an input-only and an output-only pin in the wrong direction. Similarly, it is an error to try to remove a nonexistent connection.
The connect-pin command causes a sid::component::find_pin() call on the component and pin on the input side of the arrow, and passes the result to a sid::component::connect_pin() call on the output side of the arrow. (The bidirectional <-> case simply repeats this with the two sides exchanged.) The disconnect-pin command does the same, except it uses sid::component::disconnect_pin() instead. With a pin connection, the component on the output side of the arrow can make sid::pin::driven calls to the given input pin.
The syntax is:
connect-bus MASTER ACCESSOR SLAVE BUS |
disconnect-bus MASTER ACCESSOR SLAVE BUS |
The MASTER and SLAVE parameters are reference names of existing component instances.
The ACCESSOR parameter is the name of an accessor of the MASTER component.
The BUS parameter is the name of a bus of the SLAVE component.
Adds or removes an accessor-to-bus connection between two components. Each SID component defines its own set of buses and accessors. See the component reference sections for the list for any particular component type.
The connect-bus command causes a sid::component::find_bus() call on the SLAVE component for the BUS name, and will pass the result to a sid::component::connect_accessor() call on the MASTER component for the ACCESSOR name. The disconnect-bus command does the same, except it uses sid::component::disconnect_accessor() instead. With a bus connection, the MASTER component can make sid::bus read or write calls via the given accessor to the given bus of the SLAVE component.
The syntax is:
set COMPONENT ATTRNAME ATTRVALUE |
The COMPONENT parameter is a reference name of an existing SID component instance.
The ATTRNAME parameter is the name of an attribute defined by that component.
The ATTRVALUE parameter is the value string.
Sets an attribute value. Each SID component generally defines its own set of attributes and rules for interpreting their values. See the component reference sections for the list for any particular component type.
The component instance will receive a sid::component::set_attribute_value() call with verbatim copies of these two parameters. If the sid::component::set_attribute_value() call fails (returns something other than sid::component::ok ), the configuration process will fail.
The syntax is:
relate COMPONENT1 RELATIONSHIP COMPONENT2 |
unrelate COMPONENT1 RELATIONSHIP COMPONENT2 |
The COMPONENT1 and COMPONENT2 parameters are reference names of existing component instances.
The RELATIONSHIP parameter is the name of a component relationship supported by COMPONENT1.
Adds or removes a supervisory relationship between the named components. Each SID component may define its own set of component relationships. See the component reference sections for the list of relationships it supports. It is an error to create duplicate relationships, for example by repeating the same command.
This command causes a SID component API call to be placed on COMPONENT1, supplying RELATIONSHIP and COMPONENT2. For more information on the SID component API, refer to the Component Developer's Kit Reference manual. With a component relationship, COMPONENT1 is able to make any low-level SID API call on COMPONENT2.
The configuration file may contain blank lines. Comments begin with the # character and terminate at end-of-line. Blank lines and comments are ignored during parsing. All commands take some arguments. All arguments are strings. A string is a white-space-separated sequence of printable (isprint()) characters. Strings may be enclosed in double quotes. If started with double-quotes, all characters between opening and closing quotes are included in the string. Backslash characters ( "\" ) escape double-quotes and backslash characters, in the usual C convention. The string \n is interpreted as a C \n. Without double-quotes, strings are taken to be whitespace-separated words. 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.
<<< Previous | Home | Next >>> |
Creating a New Configuration File | Up | How to Understand Component Reference Information |