QUARC Targets - Generating Code for Various Target Platforms QUARC Communications Protocols navigation bar

Table of Contents > QUARC > User's Guide

Configuration Parameters

This reference section is intended to provide information on some of the configuration parameters in the Code Generation pane of the Configuration Parameters dialog box. These configuration parameters include all the parameters from the QUARC section of the pane since they are added to the pane upon QUARC installation. In addition, the original Code Generation parameters that the user needs to modify for advanced use are also described in this section.

To open the Configuration Parameters dialog, refer to the Configuring a Model section.

This section includes description of parameters from the General, Interface and QUARC sections. Please use the following list to refer to each section:

Code Generation - General

There are only two parameters discussed form the General section; System target file and Language. The rest of the parameters' descriptions are out of scope of this document. For information in these parameters, you can click on the Help button which directs you to the corresponding MATLAB help page. Below is an illustration of the General section of the Code Generation pane in addition to the two mentioned parameters' descriptions.

Code Generation pane

System target file

This parameter specifies the target file to be used for code generation. This is basically where you configure the type of target on which you want to run your model. The target type needs to be configured once for each model. There is no need to configure this parameter every time you want to run the same model on the same target. For each target type, there is one particular system target file.

The Browse button is used to browse through the list of system target files available and select the one desired for the model.

Language

This parameter is used to specify the language with which the model codes are generated in the build process. Please refer to the External Mode Operation section to learn more about code generation in the build process. There are two options available for language; C and C++. Choosing C for the language would cause QUARC to generate C based files (with .c extension). On the other hand, choosing C++ for your language would cause QUARC to make C++ based main file (with .cpp extension). Note however, that other files would still be generated using C language.

The next line following the Language parameter is the description of the target chosen. It changes as you change the system target file. For example the description of the Windows x64 target is QUARC Win64 Target to refer to Windows 64-bit target.

Code Generation Pane - Interface

The Interface parameters that are discussed here are: MAT-file logging, MAT-file variable name modifier, Interface, MEX-file arguments and Static memory allocation. The rest of the parameters' descriptions are out of scope of this document. You can click on Help button to get information on these parameters. Below is an illustration of the Interface section of the Code Generation pane in addition to the mentioned parameters' descriptions.

Configuration Parameters Dialog

MAT-file logging

Enable MAT-file logging by checking this option. For information on MAT-file logging, please refer to the MAT-File Logging section.

MAT-file variable name modifier

You can select a string to be added to the variable names saved in the MAT-file created by MAT-file logging. There are three options available for this parameter; none, rt_ and _rt. rt_ is a prefix while _rt is a suffix in the variable names.

Data exchange interface

It specifies the data exchange interface (API) to be included in the generated C code. Selecting External mode sets the data exchange interface to external mode which is used by Simulink to use for data exchange in time of connection to the real-time code running on target. If you don't select it, you cannot connect to the real-time code from the Simulink model window. The "Host" blocks such as the "Host keyboard" would not work either since they need Simulink to talk to the real-time code. However, you can connect to the real-time code using the Windows explorer when not using external mode. For information on how to do this, please refer to the Using Windows Explorer to Manage Models section of the QUARC documentation.

MEX-file arguments

It specifies the arguments to pass to the external mode interface MEX-file for communicating with the real-time code. The external mode interface MEX-file for QUARC is quarc_comm. You can have up to six arguments to pass to the quarc_comm MEX-file; model arguments, model URI, target URI, log file, copy of model and affinity. The MEX-file arguments are put in single quotes and separated by commas:

['<model arguments>'[, '<model URI>'[, '<target URI>'[, '<log file>'[, '<model copy>'[, <affinity>]]]]]]

