Best Practices

• Existing Models
• New Models
• Sending UML events
• Processing UML events
• Names of Runnables
• Critical Regions
• Composition
• Initialization
• Active Class
• self pointer
• Legacy runnables
• Build Environment

Existing Models

• create a copy of your model
• verify if at the Component level, the stereotype RXF is applied, see Profiles.
• add the profiles ArUML_ARXF_CP and ArUML_ARXF using File | Add Profile to Model... and enable As Reference
  These are located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody\Autosar
• determine the names of your SW-C(s). If you do not use the workfklow using M2M, you can inspect SWCD files in ArXML to know what the exact names must be.
• determine the tag supportsMultipleInstantiation of your SW-C(s):
  the RTE will call multiple instantiated SW-Cs with a so-called self pointer, so Rhapsody must know how to generate a runnable: with or without an argument Rte_Instance.
• you must realize that you must allocate your SW-Cs by Rhapsody statically: the RTE instances of your SW-Cs can not be manipulated by Rhapsody.
  
• your existing model may have a main object which instantiates the other objects of your model. Rename this object to the name of the SW-C it must represent.
  If the object is not based on a class of your model, we must explicitely create it: we need the class in order to assign the SWC stereotype. To create this new class: select the object with the RHS mouse and select Expose Class.
  If the object is based on a class of your model, we can use that class.

An SWC must have at least two runnables. If you apply the stereotype CpSWC to an existing class, these runnables are not created: you must add them yourselves.

You need some runnables:

• an ‘init’ runnable which initializes the instance of your SW-C including the ARXF-CP.
• an ‘eventDispatcherSwc’ for the swc task of your SWC in which all sequential classes run. It is also the heartbeat for the ARXF-CP and allows you to use timeouts in your model.
• an ‘eventDispatcher’ for each additional active class; an active class runs in its own task.
  There can be multiple.

The behavior of how Rhapsody generates the symbol for a runnable can be set via a property, see Profiles

The ARXF-CP uses the RTE generated APIs to enter- and exit exclusive areas as Critical Region handlers, see OS Integration.
You need:

• an exclusive area of the ARXF-CP timer list: one exclusive area per SWC.
• an exclusive area of the ARXF-CP memory pools: one exclusive area per SWC.
• an exclusive area of the ARXF-CP UML event list: one exclusive area per RXF task structure: one for the SWC which uses the swc task and one per active class (each active class uses its own UML event queue).

• one for the SWC which uses the swc task
• one per active class (each active class uses its own UML event queue)

Note that for proper code generation, the ARXF-CP needs stereotyped dependencies between runnables towards inter-runnables and runnables towards exclusive areas. For more details, please refer to the section on the SodiusWillert AUTOSAR Profiles.

For sample implementations of runnables, please refer to the Standard Content of an SWC.

If you want that a class runs in its own OS task and processes its own UML event queue, you need an active class, see Concurrency:

• set its concurrency to active
  Note that all instances of this active class will run in the same OS task. Normally RXFs for RTOSses use a different OS task per instance of an active class.
• add an ‘eventDispatcher’ runnable to the SWC where this active class is part of.
  For a sample runnable implementation, please refer to the Standard Content of a SWC. An event dispatcher of an active class usually has the same implementation as an event dispatcher of an SWC.
  You must also add to the SWC where this active class is part of:
  
  • an exclusive area to which RTE enter- and exit functions serve as critical region handlers of the ARXF-CP UML event list for the active class. The new runnable must have a stereotyped dependency to the exclusive area.
  • an inter-runnable variable to which RTE write and read functions are used to exchange the ARXF-CP task information for the active class. The new runnable must have a stereotyped dependency to the inter-runnable variable.

New Models

• select File | New... to create a new model, which is not based on any type or profile
• add the profile RXF using File | Add Profile to Model...
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody
• add the profile RXFStereotypesC using File | Add Profile to Model...
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody
• add the profile RXFTypesC using File | Add Profile to Model...
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody
• add the profile ArUML_ARXF using File | Add Profile to Model...
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody\Autosar
• add the profile ArUML_ARXF_CP using File | Add Profile to Model...
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody\Autosar
• add the package ARXF_CP_AutosarTypes using File | Add to Model... and enable As Reference, see Packages
  It is located in <ARXF_CP_V8.0.1 installation folder>\ARXF_CP_V8.0.1\RXF\Profiles\Rhapsody\Autosar
