2. SpaceStudio User Guide#

2.1. The SpaceStudio IDE#

SpaceStudio is a tool suited for system designers that focuses on application acceleration and architecture evaluation. It offers extensive automatic code generation processes (for virtual platforms, drivers, communication layers, bootloaders, etc…) to avoid error-prone and time-consuming manual coding. SpaceStudio also provides means to evaluate and predict system performance using a non-intrusive monitoring infrastructure. Moreover, the architetcures designed in SpaceStudio can be easily exported for downstream implementation.

2.1.1. Launching SpaceStudio#

After running the installer (please refer to the installation guide), a “SpaceStudio” shortcut will be added to the Windows start menu/Ubuntu applications menu. Use it to launch the IDE.

2.1.2. Welcome Page#

When SpaceStudio starts, the welcome page below is shown. It displays quick access to create or open projects, as well as links to the documentation and a list of recently opened projects.

_images/user_welcome_page.png

Figure 2.1 SpaceStudio’s welcome page#

2.1.3. The Architecture Editor#

The main view of SpaceStudio is the architecture editor. It is an interactive block design environment that allows the user to view the system, connections, and edit them as required.

Moreover, it offers flexibility on architectural choices (for instance, you can connect a device’s master interface to a free high-speed interface of a Zynq UltraScale+ MPSoC). This editor should feel familiar to system designers, since it shares the principles of downstream EDA design tools, such as Mathworks Simulink and Xilinx Vivado.

Many diagram views can be opened at once in tabs, allowing a user to work on an architecture while another one is being compiled. The last active diagram is the one that will be affected by the quick access buttons in the toolbar (such as the “Run simulation” button).

_images/user_diagram.png

Figure 2.2 SpaceStudio’s architecture diagram view#

2.1.3.1. Diagram block color scheme#

Blocks in the SpaceStudio diagram are colored according to their type, as follows:

Color

Description

Example

Red

Module mapped to hardware

 _images/user_hw_block1.png

Green

Processor or module mapped to software

 _images/user_sw_block1.png

Gray

User-defined device

 _images/user_dev_block1.png

Blue

Component instance added automatically by SpaceStudio

 _images/user_auto_block1.png

Yellow

Component instance added manually by the user that is neither an application component or a processor

 _images/user_man_block1.png

2.1.3.2. Action on double clicking a block#

Double clicking a block in the diagram will perform an action depending on the block type, as follows:

  • For an application component instance (modules, devices), the related C++ source code file will be opened in the code editor.

  • For a hierarchical component instance, it will expand or collapse the hierarchy.

  • For a component instance with multiple grouped ports of the same type, it will collapse or expand all ports.

2.1.3.3. Hierarchical components#

A hierchical component is a component that contains sub-components. They show a expand_icon icon when hovering over them. An example of both a collapsed and expanded hierarchical component is shown below.

_images/user_hier_collapsed.png

Figure 2.3 Example of a hierarchical component in the diagram, in its collapsed state#

_images/user_hier_expanded.png

Figure 2.4 Example of a hierarchical component in the diagram, in its expanded state#

2.1.3.4. Grouped ports#

In order to make the diagram easier to read, ports of the same kind on a component instance are grouped together in the architecture diagram. By default, they are collapsed, but can be expanded to show each individual port.

A collapsed group shows a + icon, while an expanded group shows a - icon, as shown below.

_images/user_port_group.png

Figure 2.5 Example of a component instance with grouped ports. Expanded ports are shown on the left, while collapsed ports are shown on the right.#

Note

When connecting interfaces manually, the user can connect to a collapsed group. When doing so, SpaceStudio will use the first non-connected port in the group for the connection.

2.1.4. The Project Explorer#

The project explorer displays relevant information about the currently opened project.

A project follows the following structure:

  • SolutionsGroup of architectures that share the same set of user-define components and files.

    • Application Components : User-define application intellectual property (IP), modules and devices.

    • Architectures : Diagram file (can be double-clicked to open the architecture diagram) and related SpaceStudio-generated files (virtual platform definitions, database, etc…). When in monitoring mode, the monitoring view can also be opened from here.

Note

From the project explorer, files can be opened by double-clicking on them. If a file is generated by SpaceStudio, it will be opened in a read-only editor.

