Hiding Technical Implementation - dSPACE

FAQ 022

Hiding Technical Implementation Keywords encrypting models; hiding implementation; subsystems; S-functions; model referencing; protected model Question I want to share my model or my S-function with other companies without providing the model or Sfunction source code. How can I hide the information and technology in my model or S-function? Relevant Products Real-Time Interface (RTI) and ConfigurationDesk, differences between Real-Time Interface (RTI) and ConfigurationDesk are explicitly marked. Solution You can hide the technical implementation of an S-function by distributing the required object files together with a dummy C source file. If you want to hide the technical implementation of a model or submodel, you must first convert the model into an S-function. Therefore, use the Simulink Coder™ (formerly Real-Time Workshop) to generate an S-function from a model/submodel. Another approach is using protected models. In this case, an encrypted referenced model is shared.



You cannot use the encrypted S-function file in a different MATLAB or dSPACE Release than the one it was created with, and you must use it for the same dSPACE platform it was created for.



Make sure to use the encrypted S-function files only in the timer task mode it was created for. For example, do not use an S-function file that was created in the single timer task mode if the model is to be built in the multiple timer task mode.



Make sure that the model or subsystem you want to generate does not contain any RTI blocks or Model Port block and blocks from TargetLink Blockset (standalone). Since TargetLink 3.x, most of the blocks from the TargetLink Blockset (standalone) are based on standard Simulink blocks, and therefore can be used in the model or the subsystem.

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 1

Table of Contents

How to Hide the Implementation of a Handcoded S-Function

3

How to Hide the Implementation of a Generated S-Function

5

How to Hide Technical Implementation Using a Protected Model

8

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 2

How to Hide the Implementation of a Handcoded S-Function

1. It is assumed that the S-function is named sfun. If your S-function has a different name, adjust the instructions accordingly. Generate the sfun.mexw1 MEX DLL file from the sfun.c S-function source file. 2. Run the build process for a real-time model that contains the sfun S-function. Depending on the hardware platform and the timer task mode, the following real-time object file for the Sfunction is placed in the build directory. RTI: _rti ConfigurationDesk: \ Build\\Compile Platform

Single Timer Task Mode

Multiple Timer Tasks Mode2

DS1005

sfun.o50

sfun.m50

DS1006

sfun.o86

sfun.m86

DS1007

sfun.o07

sfun.m07

DS1103

sfun.o04

sfun.m04

DS1104

sfun.o03

sfun.m03

DS1202

sfun.o07

sfun.m07

DS1401

sfun.o03

sfun.m03

SCALEXIO

sfun.o86

sfun.o86

Subsequently, the extension is used as a placeholder. 3. Rename the object file (keeping the file name extension). For example, sfun_hiddensrc. 4. Create an empty sfun.c dummy file (it can contain C comments). 5. Distribute the following files to the end user:



sfun.c (the dummy file)



sfun.mexw1



sfun_hiddensrc.

6. The end user must specify the sfun_hiddensrc. file at Include list of additional – Libraries (space-separated list) in the Code Generation (formerly Real-Time Workshop) – Custom Code pane of the Configuration Parameters dialog (refer to FAQ 298 for more information and alternatives).

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 3

7. sfun.mexw1, sfun_hiddensrc. and sfun.c (the dummy file) must also be kept in the working directory of the model unless the path information has been introduced to the build process (please refer to FAQ 298) If external C modules are used in the S-function, the external C source files can be encrypted in a similar manner. Instead of using the renamed object file, it is also possible or even necessary to create a library from the object file, and use this library. For detailed information on how a library can be created and used, refer to FAQ 012 and FAQ 298.

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 4

How to Hide the Implementation of a Generated S-Function