• add new RXFErrorHandler package for Error handling to your UML model which you can detail later to fit your application needs.
• rename the Component DefaultComponent into something meaningful and apply the stereotype RXF from the profile RXF.
  You may want to use different Configurations: one for AUTOSAR and one for simulation in Windows:
  
  • add two Configurations to the Component
  • select the Features tab of a Configuration and then the Properties tab
  • in the dropdown list, select the RXF property perspective
  • select the Deployer tab and set the property RXF::DeployerFolders::RTOS to Autosar
    

  • on the Configuration for simulation in Windows, you might want to set ARXF_CP::Configuration::AdditionalDefines to #define WINDOWS_SIMULATION
    Use the ARXF-CP property perspective to do this.
• rename the package Default to something more meaningful and apply the stereotype ArPackage from the profile ArUML_ARXF.
add an AUTOSAR composition to the package:

• determine the names of your SW-C(s). If you do not use the workflow using M2M, you can inspect SWCD files in ArXML to know what the exact names must be.
• determine the type of your SW-C(s) with respect to support multiple instantiation or not: the RTE will call multiple instantiated SW-Cs with a so-called self pointer, so Rhapsody must know how to generate a runnable: with or without an argument.
• for each SW-C you want to model (there can be multiple or just one in a Rhapsody project) add an SWC. Standard Content is attached to some stereotypes: you can add an SWC to the model by adding the (New Term) stereotype CpSWC from ArUML_ARXF_CP:
  
  
• you must allocate your SW-Cs by Rhapsody statically: the RTE instances of your SW-Cs can not be manipulated by Rhapsody. The structured class which represents your SW-C is used to contain all classes of your SW-C and now will statically instantiate these inside this structured class.
• the generated C code of your SWC must include the RTE generated contract:
  set the property C_CG::Class::ImpIncludes to the proper contract.
• add the RTE instances of your SWCs to the AUTOSAR composition. The RTE instances are generated by the RTE, but Rhapsody needs to initialize the SWCs using the proper names of the instances. You can add the RTE instances to your model via Add New | ArUML_ARXF | ArSwcPrototype
• you may want to use Reverse Engineering to add a package which shows the AUTOSAR artifacts in your model.
• add exclusive areas used for mutexes: RTE generated APIs to enter- and exit exclusive areas are used in the ARXF-CP as a Critical Region handlers.
  
  • an exclusive area of the ARXF-CP timer list: one exclusive area per SWC.
  • an exclusive area of the ARXF-CP memory pools: one exclusive area per SWC.
  • an exclusive area of the ARXF-CP UML event list: one exclusive area per ARXF-CP task structure: one for the SWC which uses the swc task and one per active class (each active class uses its own UML event queue).
  See Code Generation for more details.
• add inter-runnable variables used to pass ARXF-CP information between runnables: you need one inter-runnable variable per ARXF-CP task structure:
  
  • one for the SWC which uses the swc task
  • one per active class (each active class uses its own UML event queue)
• an SWC created using StandardContent has two runnables:
  
  • an ‘init’ runnable which initializes the instance of your SW-C including the ARXF-CP and connect the AUTOSAR world to the Rhapsody world.
  • an ‘eventDispatcherSwc’ for the swc task of your SWC in which all sequential classes run and the heartbeat for the ARXF-CP, which allows you to use timeouts in your model

  These sample implementations use different runnables for a timerTick and event dispatcher, but you can combine these two. The behavior of how Rhapsody generates the symbol for a runnable can be set via a property, see CpRunnable in Profiles.

