Simulink.ModelReference.protect

Obscure referenced model contents to hide intellectual property

Syntax

Simulink.ModelReference.protect(model)

Simulink.ModelReference.protect(model,Name,Value)

[harnessHandle] = Simulink.ModelReference.protect(model,'Harness',true)

[~ ,neededVars] = Simulink.ModelReference.protect(model)

Description

Simulink.ModelReference.protect(model) creates a protected model from the specified model. It places the protected model in the current working folder. The protected model has the same name as the source model. It has the extension .slxp.

Simulink.ModelReference.protect(model,Name,Value) uses additional options specified by one or more name-value pair arguments.

[harnessHandle] = Simulink.ModelReference.protect(model,'Harness',true) creates a harness model for the protected model. It returns the handle of the harnessed model in harnessHandle.

[~ ,neededVars] = Simulink.ModelReference.protect(model) returns a cell array that includes the names of base workspace variables used by the protected model.

Examples

Protect Referenced Model

Protect a referenced model and place the protected model in the current working folder.

openExample('sldemo_mdlref_bus');
model= 'sldemo_mdlref_counter_bus'

Simulink.ModelReference.protect(model);

A protected model named sldemo_mdlref_counter_bus.slxp is created. The protected model file is placed in the current working folder.

Place Protected Model in Specified Folder

Protect a referenced model and place the protected model in a specified folder.

openExample('sldemo_mdlref_bus');
model= 'sldemo_mdlref_counter_bus'

Simulink.ModelReference.protect(model,'Path','C:\Work');

A protected model named sldemo_mdlref_counter_bus.slxp is created. The protected model file is placed in C:\Work.

Generate Code for Protected Model

Protect a referenced model, generate code for it in normal mode, and obfuscate the code.

openExample('sldemo_mdlref_bus');
model= 'sldemo_mdlref_counter_bus'

Simulink.ModelReference.protect(model,'Path','C:\Work','Mode','CodeGeneration',...
'ObfuscateCode',true);

A protected model named sldemo_mdlref_counter_bus.slxp is created. The protected model file is placed in the C:\Work folder. The protected model runs as a child of the parent model. The code generated for the protected model is obfuscated by the software.

Generate HDL Code for Protected Model

Protect a referenced model, and generate HDL code for it in normal mode.

openExample('hdlcoder/ParentModelWithModelReferenceExample')
parent_model= 'hdlcoder_protected_model_parent_harness';
reference_model_to_protect = 'hdlcoder_referenced_model_gain';

Simulink.ModelReference.protect(reference_model_to_protect, ...
                        'Mode','HDLCodeGeneration')

A protected model named hdlcoder_referenced_model_gain.slxp is created. The protected model file is placed in the same folder as the parent model and the referenced model. The protected model runs as a child of the parent model.

Set the hdl option to true with Mode set to CodeGeneration to enable both C code generation and HDL code generation support for a protected model that you create.

openExample('hdlcoder/ParentModelWithModelReferenceExample')
parent_model= 'hdlcoder_protected_model_parent_harness';
reference_model_to_protect = 'hdlcoder_referenced_model_gain';

Simulink.ModelReference.protect(reference_model_to_protect, ...
                        'Mode','CodeGeneration','hdl',true)

Control Code Visibility for Protected Model

Control code visibility by allowing users to view only binary files and headers in the code generated for a protected model.

openExample('sldemo_mdlref_bus');
model= 'sldemo_mdlref_counter_bus'

Simulink.ModelReference.protect(model,'Mode','CodeGeneration','OutputFormat',...
'CompiledBinaries');

A protected model named sldemo_mdlref_counter_bus.slxp is created. The protected model file is placed in the current working folder. Users can view only binary files and headers in the code generated for the protected model.

Create Harness Model for Protected Model

Create a harness model for a protected model and generate an HTML report.

openExample('sldemo_mdlref_bus');
modelPath= 'sldemo_mdlref_bus/CounterA'

[harnessHandle] = Simulink.ModelReference.protect(modelPath,'Path','C:\Work',...
'Harness',true,'Report',true);

