Simics Model Development Checklist

1 Simics Model Development Checklist

This application note provides a checklist for use when developing models of devices and systems for Simics. The intention is to help developers with creating high quality models that work well in Simics, including future versions, that behave in a way that Simics users expect models to, and that can be used together with other device models easily.

1.1 Generic Checklist

This section describes important generic items that should be taken into consideration when working with Simics. This applies if one is writing device models, components or general functionality to extend Simics.

GE-01 — Checkpointing

Device models and other Simics extensions must support checkpointing. All state associated with the modeled machine should be included in the checkpoint. The simulation session is not checkpointed. Simply loading a machine, taking a checkpoint without having advanced the simulation and restarting from that checkpoint should result in the same machine state. The same should be true at anytime during the simulation and care must be taken to checkpoint any transient state in a module, such as pending events.

For more information refer to the sections about events and attributes in "Programming with DML", the section about general usability in "Building Well-Behaved Models" and the section about configuration attributes in "Overview" in the Model Builder User's Guide. Also refer to the section "Configuration and Checkpointing" in the Simics User's Guide

GE-02 — Reverse Execution

Models that are deterministic and support checkpointing also work with reverse execution. But the performance of the attribute get/set methods, as well as their memory consumption, are more important. Use image objects for storing data-type attributes, such as internal memories, of more than a few kilo bytes. This can have dramatic effects on performance, especially when reverse execution is enabled. See also GE-13.

For more information refer to the sections about events and attributes in "Programming with DML", the section about general usability in "Building Well-Behaved Models" and the section about configuration attributes in "Overview" in the Model Builder User's Guide. Also refer to the section "Configuration and Checkpointing" in the Simics User's Guide

GE-03 — Use the Most Recent API

The most recent version of the Simics API should be used. Functions and interfaces marked as deprecated should be avoided.

The latest API is documented in the Reference Manuals included in each Simics package.

GE-04 — Use Standard Simics Interfaces

The Simics interface mechanism should be used when communicating between objects. The standard interface types should be used when possible, allowing newly developed objects to connect to existing ones. References between objects should be implemented using attribute, with the type "os" for port interfaces, "o" for interfaces implemented by the object without any port and "n" to allow no connection. It is recommended that all three variants are supported, i.e. "os|o|n".

For more information see the section about Simics interfaces in "Overview" in the Model Builder User's Guide. The standard interfaces are documented in the Reference Manuals included in each Simics package.

GE-05 — Host Independence

Code should be written to work on both little- and big-endian host systems. Operating system specifics should be avoided if possible, allowing code to run on Windows and Linux. Any access to the host, for example a real network, real display, real USB, etc, should be in a separate "host access" module and not in the device itself

GE-06 — Use Compiler to Catch Possible Errors

All code should compile without warnings. It is recommended that the default flags for the compiler in the Simics build environment are used. For GCC, this is something like -O2 -Wall -Werror.

GE-07 — Implement info and status Commands

All Simics classes should have an info and a status command. The info shows static information about an object. Required attributes used for configuration are typically presented here. The status command shows dynamic information about an object. For really detailed information, a class specific command is better suited. Objects that do not have any dynamic information should print this fact in the status command output.

For more information refer to the section about general usability in "Building Well-Behaved Models" in the Model Builder User's Guide.

GE-08 — Check for Memory Leaks

A module should not leak memory while running the simulation, including when taking checkpoints and using reverse execution. The internal Simics command mm-list-* can be used to see where memory has been allocated. To enable the command, set the environment variable SIMICS_MEMORY_TRACKING before starting Simics and enable internal commands, using the enable-unsupported-feature "malloc-debug" command.

For more information see the application note on Debugging User-Developed Simics Modules.

GE-09 — No Side Effects on Attribute Reads

There should never be any side effects when attributes are read. It should always be possible to read out attribute values without affecting the model.

