Using the dSPACE Data Dictionary in a Multi-User Environment

Version: 1.0

January 2006

How to Contact dSPACE Mail dSPACE GmbH

Technologiepark 25 D-33100 Paderborn Germany

Phone +49-5251-1638-0 Fax +49-5251-66529 E-mail info@dspace.de Web http://www.dspace.de Subscription to e-mail newsletter http://www.dspace.de/en/Support/enews.htm Technical support support@dspace.de

Software Updates and Patches dSPACE strongly recommends that you download and install the most recent patches for your current dSPACE installation. Visit http://www.dspace.de/en/Support/Support.htm for software updates and patches.

Important Notice This document contains proprietary information that is protected by copyright. All rights are reserved. Neither the documentation nor software may 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. © Copyright 2001-2002 by: dSPACE GmbH Technologiepark 25 D-33100 Paderborn Germany This publication and the contents hereof are subject to change without notice. dSPACE GmbH makes no warranty of any kind with regard to this publication, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. dSPACE GmbH shall not be liable for errors contained herein or direct, indirect, special, incidental, or consequential damage in connection with the furnishing, performance, or use of this publication. Brand names or product names are trademarks or registered trademarks of their respective companies or organizations.

3

Contents

Contents

Abstract 4

Basic Concept 5

Setting up the Environment 7 Creation of a Global DSDD FILE ...................................................................... 7 Data Dictionary Objects for Code Generation ................................................... 8 Setting Access Rights for Protection................................................................. 8

Export of DSDD Files.............................................................................................. 8 Creation of a Local DSDD File.............................................................................. 10

Associating DD and Model for the Local Developer........................................ 10 Configuration of the Local DSDD File ............................................................. 11

Typical Workflow 12 Data Handling by the Individual Developer........................................................... 12 Data Handling by the Administrator ...................................................................... 14

Appendix 15 Reference ....................................................................................................... 15 Abbreviations .................................................................................................. 15

Abstract

Abstract

TargetLink, the automatic production code generator from dSPACE, is fully integrated in the MATLAB®/Simulink®/Stateflow® environment and performs highly efficient C code generation for microcontrollers in electronic control units (ECUs).

For ECU development, TargetLink is often used by multiple users in one development department. The users work simultaneously on different models, which are finally combined in one ECU application. Special support must be given to such multi-user environments, since administering the data and keeping it consistent is an important objective.

The dSPACE Data Dictionary (DSDD), which was introduced with TargetLink 2.0, provides new features for supporting multi-user environments. This application note describes how to set up TargetLink in a multi-user environment to ensure a consistent workflow for all users and how to work in that framework.

5

Basic Concept

Basic Concept

In multi-user environments it is necessary to ensure that the workflow is consistent for all users and that the environment can be easily adapted to new project configurations. Project-related information and data must be kept in data repositories, for which the dSPACE Data Dictionary (DSDD) is used in combination with TargetLink. It is also recommended to use more than one DSDD to store the information. Figure 1 shows the basic concept.

.

Figure 1: Use of various data dictionaries (DSDDs) in a multi-user environment. Global data relevant for all developers is stored in a global DSDD (optionally, multiple global DSDDs can be used). The data in the global DSDD is then made available and kept up to date for each individual developer (only one is displayed here) via the data dictionary include mechanism.

6

Basic Concept

The process involves a global DSDD, which stores data that has to be made available to each developer working on an individual part of the ECU application. Global data is information which must not be altered or set by the individual developer but has global significance for the entire project or ECU application. This might involve interface variables, their scalings, typedefs, etc., which should be stored in the global DSDD. The challenge is to keep the global data up to date and consistent for all individual developers with minimum maintenance effort. This is achieved by the DSDD include mechanism, which makes the data in the global DSDD available to all users. The global DSDD and the data in it must be maintained by an administrator.

Each local user (developer) working on an individual model (part) uses a local DSDD which not only stores the data relevant to that model (part) but also provides access to the global information defined in the global DSDD. Access is established by the include mechanism of the DSDD, which ensures that the local DSDD contains all the relevant information from the global DSDD and keeps it up to data, i.e., as defined by the administrator. Any modifications to the global data require only changes in the global DSDD, which are reflected almost immediately in the local DSDD files of the individual developers.

The application note is divided into two main chapters:

Setting up the Environment