The [] indicate entries that are optional. Model arguments are the command-line arguments passed to the model when it is run, the model URI entry is the URI used to communicate with the real-time code for streaming data and parameter tuning, and the target URI is the URI used to communicate with the QUARC Target Manager for downloading and running the real-time code. The log file entry provides a file in which to log information about each run of the model. The model copy entry provides a file in which to copy the model before each run of the model. Finally, the affinity entry determines the CPUs on which the communications thread is allowed to run on the host.

Model arguments

The model arguments can have different options as arguments as described below:

-w

-

including this option causes real-time code to wait until host connects to it before starting. Not including this option would cause the real-time code to start once it is downloaded to the target.

-d

-

sets the current directory for QUARC. This directory could be used to save data streamed from the real-time code. The MAT-file created using MAT-file logging for example is saved in this directory. Example of using this option would be -d pathname where pathname is the pathname of the desired directory. "%d" can also be used which is a format specifier and gets replaced by the default current directory.

-tf

-

sets the final time for the real-time code, at which time the model stops. For example -tf 10 causes the real-time code to run for 10 seconds.

-td

-

sets the time delay before the real-time code initializes and starts running. For example -td 5 causes the real-time code to wait for 5 seconds before it initializes the model and starts running at the specified sampling period. This option is primarily useful when a model is configured to run at boot and needs to wait for drivers to be loaded for devices used by the model.

-pri

-

sets the minimum thread priority. The minimum thread priority is for the thread or task with the slowest sampling rate. If you are using normal simulation, lowest possible number for the minimum thread priority is 0. In external mode however, two additional threads are created by QUARC for communication between model and real-time code. In this case, the lowest number becomes 2 since 0 and 1 are used for the communication threads. Example of using this option would be -pri 3 which sets the minimum thread priority to 3.

-ss

-

sets the stack size for model threads. -ss 65536 would set the stack size to 65536 bytes.

-uri

-

sets the URI to which the model should listen. This is a reference to the model URI which is used for communication between the model and the real-time code. Example of using this option would be -uri %u where "%u" is a format specifier and gets replaced with the default model URI.

-reconfig

-

sets the reconfiguration group used when performing dynamic reconfiguration. Please refer to Dynamic Reconfiguration for information. -reconfig 1 for example would set the reconfiguration group to 1.

-switch

-

causes the model from the specified group to switch out. -switch 0 switches out the model from group 0. This option is used when performing dynamic reconfiguration. Please refer to Dynamic Reconfiguration for information.