For more information refer to the sections about attributes in "Programming with DML" and the section about configuration attributes in "Overview" in the Model Builder User's Guide.

GE-10 — Class, Attribute and Command Documentation

Classes, non-internal attributes and CLI commands should all be properly documented. For attributes that users may change, all allowed values have to be described.

For more information refer to the sections about structuring DML code in "Building Well-Behaved Models" and "Adding New Commands" in the Model Builder User's Guide.

GE-11 — Follow Naming Guidelines

Try to use coherent naming when creating files, classes, components, objects, attributes and commands in Simics. As a general rule, use lower case names. Abbreviations may be written in all capital letters, but avoid mixing upper and lower case letters, e.g., do not use capitalization. Avoid special characters and stick to plain ASCII.

Directories, C/C++, DML and .simics files

Use dash instead of underscore. Do not use spaces.

Python files

Use underscore instead of dash since the file name is used as a module name in Python.

Component Modules

Component modules typically end with the -comp suffix.

Classes and components

Use dash or underscore for class names in C and DML.
Use underscore for class and component names in Python (mandatory).

Objects and attributes

Use underscore in all names to simplify Python wrapping. Support for using dashes in these names will be removed in the future.

Commands

Use dash to separate words. Commands typically have the form <verb>-<noun>, for example list-objects.

Look at the existing naming for things not covered by the guidelines here.

GE-12 — Avoid Using Indexed Attributes

Index support for attributes should only be added if it is really needed for performance reasons. When lists attributes have index support, the index should run from 0 up to size − 1. If this is not the case, a dictionary attribute should be used instead of a list.

GE-13 — Write Deterministic Models

A simulation model should behave exactly the same way when it is run with identical external stimuli (e.g., using a recorder, or only scripted input). Never use host functions that do not behave identically between runs in your model, such as gettimeofday() or rand().

This is essential for reverse execution to work correctly, and greatly helps in pinpointing bugs, as those are guaranteed to be repeatable in a deterministic simulation.

For more information refer to the section about general usability in "Building Well-Behaved Models" in the Model Builder User's Guide.

GE-14 — Check Spelling

All user visible strings should be checked for correct spelling and grammar.

GE-15— Do not Assert on User Errors

Errors that can be triggered by a user, for example by running target software that does not follow the specification should not cause Simics to assert. For errors signalling use log messages of the "info", "spec-violation" or "error" type depending on severity. Assert should only be used to protect against bugs in the simulator code.

GE-16 — Do Not Use Deprecated Features

Avoid using features listed as deprecated in the Simics Migration Guide. Check the prefs object for settings (attributes) whose names start with legacy_. Make sure your system works with all such settings turned off. Also run Simics with the -wdeprecated command line argument and make sure that there are no run-time warnings generated during simulation.

GE-17 — Avoid Saving Attributes as Binary Data

Structured attribute data should not be saved in binary form, since it prevents user inspection, for example by the info and status commands, and makes it difficult to keep compatibility with old checkpoints. Binary data should only be used when saving memory images and similar.

1.2 Device Checklist

This section describes important items that, in addition to the generic checklist, should be taken into consideration when writing device models. For more in depth understanding of the importance of these items, please refer to the Model Builder User's Guide.

DE-01 — Source Code in DML

Device models should in general be written in DML. Example of an exception to this rule is code for algorithms already available, or better expressed, in some other language.

DE-02 — Reset Support

Models of devices with one or more reset inputs should properly implement reset. The Simics signal interface should be used as input with one port interface for each reset input.

DE-03 — Logging

The standard Simics log mechanism should be used to trace things happening in the device. It is important that target software access to unimplemented registers and features of the device are properly logged with the correct type.

A message is most of the time a fragment or, more rarely, one or more complete sentences. If it is a fragment, the message shall start with a lowercase letter (with the obvious exception for words and abbreviations that shall start with an uppercase letter) and have no period at the end. Sentences shall start with an uppercase letter and end with a period.

