Integrating visualstate code with C++

Transcription

1 Integrating visualstate code with C++ The information in this document is based on version 4.2 of the IAR visualstate software. It may also apply to other versions of IAR visualstate. SUMMARY The code generated by visualstate is ANSI C-compliant. A visualstate System share several properties with the concept of a class, thus it would be convenient to wrap a visualstate System in a C++ class. This note outlines how this could be done. KEYWORDS C++, class, instantiation, instances, visualstate System. The problem to be solved If the primary language of an embedded application is C++, it would be convenient to interface to the visualstate generated code in an object-oriented manner. But since the code generated by visualstate is ANSI C-compliant, this is not straightforward. The entity in the code generated by visualstate that resembles the concept of an object-oriented class most closely, is a visualstate System. However, as visualstate Systems are primarily encoded as sets of functions and statically allocated variables, a class must be constructed for each visualstate System that embeds the visualstate System. Such classes are referred to by embedders in the following. Note: It may be beneficial to read IAR Application Note Interfacing visualstate and existing C code before proceeding with this note. Solution Since the number of instances of a visualstate System is fixed when the visualstate Coder is invoked, instantiation of embedder objects should be restricted. The simple case is when a single statically allocated instance of a visualstate System is used. Matters are slightly more complicated when multiple statically allocated instances of a visualstate System are used. Clients of the embedder should not have access to the functions and variables that make up the visualstate System, but they should have access to more general visualstate elements such as completion codes. The application structure could be as outlined in Figure 1. 1

2 embedder.h semlibb.h (general VS elements) client.cpp embedder.cpp vssystemdata.h vssystemaction.h (System specific VS elements) Figure 1: Application structure In this example, embedders for single and multiple statically allocated instances are constructed assuming the use of the IAR visualstate Basic API. The embedders are for a visualstate System with the following events and action functions: Events: Action functions: Event1() Event2() VS_VOID Func1() VS_VOID Func2(VS_INT i) Single statically allocated instance When using the visualstate Basic API with a single instance, the embedder should be a singleton, i.e. a class that can be instantiated only once. This can be achieved by declaring the constructor and copy constructor as private members of the embedder. Access to the single instance can be via a static data member that has the type of the embedder. In the code shown below, this data member is denoted s. The class definition for the embedder could be as follows: embedder.h #include "semlibb.h" class UserSystem public: // events unsigned char _Event1(); unsigned char _Event2(); // action functions void _Func1(); void _Func2(VS_INT i); static UserSystem s; private: UserSystem(); UserSystem(const UserSystem&); 2

3 unsigned char MacroStep(SEM_EVENT_TYPE eventno); ; Because this file is a header file intended for inclusion by C++ source files, the visualstate API header semlibb.h file must be included via the linkage specification. For every event in the visualstate System, the embedder has a member function that initiates a visualstate macrostep for that event. For every action function in the visualstate System, the embedder has a member function with the same declaration as the globally defined action function. Both types of mapper functions must be public: the event mapper functions in order to enable clients to access the embedder, the action mapper functions in order for the globally defined action functions to be able to call the action mapper functions. A private member function MacroStep is called by the event mapper functions in order to perform a macrostep. The implementations of the member functions are as follows: embedder.cpp #include "embedder.h" #include "vssystemdata.h" #include "vssystemaction.h" unsigned char UserSystem::_Event1() return MacroStep(Event1); unsigned char UserSystem::_Event2() return MacroStep(Event2); void UserSystem::_Func1() /*... */ void UserSystem::_Func2(VS_INT i) /*... */ UserSystem::UserSystem() unsigned char UserSystem::MacroStep(SEM_EVENT_TYPE eventno) unsigned char cc; SEM_ACTION_EXPRESSION_TYPE actionexprno; if ((cc = SEM_Deduct(eventNo))!= SES_OKAY) while ((cc = SEM_GetOutput(&actionExprNo)) == SES_FOUND) SEM_Action(actionExprNo); if (cc!= SES_OKAY) return SEM_NextState(); UserSystem UserSystem::s; 3

4 VS_VOID Func1(VS_VOID) UserSystem::s._Func1(); VS_VOID Func2(VS_INT i) UserSystem::s._Func2(i); The event mapper functions initiate a macrostep by calling MacroStep with their associated event. The action mapper functions are left empty for the developer to define their functionality. The constructor is empty, and it is included with the sole purpose of making it private. Alternatively, code for initializing the visualstate System and sending the initialization event (normally SE_RESET) could be inserted here. This however requires the constructor to be able to signal error in case the initialization fails. Since the singleton pattern is implemented with a statically allocated instance, this potential error will occur before control is transferred to the main function, which may not be preferable. The function MacroStep is a straightforward implementation of a visualstate macrostep (see IAR Application Note Setting up the visualstate main loop with the IAR visualstate Basic API). The action functions in the visualstate System must be defined with the linkage specification, since they are referred to by the visualstate System. The action functions call the action function wrappers defined in the embedder class via the singleton object s. However, if the context of the embedder is not needed for performing the tasks of the action functions, the action function wrappers may be omitted, and the globally defined action functions may perform their tasks directly without involving the embedder. Multiple statically allocated instances When using the visualstate Basic API with multiple instances, the technique used above for restricting the creation of embedders can be applied in a slightly modified way. Instead of statically allocating a single instance of the embedder, an array as of such objects is allocated. The size of the array should be the number of instances in the visualstate System which is encoded in the Coder-generated macro VS_NOF_INSTANCES. The class definition for the embedder class is as follows: embedder.h #include "semlibb.h" class UserSystem public: // events unsigned char _Event1(); unsigned char _Event2(); // action functions void _Func1(); 4

