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 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.
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
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 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.
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 |
-tf |
- |
sets the final time for the real-time code, at which time the model stops. For example |
-td |
- |
sets the time delay before the real-time code initializes and starts running. For example |
-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 |
-ss |
- |
sets the stack size for model threads. |
-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 |
-reconfig |
- |
sets the reconfiguration group used when performing dynamic reconfiguration. Please
refer to Dynamic Reconfiguration for
information. |
-switch |
- |
causes the model from the specified group to switch out. |
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. |
%{expr} |
- |
the result of evaluating the MATLAB expression 'expr' (on the host!) e.g. |
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.
This field may be set more easily using the Set Model Log File dialog that is accessible from the 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.
This field may be set more easily using the Set Model Log File dialog that is accessible from the 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.
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
MATLAB Command Line
Click to copy the following command line to the clipboard. Then paste it in the MATLAB Command Window:
qc_open_library('simulink/Model Verification')
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.
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.