3 Build Environment

The functionality of Simics can be extended by user-written modules. Modules can, among other things, contain new device models, new commands, new components, and new extension to Simics. All of need to be compiled or built to be used in simulation and the environment in which that is done is referred to as the build environment.

This chapter will describe how to configure, maintain and use that environment to build new modules for use with Simics. A project is used to contain and build user-written modules, this permits many users to share a system-wide (read-only) Simics installation. The Model Builder product contains the necessary files and tools to develop your own modules.

3.1 Notes for Windows Users

To develop new modules for Simics on the Windows platform, you need the MinGW compiler suite and make tools installed. See the Simics Installation Guide for more information.

If you do not wish to use the GCC compiler, you can use the Microsoft Visual C++ compiler to compile C++ modules (n.b., the Visual C++ compiler is not supported for C modules). See section 3.5.2 for more information.

The commands below should be invoked in a cmd.exe command prompt window, and the path names should be entered with backslashes as directory separators, and bin\make.bat (a shortcut to the MinGW installation) should be used when instructed to run make.

3.2 Notes for Linux Users

On Linux, the project makefiles require GNU make (a.k.a. gmake), which is available from ftp.gnu.org/gnu/make. In the following text, when you are asked to run gmake, this refers to running the GNU make binary, which may be called gmake or make, depending on your installation.

Simics supplies own version of libraries, for example libstdc++.so.6, under [simics-base]/[host]/sys/lib/ directory. They are actually for machines with older libraries or none at all. If user has a more recent copy than one supplied with Simics, error like "GLIBCXX... not found" would happen when try to run a binary or load a module compiled from this newer library from within Simics. If this happens the suggested workaround is to remove the older library supplied with Simics.

3.3 Setting up a Project

A project is a directory which contains all necessary user-specific files needed to run Simics and develop modules. Setting up a project is done with the File → Create Project… or using the project-setup script, like this:

where [simics] is the location of the Simics-installation.

The script will create a project directory with the following contents:

When the project has been created, you may type make (or possibly gmake) to build all the modules, or ./simics-gui to start Simics.

In order to rebuild all modules, type make clean, followed by make. In order to rebuild just a single module, type make clean-modulename, for example:

 project$ make # builds all modules
 project$ make clean-mymodule # removes all objectfiles for "mymodule"
 project$ make mymodule # builds "mymodule"

The clean targets only remove object files and similar intermediates for the module not needed when running. To remove the actual module files as well, use make clobber or make clobber-modulename.

3.3.1 Project Setup Script Invocation

The project setup script is used to create and upgrade projects. It can also create module skeletons to start with when writing new devices.

See Simics Reference Manual for the full documentation of the script.

3.3.2 Updating Projects

To upgrade your project to a new Simics version, run the script again with no arguments. It is also possible to update the project from the Simics GUI. The project will then be updated to match the version of the running Simics.

It will do the necessary updates in the project, but leave the user-modifiable files intact. (Modified files that need to be overwritten are saved in backup versions with the extension ".~N~" (Linux) or "~N~.backup" (Windows), where N is the first free number.)

If you upgrade to Simics with a different major version number, the compiled modules will not be compatible and you need to do a make clobber to force a rebuild when you issue make.

3.4 Adding Modules to a Project

The modules subdirectory contains source code for modules, one module per directory entry.

3.4.1 Creating a New DML Module

To add a DML module to a project, specify the --device option.

This will create some skeleton code under the modules/ directory.

After adding a module, you can build it using the top-level makefile:

project$ gmake

To emphasize that the makefile require GNU Make, it is called GNUmakefile. The sub-makefiles in the module directories are named Makefile.

When running make, command lines will not be printed by default. To see the commands, pass V=1 to make:

project$ gmake V=1

3.4.2 Creating a New C/C++ Module

An example module written in C can be added in the same way as DML modules, but using the --c-device option. Similarly, a C++ module can be created using --c++-device.

3.4.3 Adding an Existing Module