Typical Workflow

The first chapter describes all the tasks an administrator and local users have to perform before starting actual development. The typical workflow using the DSDDs is described in the second chapter.

7

Setting up the Environment

Setting up the Environment

Creation of a Global DSDD FILE First the administrator has to create the global DSDD file which stores all the global data that have to be made available consistently for all developers.

A new data dictionary file can be created from scratch most easily by using the data dictionary Manager (DSDDMAN), see Figure 2, which is a graphical user interface for handling DSDDs. The DSDDMAN also provides some predefined templates to support you in creating data dictionary files from scratch. The templates contain a number of predefined DSDD objects like scalings, typedefs, variable classes, etc., which are generally useful and can serve as starting points for the creation of project-specific data dictionary objects.

Figure 2: To open the data dictionary manager, enter dsddman on the MATLAB command line. A new DSDD file is created via the menu item New DD Project File and the subsequent selection of a data dictionary template. The Advanced Template provides the maximum number of predefined data dictionary objects for the file to be created.

8

Setting up the Environment

Data Dictionary Objects for Code Generation Most of the data needed for production code generation is stored in the Pool area of the data dictionary (path /Pool), where you can create variable classes, scalings, typedefs, function classes, templates, and RTOS-related data to specify code generation properties for TargetLink.

All the variables, global scalings, typedefs that must be available for all developers have to be created in the Pool area of the global DSDD. This should be performed by the administrator, who is then also responsible for maintaining the objects whenever changes are necessary.

The Data Dictionary Manager is also the best way to create and modify objects in the data dictionary, see Figure 3.

Setting Access Rights for Protection The Data Dictionary supports the use of different roles and associated access rights to protect data dictionary objects from undesired modification or deletion. The roles that are supported are that of an administrator of a DSDD file and that of an ordinary user. Read and write access to individual areas of a DSDD file is then granted by the administrator. In addition, a password can be specified to prevent swapping to the administrator mode.

This mechanism can be used to protect the global DSDD file, i.e., global data required for all developers, from undesired modifications. The administrator must have full read/write access to all data in the global DSDD, but write permission to the global data should be denied to individual developers, see Figure 4.

Export of DSDD Files Once a global DSDD file has been created, it is useful to store the contents of its individual branches, like those for variables, typedefs, scalings, etc., in separate files, see Figure 5. This enables the data dictionary include mechanism to be used to include the branches of the global DSDD in local data dictionary files.

Since the data dictionary files must be accessible to all local developers, they should be stored on a network drive. Then everyone can work with the same settings of the global DSDD file.

Figure 3: The Pool area of a DSDD file displayed with the data dictionary manager. DSDD objects like variables, scalings, variable classes, etc., that must be accessible to all developers, should be created in the global DSDD.

9

Setting up the Environment

Figure 4: The access rights for individual branches of the DSDD can be set via the access dialog, which is opened by right-clicking an object. Read and write access can be specified separately for administrators and ordinary users. Changing from User mode to Admin mode via the menu can be protected by an admin password (menu item Set Admin Password).

Figure 5: To grant each developer access to the global DSDD objects, the branches for scalings, typedefs, variables should be stored in separate files. The Save as option is available after the proper branch has been selected and a consecutive right mouse click.

10

Setting up the Environment

Creation of a Local DSDD File In addition to the global data dictionary, all developers need their individual local DSDD files to store data that is specific to their model (part). Access to the required global data is provided via the data dictionary include mechanism. The TargetLink model that a developer is working on must be associated with the local DSDD file.

Since the preparations for all local developers are identical, it might make sense to automate the procedure to set up the local DSDD file via a MATLAB M script that makes use of the DSDD´s and TargetLink´s M-API. This ensures correct settings for all models in the ECU application.

The following steps demonstrate how to set up the local DSDD manually for an individual developer for use in the multi-user environment.

Associating DSDD and Model for the Local Developer

A data dictionary file for an individual developer can be created as described in a previous section. However, there is a difference in that the local DSDD is used directly for working with TargetLink models. The data dictionary file must therefore also be associated with the corresponding model, see Figure 6.

Figure 6: To associate a TargetLink model with a data dictionary file, select Associate model with fixed DD project file from the Options tab of the TargetLink Main Dialog. If the data dictionary does not yet exist, it can be created from scratch, for instance by using one of the templates provided.