1. It is assumed that you want to create an S-function from a model named sfun.slx4 or a subsystem named sfun. If your model or subsystem has a different name, adjust the instructions accordingly. RTI blocks or Model Port blocks do not support Simulink Coder’s S-Function Target and Generic Real-Time Target. This is why the model or subsystem you want to generate must not contain any RTI blocks or Model Port blocks. There is no option to work around this limitation. 2. Use the S-function target of Simulink Coder (formerly Real-Time Workshop) to generate the sfun_sf S-function from the sfun.slx4 model or the sfun subsystem. As a result, Simulink Coder generates an sfun_sf S-function block, an additional subdirectory sfun_sfcn_rtw, the header and source files, e.g., sfun_sf.c, sfun_sf.h, and the sfun_sf.mexw1 MEX DLL file in the working directory. For more information on the S-function target, refer to the Simulink User's Guide by The MathWorks. 3. Place the generated sfun_sf S-function block in a new model and run the build process for the intended hardware platform in the current working directory. Depending on the hardware platform and the timer task mode, the following real-time object file is placed in the build directory. RTI: _rti ConfigurationDesk: \ Build\\Compile Platform

Single Timer Task Mode

Multiple Timer Tasks Mode2

DS1005

sfun_sf.o50

sfun_sf.m50

DS1006

sfun_sf.o86

sfun_sf.m86

DS1007

sfun_sf.o07

sfun_sf.m07

DS1103

sfun_sf.o04

sfun_sf.m04

DS1104

sfun_sf.o03

sfun_sf.m03

DS1202

sfun_sf.o07

sfun_sf.m07

DS1401

sfun_sf.o03

sfun_sf.m03

SCALEXIO

sfun_sf.o86

sfun_sf.o86

Subsequently, the extension is used as a placeholder. 4. Rename the object file (keeping the file name extension), for example, sfun_sf_hiddensrc. Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 5

5. Create an empty sfun_sf.c dummy file (it can contain C comments) in the working directory. 6. Distribute the following files to the end user: Files3 from the working directory1 MATLAB R13.x

MATLAB R14.x and later

sfun_sf.c (the dummy file)

sfun_sf.c (the dummy file)

sfun_sf.dll

sfun_sf.mexw

sfun_sf_hiddensrc.

sfun_sf_hiddensrc.

sfun_sf.h (contains an include directive for sfun_sfcn_rtw\sfun_sf.h)

sfun_sf.h (contains an include directive for sfun_sfcn_rtw\sfun_sf.h)

Files3 from the subdirectory sfun_sfcn_rtw MATLAB R13.x

MATLAB R14.x and later

sfun_sf.h

sfun_sf.h

sfun_sid.h

sfun_sid.h

sfun_sf_private.h

sfun_mid.h

sfun_sf_types.h

sfun_sf_types.h sfun_sf_private.h sfun.mk rt_look.c (*) rt_look.h (*) rt_look1d.c (*) rt_look1d.h (*) rt_look2d_normal.c (*) rt_look2d_normal.h(*) buildinfo.mat (*)

The code that is generated for your model requires the header files. This should not be a problem because no practical information is contained in the files. -

If the Simulink® blocks Lookup and Lookup (n-D) are used in the sfun.slx model or in the sfun subsystem, additional files have to be placed in the reduced S-function directory (sfun_sfcn_rtw). These files are marked with

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 6

(*). -

If the generated S-function contains Stateflow charts or blocks from a Simulink blockset, more header files may be necessary.

7. The end user has to specify the sfun_sf_hiddensrc. file at Include list of additional – Libraries (space-separated list) on the Code Generation (formerly Real-Time Workshop) – Custom Code pane of the Configuration Parameters dialog (please refer to FAQ 298 for more information and alternatives). 8. sfun_sf.mexw1, sfun_sf_hiddensrc. and sfun_sf.c (the dummy file) must also be kept in the working directory of the model unless the path information has been introduced to the build process (please refer to FAQ 298). The first sfun_sf.h file (originating from the working directory) consisting of a single include directive must be kept in the working directory. The second sfun_sf.h file, the make file (MATLAB R14.x and later), and the other header files have to be located in the sfun_sfcn_rtw subdirectory. You must create this directory manually. When you build a model, the sfun_sf.c dummy file is compiled and linked to the application. However, this does not have any effect because the source file is empty. The reference to the Sfunction calls in the generated model code is resolved by linking the sfun_sf_hiddensrc. file, which contains the real-time object code of the S-function. Instead of using the renamed object file, it is also possible or even necessary to create a library from the object file, and use this library with RTI. For detailed information on how a library can be created and used, refer to FAQ 012 and FAQ 298.