In DML, a typical log statement may read: log info, 2, 0: "increased counter: %d", value;.

Do not use exclamation marks and avoid question marks. Multiple question marks in a row shall never be used.

Do not start an "info" message with the words "error", "unimplemented" or "spec_violation", use the appropriate log-type instead.

Do not start an "error" message with the word "error", it is just a repetition. The word "error" might be appropriate inside the message but should in most circumstances be avoided. Same goes for the "critical", "spec_violation", and "unimplemented" log-types.

Do not use newlines, in particular not at the end of the message. Also do not use multiple log statements to output longer messages, include everything in one statement. It is up to the presentation layer to output a long message in a readable format.

Do not mention the name of the object or class which the message refers to, as it is implicitly given by the log statement and output in the log message prefix.

For abbreviations and other special words, write them as specified in the "Dictionary" chapter of the "Writing Documentation" manual or in the src/docs/common/simics-documentation-word-list or src/docs/internal/documentation-manual/usage.docu files. Here are some examples: IRQ, DMA, CPU, CPUs.

A message followed by a more specific message, such as: "can't open file "abc": no such file or directory" should be (as above) separated by a colon. If even more specific messages follow, these are also appended using a colon as separator.

A message which contains some extra information at the end should be written as: "read from register XYZ (value = 0x5000)"

Do not use cryptic abbreviations such as @, addr, idx, reg, len. Instead use: at, address, index, register, length