2.1.5. Miniature View#

A large architecture may not fit in the architecture diagram view, even with zooming out. The miniature view provides a quick overview of the whole architecture, with a frame showing the current view in the full diagram view.

You can click and drag the frame in the miniature view to quickly navigate to different parts of the architecture diagram.

2.1.6. Outline View#

The outline view displays the component instances found in the architecture in a tree view. Selecting a component instance in the outline view will synchronize the architecture editor to center the selected component instance. This feature is useful to quickly locate a component instance in a large architecture diagram.

The outline can also be used to rename, delete and copy-paste component instances through the right-click context menu.

Moreover, the outline view can be used to move module instances between hardware and software the same way as in the architecture diagram, by dragging and dropping the instance on a processor or on the root architecture node.

Finally, a “Quick Outline” tool can be invoked by pressing “Ctrl+O” in the architecture diagram. In addition to an outline of the component instances, it also provides a search bar to quickly find a component instance by name.

2.1.7. Console View#

The console displays the logs of SpaceStudio. It shows the output of the different processes launched by SpaceStudio, such as the compilation and simulation processes, as well as the simulation’s text output.

Sub-consoles will be created for architetcure implementation and FPGA estimation launches. To select between the different sub-consoles, click on the console_icon icon in the console’s toolbar, and select a console from the dropdown menu.

2.1.8. Properties View#

The properties view works with both the project explorer and the architecture diagram. When selcting a node from either of those, the properties view will update to show the properties of the selected element.

In general, the properties of a node from the project explorer display information about the related file, such as its path, size and type. Selecting a node from the architecture diagram allows the user to edit the properties of the related component instance.

2.1.9. Progress View#

The progress view shows the status of running jobs. SpaceStudio may start multiple jobs across different architectures at the same time, and each architecture may have multiple running processes. For instance, FPGA estimation can be run on an architetcure while another architecture is being compiled for simulation. The progress view allows the user to keep track of all these processes and their status.

2.2. Project management#

SpaceStudio projects are organized as a set of solutions, themeselves being a set of architectures. In a solution, multiple architectures can be created to represent slight modifications to the system (for architecture exploration purposes for instances). An architecture contains all the information about the system design, such as the components, their connections and properties.

Solutions can be seen as multiple versions of the same application. For instance, the first solution may implement a sequential execution, while the second implements the same application with a multi-threaded execution. A solution contains a set of application components (modules and devices), and a set of architectures which describe instances of those application components, hardware/software mapping, and their connections.

2.2.1. Creating a new project#

  1. Click on the File menu.

  2. From the dropdown menu, click on New Project…. The following dialog will open.

    _images/user_new_project_dialog.png

    Figure 2.6 New project dialog#

  3. In the dialog that opens, enter the name of the project, and choose the path where it will be created.

  4. Click the OK button to create the project. If the corresponding option is enabled in the dialog, a subdirectory with the project name will be created in the selected path, and the project files will be created inside it. Otherwise, the project files will be created directly in the selected path.

2.2.2. Opening an existing project#

SpaceStudio projects are stored in a diretcory which contains a file with the .spacestudio extension. To open an existing project, follow the steps below:

  1. Click on the File menu.

  2. From the dropdown menu, click on Open Project….

  3. In the file browser dialog that opens, navigate to the directory containing the project you want to open, select the file with the .spacestudio extension.

  4. Click the Open button to open the project.

Only one project can be opened at a time in SpaceStudio. Trying to open another project while one is already opened will cause the currently opened project to be closed (with a prompt to save any unsaved changes) before opening the new project.

2.2.3. Closing a project#

To close the currently opened project, follow the steps below:

  1. Click on the File menu.

  2. From the dropdown menu, click on Close Project.

When you close a project, all open files will be closed, and you will be prompted to save any unsaved changes.

2.3. Solution management#

A solution represents an implementation of an application. There can be several solutions in a project. A solution is composed of a set of user-defined components (modules and devices), and a set of architectures which share the same set of user-defined components.

