Simulink.ModelReference.protect - Obscure referenced model contents to hide intellectual property - MATLAB (original) (raw)

Obscure referenced model contents to hide intellectual property

Syntax

Description

[harnessHandle](#btrh4%5Fd-harnessHandle) = Simulink.ModelReference.protect([mdl](#btrh4%5Fd-model)) creates a protected model from the model specified by mdl. The protected model has the same name as the source model and an.slxp file extension. By default, the software places the protected model in the current working folder.

When model protection creates and opens a harness model, the handle of the harness model is returned by harnessHandle. By default,harnessHandle returns 0.

example

[harnessHandle](#btrh4%5Fd-harnessHandle) = Simulink.ModelReference.protect([mdl](#btrh4%5Fd-model),[Name=Value](#namevaluepairarguments)) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, to collect the dependencies in a project, set Project totrue.

example

[[harnessHandle](#btrh4%5Fd-harnessHandle),[neededVars](#btrh4%5Fd-neededVars)] = Simulink.ModelReference.protect(___) returns the names of base workspace variables used by the protected model inneededVars. Specify an input argument combination from the previous syntaxes.

example

Examples

collapse all

Open an example that contains the referenced model namedCounterAlgorithm.

openExample('simulink/ComponentInterfaceSpecificationUsingBusesExample')

Protect the referenced model.

mdl = "CounterAlgorithm"; Simulink.ModelReference.protect(mdl);

The Simulink.ModelReference.protect function creates a protected model named CounterAlgorithm.slxp in the current working folder.

In the base workspace, the function returns 0 for the harness handle because the model protection process does not create a harness model by default.

When a Model block does not specify a file extension, the block refers to the protected model instead of the original model. By default, the model that references the protected model can run in normal, accelerator, or rapid accelerator mode.

When you generate code for a protected model, a model that references the protected model can support code generation.

For example, generate C and C++ code when you protect a referenced model named CounterAlgorithm.

Open an example that contains the referenced model.

openExample('simulink/ComponentInterfaceSpecificationUsingBusesExample')

Protect the referenced model, generate C and C++ code for the protected model, and do not obfuscate the generated code. Generating readable code for the protected model helps recipients integrate the protected model code with their own code.

mdl = "CounterAlgorithm"; Simulink.ModelReference.protect(mdl, Mode="CodeGeneration", ... ObfuscateCode=false);

The function creates a protected model named CounterAlgorithm.slxp. A model that references the protected model can support C and C++ code generation.

For another example, generate HDL code when you protect a referenced model named hdlcoder_referenced_model_gain.

Open an example that contains the referenced model.

mdl = "hdlcoder_referenced_model_gain"; openExample(mdl)

Protect the referenced model and generate HDL code for the protected model.

Simulink.ModelReference.protect(mdl, Mode="HDLCodeGeneration");

The function creates a protected model namedhdlcoder_referenced_model_gain.slxp. A model that references the protected model can support HDL code generation.

To create a protected model that supports C, C++, and HDL code generation, set Mode to "CodeGeneration" andhdl to true.

When you plan to share a protected model with third parties, package the protected model, a harness model, and the supporting files in a project.

Open an example that contains the referenced model namedCounterAlgorithm.

openExample('simulink/ComponentInterfaceSpecificationUsingBusesExample')

Protect the referenced model and collect the protected model dependencies in a project. Optionally, generate a report that describes the supported functionality.

mdl = "CounterAlgorithm"; Simulink.ModelReference.protect(mdl, Project=true, Report=true);

The function creates a protected model namedCounterAlgorithm.slxp and a project archive namedCounterAlgorithm_protected.mlproj.

The project archive contains:

• The protected model namedCounterAlgorithm.slxp
• A harness model namedCounterAlgorithm_harness.slx
• A data dictionary namedBusTypes.sldd
• A Simulink® cache file namedCounterAlgorithm_harness.slxc

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 the missing files. Add the missing dependencies to the project and update the harness model as needed.

To share the protected model with a third party, share the project archive. For more information on how to create a project archive, see Share Projects.

For information about how recipients can use the protected model and project archive, see Reference Protected Models from Third Parties.

The protected model automatically stores some information, such as the name and version of the design file and the platform used to create the protected model. When a continuous integration system creates the protected model, consider including provenance information such as the job number, Git™ commit, or continuous integration system tag associated with creating the protected model.

For example, suppose you use Jenkins® for continuous integration. Create a tag that contains provenance information for the protected model. For example, construct the tag using the GIT_COMMIT and BUILD_ID variables from the Jenkins environment.

JenkinsInfo = [getenv("GIT_COMMIT")+"@"+getenv("BUILD_ID")];

Protect the model and include the tag with the file provenance information. Optionally, generate a report that includes the model version used to generate the protected model. In this example, the model to protect is specified by mdl.

Simulink.ModelReference.protect(mdl, Tag=JenkinsInfo, Report=true);

The function creates a protected model. To get the information stored in the tag, open the protected model report or use the slxpinfo function.

To simulate a model that references a protected model, you might need to define variables in the base workspace or data dictionaries. For example, theCounterAlgorithm 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.

Open an example that contains the referenced model namedCounterAlgorithm.

openExample('simulink/ComponentInterfaceSpecificationUsingBusesExample')

Generate the protected model, create a harness model for the protected model, and determine the variables required by the protected model.

mdl = "CounterAlgorithm"; [harnessHandle,neededVars] = Simulink.ModelReference.protect(mdl, ... Harness=true)

The harness model handle is given byharnessHandle.

The variables you must send the recipient are given byneededVars. The value ofneededVars 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

collapse all

Model to protect, specified as a character vector or string scalar. Specify the name of the model that you want to protect or the path of theModel block that references the model that you want to protect.

Data Types: char | string

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=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.

Example: Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",OutputFormat="Binaries",ObfuscateCode=true) specifies that obfuscated code be generated for the protected model and that only binary files and headers in the generated code be visible to users of the protected model.

File Creation Options

expand all

Since R2020b

Option to collect dependencies in project, specified as false ortrue.

Specify whether to package supporting files, including a harness model, with the protected model in a project archive. The type and number of supporting files depends on the model being protected. Examples of supporting files are a MAT file with base workspace definitions and a data dictionary pruned to relevant definitions. The supporting files are not protected.

• false — Create only the protected model. If the protected model has dependencies, you must share them separately. Similarly, if you create a harness model for the protected model, you must share the harness model separately.
• true — Create a project archive (.mlproj) that contains the protected model, its dependencies, and its harness model. The supporting files are not protected. The project archive is a single file that allows for easy sharing. To create the interactive project, open the project archive.

Example: Simulink.ModelReference.protect(mdl,Project=true)

Tips

Before sharing the project, check whether the project contains the required 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. For more information, see Manage Project Files.

Dependencies

To set Project to true, setMode to a value that supports simulation. For example, set Mode to"Simulation" (default).

Data Types: logical

Since R2020b

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

Specify the name of the project archive that contains the generated files. The project inside the archive uses the same name.

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

Example: Simulink.ModelReference.protect(mdl,Project=true,ProjectName="MyProject")

Dependencies

To enable this argument, set Project totrue.

Data Types: char | string

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

Specify whether to create a harness model for the protected model. The harness model provides an isolated environment for the protected model, which is referenced by a Model block.

• false — Do not create a harness model for the protected model.
• true — Create a harness model for the protected model.

When you create a harness model for a protected model that relies on base workspace definitions, the software 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: Simulink.ModelReference.protect(mdl,Harness=true)

Dependencies

• To set Harness totrue, set Mode to a value that supports simulation. For example, setMode to"Simulation" (default).
• When you set Project to true,Harness is set to true.

Data Types: logical

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

Example: Simulink.ModelReference.protect(mdl,Path="C:\Work")

Dependencies

The model being protected must be on the MATLAB® path.

Data Types: char | string

Since R2024b

Custom text string for additional information, specified as a character vector or string scalar.

Being able to trace a protected model to the corresponding version of the design file can be useful for debugging. To store file provenance information in a protected model, specify a custom text tag with information such as the job number, Git commit, or continuous integration system tag associated with creating the protected model.

The tag length must not exceed 256 characters.

To generate a tag based on environment variables, use the getenv function.

Example: Simulink.ModelReference.protect(mdl,Tag=_`myTag`_)

Data Types: char | string

Since R2024b

Verbose output of build process information, specified as a numeric or logical 1 (true) or0 (false).

By default, the model protection process displays limited build process information. To display verbose build process information during model protection, set Verbose totrue.

To control the display of build process information, the model protection process temporarily overrides the values of the Verbose accelerator builds and Verbose build configuration parameters.

Example: Simulink.ModelReference.protect(mdl,Verbose=true)

Data Types: logical

Functionality Options

expand all

Option to generate report, specified as a Boolean value.

To view the report, perform one of these actions:

• Simulink Editor: On the Model block, right-click the protected-model badge icon . Then, select Display Report.
• MATLAB Command Window: Use the Simulink.ProtectedModel.open function. For example, to display the report for a protected model specified by mdl, enter this command.
  Simulink.ProtectedModel.open(mdl,"report");

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

Example: Simulink.ModelReference.protect(mdl,Report=true)

Dependencies

To set Report to true, setMode to a value that supports simulation. For example, set Mode to"Simulation" (default).

Data Types: logical

Option to include read-only web view, specified as a Boolean value.

Specify whether to share an interactive rendition of a Simulink model that the recipient can view in a web browser. This read-only web view of the model includes the contents and block parameters of the model.

• false — Do not share a web view of the model that you protect.
• true — Share a web view of the model that you protect.

To open a web view of a protected model, perform one of these actions:

• Files panel: Double-click the protected model file (.slxp).
• MATLAB Command Window: Use the Simulink.ProtectedModel.open function. For example, to display the web view for a protected model specified by mdl, enter this command.
  Simulink.ProtectedModel.open(mdl,"webview");

Example: Simulink.ModelReference.protect(mdl,Webview=true)

Dependencies

Creating a read-only web view of the model requires a Simulink Report Generator™ license.

Data Types: logical

Model protection mode, specified as one of these values:

• "Simulation" (since R2023b) — A model that references the protected model can run in normal, accelerator, or rapid accelerator mode.
  Before R2023b: Use"Accelerator" instead of"Simulation".
• "CodeGeneration" — A model that references the protected model can run in normal, accelerator, rapid accelerator, or external mode and can support C and C++ code generation. This option requires a Simulink Coder™ license.
• "HDLCodeGeneration" — A model that references the protected model can run in normal, accelerator, or rapid accelerator mode and can support HDL code generation. This option requires an HDL Coder™ license.
• "ViewOnly" — The protected model supports only a read-only web view. The protected model does not support simulation or code generation. This option requires aSimulink Report Generator license.

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

Example: Simulink.ModelReference.protect(mdl,Mode="Simulation")

Interface for generated code, specified as one of these values:

• "Model reference" — A Model block that references the protected model can support C and C++ code generation and simulation in accelerator, software-in-the-loop (SIL), or processor-in-the-loop (PIL) mode. For SIL and PIL simulations, the software deploys the generated code as part of a larger application that uses the referenced model. The generated artifacts match those generated by theslbuild function with the "ModelReferenceCoderTarget" build specification.
• "Top model" — A Model block that references the protected model can support simulation in accelerator, software-in-the-loop (SIL), or processor-in-the-loop (PIL) mode. For SIL and PIL simulations, the software deploys the generated code as a standalone application. The generated artifacts match those generated by the slbuild function with the "StandaloneCoderTarget" build specification.

SIL and PIL simulations can verify the protected model code.

Example: Simulink.ModelReference.protect(mdl,CodeInterface="Top model")

Dependencies

The System target file configuration parameter must be set to an ERT-based system target file, for example,ert.tlc. This option requires an Embedded Coder® license.

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

For the protected model to support simulation, C and C++ code generation, and HDL code generation, set Mode to"CodeGeneration" and hdl totrue.

Example: Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",hdl=true)

Tips

For the protected model to support simulation and HDL code generation, but not C or C++ code generation, set Mode to"HDLCodeGeneration". You do not have to sethdl to true.

Dependencies

• To generate HDL code, you must have an HDL Coder license.
• This argument affects the output only when you setMode to"CodeGeneration".

Data Types: logical

Since R2022a

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

Specify the parameters from external data sources that you want the recipient to be able to tune during simulation.

The model protection process honors the tunability of parameters in the model workspace. Model arguments are inherently tunable. You do not need to specify the tunability of model arguments.

When you protect a model that references one or more protected models, specify the tunable parameters of each referenced protected model as also being tunable for the parent model. To get the list of tunable parameters for a protected model, use the Simulink.ProtectedModel.getTunableParameters function.

For more information about tunable parameters for simulation, see Tune and Experiment with Block Parameter Values.

Example: Simulink.ModelReference.protect(mdl,TunableParameters=["param1","param2"])

Data Types: char | string | cell

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

Example: Simulink.ModelReference.protect(mdl,Callbacks={pmcallback_sim,pmcallback_cg})

Data Types: cell

Protection Options

expand all

Option to obfuscate generated code, specified as a Boolean value.

Example: Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",ObfuscateCode=true)

Dependencies

This option is applied only when you set Mode to"CodeGeneration". Obfuscation is not supported for HDL code generation.

Data Types: logical

Protected code visibility, specified as one of these values:

• "CompiledBinaries" — Include only compiled binaries for the generated code. The binary files and headers are visible.
• "MinimalCode" — Include only the minimal header files required to build the code with the chosen build settings. The code in the build folder is visible. Recipients can inspect the code in the protected model report and recompile it for their purposes.
• "AllReferencedHeaders" — Include header files found on the include path. The code in the build folder is visible. The 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: Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",OutputFormat="AllReferencedHeaders")

Dependencies

This argument affects the output only when you set Mode to"Simulation","Accelerator", or"CodeGeneration".

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: Simulink.ModelReference.protect(mdl,Sign="_`certificatefile`_.pfx")

Data Types: char | string

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. The object also provides information on exported symbols that you must not modify. Prior to packaging the protected model, the software calls the postprocessing function.

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

Example: Simulink.ModelReference.protect(mdl,Mode="CodeGeneration",CustomPostProcessingHook=@(protectedMdlInf)myHook(protectedMdlInf))

Dependencies

To enable this argument, set Mode to"CodeGeneration".

Output Arguments

collapse all

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, setHarness to true andProject to false (default).

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

The cell array includes:

• Tunable parameters
• Parameters that are used by the model interface
• Parameters that specify part of a data type, such as a bus object, enumerated type, or value type
• Parameters that are used by data store memory

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

Version History

Introduced in R2012b

expand all

The new Tag argument lets you specify custom text with information that is relevant to the protected model.

Being able to trace a protected model to the corresponding version of the design file can be useful for debugging. To store file provenance information in a protected model, specify a custom text tag with information such as the job number, Git commit, or continuous integration system tag associated with creating the protected model.

To focus on the high-level steps in the model protection process, theSimulink.ModelReference.protect function now displays limited build process information by default. The model protection process temporarily overrides the values of the Verbose accelerator builds and**Verbose build** configuration parameters.

To display verbose build process information during model protection, setVerbose to true.

When you create a harness model for a protected model that has model arguments, the harness model uses the default instance parameter values for theModel block. Previously, the harness model inconsistently applied the instance parameter values.

When you set Mode to 'CodeGeneration', the protected model supports external mode simulation.

The name of the default Mode value has changed from'Accelerator' to 'Simulation'. The behavior of the default value has not changed.

Setting Mode to 'Accelerator' is not recommended. Set Mode to 'Simulation' instead.

• 'Simulation' and 'Accelerator' behave the same.
• 'Simulation' aligns better with the simulation option in the Create Protected Model dialog box.
• 'Accelerator' refers to only one of the supported simulation modes. A model that references a protected model that supports simulation can run in normal, accelerator, or rapid accelerator mode.

There are no plans to remove 'Accelerator'.

Setting Mode to 'Normal' is not recommended. Set Mode to 'Simulation' instead.

• When you set Mode to 'Normal', the function creates a protected model that supports simulation only when the parent model simulates in normal mode.
• 'Simulation' aligns better with the simulation option in the Create Protected Model dialog box. When you setMode to 'Simulation', the function creates a protected model that supports simulation when the parent model simulates in normal, accelerator, or rapid accelerator mode.

There are no plans to remove 'Normal'.

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 andSimulink.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.

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.

To get the list of tunable parameters for a protected model, use the Simulink.ProtectedModel.getTunableParameters function.

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.

When you create a protected model, you can automatically package it with its dependencies and a harness model in a project archive. When the recipient extracts the contents of the project archive and opens the harness model, they should be able to simulate the protected model without needing to define missing variables or objects. Before sharing the project archive, check whether the project contains the required supporting files, and update the harness model as needed.

Use Project to save the protected model, its dependencies, and its harness model in a project archive (.mlproj). The project archive provides a way to share a project in a single file.

Use ProjectName to specify a custom project name.

For more information, see Package and Share Protected Models

See Also

Tools

• Protected Model Creator

Functions

• Simulink.ModelReference.modifyProtectedModel | Simulink.ModelReference.ProtectedModel.setPasswordForModify | Simulink.ModelReference.ProtectedModel.setPasswordForCodeGeneration | Simulink.ModelReference.ProtectedModel.setPasswordForHDLCodeGeneration | Simulink.ModelReference.ProtectedModel.setPasswordForSimulation | Simulink.ModelReference.ProtectedModel.setPasswordForView | Simulink.ModelReference.ProtectedModel.clearPasswords | Simulink.ModelReference.ProtectedModel.clearPasswordsForModel | Simulink.ProtectedModel.getTunableParameters

Topics

• Protect Models to Conceal Contents
• Protected Model Capabilities
• Test Protected Models
• Package and Share Protected Models
• Specify Custom Obfuscators for Protected Models
• Configure and Run SIL Simulation (Embedded Coder)
• Code Interfaces for SIL and PIL (Embedded Coder)
• Define Callbacks for Protected Models
• Reference Protected Models from Third Parties