5 Migrating from Simics 4.8

5.1 Introduction

This chapter describes how to port device models, components, and scripts to Simics 5 from Simics 4.8. For information about what is new in Simics 5, read the product release notes.

5.2 Running 4.8 Modules and Scripts in 5

The first step when migrating from an older version of Simics is to get all code and scripts to run using the legacy API support. You should follow the checklist from chapter 3, but you may skip the last two steps.

If there are warnings about deprecated functionality, start Simics with the -no-wdeprecated command line flag or set the sim→deprecation_level attribute to 0.

The following list shows the changes between 4.8 and 5 that may affect the migration process.

• When setting the SIMICS_API version to 5 or newer, the module makefiles will no longer add directories specified in neither VPATH nor EXTRA_VPATH to the include search path for C, C++ or DMLC. Both EXTRA_MODULE_VPATH and EXTRA_VPATH_IN_SIMICS work as before, and can be used instead. Otherwise use MODULE_CFLAGS, or similar, to add the paths to your include search paths with -I.
• With SIMICS_API set to 5 or newer, the commands.py and gcommands.py files are no longer recognized as being run upon module or simics initialization. These should be replaced with module_load.py and simics_start.py. Note that these need to be listed explicitly in the PYTHON_FILES variable. This is further discussed in the Using Python in a Simics module section of Model Builder User's Guide.

  In order to help migration, the build system will detect any lingering files named commands.py or gcommands.py, and report these as build errors.

• With SIMICS_API set to 5 or newer, the support for .py files listed in the SRC_FILES variable found in a Simics module Makefile was deprecated. Instead, the PYTHON_FILES variable should be used to list .py files which are present in a Simics module. Current support for having Python files in Simics modules is further discussed in the Using Python in a Simics module section of Model Builder User's Guide. Generally, in order to migrate a Simics module the following should be done:
  • Move all .py files from SRC_FILES to the PYTHON_FILES variable in the module Makefile.
  • Remove all "# MODULE: xyz-comp" comments from .py files with no replacement.
    Note: The comments like "# MODULE: xyz-comp" were previously used to create a separate Simics module xyz-comp from a single Python file located in a Simics module. Now all .py files from a Simics module are considered to be parts of that Simics module and can be accessed as Python modules with the statement import simmod.xxx.yyy where the xxx part is the Simics module name (hyphens replaced with underscores) and the yyy part corresponds to a particular Python file from that Simics module.
  • Remove all "# CLASS: xyz" and "# COMPONENT: xyz" comments from .py files replacing them with generally used "MODULE_CLASSES = xyz" and "MODULE_COMPONENTS = xyz" items in the module Makefile.
  • Generally, the module_load.py file is required for a Simics module containing Python code. This file serves as an entry point executed whenever the Simics module containing it is loaded. Once created, the module_load.py file should be added to the PYTHON_FILES Makefile variable. To have any Python code executed on module load (e.g., the code registering Simics classes or components and located in the yyy.py file), this code could be imported in the module_load.py file with the statement "from . import yyy".
  • Python files containing "# MODULE: xyz-comp" lines can no longer be imported with import mod_xyz_comp. Use import simmod.xxx.yyy (where the imported file is yyy.py in the module xxx) instead.

    An import of mod_xyz_comp implicitly causes the xyz-comp Simics module to be loaded, while import simmod.xxx.yyy does not. If the import of yyy.py causes a Simics class to be registered, Simics will then attribute this class to the currently loading module instead of xxx, which causes warning messages in runtime.

    There are two ways to solve this problem:

    • Load the module explicitly, using simics.SIM_load_module("xxx"), before importing simmod.xxx.yyy. This is a quick solution, which preserves existing behaviour. However, it may seem unnatural to have to load a module just to access some shared Python code.
    • Restructure the yyy.py file so it can be imported without side-effects. This is typically done by moving any registration calls away from global scope into functions, and letting xxx/module_load.py call those functions.

      Note that components (and other classes based on pyobj) are normally implicitly registered when the Python file is imported. In order to make an import side-effect free, this registration can be suppressed by setting _do_not_init = object() in all such class definitions in yyy.py. The classes can then be registered by calling their register methods from module_load.py.

      In future versions of Simics, pyobj-based classes will not be automatically registered, and an explicit register call will be required for all classes.

    Note: Imports on the form import mod_xyz_comp should not be confused with imports on the form import xyz_comp_[g]commands. The latter is a completely separate import mechanism, which is also deprecated but handled differently, as described in a separate note below.
  • Please note the build procedure now will generate different files. This may affect users who (re)package compiled Simics modules.

    Typically, host/lib/python/mod_xyz_comp.pyc has been moved to host/lib/python/simmod/xyz_comp/yyy.pyc. Also $(HOST)/lib/module-name.so, which may not have been generated previously, should be added to packaging. .pymod files are not generated any more.

  • Python files which do not adhere to Python module naming conventions (e.g., contain hyphens in the file name) are supported though discouraged. Such files have to be renamed (e.g., by replacing hyphens with underscores) in order to be imported from Python using the plain import statement.
• The special Python imports import mod_XYZ_commands and import mod_XYZ_gcommands have been deprecated. The corresponding module in simmod (typically simmod.XYZ.module_load and simmod.XYZ.simics_start, respectively) should be used instead.
• The device initialization functions generated by the DMLC compiler are now called automatically when a module is loaded. Previously, one had to manually call them from the init_local function. Thus, any existing calls to DMLC initialization functions (typically named initialize_classname) must be removed from init_local, in order to prevent the same class from being registered twice. For the same reason, any invocations of scripts/build/gen_init_local.py must be removed. For the same reason, the -m switch to DMLC is redundant and can no longer be used. This typically means that the line DMLC_FLAGS = -m in module makefiles should be removed.

  This change only applies when SIMICS_API is 5 or newer; the previous behaviour is preserved with lower values of SIMICS_API.

• The order in which init and hard_reset are called during object instantiation has been reversed; hard_reset is now called after init.

  The change may cause code to break; in particular, if init initializes a register value, then the hard_reset call will immediately restore the value to its hard_reset_value. If the intent of such code is to provide different values on instantiation and manual hard reset, then a better approach is to override the register's hard_reset method, and use the condition SIM_object_is_configured($dev.obj) to deduce whether the hard reset was manual.

• All objects of the Ram or Rom class must have an associated clock/CPU object, i.e., the queue attribute must be set. It is also possible to set the queue attribute of the corresponding Image object instead.

5.3 Updating 4.8 Modules and Scripts to 5

Enabling old code and scripts to work with Simics 5 is the first step in the migration and all that is needed to start using the new Simics version. But it is also a good idea to start removing the use of features and API functions that have been deprecated in 4.8 and 5.

1. Remove the -no-wdeprecated flag when running Simics, or set the sim→deprecation_level attribute to 1. Whenever deprecation warnings are encountered, use the table in chapter 8 to find out what has been deprecated in Simics 5 and what the recommended replacement is.
2. Change the API in both C/C++ and Python modules to 5. Use the table in chapter 8 to find out what has been deprecated in Simics 5 and what the recommended replacement is.

5.4 Updating 4.8 devices to 5

Usage of the translate interface has changed compared to Simics 4.8. In particular, implementors of translate will need to handle large inquiry-type accesses. See the documentation for the translate interface for details.

Several DML 1.2 files have been removed from the standard library. Most of them are redundant and do nothing else than import another file. Devices need to update import statements accordingly:

5.5 Updating 4.8 components to 5

In Simics 5, component implementation has changed. For details about the new implementation, please refer to the Implementing Components section in the Model Builder User's Guide.