Warning Double quotes (") are not allowed in the model arguments because they are not understood by the MATLAB interpreter. To enter a double quote, used the "%q" format specifier instead. For example, use %qmy directory with spaces in it%q to specify a directory containing spaces. The "%d" format specifier accounts for spaces in the path.

A complete list of the format specifiers that may be used in the model arguments are listed below:

%d

-

the current Matlab directory in quotes

%D

-

the current Matlab directory using short filenames (PC) or escaped spaces (UNIX)

%m

-

the model name

%u

-

the model URI

%h

-

the hostname from the model URI

%p

-

the port from the model URI (not usually used)

%P

-

the path from the model URI i.e. the portion following the '/' after the hostname and port (not usually used)

%a

-

the authority from the model URI and any path separator e.g. '//hostname:port/', if present

%o

-

the options from the model URI (not usually used)

%f

-

the fragment from the model URI i.e. the portion following the '#' (not usually used)

%t

-

replaced with the target type e.g. win64

%q

-

replaced with a double quote

%(var)

-

the value of environment variable 'var' (on the host!) e.g. %(PATH)

%{expr}

-

the result of evaluating the MATLAB expression 'expr' (on the host!) e.g. %{pi/2}

Model URI

The model URI argument is described in detail in the Real-Time Code - the Model URI section. You can use "%m" format specifier for the model URI which gets replaced with the model name. When this argument is included in the MEX-file arguments, the default model URI gets overridden by this model URI. For information on the default model URI, please refer to the Default Model URI section.

Target URI

The target URI argument is described in detail in the QUARC Target Manager - the Target URI section. There are a variety of format specifiers that can be used for the target URI. For example, "%m" for model name, "%h" for hostname from the model URI, "%p" for port number from the model URI and "%o" for options from the model URI. When this argument is included in the MEX-file arguments, the default target URI gets overridden by this target URI. For information on the default target URI, please refer to the Default Target URI section.

Log file

The log file argument is described in detail in the QUARC Model Logging section. There are a variety of format specifiers that can be used for the log file. For example, "%m" for model name, "%t" for the target type, "%q" for a double quote, "%(var)" for environment variable, var, such as "%(HOME)", and "%{expr}" for a MATLAB expression, such as "%{date}", "%{time}" or "%{instance(3)}". When this argument is included in the MEX-file arguments, the default log file, if any, gets overridden by this log file. For information on the default log file, please refer to the QUARC Preferences dialog documentation.

Hint

This field may be set more easily using the Set Model Log File dialog that is accessible from the QUARC/Set Log File... menu item.

Model copy

The model copy argument is described in detail in the QUARC Model Logging section. There are a variety of format specifiers that can be used for the model copy argument. For example, "%m" for model name, "%t" for the target type, "%q" for a double quote, "%(var)" for environment variable, var, such as "%(HOME)", and "%{expr}" for a MATLAB expression, such as "%{date}", "%{time}" or "%{instance(3)}". When this argument is included in the MEX-file arguments, the default file to which to copy the model, if any, gets overridden by this argument. For information on the default model copy, please refer to the QUARC Preferences dialog documentation.

Hint

This field may be set more easily using the Set Model Log File dialog that is accessible from the QUARC/Set Log File... menu item.

Affinity

The affinity argument is used to achieve optimal performance on certain targets, such as the INtime target. It is a vector of CPU numbers and indicates the set of CPUs upon which the communications thread may run on the current (host) machine. CPU numbers range from 0 to (qc_get_num_cpus-1), where qc_get_num_cpus returns the number of CPUs present. The communications thread is used to interface between Simulink and the real-time code on the target. For most target types, this entry is not configured, so any CPU may be used by the communications thread. However, for the INtime target it is set to qc_get_num_cpus-1 so that the communications thread is restricted to run on the last CPU on the system. This restriction on the INtime target leads to significant performance gains on CPUs with more than two cores when INtime is configured in dedicated mode.

Static memory allocation

You can control the memory buffer for external mode communication with this parameter. When this parameter is disabled, a static memory buffer is used for external mode communication instead of allocating dynamic memory (calls to malloc). Enabling this parameter would enable another parameter called Static memory buffer size which in turn allocates dynamic memory. The default value for Static memory buffer size parameter is 1000000 bytes. If a very small number is set, an out-of-memory error is issued. You can enable verbose mode for your real-time code generation (by default, this mode is enabled) which causes the MATLAB command window to display the progress of the real-time code generation and the amount of memory the real-time code tries to allocate and the amount that is actually available.

Code Generation Pane - QUARC

The QUARC parameters are added to the Code Generation pane of the configuration parameters upon QUARC installation. Below is an illustration of this section of the pane in addition to the QUARC parameters' descriptions.

Code Generation pane

Stop the model if an overrun occurs

This parameter, if enabled, causes the real-time code to stop if an overrun occurs. Overrun occurrence refers to a task missing a sampling instant or oversampling. By default, this parameter is disabled. The reason is the fact that the Windows target sampling rate of 1 khz is crude and inaccurate in some systems and causes a lot of overrun occurrences in your model. With this option enabled, your model would stop excessively which becomes annoying over time.

Allow use of fast system timer

The QUARC Target for Windows now supports an experimental "fast system timer" on multiprocessor or multicore platforms. The fast system timer is managed by QUARC Timing Services. It is used for sample times faster than one or two milliseconds (depending on the platform) when this option is enabled. The fast system timer generally provides much better performance at one millisecond than QUARC 1.1, and also allows sample times faster than one millisecond to be specified.

Unfortunately, the fast system timer is very CPU intensive and may not be the best option for battery-powered platforms or models with large computational overhead. It works best on systems with more than two processors or cores. This option may be unchecked to prevent use of the fast system timer.

If this option is not checked then sample times are limited to one millisecond. Performance at two milliseconds or slower is greatly improved over QUARC 1.1, but performance at one millisecond may still have significant jitter on some platforms when the fast system timer is not used. The fast system timer is always disabled on single CPU systems. Hence this option is ignored on single CPU platforms.

Use of a hardware timebase is still the recommended timing mechanisms on the QUARC Target for Windows for sample rates faster than two milliseconds. For sampling periods of two milliseconds or slower, the system timer is suitable.

Allow console output (printing to stdout)

This option allows output to the QUARC Console. Models typically output information about their command-line arguments and sample times to the QUARC Console. Disabling this option prevents this output from occurring. This parameter works by changing the way the ssPrintf macro is expanded. Use this macro in your own code to make it compatible with this option.

Support dynamic reconfiguration

This parameter enables the support for dynamic reconfiguration. For information on this topic, please refer to the Dynamic Reconfiguration section in the QUARC documentation. This option is disabled by default.

Enable heap checking (Debug Build configuration only)

This parameter may only be used when the Debug Build configuration is selected in the Toolchain settings. It adds debugging to the generated code to check for heap corruption and memory leaks. The QUARC Console must be used to see the output from the debugging code if any problems are detected.

Assertions

This parameter specifies the action to take on assertions, such as those used in the Model verification blocks. The Model Verification blocks can be used in the model to verify the correctness of the model. The Assertion block for instance, can be used to check whether a signal is nonzero. If signal is nonzero, nothing happens. For a zero signal, an assertion takes place. Another example of this type of blocks is the Check Static Upper Bound block. You can use this block to check if each element of the input signal is less than (or optionally equal to) a specified upper bound at the current time step. If the verification condition is true, nothing happens. Otherwise an assertion takes place. These blocks can be found under Simulink/Model Verification library in the Simulink Library browser. For more information on each of these blocks, you can refer to their reference pages.

When an assertion occurs, the Assertion parameter can be used to specify the action to take. There are three options to choose from: Ignore which ignores the assertion, Stop model with an error which stops the model upon assertion displaying an error, and Print assertion which does not stop the model but prints the error to the QUARC console. The last option is very useful since you do not interrupt the run process and still obtain information about any violations that occur. By default, Stop model with an error is chosen for the action.

Minimum thread priority

This parameter specifies the minimum thread priority. The minimum thread priority is for the thread or task with the slowest sampling rate. If you are using normal simulation, lowest possible number for the minimum thread priority is 0. In external mode however, two additional threads are created by QUARC for communication between model and real-time code. In this case, the lowest number becomes 2 since 0 and 1 are used for the communication threads. The default value is 0 which becomes 2 when support for external mode is enabled for the real-time code.

Stack size

This parameter can be used to set the stack size used by model threads. the default value is 0 which refers to the default stack size.

Model affinity

In multi-core or multi-processor systems, you can restrict the set of CPUs upon which the real-time code may run using this parameter. For instance, in a quad-core system, if you set this parameter to [0 2], then only CPU 0 and CPU 2 will be used for running the real-time code. The default value is [] which sets no restriction on the set of CPUs so that the real-time code may run on any or all of the available CPUs. If you set this parameter to an invalid value then no restriction will be placed on the set of CPUs. This assignment of a process to particular CPUs is called setting the process affinity, which is where this field derives its name.

When using the fast system timer, avoid restricting the real-time code to run on the CPUs that are busiest in Task Manager. The second-last CPU is typically the CPU to avoid in this case. For example, in a quad-core system CPU 2 (where the CPUs are numbered 0 to 3) is generally the CPU used for the fast system timer and is the CPU to avoid.

 

navigation bar