2.3.1. Creating a new solution#

  1. Create a new project or open an existing one.

  2. Open the Solution menu and click on New Solution…. The following dialog will open.

    _images/user_new_solution_dialog.png

    Figure 2.7 New solution dialog#

  3. In the dialog that opens, choose a unique name for the solution.

  4. If the box Based on existing solution is checked, select the solution you want to copy.

  5. Click the OK button to create the solution.

2.3.2. Deleting a solution#

  1. In the project explorer, right-click on the solution you want to delete and select “Delete”.

2.4. Application Components#

Application components, or application-specific user-defined functions, are programming elements whose implementation is defined by the system designer. An application component can be a functional or non-functional element of the application. In the case of a non-functional element, the application component implementation is composed of computation timing and communication budget based on the application specification.

2.4.1. Modules#

Modules perform a task of the application and are developped by the user. They can be mapped to hardware components or software threads to be run on a processor.

2.4.1.1. Creating a module#

  1. Create a new project or open an existing one.

  2. Create a new solution or open an existing one (by selecting it in the project explorer).

  3. Open the Solution menu and click on New Module…. The following dialog will open.

    _images/user_new_module_dialog.png

    Figure 2.8 New module dialog#

  4. In the dialog that opens, choose a unique name for the module.

  5. Click the OK button to create the module.

The newly created module will be added to the list of application components in the project explorer, and will be made available in the toolbox of the architecture diagram.

2.4.1.2. Removing a module#

Before removing a module, make sure that the module in not instantiated in any architecture. If it is, SpaceStudio will not allow you to remove it, and will prompt you to first remove all instances of the module from the architectures.

  1. In the project explorer, select and expand the solution containing the module you want to remove.

  2. Expand the Application Components section to show the list of modules.

  3. Right-click on the module you want to remove and select “Delete”.

2.4.1.3. Manage imports for a module#

Modules can depend on external source files, in addition to their own module header and source files. They can be managed using the following steps:

  1. In the project explorer, select and expand the solution containing the module you want to manage imports for.

  2. Expand the Application Components section to show the list of modules.

  3. Right-click on the module you want to manage imports for and click either Import File… or Import Folder… depending on whether you want to import a single file or a whole folder. The corresponding file browser dialog will open.

  4. In the file browser dialog, select the file or folder you want to import and click the Open button.

2.4.1.4. Manage toolchain build options for a module#

Modules can have specific compilation and linker preferences (for instance, to link a software module to a specific library). These preferences can be managed using the following steps:

  1. In the project explorer, select and expand the solution containing the module you want to manage toolchain build options for.

  2. Expand the Application Components section to show the list of modules.

  3. Right-click on the module you want to manage toolchain build options for and click on Toolchain Build Options…. The following dialog will open.

    _images/user_module_toolchain_options.png

    Figure 2.9 Module toolchain build options dialog#

  4. Configure the compilation and linker options in their corresponding tabs.

  5. Click the OK button to save the changes.

2.4.2. Devices#

Devices are application components that represent peripherals of the system. They are always hardware copenents, and their primary interfaces are memory-mapped, either as slave or master.

2.4.2.1. Creating a device#

  1. Create a new project or open an existing one.

  2. Create a new solution or open an existing one (by selecting it in the project explorer).

  3. Open the Solution menu and click on New Device…. The following dialog will open.

    _images/user_new_device_dialog.png

    Figure 2.10 New device dialog#

  4. In the dialog that opens, choose a unique name for the device.

  5. Select the type of the device’s primary interface (slave or master).

  6. Click the OK button to create the device.

The newly created device will be added to the list of application components in the project explorer, and will be made available in the toolbox of the architecture diagram.

2.4.2.2. Removing a device#

Before removing a device, make sure that the device in not instantiated in any architecture. If it is, SpaceStudio will not allow you to remove it, and will prompt you to first remove all instances of the device from the architectures.

  1. In the project explorer, select and expand the solution containing the device you want to remove.

  2. Expand the Application Components section to show the list of devices.

  3. Right-click on the device you want to remove and select “Delete”.

2.4.2.3. Manage imports for a device#

The imports of a device are managed the same way as for modules. See Manage imports for a module for more details.

2.4.2.4. Manage toolchain build options for a device#

Toolchain build options for a device are managed the same way as for modules. See Manage toolchain build options for a module for more details.

