Knowledge Base

Back

Upgrade Guide

How to upgrade your models to Release 4 v9.0.0

 

When you want to upgrade your models to Release 4 v. 9.0.0, please be aware that this may have an effect on your models and handwritten code. This upgrade guide explains how you can best upgrade your models and projects. Please read this carefully before upgrading to v9.0.0!

Step 1

Make a backup of your models and code.

Step 2

In case any of your models contain deprecated 'secondary references', you'll need to change this before you can upgrade your models to v9.0.0. The concept of secondary references has been removed from v9.0.0, as this was hardly (if ever) used, and had a number of undesired side-effects. The converter cannot automatically remove these secondary references and repair your model properly, and will report that the upgrade has failed. 

To remove the secondary references and still have a working model, see this Knowledge Base article

Note that the effect of secondary references (i.e. to address different used components that implement the same service as a group) can still be achieved by using component construction parameters.

Step 3

Upgrade your models to v9.0.0. Either by opening them in the ASD:Suite ModelBuilder, or by using the commandline tool AsdConvert that enables you to convert all models within your project in one go: 

   AsdConvert --recurse . 

This will upgrade all ASD models in the current directory and all subdirectories to v9.0.0.

     Notes:

  • Upon conversion, data variables may be automatically renamed by the converter to avoid name clashes
  • Upon conversion, all official ITimer.im models will be deleted since it is now a built-in model. However, if there are ANY modifications to the model, it will not be deleted and you have to decide whether to delete it yourself.

Step 4

Use AsdEdit to set the code generator version to v9.0.0 for all models within your project in one go. 

   AsdEdit -v 9.0.0 --recurse .

Step 5

Please follow the links below for a more detailed explanation of how to proceed with the upgrade for these specific items:


Data Variables

Data variables (previously also known as component variables or context variables) are now explicitly declared and verified. During upgrade of your design models, all data variables are automatically declared, with default settings. 

In case a data variable has the same name as a rule case local variable in your model, the converter will postfix the data variable with a number to make the name unique again (for an explanation of rule case local variables see the Parameter Usage section of the User Manual).

During upgrade the properties of the data variables are set such that the data variables are checked for proper validation during verification. 

  • After upgrade, the "Auto-Initialise" property of a data variable is set to "No". In case that the value that the data variable gets upon construction is a value that you want to use in your component, you can change this setting to "Yes". In case of doubt, leave the setting on "No". The verification will tell you whether there may be issues with it. 
  • After upgrade the "Auto-Invalidate" property of a data variable is set to "No". In case you want to make sure that when an action sequence ends (and a transition to a normal state is made), the value of the data variable is no longer valid (to prevent 'data leakage' to other rule cases) you can set the "Auto-Invalidate" property to "Yes".  The data variable is then invalidated at the end of each action sequence. 

To verify the validity of the data variables in your existing models, follow these steps:

  1. Open the model, and open the Data Variables tab. 
  2. Check for data variables with a number postfix. To give these a different name, right-click on the data variable name and choose "Rename all occurrences". This will update the name in the data variables table and all occurrences in the SBS.
  3. For data variables for which you are certain that they are properly initialised upon construction, you can set the "Auto-Initialise" property to "Yes". In case of doubt, leave the property setting on "No". If this is not correct, the verification will tell you. 
  4. Per data variable, filter out rule-cases that contain that data variable (in the Data Variable tab, right-click on the data variable name, and choose "Filter SBS by Data Variable"). Determine which use case the data variable is intended for (crossing rule cases within a single action sequence and within a thread, or crossing threads).

    If its only purpose is to cross rule-cases within an action sequence, set the "Auto-Invalidate" property to "Yes". This will automatically invalidate the data variable at the end of every action sequence, such that the verification checks that for the next time the data variable is used, it is given a proper value again before it is read.

    If the data variable is used to cross threads, it's probably a good idea to add explicit "invalidate" actions to the SBS at relevant locations. You can also use data invariants to check whether the data variable is valid or invalid in a certain state (similar to the state invariants).
  5. Verify your model to check whether the data variables are used properly.

For more details about data variables, see the Data Variables section in the User Manual

 

State Variable Types

In v9.0.0 you can define enumerated types to be used for state variables. During upgrade of your models, all enumerated values that are used in the model (state variable table or SBS) are combined into one type "MyEnumType". This is done to retain the same semantics of the enumerated variables in the model as in previous versions. 

In case you want to separate the enumerated values, you can create additional types, and distribute the enumerated values over these types. 

Note that you can now assign one state variable of enumerated type to another, but they have to be of the same enumerated type. 

For more details about state variable type, see the state variable Type Definition section in the User Manual

 

GetInstance