A protected model named sldemo_mdlref_counter_bus.slxp is created, along with an untitled harness model. The protected model file is placed in the C:\Work folder. The folder also contains an HTML report. The handle of the harness model is returned in harnessHandle.

Determine Variables Required by Protected Model

To simulate a model that references a protected model, you might need to define variables in the base workspace or data dictionaries. For example, the sldemo_mdlref_counter_bus model needs the variables that specify the buses at the root input and output ports of the model. When you ship a protected model, you must include definitions of the required variables or the model is unusable.

Tip

To automatically package required variable definitions with the protected model in a project, set Project to true.

Generate the protected model and determine the required variables.

openExample('sldemo_mdlref_bus');
model= 'sldemo_mdlref_counter_bus'

[~, neededVars] = Simulink.ModelReference.protect(model)

The second output, neededVars, determines the variables you must send to the recipient. The value of neededVars is a cell array that contains the names of the variables required by the protected model. However, the cell array might also contain the names of variables that the model does not need.

Before you share the protected model, edit neededVars to delete the names of any variables that the model does not need. Save the required variables in a data dictionary.

Input Arguments

model — Model name

character vector | string scalar

Model name, specified as a character vector or string scalar. It contains the name of a model or the path name of a Model block that references the model to be protected.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Mode','CodeGeneration','OutputFormat','Binaries','ObfuscateCode',true specifies that obfuscated code be generated for the protected model. It also specifies that only binary files and headers in the generated code be visible to users of the protected model.

File Options

Project — Option to collect dependencies in project

false (default) | true

Option to collect dependencies in project, specified as true or false.

The protected model, its dependencies, and its harness model are saved in a project archive (.mlproj). The project archive provides a way to share a project in a single file. You must open the project archive to create the interactive project.

Note

Before sharing the project, check whether the project contains the necessary supporting files. If supporting files are missing, simulating or generating code for the related harness model can help identify them. Add the missing dependencies to the project and update the harness model as needed.

Example: 'Project',true

Data Types: logical

ProjectName — Custom project name

character vector | string scalar

Custom project name, specified as a character vector or string scalar.

If you do not specify a custom project name, the default name for the project is the protected model name followed by _protected.

Example: 'ProjectName','myname'

Dependencies

To enable ProjectName, set Project to true.

Data Types: char | string

Harness — Option to create harness model

false (default) | true

Option to create harness model, specified as a Boolean value.

When you create a harness model for a protected model that relies on base workspace definitions, Simulink^® creates a MAT-file that contains the base workspace definitions.

The harness model must have access to supporting files, such as a MAT-file with base workspace definitions or a data dictionary.

Example: 'Harness',true

Dependencies

To set Harness to true, set Mode to a value that supports simulation. For example, set Mode to 'Accelerator'.

Data Types: logical

Path — Folder for protected model

current working folder (default) | character vector | string scalar

Folder for protected model, specified as a character vector or string scalar.

Example: 'Path','C:\Work'

Data Types: char | string

Functionality Options

Report — Option to generate report

false (default) | true

Option to generate report, specified as a Boolean value.

To view the report, right-click the protected-model badge icon and select Display Report. Or, call the Simulink.ProtectedModel.open function with the report option.

The report is generated in HTML format. It includes information on the environment, functionality, and interface for the protected model.

Example: 'Report',true

Data Types: logical

Webview — Option to include read-only Web view of protected model

false (default) | true

Option to include read-only Web view of protected model, specified as a Boolean value.

To open the Web view of a protected model, use one of the following methods:

• Right-click the protected-model badge icon and select Show Web view.

• Use the Simulink.ProtectedModel.open function. For example, to display the Web view for protected model sldemo_mdlref_counter, call:

  Simulink.ProtectedModel.open('sldemo_mdlref_counter', 'webview');

• Double-click the .slxp protected model file in the Current Folder browser.

• In the Block Parameter dialog box for the protected model, click Open Model.

Example: 'Webview',true

Data Types: logical

Mode — Model protection mode