Footnotes 1

Since MATLAB R14SP2, the MEX file extension .dll has been replaced by .mexw32. For 64-bit MATLAB, .mexw32 is replaced by .mexw64.

2

In the multiple timer task mode files with the extension *.m are generated, if the respective model consists of at least two timer tasks.

3

The list of files makes no claim to be complete. Certain modelling might require further header and source files.

4

The model file extension .slx was introduced with MATLAB 2012a. Before, the file extension .mdl was used.

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 7

How to Hide Technical Implementation Using a Protected Model

Another approach of hiding technical implementation is using protected models. Protected models are a feature of Simulink. From a technical point of view, protected models are referenced models with a DRM protection. Note the limitations for protected models in the MATLAB/Simulink documentation. In particular, protected models may not contain non-inlined S-functions. A protected model can be created as follows: 1. Place the part to be protected in a subsystem. 2. Make the subsystem atomic: Right-click it and select ‘Block Parameters’ from the context menu, check the option ‘Treat as atomic unit’. 3. To generate a referenced model from the subsystem a. go to ‘Model Configuration Parameters – Diagnostics – Data Validity’ of your model and set ‘Signal resolution’ to ‘None’ or ‘Explicit only’. b. Right-click the subsystem and select ‘Subsystem & Model Reference – Create Referenced Model’ from the context menu. 4. To generate a protected model from the referenced model a. right-click the model block and select ‘Subsystem & Model Reference’ – ‘Create Protected Model …’ from the context menu. b. Select the option ‘Use generated code’. c.

Set the content type to ‘obfuscated source code’.

5. Replace the referenced model with the protected model in the model block. 6. You can now provide the protected model (slxp file) to a third party. 7. The protected model can be used similarly to usual referenced models.

The main and the protected model need to be created with the same tool chain, including dSPACE and MATLAB software. This includes RCP and HIL software, MATLAB, and the selected target file.

-

We recommend at least MATLAB 2013b when working with protected models. o

-

The first supported version is MATLAB 2013a but there are known issues with this version.

SCALEXIO requires at least MATLAB 2014a or later.

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 8

Protected models require at least dSPACE Release 2014-A. -

For SCALEXIO dSPACE Release 2015-B or later is required.

Note that the TRC file generation changed with MATLAB 2015b. These changes also affect referenced and protected models. If you want to benefit from these changes, use dSPACE 2015-B and MALTAB 2015b or later.

Related dSPACE HelpDesk Documents 

Software – RTI and RTLib – RTI and RTI-MP Implementation Documents - RTI and RTI-MP Implementation Guide – Referencing Models

Related FAQ 

FAQ 012 Creating Libraries for RTI



FAQ 298: Best Practice for Handling S-Functions, Libraries and Additional Source Files

FAQ Overview http://www.dspace.com/go/faq Support To request support, please use the form at http://www.dspace.com/go/supportrequest Updates and Patches Software updates and patches are available at http://www.dspace.com/go/patches. dSPACE strongly recommends to use the most recent patches for your dSPACE installation. Important Notice This document contains proprietary information that is protected by copyright. All rights are reserved. The document may be printed for personal or internal use provided all the proprietary markings are retained on all printed copies. In all other cases, the document must not be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of dSPACE GmbH. © 2017 by: dSPACE GmbH Rathenaustraße 26 33102 Paderborn Germany This publication and the contents hereof are subject to change without notice. A list of registered dSPACE trademarks is available at: http://www.dspace.com/go/Trademarks

Hiding Technical Implementation FAQ Version: 12 / 2017-08-25 Page 9