2.5. Architectures#

An architecture represents a design scenario for a solution. These scenario are composed of application component instances (modules and devices) mapped onto a system architecture. Thus, an architecture contains the architectural details regarding a specific design (component instances, their connections and properties).

For example, a user may decide to implement two variations on the same application : one with a single processor and another one with two. A solution contains as many architectures as the user wants to create to explore different design scenarios.

2.5.1. Creating an architecture#

To create a new architecture, at least one solution must be created.

  1. Create a new solution or open an existing one (by selecting it in the project explorer).

  2. Open the Solution menu and click on New Architecture…. The following dialog will open.

    _images/user_new_architecture_dialog.png

    Figure 2.11 New architecture dialog#

  3. In the dialog that opens, choose a unique name for the architecture.

  4. If the box Based on existing architecture is checked, select the architecture you want to copy.

  5. Click the OK button to create the architecture.

2.5.2. Removing an architecture#

  1. In the project explorer, select and expand the solution containing the architecture you want to remove.

  2. Select the architecture you want to remove, right-click on it and click Delete.

Note

The architecture will be deleted permanently from the project, and all related files will be removed from the disk.

2.5.3. Editing an architecture#

To modify an architecture, you must open its architecture diagram. TO do so, expand the architecture node in the project explorer and double-click on the diagram file. The architecture diagram will open in a new tab, and you can edit it as required.

2.5.3.1. The Architecture Editor#

The architecture editor is the centerpiece of SpaceStudio. It enables the user to :

  • Instantiate application and library components (interconnects, processors, timers, etc…).

  • Adjust architecture parameters and application component properties.

  • Connect devices and library components together.

  • Map modules to hardware or software.

The architecture editor works in conjunction with the properties view which shows the parameters for the component instance currently selected in the architecture diagram.

_images/user_architecture_editor.png

Figure 2.12 Architecture editor view#

In the figure Architecture editor view, section number 1 is the diagram editor itself. This editor displays the complete virtual platform in a block design graphical interface with which the user can directly interact.

Section number 2 contains the library components that the user can instantiate. It is made up of both platform components (IPs provided by SpaceStudio) and application components (defined by the user in the solution). To instantiate a component in the architecture diagram, simply drag and drop it from the library to the diagram.

Section number 3 is the properties view, which displays the parameters for the component instance currently selected in the architecture diagram. It is not part of the architetcure editor per se, as it can also be used to edit properties of elements from the project explorer. However, it is an essential part of the workflow when editing an architecture, as it allows the user to adjust the properties of component instances in the architecture diagram.

2.5.3.1.1. Instantiate a component in an architecture#

To instantiate application components and platform IPs :

  1. Open the architetcure editor for the architecture you want to edit.

  2. In the library section of the architecture editor, select the component you want to instantiate and drag and drop it in the diagram.

Technical close-up

SpaceStudio supports instantiating the same module multiple times. Each instance will use the same module implementation which can be parametrized using user-defined properties. Moreover, different instances of the same module can differntiate their behaviour by using the INDEX global macro defined by SpaceStudio. More details about it can be found in the SpaceLib API documentation.

2.5.3.1.2. Parameterize a component instance#

Component instances in the architecture have parameters associated to them which can be modified using the properties view. To inspect and modify the parameters of a component instance :

  1. Open the architecture diagram containing the component instance you want to parameterize.

  2. Click on the component instance in the diagram to select it. The properties view will update to show the parameters of the selected component instance.

  3. In the properties view, modify the parameters as required.

2.5.3.1.3. User-defined parameters#

The user can add user-defined parameters (i.e. key-value pairs) to module and device instances. When a module or device is instantiated in the architecture, the value of each user-define parameter can be set for the instance in the properties view, and each instance can have different values for the same user-defined parameter.