Do not use variable names (if they aren't complete words) in log messages with log levels 1-3. If values are output, it should be possible to understand what the value represents without reading the source code. I.e. it should be possible to understand the log message without reading the source code.

Do not use assert statements on conditions that can be triggered by users, see GE-15.

Use pre-defined DML templates for different implementations. Log level is automatically handled in some of these templates. For example, reserved, unimplemented and read_only. Full list and descriptions about these templates can be found in the Model Builder DML 1.2 reference manual.

Spec-violation and unimplemented messages are typically logged on level 1. Sometimes they are first logged at log level 1 then log level 3 for spam reduction when unimplemented registers or features are always accessed. log level 3 should be avoided for spec-violation.

For more information refer to "Logging" in the Model Builder User's Guide.

DE-04 — Avoid SIM_ Functions when Modeling Behavior

Code that models the behavior of a device should avoid SIM_ and internal VT_ functions as far as possible. Such functions are mainly intended for simulator specifics such as configuration and logging, but not to model the actual device. Simics interfaces should be used instead to communicate with other objects that a device is connected to. The most common exceptions are SIM_ functions used to access fields in the generic_transaction_t, timing API functions and event API functions for devices not written in DML.

DE-05 — Avoid Attribute Access when Modeling Behavior

Simics attributes are intended for configuration and diagnostic access to a device. Communication between devices should use Simics interfaces and not rely on reading or writing attributes.

For more information see the section about Simics interfaces in "Overview" in the Model Builder User's Guide. The standard interfaces are documented in the Reference Manuals included in each Simics package.

DE-06 — Handle Persistent Storage

Some kinds of storage are persistent and survive power cycling, for example NVRAMs, certain device registers, and disk images. Models of such entities should be handled as persistent in Simics, allowing the save-persistent-state and load-persistent-state commands to work properly for simulating power off followed by power on. To check which images are marked as persistent, use the list-persistent-images command.

The image interface on objects of the Simics image class provides a way to mark an image object as holding persistent data. Custom disk and storage models must call this interface on their associated image objects, if they are persistent.

Device register and device state saved in attributes are marked as persistent by using the Sim_Attr_Persistent flag on the attribute when it is registered with Simics.

For NVRAMs the persistent-ram class can be used.

For more information see the section about saving and restoring persistent data in "Configuration and Checkpointing" in the Simics User's Guide

DE-07 — Use DML Device Class Library Code

Device models should share common code if possible, such as the generic PCI, I2C or MII device code, see the Model Builder User's Guide.

DE-08 — Document Limitations

Parts and features of a device that is not modeled should be described in documentation. For devices written in DML, use the limitations parameter. For devices not written in DML add the information to the class documentation. Use free form complete sentences or bullet lists:

<ul>
  <li>The X device does not implement Y hashing.</li>
  <li>The Z feature does not work with the Windows 7 driver.</li>
  <li>...</li>
</ul>

See the DML Reference Manual for more information.

Unimplemented registers, or registers with limited functionality, should use the standard Simics log mechanism with the Sim_Log_Unimplemented type to log any accesses.

DE-09 — Performance

Devices should be written with performance in mind. In general this simply means avoiding expensive operations and using events instead of polling. The Model Builder User's Guide includes a discussion on performance for device models.

DE-10 — Internal Device to Device Register Access

Device objects should use the int_register interface if it has to access registers in another object directly. The typical case is for objects that represent tightly coupled devices. In other situations the devices can use the architecturally specified way of communicating, for example by doing memory mapped accesses or sending bus transactions if a bus interface exists.

The int_register interface is documented in the Simics Reference Manual

DE-11 — Handle inquiry accesses

Device objects should handle inquiry accesses without performing any side effects beyond changing the state of the register itself. This is done automatically for registers which does not override the read_access and write_access methods, but if you override these methods or implement the access at the bank level you have to implement it yourself.

DE-12 — Reboot Support

A machine model should support system reboot. This means software reboot and commands to trigger any reset buttons. Reset signals are typically distributed between simulated devices using the signal interface unless reset is already part of some technology specific interface such as the pci_device interface.

DE-13 — Optional attributes should be optional

Any optional attribute should be truly optional. It should make sense and be possible to instantiate the object without setting any optional attributes. Accesses to the device should not cause simulation errors if any optional attributes are not set, for example dereferencing a NIL pointer for an optional object attribute.

DE-14 — Support Multiple Instantiation

It should always be possible to create multiple instances of a device model, for example to have several similar systems networked together.

DE-15 — Use Standard Memory Classes When Possible

When modeling address spaces, reusing the Simics memory-space or port-space classes is almost always possible. Similarly, the ram, rom and persistent-ram classes should be used to model RAM and ROM. This is true also for on-chip memory, unless the memory is very small, perhaps a few kilobytes or less. The storage for larger memory areas should be implemented using the standard image class, that provides delta checkpointing and efficient run-time memory handling.

DE-16 — Only Use the Device API

When writing device models only the Device API should be used. API function, and interfaces, from the Simulator API should not be used. The Device API is documented in the Model Builder User's Guide. See also DE-04 about avoiding SIM_ functions.

DE-17 — Support Deletion

It should be possible to delete object of the device class. All allocated memory should be freed, events should be cancelled, etc.

1.2.1 Ethernet Devices

ET-01 — Separate Transceiver (PHY) Model

Ethernet devices where the transceiver is visible to the software, for example exposed by the MII or similar interface, should have the transceiver modeled as a separate object in Simics. This allows for reuse of transceivers and a number of such models already exist, including a generic MII transceiver.

For more information see the section on Ethernet transceiver in "Modeling Ethernet Devices" in the Model Builder User's Guide.

ET-02 — Bandwidth Limitation

Ethernet devices should use the standard bandwidth limitation support provided by the ieee_802_3_phy_v3 interface. This interface is used when communicating with PHY devices.

ET-03 — Configurable MAC Address

Ethernet devices should provide a way to set the Ethernet MAC address when setting up the system. Typically by providing a mac_address attribute.

1.2.2 Interrupt Devices

IN-01 — Edge vs. Level Triggered Interrupts

Interrupt inputs are either edge or level triggered. The device should correctly model the kind used for each input.

IN-02 — Use signal Interface Ports for Input

Each interrupt input should be implemented using a port interface of the signal type.

1.2.3 PCI Devices

PC-01 — The print-pci-config-regs Command

The standard <pci-device>.print-pci-config-regs command should be supported by all PCI devices.

PC-02 — Expansion ROM

Components for PCI devices that may be configured with an on-board ROM image should have a bios attribute that is the image file for the expansion ROM.

1.2.4 Serial Devices

SE-01 — Intentionally left out.

SE-02 — Support Baud Rate but Allow Override

Serial devices should obey the baud rate setting since software may not work with an unrealistic timing behavior. Still, for simulator performance reasons, it is often of interest to optionally run faster in virtual time than the actual device would.

1.3 Processor Model Checklist

This section describes important items that, in addition to the generic checklist, should be taken into consideration when writing processor models. For more information about processor models, see the Processor Model Integration Guide.

PR-01 — Trigger Standard Haps

Processor models should trigger standard haps.

PR-02 — Support Common Processor Commands

Processor should implemented the same set of commands with the same semantics as pre-existing processor models.

PR-03 — Support Standard Interfaces

Interfaces listed in the Processor Model Integration Guide should be supported by a processor model.

PR-04 — Simics Style Register Names

To support remote GDB and allow portable Simics scripts, register names used in the int register interface must be Simics style names.

1.4 Component Checklist

This section describes important items that, in addition to the generic checklist, should be taken into consideration when writing components. For more in depth understanding of the importance of these items, please refer to the Model Builder User's Guide.

CO-01 — Checkpointing of Connection Information

Information that a component receives from another component in a connect method call may have to be checkpointed in case that information has to be used again. This is sometimes the case with hot-plug connections.

CO-02 — Naming of Components and Objects

Until there are proper guidelines for component, connector, and object names, check existing objects in Simics for examples. Some common names are:

• eth_adapter — basename for Ethernet PCI cards.
• ethernet — ethernet-link connector name for components with a single ethernet-link connector.

CO-03 — Use Standard Connector Types When Possible

The standard component connector types are listed in the Model Builder User's Guide. By using the standard types, the component can more easily be reused in other systems.

CO-04 — Correct Component Abstraction

Components should represent real separate hardware entities with standard hardware interfaces, such as PCI or Ethernet. It should only be possible to build valid systems using components and their connectors. More low-level kinds of connections should be done between configuration objects within the components.

CO-05 — Implement Standard Attributes and Names

Components should implement standard attributes, and in some cases have well defined sub-strings in their names, that are used by the GUI to extract system information. This applies to top-level components, components with memory, Ethernet connectors or disks on them. A complete list is included in the section about component references in "Components" in the Model Builder User's Guide. Some commonly used component attribute names are:

• cpu_frequency
• num_cpus
• num_cores
• memory_megs — for components with RAM.
• rtc_time — format: "YYYY-MM-DD HH:MM:SS Z".
• mac_address — single Ethernet device.
• mac_address0, mac_address1, ... — multiple Ethernet devices.
• size — for disk components.

CO-06 — Slot Names

The slot names in the component should be chosen with care since there can be name conflicts with attributes and commands for the component. The priority order for conflicting names are defined in the Model Builder User's Guide.

CO-07 — Intentionally left out.

CO-08 — Component Error Handling

It should always be possible to create a non-instantiated component as long as the provided arguments are valid. If the component requires any external file, for example, then it should check for its existence and possibly signal any error in the pre_instantiate method. The connect_<connection>(), add_objects() and post_instantiate() methods should never trigger any errors.

CO-09 — Optional Attributes

Component attributes should in general be made optional with well chosen default values instead of being required.

CO-10 — On-board Software

Boot software such as BIOS, OBP and other firmware that is resident on the hardware should be setup as part of the component. If changing the firmware makes sense, then there should be a configuration attribute to set the image file to use.

1.5 System Checklist

This section describes important items that, in addition to the generic checklist, should be taken into consideration when assembling a larger system. See also the "Target Script Checklist".

SY-01 — Reuse of Existing Models

Since developing a new device model may involve a lot of work, it is a good idea to make sure that no previous model of the device exists. Also similar device models can be useful if code can be shared between them.

SY-02 — Build SimicsFS for Linux Target

If Linux is supported for the target system, then a SimicsFS kernel module should be built and installed on the Linux image.

SY-03 — Moved to ST-01.

SY-04 — Moved to ST-02.

SY-05 — Moved to ST-06.

SY-06 — Moved to ST-08.

SY-07 — Moved to ST-17.

SY-08 — Moved to ST-18.

SY-09 — Moved to ST-20.

SY-10 — Only Create Device Objects from Components

All objects implementing the functionality of a target system should be created by components. There should not be any model objects created automatically when loading modules. Also target scripts should only create component objects and no other model objects.

1.6 Target Script Checklist

This section describes important items that, in addition to previous checklists, should be taken into consideration when writing the target scripts for a virtual platforms.

ST-01 — Follow Machine Script Guidelines

The .simics and .include scripts for a machine should follow the guidelines in the section about ready-to-run configurations in "Configuration and Checkpointing" in the Simics User's Guide. For example the setup of the simulated hardware should be separate from the software configuration. See also "System Configurations" in the Model Builder User's Guide.

ST-02 — Possible to Start from All .simics Scripts

It should be possible to start any .simics file from scratch. Scripts that require other files to have run first, or require CLI variables to be set, should have the .include suffix.

ST-03 — Location Independence

It should be possible to launch a target script in Simics no matter what the current directory of Simics is. The %simics% path marker can be used to reference other scripts in a Simics project, the same, or other packages.

ST-04 — Do not Advance the Simulation

A target script should not run the simulation, but start all processors at step and cycle 0. Script branches can be used to automate setup needed while the system is booting although adding support for it in a system component is recommended, to make sure checkpoints can be taken early.

ST-05 — Supply System Information for GUI Views

The target viewer should report correct information about the system in the built-in Winsome GUI.

ST-06 — Proper Command Error Handling

Errors that are detected in a script should be reported using the interrupt-script command. Using the quit command is not advisable in scripts since it will close the interactive session for a user. It is not needed either since Simics will exit on errors anyway when run in batch mode.

ST-07 — Check for External Files

If the script uses files which are not included in the same package, it should verify their presence before referencing them and, if needed, interrupt the script. The lookup-file command searches for a file and, if not found, it emits an error message and interrupts the script. Otherwise, use the two commands file-exists and interrupt-script.

ST-08 — Naming of the Top Component

A machine script (<architecture>-system.include) should create the top level component with the name configured by the $machine_name variable. If this variable is not set, it should default to the system name. The name of the created component should then be saved in $system. It will typically be the same as $machine_name unless there is a name collision. See also "System Configurations" in the Model Builder User's Guide.

For example:

(in decl) param machine_name : string = "board"
$system = (create-chassis-qsp-x86 name = $machine_name)

As a result, multiple machines can be instantiated in the following way:

$machine_name = machine1
run-command-file "%simics%/targets/qsp-x86/firststeps.simics"
$machine_name = machine2
run-command-file "%simics%/targets/qsp-x86/firststeps.simics"

The old component prefix support should not be used anymore as it will be removed in the future.

ST-09 — Use Common Script to Create Ethernet Network

If applicable to the system being modeled, use the targets/common/add-eth-link.include script to create a simulated Ethernet network and to configure the service-node.

ST-10 — Include an Ethernet Network

Target scripts should create an Ethernet network by default and connect the primary Ethernet adapter of the system to it.

ST-11 — No Connection to the Real Network

Target scripts should not connect the virtual Ethernet network to the real network by default.

ST-12 — Allow Parameterization

Target scripts should allow users to modify its behavior by setting parameters using CLI variables. All parameters should be optional and have good default values. For boolean variables, TRUE/FALSE should be used. See also ST-13.

ST-13 — Use Standard Parameter Variables

The following standard variables should be implemented if applicable for the target system:

$memory_gigs or $memory_megs

Amount of system memory in GiB or MiB.

$freq_mhz

Frequency of the main processor cores in MHz.

$num_cpus

The number or processors in the target system; compare with $cpu_cores.

$cpu_cores

The number of cores on processor components and SoCs with multiple cores. Use this parameter when $num_cpus would be misleading.

$cpu_class

The name of the processor class for systems that support more than one kind of processor.

$host_name

The name of the target system. Used as name of the top component. (For legacy reasons this variable has a confusing name. It should really be called $target_name.)

$mac_address

The MAC (Ethernet) address of the primary network controller.

$disk_image

The file name of an image to use for the primary disk.

$disk_size

The size of the file in $disk_image, if it cannot be automatically determined from the file.

$rtc_time

The starting time of the RTC (Real Time Clock) in the "YYYY-MM-DD HH:MM:SS UTC" format.

$ip_address

The primary IP address of the system. (If it can be set.)

$connect_real_network

Connect the virtual Ethernet network to the real network using port-forwarding/NAT.

The following variables are automatically supported if the targets/common/add-eth-link.include script is used to create a virtual Ethernet network. Scripts creating their own Ethernet network without using add-eth-link.include should support some subset of these variables.

$create_network

Boolean variable specifying if a simulated Ethernet network link should be created together with the system.

$eth_link

The name of an existing Ethernet link object.

$service_node

The name of an existing service node object.

$service_node_ip_address

The IP address of the $service_node object on the $eth_link link.

$dhcp_pool_ip

The first address in the pool of IP addresses used for DHCP in the $service_node.

$dhcp_pool_size

The size of the IP address pool used for DHCP in the $service_node. Set to 0 to disable DHCP.

$network_goal_latency

The requested network latency of the $eth_link link.

$eth_link_gid

The global identifier for the $eth_link link, used in distributed simulation.

ST-14 — Do not Leak CLI Variables

CLI variables are global by default. Scripts should try to make variables local if possible, or unset them after use, to avoid conflicts with other scripts. See also ST-15.

ST-15 — Support Multi-Machine Setup

It should be possible to create multiple target machines by setting the $host_name variable and then running the target start script (with the -local flag) without getting any conflicts.

ST-16 — Configure OS Awareness

All top-level components should have software slot with an os_awareness component in it. This is typically created in the <architecture>-system.include script:

new-os-awareness $system.software

If the OS awareness framework in Simics supports the operating system that is configured on the machine, then a parameter file should be created that matches the operating system and that is loaded in the software setup script (i.e. the <architecture>-<software>-setup.include file), typically using:

$system.software.load-parameters <architecture>-<software>.params

For more details refer to the section "OS Awareness Details" in the Analyzer User's Guide.

ST-17 — Do Not Reference Objects by Name

Simics scripts should not expect that objects created as part of components will get certain names. When creating a component, the returned component name can be saved in a variable for later use.

$console = (new-text-console-comp)
$console.con->title = "new title"

When referencing component and objects created by another machine script, the $system variable (ST-08) will provide a reference to the top-level component created by that script.

ST-18 — Set Up a Valid Cell Partitioning

Check that the cell partitioning set up by the script is correct by using check-cell-partitioning, both after the script has run and for checkpoints taken of the system. For more information see the section on simulation cells in the "Multithreading" section of the API Reference Manual.

ST-19 — Keep default global simulation settings

Scripts should not modify default simulation settings. Examples of settings that should not be done in scripts: changing log-level (log-level 2), explicitly enabling reverse execution (enable-reverse-execution).

ST-20 — Keep Target Scripts Simple

While following the guidelines in this section, also try to keep the target scripts as simple as possible. Avoid switching between Python and CLI for example. If Python code is needed in a target script, then some component is probably not powerful enough or some new CLI command is needed.