• if you want that a class runs in its own OS task and processes its own UML event queue, you must:
  
  • create a new class and set its concurrency to active, see Concurrency.
    Note that all instances of this active class will run in the same OS task. Normally RXFs for RTOSses use a different OS task per instance of an active class.
  • the active class must be part of the SWC (which is a structured class)
  • add an exclusive area which RTE enter- and exit functions serve as critical region handlers of the ARXF-CP UML event list for the active class.
  • add an inter-runnable variable which RTE write- and read functions are used by the ARXF-CP to exchange a task pointer for the active class.
  • add an ‘eventDispatcher’ to the SWC where the active class is part of
    
    • add a stereotyped dependency to the exclusive area
    • add a stereotyped dependency to the inter-runnable variable
  • set the property C_CG::Class::ImpIncludes to the proper contract. Please refer to Reuse of Classes in multiple SW-Cs.

  Sending UML events

  When one sends a UML event to some class, only the pointer to that event is actually send (or added to the FIFO queue of the destination class). Events are either dynamic (although allocated from a static allocated memory pool) or static allocated (sometimes used when sending a UML event from a legacy runnable into your model).

  The ARXF-CP is instantiated per SW-C instance (in AUTOSAR terminology: prototype). As a result, memory allocation functions need an argument so the memory is allocated from the proper memory pool instance. The macro to send a dynamic event is CGEN(), see section Events. The code generation automatically adds an argument so the event is allocated in the proper memory pool instance.

  The macro to send a static event is CGEN_ISR(), see section Events. For compliency reasons, this macro uses the same name of sending an event from within an Interrupt Service Rountine in non-AUTOSAR embedded environments, supported by other RXF products.

  Processing UML events

  The event dispatcher runnables all process UML events from their event queue. Such runnables are of category 2: they run endlessly.

  In order to prevent an Execution Budget exception by the OS, you can specify the maximum number of events such runnable may process as argument to the function RXF_Active_eventDispatcher() which is typically called to process the UML event queue for this task. See Standard Content.
  The runnable will return when there are no more UML events in the queue or when this maximum number of events has been processed.

  Currently there is no property and/or tag to do so at the UML model level: you must modify this via the Implementation tab when selecting the Features of a runnable.

  Names of Runnables

  You can influence the Rhapsody symbol for runnables; see stereotype cpRunnable in Profiles on how to do this.

  Critical Regions

  The ARXF-CP uses the AUTOSAR Exclusive Area mechanism for an exclusive area as critical region handler for accessing ‘global’ data per SW-C: event list, timer list and memory pools. If you need a Critical Region yourselves, you must use a dedicated exclusive area (which is configured by an AUTOSAR authoring tool) and use the RTE generated enter- and exit functions for your Critical Region.

  If you want to use to protect data shared between runnables in your model you must add exclusive areas:

  • add them to your SWC. By making required AUTOSAR artifacts visible, it helps in communicating the AUTOSAR requirements for your model.
  • the imported SW-C contract must contain the related RTE generated enter- and exit functions, which can be verified or used when using these.

  Composition

  In Rhapsody you must specify the instances of your SWCs in order to have the proper package initialization code generated:
  • the RTE instances or prototypes are generated by the RTE, but Rhapsody needs to initialize the SWCs using the proper names of the instances.
    You can add the RTE instances to your model via Add New | ArUML_ARXF | ArSwcPrototype.
  • set the correct Type to the ArSwcPrototype: browse to the appropiate SWC. For example:
    

  The ARXF-CP allows you to model multiple SW-Cs in a single model. For the active Component in your model, Rhapsody generates code to initialize all packages in scope. At the package level, the init() and startBehavior() functions are called by <yourSwc>_Init() from an ‘init’ runnable.

  During Code Generation the functions <yourSwc>_getMe() and <yourSwc>_getSelf() are generated to get the address of your Rhapsody instance versus the RTE instance of your SWC.

  Initialization

  SWC initialization

  This ARXF-CP relies on the fact that a SWC is a structured class: its instance automatically instantiates its parts. At the AUTOSAR level, the RTE also instantiates an SW-C.

  The ‘init’ runnable is responsible for connecting both worlds: AUTOSAR and Rhapsody. During Initialization of your SWC via a call to <yourSwc>_Init(), addresses of ARXF-CP internal pointers are stored into inter-runnable variables. Other runnables of the same SW-C instance can read these inter-runnable variables and via this pointer, process UML events.

  Via this pointer we can access the RXF_SWC structure which relates to the instance of an SWC. It contains a member isInitialized, which we can use to test before calling ARXF-CP functions.

  Please inspect the Standard Content for an SWC.

  Singleton initialization

  Rhapsody does not allow to use a Singleton as a part: you can not use a Singleton within the structured class which represents an SWC. So the code generator does not know to which SWC the Singleton belongs and can not initialize the Singleton. For this reason, you must call the init() and startBehavior() of a Singleton yourselves in your model. These functions are not generated into the init() and startBehavior() at the package level.

  It is good practice to use an initializer in the SWC to call the init() and startBehavior() of the Singleton which belongs to the SWC.

  Structured Class

  If you use a structured class as a part of your SWC, this structured class needs to know its SWC, but its parts do not. Rhapsody generates a function initRelations() for this structured class but the pointer to the SWC has not been initialized yet so you need a workaround.

  Basically the workaround is to initialize this pointer on forehand, using the property CG::Class::AdditionalInitializationCode

  The screenshots below are taken from the SystemTest, where TestPart07_TSK_Controller is a part of SwcB. TestPart07_TSK_Controller in its turn is a structured class, but its parts do not know (or need to know) the relation to SwcB. TestPart07_TSK_Controller itself does know that relation, which is sufficient.
  

  TestPart07_TSK_Controller knows its SwcB as itsTestMain. If you open a Structure Diagram of the SWC you see its parts. Using your righthandside mouse button, select the Features of the part (in this example TestPart07_TSK_Controller)
  

  

  We first specify an Init operation for the structured class, which is passed a pointer to the SWC. It is an InOut parameter, which prevents const from being generated.
  

  

  

  Now we must add a call to this initializer: at the righthand side of Initialization press the ... button
  

  Select the argument and press Set Value and set it to me
  

  

  Finally, add the workaround. Select the SWC and open its properties and browse to CG::Class::AdditionalInitializationCode We must set the relation to the SWC, which results in the generated code, but before initRelations() is called:
  

  

  Active Class

  UML distuinguishes between sequential and active classes, see Concurrency. All sequential classes run in the so-called swc task. Each active class has its own UML event queue and uses its own OS task.
  For this, set the concurrency of a class to active and add a ‘eventDispatcher’ runnable to the SWC:
  • add a runnable to the SWC
  • add an inter-runnable variable to exchange the ARXF-CP task pointer for the active class
  • specify the variableAccess dependency between runnable and inter-runnable variable and set its acces to read
  • specify the variableAccess dependency between the existing init runnable and inter-runnable variable and set its acces to write
  • specify the eventDispatcherActiveClass dependency between the new runnable and the new active class
  • add an exclusive area which RTE functions are used as critical region handlers when manipulating its UML event queue
  • specify the exclusiveAreaAccess dependency between runnable and exclusive area

  The sample implementation of runnables use a pointer to the Rhapsody instance of the SWC in order to test if it has been initialized. For this, it needs to know the C structure of the SWC, for example SwcB which is defined in SwcB.h in our Blinky example.

  As a consequence, we must make Rhapsody generate an include statement for the Rhapsody SWC which we do by adding a dependency to it:
  

  Browse to the structured class which represents your SWC:
  

  Next we must inform Rhapsody to generate the include statement in the C source of the active class, not its header. We do this by using the stereotype UsageImp in the package Stereotypes_Pkg_Cls_File:
  

  This is the result: a dependency to the SWC and a generated include statement in the its source file:
  

  Self pointer

  If the tag supportsMultipleInstantiation of an SWC is set, the RTE will call runnables of such SWC with a so-called self pointer. During code generation, an argument of type Rte_Instance is automatically added to such runnable if you did not add the argument to the operation yourselves already.

  However, all RTE calls done from a class within such SWC, must use the self pointer as argument. The Code Generation does not offer a <self> in RTE APIs you do. You must add an attribute to the SWC and a relation to the SWC, or pass this self pointer as argument to an initializer of a class which is part of such SWC.

  Legacy runnables

  The BlinkyPlusLegacy example shows how a legacy runnable can send a UML event into your model. The easiest way is to call an operation of a class which sends this event and have your legacy code call this operation.

  If the legacy runnable runs in a different OS task then the runnable used as UML eventDispatcher, then you must call the function RXF_Active_signalEventReceived() to trigger that runnable. RXF_Active_signalEventReceived() will use the RTE event dispatcher specified for an SWC or an active class. See AUTOSAR section ARXF-CP Event Dispatcher.

  Build Environment

  The examples show two environments to build the generated model and ARXF-CP. It is easy to add others:
  • use an extra Component if you want to generate code for a different environment.
    At the Component level, the tab Scope of the Features dialog lets you specify for which packages code is generated. If you want to deploy SWCs to a multiple build environments, you must organize your Components accordingly.
    When you add a Component, set the stereotype RXF to it and select as RTOS AUTOSAR
    
    
    
  • use an extra Configuration if you want to build your model with only different defines, but in the same environment. A typical example is to distinct between a debug version versus a release version; you can have additional defines set via the Code Generation tab of the ARXF-CP Configuration.
    Deployment configurations are stored per Configuration.