The top-level makefile will automatically attempt to build all modules under the modules/ directory. If you have located a module somewhere else, you must create a symlink or junction to the module from there:

You may need to adapt the Makefile for the project-based build environment. Use a generated skeleton Makefile as a template for your rewrite.

A module to which the source is distributed with Simics, can be copied into the project by using --copy-module.

3.5 Advanced Tweaks

3.5.1 Compiling Modules in Debug Mode

The project makefiles are configured to compile optimized modules by default. To turn off optimization and turn on debugging, set the following line in config-user.mk:

D=1

Set D=0 or remove the line entirely to use optimization again.

The D flag can also be passed on the command line:

project$ gmake D=1

3.5.2 Platform Specific Notes

The project setup script has a default set of make-variables (CC, CFLAGS, BLD_CFLAGS, etc.), which are set up in the compiler.mk and [simics]/config/project/config.mk files. The compiler.mk may be edited by the user. Additional options can be specified in config-user.mk.

The makefile with the actual build rules for all modules is [simics]/config/project/module.mk. This file is included at the end of each module Makefile. To override rules or variables in this module.mk, add a module-user.mk file in the project, similar to the config-user.mk file described above.

The default set of variables assumes that you will be using GCC. If you want to use a different compiler, you need to change the CC variable in compiler.mk. The flags for the compiler are set up in [simics]/config/project/config.mk.

On Windows host, the Microsoft Visual C++ compiler is supported for compiling C++ modules. To use it, you have to run all project setup and build commands from a Visual Studio command prompt, which can be started from the Start menu.

The exact names of the menu items varies with the version of Microsoft Visual C++ you have installed. For Visual C++ 2008 Express Edition, it defaults to Start menu → Microsoft Visual C++ 2008 Express Edition → Visual Studio Tools → Visual Studio 2008 Command Prompt.

Once you have started the Visual Studio command prompt, set both of the CC and CXX environment variables to cl. This should allow you to run GNU make as usual.

If your compiler is not supported by config.mk, please report to Simics Support.

3.5.3 Module Makefiles

In order to make the build environment in Simics recognize a module as a build target, there must be a makefile called Makefile in its source directory.

A module makefile must set up a number of make variables and then include the generic makefile for Simics modules. The following is an example of a module's Makefile, for a module written in C:

MODULE_CLASSES=FAS366U

SRC_FILES=esp.c

MODULE_CFLAGS=-DFAS

SIMICS_API = 5

include $(MODULE_MAKEFILE)

A complete list of the available variables to set is provided below:

DMLC_FLAGS

(optional) Module-specific parameters for the DML dependency generator and compiler

EXTRA_MODULE_VPATH

(optional) space- or colon-separated list of module names (optionally followed by a subdirectory: modulename/some/path). The source code directory of this module (or the corresponding subdirectory) will automatically be added to make's VPATH. The directories will also be added to the include search path for DML and C modules (using the -I options to the compilers).

The current project as well as any installed Simics packages will be searched for the module source code. Note that only the first matching source code directory found will be used, allowing the project to override the version of an installed package.

EXTRA_OBJ_FILES

(optional) Additional object files to link into the module. The module build will be dependent on these files, so additional rules can be provided in the module's Makefile to build these files before linking them.

EXTRA_VPATH

(optional) Directories to add to VPATH when building.

IFACE_FILES

Header files to compile for an interface module. If IFACE_FILES contains file-name.h, in a Simics module named module-name, then the Python module simmod.module_name.file_name will be created, containing the Python bindings for all interfaces and types defined in file-name.h. The filenames in IFACE_FILES must not include any directory components; if any files are to be found in another directory, then that directory must be included in VPATH so the file is found correctly; e.g., by setting the EXTRA_MODULE_VPATH variable.

See also section Restrictions in Defining New Interface Types in Model Builder User's Guide for restrictions and usage of Python bindings.

MODULE_CFLAGS

(optional) Parameters for the C and C++ preprocessor and compiler

MODULE_CLASSES

