3 Migrating to a New Simics Version

3.1 Introduction

This chapter gives a short overview of the process of updating code and scripts from any older Simics version to the most recent one. The following chapters, on the other hand, contain version specific descriptions.

It is assumed that the migration is from Simics 5 or Simics 4.8, the two supported Simics versions at the time of the Simics 6 release.

3.2 Step-by-step Guide

1. First make sure that any C/C++, DML and Python modules compile with the most recent API in the version of Simics that you are migrating from. In Simics 5, set SIMICS_API to 5 in the module Makefile and correspondingly for Simics 4.8. If the code does not compile cleanly, consult the Migration Guide for that Simics version. When moving to Simics 5, you should always start with modules that are updated to use the most recent API in the Simics version you migrate from.
2. Update Python modules to the most recent API in the version of Simics that you are migrating from. This can be done by importing the Simics API using a specified version:

   import simics_5_api as simics

   This will simplify the migration of code to a newer version of Simics later.

3. Run all scripts in Simics with the -wdeprecated command line flag to the Simics binary. This will catch uses of some deprecated features that can only be detected in run time. An alternative is to set the sim→deprecation_level attribute to 2.
4. When all modules and scripts run fine using the most recent API in the old version of Simics, it is time to migrate to Simics 6. Update the existing project to point to a Simics 6 installation or, even better, create a new project for Simics 6 development, since the old project may be needed for comparison purposes.
5. Build all modules using the API version corresponding to the Simics version that you are migrating from. This should simply be a recompilation, since the old API version is already selected in the Makefiles and Python source files.
6. In a few cases there are API changes that the pre-processor cannot hide. They may cause the build to fail even when an old API is selected. Use the table in chapter 8 and the version specific migration chapters 4 and 5 to figure out what changes are necessary.
7. Run all your tests and scripts to ensure that everything works in Simics 6 when using the old API. Make sure to pass -no-wdeprecated to suppress deprecation warnings in the process. Once everything works, you can start using the new version of Simics for actual work. The following steps are optional at this point, but still strongly recommended.
8. Change the API used for modules and scripts to the most recent version, one module or script at a time. Update the code according to the following chapters.
9. Turn off the -no-wdeprecated flag when running tests and scripts. Update any code that yields deprecation warnings according to the following chapters.