In v9.0.0, the GetInstance method will always return an interface. In earlier versions there was the possibility to return a component, which has been made deprecated in v8.5.0.  This will have an effect on your handwritten client-code, as the call to the GetInstance method has to be changed from "...Component" to "...Interface".  For a detailed explanation of the exact changes that are needed, including coding examples, see this Knowledge Base article. Note that this only applies to the languages C++, C# and Java. 

 

Namespaces

Namespaces are now available for all languages. For long package names that are for example used in Java, a language specific prefix is introduced, to enable you to have a long package name for Java and still have short namespaces for other languages. 

When upgrading your model, the existing namespace (which is only available for Java) is moved to the namespace prefix. 

In previous versions, for Java only, when constructing a used component, the namespace that that used component is in was taken from the used interface model, and automatically inserted in the component construction by the code generator. In v9.0.0 a design model can have its own namespace. This namespace is to be used in the construction field of the using design model. During upgrade the conversion cannot automatically determine the value for the namespace in the construction field. Therefore, after upgrading models that are used in a Java environment, the construction fields in the Service Dependencies table will have to be checked and updated by you. If the namespace is not correctly set in the construction field, this can lead to compilation errors. 

For more details about using namespaces, see the Namespaces section in the User Manual.

Related to the namespace feature is the property "Use service names in fully qualified names". This is used for proper scoping of the interfaces, to allow different services having the same interface and event names. Upon upgrade the "Use service name in fully qualified names" property is set to false for languages for which code generation properties have been set before. This is to retain backward compatibility of the generated code. For new models, and when you select a language for which you have not set the code generation properties before, this property is set to true. 

 

ASD:Runtime changes

The ASD:Runtime has been restructured, amongst others to allow separation between the Multi-threaded and Single-threaded execution models. This will have an effect on your makefiles, project files and/or buildscripts. These will have to refer to the new runtime filenames. Also the Configurator option has been removed from the ASD:Runtime. An overview of the new runtime filenames you can find in the ASD Runtime Guide:

Since also some of the header files in the ASD:Runtime have changed, you possibly also have to rename them in your handwritten code, in case your handwritten code includes any of the ASD:Runtime files (this may be the case when you've used a design model as a starting point for making a handwritten component).

If your handwritten component is based on a generated stub, you'll need to regenerate the stubs and merge this with the existing stub-based handwritten component such that only the "custom code sections" of the existing component are copied over to the new generated stub.

For C and TinyC the ASD:Runtime contains a configurable header file, enabling you to configure your project to use those parts of the ASD:Runtime that are relevant to your project. For more details about this configuration, see the pages on customization and optimization in the ASD Runtime Guide.

The ASD:Runtime also includes more concurrency between a client component and an ASD component. When an action following a used notification contains a client reply event, then the client is now immediately released. Previously the client thread remained blocked until the action sequence had been completed (this was a subset of the verified behaviour). This can possible affect the runtime execution of your project, as more (verified) behaviour is now possible. Especially if any handwritten components depend on less concurrency, they may need to be re-tested. 

For more details please see the runtime execution semantics section in the ASD Runtime Guide.

Furthermore the "Configurator" option has been removed from the ASD:Runtime. In case your project contains service references of which the cardinality is defined at construction time (using the '*' in the cardinality field), you can achieve the same by using construction parameters. That way your handwritten code instantiates the desired number of instances, and these are passed as a vector via a construction parameter to the client ASD component.

For more information on how to achieve this in the various languages, see C++, C#, Java, C / TinyC

 

Construction Parameters (C only)

In C, a construction parameter of type used service reference is now always passed as vector, even if the cardinality is 1. This means that a handwritten (client) component that instantiates the ASD component will have to include an extra cardinality parameter with the GetInstance method. 

For example: in case the design model Alarm.dm contains a construction parameter 

   [in]sensors:service[](Sensor)


Then the constructor for this Alarm component is generated as:

   Alarm* Alarm_construct(Alarm* self, SensorInterface_Intf* sensors[], asdUInt sensors_size);


Therefore the calling client has to include the sensors_size parameter in the GetInstance call. 

 

Using command-line tools in your build environment

The set of command-line tools has been extended and reorganised. This may impact your build-environment:
  • ASDC has been split into various command-line tools:

    - AsdGenerate to generate code or download the ASD:Runtime

    - AsdAuthorize to check the available languages and versions and to save your user credentials into the registry

    This means that if you currently use ASDC in your build environment, you have to change this into AsdGenerate. For example:

       asdc -g -l cpp -v 8.4.0 *.dm

    now becomes

       AsdGenerate -l cpp -v 9.0.0 *.dm
  • Command-line verification has been added. You can use AsdVerify to:

    - check whether ASD models are verified

    - check whether generated code is generated from a verified model

    - verify all ASD models in your project for which the verification status is out-of-date

For more details about the use of the command-line tools, see the Command-line Tools section in the User Manual. For more details about how to integrate the command-line tools in your build environment see the Build Integration Guidelines in the ASD Runtime Guide.