Space-separated list of configuration classes that this module registers. This information is used by SIM_get_class() to determine that this module should be automatically loaded when one of the listed classes is requested.

MODULE_COMPONENTS

Space-separated list of components that this module registers.

MODULE_LDFLAGS

(optional) Module-specific flags for the C and C++ linker. Any particular library linking (such as -lpthread, -lm, or -L to give paths to search for libraries) can be included here. If the module has dependencies on LD_MODULE_PATH, it is possible to specify -rpath so that the module will contain the paths that were valid at compilation time.

PYTHON_FILES

Space-separated list of Python source files to include. These Python files will be copied and potentially compiled (see COMPILE_PYC) and placed in a Python package specific to the module. If a module my-module includes the file file.py in PYTHON_FILES, then the resulting Python module will be available as simmod.my_module.file in Simics. Two filenames get special treatment if included in PYTHON_FILES:

• simics_start.py is automatically imported while Simics is launched.
• module_load.py is imported by Simics when the Simics module is loaded.

The names checkpoint_update.py and init.py are reserved for future use, and not allowed in the list of files.

MODULE_USER_VERSION

(optional) User supplied free-text string describing the module version. The version string is available in Simics even without loading the module, through the list-modules command or the SIM_get_all_modules API function.

SIMICS_API

(optional) Simics API to use when compiling the module. See the Simics Migration Guide for a description on how to compile old modules with a new Simics version. Valid API settings are listed in [simics]/[host]/include/api-versions.mk.

SRC_FILES

Source files to compile in the module. C source file names must end in .c; C++ source file names must end in .cc, .cpp, .cxx or .C (the last not allowed on Windows). DML file names must have a .dml suffix. Any .py files should be listed in the PYTHON_FILES variable. For backward compatibility, modules using Simics API 4.8 or older may still list Python files in the SRC_FILES variable.

SRC_IMAGES

(optional) Images to copy directly in the images subdirectory in $(TARGET_DIR)

SYSTEMC

If set to 'yes', provides compiler and linker flags that allow building the SystemC Library adapter and SystemC devices. See the SystemC Library Programming Guide for more information.

SYSTEMC_CORE_CFLAGS

(optional) Parameters for the C and C++ preprocessor and compiler when using user-specified SystemC source.

SYSTEMC_CORE_LDFLAGS

(optional) SystemC core specific flags for the C and C++ linker. Any particular library linking can be included here.

SYSTEMC_MODULE_CFLAGS

(optional) Parameters for the C and C++ preprocessor and compiler when compiling SystemC modules.

THREAD_SAFE

If set to yes, declare that the module is thread-safe.

USE_CC_API

It can be set to a specific version to select which version of C++ Device API to use. Current supported versions are '1' and '2'. See the C++ Device API Programming Guide for more information.

SUPPRESS_DEVICE_INFO

If set to 'yes', suppress output of the .xml device info file by the DML compiler.

COMPILERS

An optional list of compatible compilers, in order of preference. The allowed list element values are gcc and cl, for MinGW and Visual Studio respectively. On platforms other than Windows, cl is ignored.

COMPILE_PYC

If this is set to 1, then the files listed in PYTHON_FILES are compiled, not copied.

The user can also add new rules to the makefile, after the inclusion of the generic $(MODULE_MAKEFILE). This is usually not needed.

The following variables can be used in the module's makefile (i.e., [project]/modules/<module>/Makefile). They should be considered read-only, i.e., they should not be changed.

• SIMICS_PROJECT is the full path to the project directory.
• TARGET_DIR is the directory in which compiled modules are placed ([project]/[host-type]/lib).
• SRC_BASE is the full path to the project modules directory ([project]/modules).
• HOST_TYPE is the Simics host architecture, i.e., what OS/hardware Simics has been compiled for, such as win64 or linux64.
• LATEST_API_VERSION is the API version you get if 'latest' is specified in the module's makefile.
• TARGET is the name of the module being compiled. Note that SRC_BASE and TARGET gives you access to the module source code directory, so that you can refer to source code files with absolute paths when necessary, as in $(SRC_BASE)/$(TARGET)/foo.c.