5 void _Func2(VS_INT i); const SEM_INSTANCE_TYPE instanceno; static UserSystem as[vs_nof_instances]; static UserSystem& ActiveInstance(); private: UserSystem(); UserSystem(const UserSystem&); unsigned char MacroStep(SEM_EVENT_TYPE eventno); ; static SEM_INSTANCE_TYPE nextinstanceno; static SEM_INSTANCE_TYPE activeinstanceno; Each instance of the embedder object is associated with an instance of the visualstate System through the constant data member instanceno. The static member function ActiveInstance is to be used by the globally defined action functions to determine which embedder object to manipulate. The function uses the static data member activeinstanceno to determine the embedder to return. Finally the embedder class uses the static data member nextinstanceno as a counter for initializing the non-static data member instanceno. The implementations of the member functions are as follows: embedder.cpp #include "embedder.h" #include "vssystemdata.h" #include "vssystemaction.h" unsigned char UserSystem::_Event1() return MacroStep(Event1); unsigned char UserSystem::_Event2() return MacroStep(Event2); void UserSystem::_Func1() /*... */ void UserSystem::_Func2(VS_INT i) /*... */ UserSystem::UserSystem(): instanceno(nextinstanceno++) unsigned char UserSystem::MacroStep(SEM_EVENT_TYPE eventno) unsigned char cc; SEM_ACTION_EXPRESSION_TYPE actionexprno; 5

6 activeinstanceno = instanceno; if ((cc = SEM_SetInstance(instanceNo))!= SES_OKAY) if ((cc = SEM_Deduct(eventNo))!= SES_OKAY) while ((cc = SEM_GetOutput(&actionExprNo)) == SES_FOUND) SEM_Action(actionExprNo); if (cc!= SES_OKAY) return SEM_NextState(); UserSystem UserSystem::aS[VS_NOF_INSTANCES]; UserSystem& UserSystem::ActiveInstance() return as[activeinstanceno]; SEM_INSTANCE_TYPE UserSystem::activeInstanceNo = 0; SEM_INSTANCE_TYPE UserSystem::nextInstanceNo = 0; VS_VOID Func1(VS_VOID) UserSystem::ActiveInstance()._Func1(); VS_VOID Func2(VS_INT i) UserSystem::ActiveInstance()._Func2(i); The most important difference between this implementation and the implementation for the single statically allocated instance is the initialization of the instanceno member in the constructor, and the change of active instance in the MacroStep function. Dynamically allocated instances Although the visualstate Expert API is able to use dynamic memory allocation, it is not possible to allocate an arbitrary number of instances of a visualstate System. The reason is that the visualstate Expert API only uses dynamic memory to allocate parts of a visualstate System, while other parts are allocated statically. So even when using the Expert API, instantiation of embedder objects should be restricted to the number of instances specified by the visualstate System. Conclusions visualstate Systems can be embedded in a C++ class to ease interfacing from other C++ objects. In addition, the use of C++ features such as protected members makes it possible to better encapsulate a visualstate System and to protect a visualstate System from accidental (unintended) changes. 6

7 Constructors can be used to ensure that initialization takes place before events are deducted. Singleton patterns and variants can be used to restrict access to instantiation of embedder objects. References IAR Application Note Interfacing visualstate and existing C code. IAR Application Note Setting up the visualstate main loop with the IAR visualstate Basic API. Contact information SWEDEN: IAR Systems AB P.O. Box 23051, S Uppsala Tel: / Fax: info@iar.se USA: IAR Systems US HQ - West Coast One Maritime Plaza, San Francisco, CA Tel: / Fax: info@iar.com USA: IAR Systems - East Coast 2 Mount Royal, Marlborough, MA Tel: / Fax: info@iar.com UK: IAR Systems Ltd 9 Spice Court, Ivory Square, London SW11 3UE Tel: / Fax: info@iarsys.co.uk GERMANY: IAR Systems AG Posthalterring 5, D Parsdorf Tel: / Fax: info@iar.de DENMARK: IAR Systems A/S Lykkesholms Allé 100, DK-8260 Viby J Tel: / Fax: info@iar.dk JAPAN: IAR Systems K.K. 1-2 Kanda-Ogawamachi, Chiyoda-ku Tokyo, Tel: +81 (0) / Fax: +81 (0) info@iarsys.co.jp Copyright 2001 IAR Systems. All rights reserved. The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. visualstate is a registered trademark of IAR Systems. IAR visualstate RealLink, IAR Embedded Workbench and IAR MakeApp are trademarks of IAR Systems. Microsoft is a registered trademark, and Windows is a trademark of Microsoft Corporation. All other product names are trademarks or registered trademarks of their respective owners. First published: March Revised: October