'Accelerator' (default) | 'CodeGeneration' | 'HDLCodeGeneration' | 'ViewOnly'

Model protection mode, specified as one of these values:

• 'Accelerator': A model that references the protected model can run in normal, accelerator, or rapid accelerator mode.

• 'CodeGeneration': A model that references the protected model can run in normal, accelerator, or rapid accelerator mode and can support code generation.

• 'HDLCodeGeneration': A model that references the protected model can run in normal, accelerator, or rapid accelerator mode and can support HDL code generation. Requires HDL Coder™ license.

• 'ViewOnly': The protected model supports only read-only view. It does not support simulation or code generation.

For more information about simulation modes in model hierarchies, see Choose Simulation Modes for Model Hierarchies.

Example: 'Mode','Accelerator'

CodeInterface — Interface through which generated code is accessed by Model block

'Model reference' (default) | 'Top model'

Interface through which generated code is accessed by a Model block, specified as one of the following values:

• 'Model reference': Code access through the model reference code interface, which allows use of the protected model within a model reference hierarchy. Users of the protected model can generate code from a parent model that contains the protected model. In addition, users can run Model block SIL and PIL simulations with the protected model.

• 'Top model': Code access through the standalone interface. Users of the protected model can run Model block SIL and PIL simulations with the protected model.

Example: 'CodeInterface','Top model'

Dependencies

The system target file (SystemTargetFile) must be set to an ERT-based system target file, for example, ert.tlc). Requires Embedded Coder^® license.

hdl — Option to generate HDL code

false (default) | true

Option to generate HDL code, specified as a Boolean value.

This option requires an HDL Coder license. When you enable this option, make sure that you specify the Mode. You can set this option to true in conjunction with the Mode set to CodeGeneration to enable both C code and HDL code generation support for the protected model.

If you want to enable only simulation and HDL code generation support, but not C code generation, set Mode to HDLCodeGeneration. You do not have to set the hdl option to true.

Example: 'hdl',true

Data Types: logical

TunableParameters — Tunable parameters for simulation

'None' or {} (default) | 'All' | string array | cell array of character vectors

Tunable parameters for simulation, specified as 'None', {}, 'All', a string array, or a cell array of character vectors.

Recipients of the protected model can tune the specified parameters during simulation.

Parameters that are not tunable are not listed as needed variables unless:

• They are used by the model interface.

• They specify part of a data type, such as a bus object, enumerated type, or value type.

• They are used by data store memory.

When you protect a model that references one or more protected models, you must specify the tunable parameters of each referenced protected model as tunable for the model you are protecting.

Example: 'TunableParameters',{'param1','param2'}

Example: TunableParameters=["param1","param2"]

Data Types: char | string | cell

Callbacks — Option to specify callbacks for protected model

cell array

Option to specify callbacks for protected model, specified as a cell array of Simulink.ProtectedModel.Callback objects.

Example: 'Callbacks',{pmcallback_sim, pmcallback_cg}

Data Types: cell

Protection Options

ObfuscateCode — Option to obfuscate generated code

true (default) | false

Option to obfuscate generated code, specified as a Boolean value. Applicable only when code generation during protection is enabled. Obfuscation is not supported for HDL code generation.

Example: 'ObfuscateCode',true

Data Types: logical

OutputFormat — Protected code visibility

'CompiledBinaries' (default) | 'MinimalCode' | 'AllReferencedHeaders'

Protected code visibility, specified as one of the following values:

• 'CompiledBinaries': Only binary files and headers are visible.

• 'MinimalCode': Includes only the minimal header files required to build the code with the chosen build settings. All code in the build folder is visible. Users can inspect the code in the protected model report and recompile it for their purposes.

• 'AllReferencedHeaders': Includes header files found on the include path. All code in the build folder is visible. All headers referenced by the code are also visible.

This argument determines what part of the code generated for a protected model is visible to users.

Example: 'OutputFormat','AllReferencedHeaders'

Dependencies

This argument affects the output only when you specify Mode as 'Accelerator' or 'CodeGeneration'. When you specify Mode as 'Normal', only a MEX-file is part of the output package.

