| SID Simulator User's Guide | ||
|---|---|---|
| <<< Previous | How to Understand Component Reference Information | Next >>> |
The simulation component documentation template is broken into the following sections.
This item provides the SID component-type name. In cases where a family of components may be described together, this item may list several names.
SID component-type names are structured so that the first part of the component-type name indicates the category of thing that is simulated:
hw usually indicates that the simulated component represents hardware.
sw indicates that the simulated component represents software.
sid indicates that the simulated component performs special simulation management tasks.
The Synopsis summarizes the component's purpose and lists its external interfaces in a condensed form. The summary includes a complete list of the names of the component's pins, buses, accessors, attributes, and relationships. These names may be referenced in SID configuration files, or by other supervisory components. The last items in this section list the component library file and symbol names in which this component-type is found. Supply these two names to a load configuration file command.
This section gives detailed information about how this component operates. It has several subsections.
The modelling subsection discusses the relationship of this SID component to the real thing (maybe hardware) being modelled. The scope of simulation focuses on whatever important differences exist between a simulated program's view of the SID model versus reality.
The behaviors subsection describes in detail how the SID component operates. Each separate behavior (stage of life, or independent processing activity) is described separately. Each behavior section describes what triggers the behavior (usually a pin, bus, or attribute call), what the component does internally in response, and what external results may be visible. These sections reference the low-level pin, bus, etc. names.
The conventions subsection describes which SID behaviors the component supports. These are called conventions, since they are high-level behaviors expressed exclusively in terms of lower-level constructs (pins, attributes, and so on). The following is a list of SID conventions.
A supervisory component may manipulate other components using the full SID API. A functional component uses only the pin and bus APIs to communicate with its neighbors. Most hardware modelling components are functional; most simulator control components are supervisory.
A SID component that supports the target view specially exports some attributes. The component classifies these selected attributes with one of the category names pin, register, or setting. The component internally associates these attributes with operations on actual SID pins or other state.
The target view will allow attributes of these three categories to be interacted with ( display = read, update = write ). The write routines associated with these attributes should be generous to permit the user a wide range of valid input formats.
A SID component that does not support the target view may still be a first class member of a SID configuration. It will be harder for a user to interact with the component, that's all.
A SID component that supports standard state save/restore function does so by exporting an attribute named state-snapshot. When read, the attribute value represents a subset of the internal state of the component; this is the state save operation. When written to with the string from a previous read, the internal state of the component will be reset according to the supplied string; this is the restore operation.
Normally, components endavour to save and restore the subset state that may be visible to an executing simulated application. Some components may save/restore additional state like configuration preferences, or transitory attributes.
A SID component that does not support state save/restore may not be safe to interoperate with other components after a restore operation.
A SID component that supports triggerpoints allows some internal state to be watched or monitored for certain conditions. Watch criteria include any change, matching a given value, or matching a given value with a given boolean mask. Whenever a component detects that an active watching criterion succeeds, it drive a special output pin.
The watchable internal state values are advertised as attributes with the additional category watchable. Watching such a state value involves, at the low level, connecting to a virtual output pins that has a special name. The name encodes the watchable item and a specification of the watch criterion.
A SID component that does not support triggerpoints may still be a first class member of a SID configuration. Monitoring the component's internal state may simply be slow and cumbersome.
Some SID components defend themselves against reentrancy. Since SID components tend to perform activity by calling other SID components, it is conceivable that the called component may in turn call back to the original component. It is a possible problem because some components may have internal data structures that are not in a consistent state at the moment of a reentrant call. It is also possible that infinite recursion could result.
A SID component that defends itself against reentrancy does this by run-time checks around certain incoming calls, like specific pin or bus signals, or attribute accesses. When it detects that more than some number of calls are in progress, it signals an error message and may even shut SID down.
A SID component that does not defend itself against reentrancy may nevertheless be vulnerable to the problem. It may be unable to detect the situation before it becomes a failure.
In order to avoid triggering these detection measures, it is important that a SID configuration avoid the possibility of violation of the reentrancy restrictions of a component. For example, avoid creating pin or bus connections that cause gratuitous loops, and abusing supervisory components.
This section talks about how instances of this component interact with their environment.
SID components are meant to connect to each other. This section discusses what other components work well together with this one. It may include configuration file fragments to demonstrate minimal interconnection instructions.
Since SID components are software modules that run on the host, they naturally interact with the host system. In some cases, there may be significant resource consumption issues that a user needs to be aware of. This section talks about what kind of impact this component may have on the host, including host I/O, security concerns, memory consumption, performance, and error handling conventions.
This section discusses the interfaces of this SID component in a tabular reference format. There are several formats, one per low level interface. In all cases, the table rows cross-reference to the Behaviors section, where fuller details about the use of that item may be found (see Behaviors for more details).
Gives the string that the connect-pin configuration command may use to reference this pin.
Identifies this pin as a possible input, output, or both.
Lists the range of values that may be driven into this pin (if an input), or what values may be driven outward (if output). The values may be limited to a subrange of the host_int_4 type.
References the behaviors associated with this pin
Gives the string with which the connect-bus configuration command may reference this bus.
Identifies the supported range of addresses for accesses on this bus.
Lists what subset of size, endianness, and read/write accesses are supported.
References the behaviors associated with this bus.
Gives the string with which the connect-bus configuration command may reference this accessor.
Lists what subset of size, endianness, and read/write accesses may be made by this component using this accessor.
References the behaviors associated with this accessor.
Gives the string with which the set configuration command may reference this attribute.
Lists the category names under which this attribute is classified.
Describes legal values of this attribute, for both reading and writing, and may include the default value. There are several common attribute value formats:
numeric strings are C-style integral numeric literals like 0, 0xEEEF, 0377, 0b1101101, and -75.
boolean strings are values such as true, false, n, yes, 0, and 1.
general strings containing a sequence of unrestricted binary bytes.
References the behaviors associated with this attribute.
Gives the string with which the relate configuration command may reference this relationship.
References the behaviors associated with this relationship.
This section may refer the reader to further material describing the component, or its real-world image.
| <<< Previous | Home | Next >>> |
| How to Understand Component Reference Information | Up | Using SID |