3.5.4 Standard Module Host Defines in C/C++

There are a number of C/C++ pre-processor defines that are set depending on the host that the module is being compiled on. They are usually not needed, but useful in some special cases. Examples: HOST_64_BIT, HOST_BIG_ENDIAN and HOST_LITTLE_ENDIAN. There are also defines specifying the host architecture and host operating system. All these defines are set in the Simics include file global.h.

3.5.5 User Defined Module Version Strings

It is possible to set a user defined version string in loadable modules. This is done by setting the MODULE_USER_VERSION variable in the module's Makefile. The version string will be printed by the list-modules and list-failed-modules commands.

3.5.6 Module Loading Support

When Simics starts, it will read the supported architecture and word size for all modules on the Simics module path. Only modules that match the architecture and word size of the running Simics binary will be available for loading into Simics. While scanning the modules, Simics will also check what classes the module will register when it is loaded. This way modules can be loaded automatically when the classes that they define are used in a configuration.

If a module cannot be loaded into the current Simics, it will be added to the list of failed modules. This list can be displayed with list-failed-modules, that takes an optional parameter -v for more verbose output.

simics> list-failed-modules

Current module version number: 1050  Lowest version number supported: 1050

MODULE           DUP  VERSION USR_VERS  LINK
---------------------------------------------
8042                   1040
image                  1040
spitfire-mmu.so                          X

The columns after the module name (or file name in the case of a link error) indicate different kinds of errors. An X in the DUP column means that this module could not be loaded because this module has the same name as another module found in the Simics module search path, and that this one was overridden. An X in the VERSION column means that the module was created for another, non-compatible, version of Simics. LINK means that this module cannot be loaded into Simics because of unresolved symbols. Use list-failed-modules -v to see the actual error message from the run-time module loader.

3.5.7 Extra libraries

If a module requires linking against libraries that are not expected to be found on end user's systems, then these libraries can be included in a Simics package. They should be placed in host/sys/lib. For testing and development, this can also be in a Simics project, by adding the project as a package path.

On Windows, Simics will add this directory to the DLL search path for every package.

On Linux, one must also make sure that the Simics module is linked in such a way that the library is found when the module is loaded at run time, by adding this to the module Makefile:

MODULE_LDFLAGS += -Wl,-rpath,'$$ORIGIN/../sys/lib'

On all platforms, Simics will detect and warn if the same library exists in multiple packages. To avoid such problems, one can for example include a version number in the library filename.

Note that the Simics module resolution logic does not apply to these extra libraries.

If an extra library is dependent on the Simics API, it must link with the Simics library in order to make symbol lookup work correctly. This can be done by building the library as part of the Simics module that uses it, and adding these linker flags:

-L$(SIMICS_BASE)/$(HOST_TYPE)/bin -lsimics-common

3.6 Emacs DML Editing Mode

The Emacs (http://www.gnu.org/software/emacs/) extensible editor is the first choice for many programmers, and Simics Model Builder includes a customized mode for editing DML source files. The DML mode is an extension of the standard Emacs editing mode for the C programming language.

Simics includes the Emacs file dml-mode.el to add support for the DML major mode. This file can be found in the [simics]/scripts directory. To use it, add the following lines to your Emacs configuration file (usually [home]/.emacs or [home]/.xemacs/init.el):

(setq load-path (cons "[simics]/scripts" load-path))
(autoload 'dml-mode "dml-mode" "DML mode" t)
(add-to-list 'auto-mode-alist '("\\.dml\\'" . dml-mode))

(you need to replace the text [simics] in the above with the full path to your Simics Base installation which includes Model Builder). After restarting Emacs, the DML mode should be automatically enabled when you open a file whose name ends in ".dml".

For more information, run the command M-x describe-mode in an Emacs buffer using the DML mode, or read the "Editing Programs" section of the Emacs documentation.