User-defined parameters are provided as C preprocessor macros to the module’s implementation (#define) so that they can be used in the module’s source code. Note that the addition of this definition is automatically handled by SpaceStudio, and the user should not add it manually in the module’s source code.

An example of a user-defined parameter in the properties window is shown below, in the red square.

_images/user_defined_param.png

Figure 2.13 Example of a user-defined parameter in the properties view#

To add a new user-defined parameter to a module or device, follow the steps below:

  1. In the project explorer, select and expand the solution containing the module or device you want to add a user-defined parameter to.

  2. In the Application Components section, select the module or device you want to add a user-defined parameter to.

  3. In the properties view, go to the Properties tab.

  4. Click on the add_param_icon button.

  5. Double click in the Name column of the newly created parameter to edit its name, and press “Enter” to save it.

  6. Do the same for the Default value column.

Note

The actual value of a user-defined parameter for a specific instance of the module or device can be set in the properties view when the instance is selected in the architecture diagram. The value set for an instance will override the default value defined for the parameter.

Tip

In component instances, you can restore the default value of a user-defined parameter by selecting its row, then clicking on the revert_default_icon icon on the right of the properties view.

Tip

To remove a user-defined parameter, select its row in the properties view, then click on the delete_param_icon icon on the right of the properties view.

2.5.3.1.4. Memory initialization#

Memory component instances can be initialized with pre-existent data to make simulation bootstrap easier. The user provides a file with the generated data. Note that this is only available for simulation, and is not used in architecture implementation.

To initialize a memory component instance with a data file, follow the steps below:

  1. In the architecture diagram, select the memory instance you want to initialize.

  2. In the properties view, go to the Parameter tab.

  3. In the Memory initialization field highlighted in the red square in the figure below, enter the path to the data file you want to use for memory initialization.

    _images/user_mem_init.png

    Figure 2.14 Memory initialization field in the properties view#

The provided file must be in the JSON format, and describes how the memory should be initialized. An example of such a file is shown below.

 1{
 2    "memory_regions" : [ {
 3        "offset" : {
 4            "long" : 0
 5        },
 6        "bytes" : {
 7            "string" : "whole_file"
 8        },
 9        "source_type" : "file",
10        "source" : {
11            "com.spacecodesign.avro.file_source" : {
12                "file" : "%project_directory%/import/image/jpeg1.jpg",
13                "offset" : 0
14            }
15        }
16    }, {
17        "offset" : {
18            "string" : "at_end_of_last_loaded_memory_region"
19        },
20        "bytes" : {
21            "long" : 4
22        },
23        "source_type" : "immediate",
24        "source" : {
25            "long" : 255
26        }
27    }, {
28        "offset" : {
29            "string" : "at_end_of_last_loaded_memory_region"
30        },
31        "bytes" : {
32            "long" : 4
33        },
34        "source_type" : "random",
35        "source" : null
36    } ]
37}

In this example, the first memory region starts at 0 (offset=0) and will load the whole file (bytes=whole_file) from a source file (source_type=file). The file path can use the %project_directory% token, which is replaced by the project directory (where the .spacestudio file is located).

The second memory region to be initialized will start at the end of the previous section (offset=at_end_of_last_loaded_memory_region) and 4 bytes (bytes=4) of immediate (source_type=immediate) value 255 (source=255) will be loaded in it.

The last memory region will start at the end of the previous section too (offset=at_end_of_last_loaded_memory_region) and will load 4 bytes (bytes=4) of random data (source_type=random).

2.5.3.1.5. Removing a component instance from an architecture#

To remove a component instance from an architecture, simply hover over the instance in the architecture diagram. A menu will show at the top right. In it, click the remove_instance_icon icon to remove the instance from the architecture.

_images/user_remove_instance.png

Figure 2.15 Remove instance menu in the architecture diagram#

Tip

Alternatively, you can select the instance in the architecture diagram and press the “Delete” key on your keyboard to remove it from the architecture.

2.5.3.1.6. Connecting component instances#

SpaceStudio goes to great lengths to automatically connect component instances together when the user instantiates them in the architecture diagram. Moreover, SpaceStudio also instantiates the required components to perform a given communication. For instance, if a module communicates with a BRAM but no interconnect is instantiated in the architecture, SpaceStudio will automatically instantiate an AXI interconnect and connect the module to the BRAM through it.

Even though SpaceStudio performs a lot of automatic connections, the system designer remains in full control of the generated system. The user can thus override decisions made by SpaceStudio. Nevertheless, SpaceStudio attempts to make connections just as the user would, so in most cases, the user should not need to manually connect component instances together.

In order to make manual connections, in the architecture diagram, click on a disconnected port, and drag and drop the connection to the port you want to connect to.

For example, the port axi_master below is disconnected. We can connect it to compatible ports of other component instances by dragging and dropping a connection from it to the compatible port.

_images/user_connect_port.png

Figure 2.16 Example of a disconnected port in the architecture diagram#

Note

The cursor will change from a pointer to ha hand when hovering on a valid destination port to connect to. If the destination port is not compatible, the connection will not be allowed and the cursor will remain an arrow.

_images/user_connect_port_invalid.png

Figure 2.17 Example of an invalid destination port in the architecture diagram. The cursor remains an arrow, and the connection is not allowed.#

_images/user_connect_port_valid.png

Figure 2.18 Example of a valid destination port in the architecture diagram. The cursor changes to a hand, and the connection is allowed.#

2.6. Real-Time Operating Systems#

SpaceStudio supports targetting various real-time operating systems (RTOS) when building embedded software for processor cores. You can use the properties view to select the RTOS you want to target for each processor instance in your architecture.

2.6.1. Supported RTOS Targets#

2.6.1.1. Baremetal#

SpaceStudio ships a baremetal operating system. This rudimentary runtime uses polling to avoid context switches, and thus only supports one task per processor core.

Supported platforms

Xilinx Zynq MicroBlaze, Zynq (AMP mode), Zynq UltraScale+ (AMP mode on Cortex-A cores)

2.6.1.2. Micrium µC/OS-II#

µC/OS-II is a multi-tasking RTOS developed by Micrium. Thus, multiple software tasks can be mapped to a single processor core when targeting this RTOS. µC/OS-II comes installed with SpaceStudio and can be evaluated for 45 days free of charge. You are legally required to purchase a license from Micrium to use µC/OS-II in any commercial application. Please contact Micrium for more information about your µC/OS-II license rights and obligations.

Supported platforms

Xilinx MicroBlaze, Zynq (AMP mode), Zynq UltraScale+ (AMP mode on Cortex-A cores)

2.6.1.3. Linux#

Linux is a full featured (non real-time) operating system. As it requires CPU support for virtual memory, it is only available on the Zynq, Zynq UltraScale+ and Versal platforms, and only on their Cortex-A cores (the Cortex-R cores on those platforms cannot run Linux).

Linux is only supported in SMP mode.

Supported platforms

Xilinx Zynq, Zynq UltraScale+ (Cortex-A cores only), Versal (Cortex-A cores only)

2.6.1.4. RTEMS 6#

RTEMS is designed for real-time embedded systems and provides extensive multi-processing and memory-management services, and even system database facilities. It is extensively documented and supported by the community.

Supported platforms

Xilinx Zynq (SMP mode), NanoXplore NG-ULTRA (SMP mode)

2.6.1.5. FreeRTOS#

FreeRTOS is a real-time operating system for embedded devices that has been ported to a wide variety of platforms. It is designed to be small and simple, making it ideal for microcontrollers and small microprocessors.

Supported platforms

Xilinx Zynq UltraScale+ (SMP mode on Cortex-R cores only), Versal (SMP mode on Cortex-R cores only)

2.7. Settings and Preferences#

The SpaceStudio environment has centralized all preferences and options to a single page to make it easier for the user to configure the environment. They are separated into two levels. First, the SpaceStudio preferences which include global preferences for the development tool. The second level is the Architecture Preferences, related to a specific architecture. Multiple architectures within the same solution can have different preferences.

To access the preferences, click on the Tools menu and select Preferences…. The following dialog will open.

_images/user_preferences_dialog.png

Figure 2.19 Preferences dialog#

2.7.1. SpaceStudio global preferences#

This section presents the following global preference categories :

  • Toolchain : Pages related to the configuration of various toolchain options for the hardware platform (i.e. compiling the hardware simulation), as well as for software on processors. One page is available for each supported platform toolchain, as well as for each supported processor toolchain. In order to speed up compilation, a compilation cache is enabled by default, and can be disabled through these pages.

  • EDA : Pages related to the configuration of EDA tools used for architecture implementation and FPGA estimation. One page is available for each supported EDA tool.

2.7.2. Architecture preferences#

This section presents the following architecture preference categories : + Simulation Options : Configuration of simulation runtime options. See the Simulation section for more details about simulation and its options. + Makefile Options : Options related to the build system (Makefile) for the platform and embedded processors.

2.8. Simulation#

SpaceStudio allows the user to simulate the system to verify its functionality. The steps required to execute the simulation are as follows:

  1. File generation : SpaceStudio generates the virtual platform (hardware and software simulation sources, platform definition files, etc…) based on the architecture design.

  2. Compilation : The generated files are compiled to produce the simulation executable.

  3. Simulation execution : The simulation executable is launched, and the system behaviour can be observed through the simulation logs in the console view.

2.8.1. Compilation#

The compilation operation compiles all user components as well as the main simulation file generated by SpaceStudio. An architetcure must be active before compiling (i.e. its diagram must be open and in the foreground) as the compilation is done for a specific architecture.

To launch the compilation, follow these steps :

  1. Open the architecture diagram for the architecture you want to simulate.

  2. Open the Tools menu, then click on Compile.

Tip

It is sometimes necessary to clean up all the object files and the executable from a previous compilation before recompiling. To do so, go to the Tools menu and click on Clean generated files before launching the compilation.

2.8.2. Executing the simulation#

An architecture must be active before launching the simulation (i.e. its diagram must be open and in the foreground) as the simulation is launched for a specific architecture.

To launch the simulation, follow these steps :

  1. Open the architecture diagram for the architecture you want to simulate.

  2. Go to the Run menu and click on Run.

  3. In the dialog that opens, select Launch in a simulator and click the OK button.

The simulation will be compiled if needed, then start, and the simulation logs will be displayed in the console view.

2.8.2.1. Specificities of Linux simulation#

When simulating a processor that targets Linux, you have the choice to redirect Linux’s output to the console or to a log file (refer to Architecture preferences). If the Linux output is redirected to the console, after launching the simulation, a console (from QEMU) will open and messages from the Linux boot process will be displayed. After the Linux kernel boots, you will have access to a Linux command prompt. However, if the Run Linux application automatically after boot option is enabled in the processor preferences, the Linux application will be launched automatically after the Linux boot process, and you will not have access to the Linux command prompt.

To run the Linux software application if not enabled to run automatically after boot, you can execute the following commands once the boot process is finished and you have access to the Linux command prompt :

cd /root
./<linux_application_executable>

Where <linux_application_executable> is the name of the Linux application executable file generated by SpaceStudio. You can find it in the /root directory in the simulated Linux file system (find its exact name by running ls /root and searching for a file with a .elf extension).

Other directories, scripts, and executables are added by SpaceStudio to the Linux file system : * /root/drivers : Linux drivers and a script generated by SpaceStudio. These drivers are generated for the specific platform configuration and may change after each compilation. The shell script is executed during boot to load the drivers.

2.8.3. Stopping the simulation#

A simulation stops gracefully when a user component calls the sc_stop() function, which enables the virtual platform to correctly terminate ongoing operations (i.e. terminate monitoring analysis). However, at any time, the user can click the stop_sim_icon icon at the top of the console view to force stop the simulation.

Forcefully killing the simulation is useful for stopping long running and faulty simulations. When using this function, SpaceStudio first tries a graceful termination, and then only proceeds with a forceful termination if the simulation does not stop within a reasonable amount of time after the graceful termination is initiated.

Note

The results of the simulation displayed in the console using printf/SpacePrint are displayed in the output view, at the bottom of the SpaceStudio window (may require to select the tab to show it instead of the properties view).

Warning

Manually stopping a simulation may cause some information not to be properly generated. To ensure a clean termination, it is recommended to call the sc_stop() function in the user code when possible.

2.8.4. Debugging in simulation#

Application components in SpaceStudio are written in C/C++. This means they can be debugged using a regular C/C++ debugger (e.g. GDB) to validate their functionality and get rid of unwanted behavior. SpaceStudio uses the Eclipse CDT to enable graphical debugging.

SpaceStudio enables co-debugging of both the platform hardware code and the software target code running on the simulated processor(s). The following figure shows two debuggers in action (one for hardware and one for software) :

_images/user_debug_example.png

Figure 2.20 Example of co-debugging hardware and software in SpaceStudio#

In order to debug a simulation, you first need to set which components to debug in the architecture diagram. Debugging for a component is enabled when the bug icon is shown when hovering as seen in Figure 2.21. Debugging is disabled for a component when the bug icon is striked through as seen in Figure 2.22. To toggle debugging for a component, simply click on the bug icon in the component instance in the architecture diagram.

_images/user_debug_enabled.png

Figure 2.21 Debugging enabled for a component instance in the architecture diagram#

_images/user_debug_disabled.png

Figure 2.22 Debugging disabled for a component instance in the architecture diagram#

Debug for instances mapped to a processor is enabled by enabling debug for the processor instance in the architecture diagram, as shown in Figure 2.23.

_images/user_proc_debug_enabled.png

Figure 2.23 Debugging enabled for a processor instance in the architecture diagram#

To start a debugging session, follow the steps below:

  1. Open the architecture diagram for the architecture you want to simulate and debug.

  2. Enable debugging for the components you want to debug by clicking on the bug icon in their instances in the architecture diagram.

  3. Go to the Run menu and click on Debug

  4. In the dialog that opens, select Launch in a simulator and click the OK button.

  5. After compilation and when the simulation starts, you will be prompted to switch to the debug view. Agree to switch to the debug view, and the debugging perspective will open with the GDB debuggers for the hardware and software components you enabled debugging for.

Note

The debugger stops at the first line of each main function (the sc_main for the hardware platform simulation, and the software main for each processor core). You can use the usual debugging features (resume, step into, step over, breakpoints, etc…) to continue executing the simulation and inspect the behavior of the components.

Important

You may be prompted by your firewall to allow GDB to accept incoming connections. This is required for the debugger to work, so make sure to allow it.

2.8.4.1. Software debugging on Zynq#

To debug software on Zynq platforms, network support must be enabled since GDB will connect to a GDB server running on the platform through TCP/IP. To enable network support for Zynq simulation, follow the steps below:

  1. Open the architecture diagram for the architecture you want to simulate and debug.

  2. Click on the Zynq processor instance to select it.

  3. In the properties view, go to the Linux tab.

  4. Make sure Network → Method is not set to Disabled

2.9. Performance Analysis and Monitoring#

The monitoring infrastructure enables users to analyze the performance and behavior of a SpaceStudio simulation. The monitoring infrastructure produces a database which contains all the events that occurred during a simulation such as bus communications, inter-module communication, memory usage, processor usage, etc…

With these tools, developers can better understand theur system, and avoid bottlenecks to optimize the system performance.

This feature is further described in the Monitoring User Guide.

2.10. Version Information#

You can use the About SpaceStudio dialog to discover :

  • The version of SpaceStudio you are using.

  • The time left in a time-limited license.

To open the About SpaceStudio dialog :

  1. Click the Help menu

  2. From the dropdown menu, click on About SpaceStudio…. The following dialog will open.

_images/user_about_dialog.png

Figure 2.24 About SpaceStudio dialog#

2.11. Frequently Asked Questions#

2.11.1. My simulation seems to hang. Why ?#

This situation is usually caused by one of the following reasons :

  1. There is an infinite loop in the user code. This doesn’t let the SystemC simulation engine schedule other processes, and thus the simulation appears to be hanging. Make sure to leave time for other processes by using the hw_compute_latency function or by adding communications.

  2. The simulation might be waiting for connections with software debuggers to be established with no success. Check the Debugging in simulation section for more details.

2.11.2. My simulation used to work before I mapped a module to software, and now it fails with an unexpected error message. Why ?#

This situation is usually caused by one of the following :

  1. The architecture’s executable might have been built using stale files. See answer to “Why does SpaceStudio keep ignoring my modifications ?” for more details.

2.11.3. Why does SpaceStudio keep ignoring my modifications ?#

If you edit the active architecture’s content with the architecture editor but when you run a simulation your recent changes are not reflected in the simulation, the following might be the cause :

  1. After editing the architecture, you must re-generate the files and compile again for the changes to be taken into account in the simulation.

  2. After you modify one of your own modules or devices, you need to regenerate and recompile the architecture.