Encrypt — Option to encrypt protected model

false (default) | true

Option to encrypt protected model, specified as a Boolean value. Applicable when you have specified a password during protection, or by using the following methods:

• Password for read-only view of model: Simulink.ModelReference.ProtectedModel.setPasswordForView

• Password for simulation: Simulink.ModelReference.ProtectedModel.setPasswordForSimulation

• Password for code generation: Simulink.ModelReference.ProtectedModel.setPasswordForCodeGeneration

• Password for HDL code generation: Simulink.ModelReference.ProtectedModel.setPasswordForHDLCodeGeneration (HDL Coder)

Example: 'Encrypt',true

Data Types: logical

Sign — Option to sign protected model with digital certificate

character vector | string scalar

Option to sign protected model with digital certificate, specified as a character vector or string scalar that specifies the digital certificate. If the certificate file is password-protected, use the Simulink.ModelReference.ProtectedModel.setPasswordForCertificate function to provide the password before you use the certificate.

Example: 'Sign','my_certificate.pfx'

Data Types: char | string

Modifiable — Option to create modifiable protected model

false (default) | true

Option to create modifiable protected model, specified as a Boolean value. To use this option:

• Add a password for modification by using the Simulink.ModelReference.ProtectedModel.setPasswordForModify function. If a password has not been added at the time that you create the modifiable protected model, you are prompted to create one.

• Modify the options of your protected model by first providing the modification password using the Simulink.ModelReference.ProtectedModel.setPasswordForModify function. Then, use the Simulink.ModelReference.modifyProtectedModel function to make your option changes.

Example: 'Modifiable',true

Data Types: logical

CustomPostProcessingHook — Option to add postprocessing function for protected model files

function handle

Option to add a postprocessing function for protected model files, specified as a function handle.

The function accepts a Simulink.ModelReference.ProtectedModel.HookInfo object as an input variable. This object provides information on the source code files and other files generated during protected model creation. It also provides information on exported symbols that you must not modify. Prior to packaging the protected model, the postprocessing function is called.

For a protected model with a top model interface, the Simulink.ModelReference.ProtectedModel.HookInfo object cannot provide information on exported symbols.

Example: 'CustomPostProcessingHook',@(protectedMdlInf)myHook(protectedMdlInf)

Output Arguments

harnessHandle — Handle of harness model

double

Handle of harness model, returned as a double. When model protection does not create a harness model or packages the harness model in a project archive, the returned value is 0.

To create a harness model that is open after model protection, set Harness to true and Project to false (default).

neededVars — Names of base workspace variables

cell array

Names of base workspace variables that the protected model uses, returned as a cell array.

The cell array can also include variables that the protected model does not use.

Alternatives

Protect Models to Conceal Contents

Version History

Introduced in R2012b

R2023a: Mode will not support normal mode restrictions

In a future release, when you set Mode to 'Normal', the function will create a protected model that supports simulation when the parent model simulates in normal, accelerator, or rapid accelerator mode. This change will standardize simulation support for new protected models. Protected models created before this change will be unaffected.

Currently, when you set Mode to 'Normal', the function creates a protected model that supports simulation only when the parent model simulates in normal mode.

R2023a: Default Mode value is 'Accelerator'

Starting in R2023a, the default value of the Mode argument is 'Accelerator'. A model that references the protected model can run in normal, accelerator, or rapid accelerator mode.

With this change, the Create Protected Model dialog box and Simulink.ModelReference.protect function use the same default model protection mode.

Previously, the default value of the Mode argument was 'Normal'. The 'Normal' model protection mode restricts the use of the protected model such that the protected model supports simulation only when the parent model simulates in normal mode.

R2022a: Tunable parameters for simulation are specified by the TunableParameters argument

Starting in R2022a, you must specify the parameters of the protected model that you want to be tunable during simulation by using the TunableParameters name-value argument. By default, no parameters are tunable during simulation.

Previously, a parameter was tunable when its code generation storage class was set to a value other than Auto. By default, the storage class for an individual data element is Auto.