11

Setting up the Environment

Configuration of the Local DSDD File To make the global data available to all (local) developers, correct information on including branches of the global DSDD files has to be entered, see Figure 7. This involves specifying the data dictionary files to be included, their locations where the files must be hooked into the local data dictionary tree, and options specifying the automatic loading and saving of the included files after the local DSDD file is opened/saved. After these preparations, the DSDDs have been properly set up.

Figure 7: Specifying the include file mechanism in the /Config/DDIncludeFile area of the local DSDD: The DSDD files to be included are those containing global scaling, typedef, variable, etc., objects and they must be specified via the FileName property. The hook where the files are included in the local DSDD is specified via DDPath. The options for AutoLoad and AutoSave determine whether updates to/from the global DSDD files are retrieved/sent automatically whenever the local DSDD file is saved or opened. The presence of included branches in the data dictionary is signaled via changed icons, see the GlobalScaling object, which is included from an external file.

12

Typical Workflow

Typical Workflow

Preparing a TargetLink model for code generation involves not only specifying a lot of code generation options on the block diagram level but also creating and referencing numerous data dictionary objects, such as variables and scalings. The typical workflow for working with global/local data dictionary objects is described in this chapter.

Data Handling by the Individual Developer A lot of the code generation settings in TargetLink involve specifications via data dictionary objects, for example variables and variable classes. These objects reside in the /Pool area of the data dictionary. Objects which have only local relevance, i.e. for individual developers, should be created by developers themselves – for example, specific scaling formulas.

Figure 8: Data Dictionary objects with relevance only for local developers, in this case a scaling object, are created by the developers themselves in the /Pool area of the local DSDD.

13

Typical Workflow

After the object in the local DSDD file has been created, it can be referenced from within TargetLink block dialogs to define the code generation options for a particular variable, see Figure 9. As a result, code is generated exactly as specified by the referenced object in the data dictionary.

Access to DSDD objects with global relevance is granted to local developers through the include mechanism, which maps the global DSDD objects onto the tree of the local DSDD. As long as no additional objects with global relevance are required, developers simply work with their local DSDDs.

If changes to the global data are required, they have to be performed by the administrator in the global DSDD files, as described in the next section. After the modifications have been completed by the administrator, they are included in the local data dictionary files via the include mechanism as soon as developers reopen their local DSDD files.

The DSDD also supports a validation mechanism, which should be applied by both local developers and administrators. This is described in the next section.

Figure 9: In order to set code generation properties for a subsequent code generation step, the developer references data dictionary objects (here a scaling object) from within TargetLink block dialogs. Other DSDD objects like types, variable classes, or variables can of course also be referenced from the data dictionary to specify code generation options.

14

Typical Workflow

Data Handling by the Administrator Whenever modifications to the global data are required, they should be performed by the administrator of the global DSDD file(s). For instance, if an additional scaling formula with global relevance is required at any time during the project, a scaling object must be created in the /pool/scalings branch of the global DSDD. The modified branch of the global DSDD must then be saved to the file which is included by the local developers. Following this procedure, the changes made by the administrator are reflected in the local DSDD files, where the new scaling object appears as soon as the local DSDD file is reopened.

The data dictionary supports a validation mechanism which checks the consistency of the objects against the data model of the data dictionary. It is generally good practice to check the validity of the DSDD objects from time to time to get feedback on the changes made, see Figure 10.

During development, it is important to ensure data consistency in all cases. All modifications in the included files, i.e., the DSDD files exported from the global DSDD file, affect the local DSDD. Both the administrator and the developers must therefore be careful when updating these files because of the risk of potential side effects for the individual developers. However, the include mechanism significantly simplifies data administration in a multi-user environment.

Figure 10: Validation performed on the data dictionary file to check the validity and consistency of the objects. Only the selected branch of the DSDD is validated.

15

Appendix

Appendix

Reference

TargetLink Production Code Generation Guide, dSPACE GmbH

TargetLink Advanced Practices Guide, dSPACE GmbH

Using TargetLink 2.0 in a MultiUser Development Environment, dSPACE GmbH, published at Electronica Embedded, Feb. 2005

Abbreviations

DSDD dSPACE Data Dictionary

DD Data Dictionary

DSDDMAN dSPACE Data Dictionary Manager