32 Examples

32.1 Creating a Custom Project Package

For purposes of this example we assume that we are using the QSP-x86 platform, that the customer has extended it with a device named secondstep, and that the new platform is called thirdstep. Finally, we assume that the goal is to distribute a single .tar.gz file.

About installing Simics Base and QSP-x86, see Simics Installation Guide. In this example we will do the installation to folder ./install.

32.1.1 Create a Development Project and Build a Sample Device

Set up a Simics project as well as create and compile a sample device.

:~/example$ ./install/simics-7.0.0/bin/project-setup project
Project created successfully
:~/example$ cd project/
:~/example/project$ ./bin/project-setup --device secondstep
Skeleton for module 'secondstep' successfully created.
:~/example/project$ make
=== Environment Check ===
'/home/joe/example/project' is up-to date
gcc version 10
=== Building module "secondstep" ===
        module_id.c
DEP     module_id.d
DML-DEP secondstep.dmldep
DMLC    secondstep-dml.c
DEP     secondstep-dml.d
DMLC    secondstep-dml.c
PYC     module_load.py
CC      secondstep-dml.o
CC      module_id.o
CCLD    secondstep.so
:~/example/project$

32.1.2 Create the Target System Scripts

Create a wrapper target in the project and edit it.

:~/example/project$ bin/project-setup --target thirdstep/thirdstep
:~/example/project$

Update the parameter block as shown.

%YAML 1.2
---
description: Thirdstep - Linux
params:
  qsp:
    import: "%simics%/targets/qsp-x86/clear-linux.target.yml"
    defaults:
      network:
        ip_address: "10.10.0.4"
code-type: simics
cmd: run-script "%simics%/targets/qsp-x86/clear-linux.target.yml" namespace = qsp
...

32.1.3 Convert the Project to a Package

Create a Simics package based on the project.

:~/example/project$ ./bin/project-packager
Descriptive Name [Customer Package] ThirdStep Package with Second Step Device
Package Name (no spaces) [Customer-Package] thirdstep
Package Number [200000]
Version [7.0.0]
Host Type (linux64/win64) [linux64]
Build ID Namespace []
Build ID [0]
Edit Files? (y/n) [n]
:~/example/project$

A file simics-pkg-200000-7.0.0-linux64.ispm has been created. The package include the sample device based on secondstep, the target script and some other files.

32.1.4 Test Installation of the Thirdstep Package

Install the new package and associate it with Simics Base.

:~/example/project$ cd ..
:~/example$ ispm install project/simics-pkg-200000-linux64.ispm --install-dir install -y
:~/example$ cd project
:~/example/project$ ./bin/addon-manager -s ../install/simics-thirdstep-7.0.0/
:~/example/project$

32.1.5 Create a Test Project and Test the Installed Packages

Create a Simics project and install the newly created package.

:~/example$ cd ..
:~/example$ ispm install project/simics-pkg-200000-7.0.0-linux64.ispm --install-dir install -y
:~/example$ ./install/simics-7.0.0/bin/project-setup test-project
Project created successfully
:~/example$ cd test-project/
:~/example/test-project$ ./bin/addon-manager -s ../install/simics-thirdstep-7.0.0/
:~/example/test-project$ ./simics thirdstep/thirdstep --batch-mode
Simics 7 (build 7000 linux64) © 2022 Intel Corporation

Use of this software is subject to appropriate license.
Type 'copyright' for details on copyright and 'help' for on-line documentation.

:~/example/test-project$

32.2 Additional project-packager Script Parameters

The project-packager could be run with a number of additional parameters. For a complete documentation of these parameters as well as a description of the normal usage of the script, run it with the -h parameter (or using the verbatim version of the same parameter: --help):

:~/project$ ./bin/project-packager -h

Here is the description of some parameters:

The -n parameter (verbatim --dry-run) runs the script without producing and output files. This makes it possible to test what inputs the script needs without creating any real files.

The -d parameter (verbatim --debug) gives some additional debug information when running the script, for example on what directory the script is run in and what the default values and names of the results of the script are.

The -b parameter (verbatim --batch) lets the user run the script without any interactive input. The script will then be run with the same default values and names that will be printed running the script interactively.