1 I-Logix Professional Services Specialist Rhapsody IDF (Interrupt Driven Framework) CPU External Code RTOS OXF Framework Rhapsody Generated Code CPU External Code IDF Framework Rhapsody Generated Code M.W.Richardson 27/01/2004

2 I-Logix Professional Services Frameworks In order to use Rhapsody in C and C++, it is necessary to have an Operating System. Rhapsody provides a Framework known as the OXF (Object eXecution Framework) that contains an OSAL (Operating System Adapter Layer) allowing the same model to run on a multitude of Operating Systems. Rhapsody in C and C++ both come with a number of adapters for a wide range of Operating Systems. However there will always be cases where a particular Operating System is not yet supported or cases where there is no operating System or even perhaps cases where the RAM and ROM requirements are such that there is no space for a framework.

3 I-Logix Professional Services Non supported OS When the OS that is needed is not yet supported, the obvious solution is to port the OS, however this generally takes between two and four weeks and requires OS knowledge An intermediate step is to first of all get a Rhapsody model to execute on the target without the OS. This can generally be achieved in about one day and doing so gives the user confidence in the generated code and Rhapsody In order to do this there are two approaches that can be used Interrupt Driven Framework (IDF) No Framework (NOF) Both of these solutions can either be used without an OS or even in conjunction with an OS where they can run inside a single thread. This approach makes it easy to get some Rhapsody generated code to run in an existing product!

4 I-Logix Professional Services Interrupt Driven Framework The IDF (Interrupt Driven Framework) is a framework that exists for C and C++ that can be used in place of the OXF The advantage of the IDF is that it does not require an OS, the disadvantage is that since there is no OS, it is not allowed in the model to create active classes, guard operations, … The IDF is of course a Rhapsody model that is documented and is relatively easy to understand and customise The IDF has already been integrated with a large number of compilers and CPU’s The IDF is suited for 16 and 32 bit CPU’s The IDF can be used with/without dynamic memory allocation Getting the IDF to run on almost any environment typically takes just a day

5 I-Logix Professional Services Interrupt Driven Framework Porting the IDF to a new environment requires creating a new properties file and also setting up a periodic interrupt (so that the tm function can be used in statecharts). This generally takes about one day. The IDF is designed to be customised by the user. For example some users decide that they never need to use the containers in which case they can be removed from the IDF library. In most cases, users should configure the size of the pre-allocated buffers for events/timeouts/etc. Depending on the CPU, the size of the framework library can be reduced to about 5k ROM. Animation can still be done on the host by using the OXF framework with animation

6 I-Logix Professional Services SiteC.prp / SiteC++.prp The first step is to add the new environment to Rhapsody. This is done using a specific properties file ex: siteC_IDF_Tasking_C166.prp SiteC++_NOF_GreenHills_Arm.prp This properties file describes how to invoke the compiler, how to create a makefile, which compilation options are to used, which libraries are to be linked, … There will also be a couple of batch files that let Rhapsody know how to invoke the make and to execute the code

7 I-Logix Professional Services Using the IDF with Rhapsody in C To try out the IDF, first of all an environmental variable called CIDF_ROOT must be added to point to the idf directory below where the model is located. Ex: If the model is located in C:\work\InterruptDrivenFramework, then CIDF_ROOT must be set to : C:\ work\InterruptDrivenFramework\idf The Rhapsody\Share\Properties\siteC.prp must be modified to incorporate the new environments ex: IDF_Microsoft_NT, IDF_Tasking_C166, …

8 I-Logix Professional Services Generating the IDF libraries The simplest way to try out the IDF is to use the IDF_Microsoft_NT environment. This environment uses the Microsoft Visual C++ compiler and uses the Windows OS just to create a timer. This environment also has the advantage that the generated executable will run on the Windows pc. Once the InterruptDrivenFramework model has been loaded into Rhapsody, select the IDF component and the “microsoft_nt” environment. Generate / Make to create the library idf.lib

9 I-Logix Professional Services Using the IDF Once the library IDF.lib has been created, a new project can be created. In order to use the IDF, we need several properties to be set, the simplest way to achieve this in a new project is to “add to model” as reference the IDF profile. This can be done by using “Add To Model” and then locating the IDFProfile.sbs file

10 I-Logix Professional Services IDFProfile This profile will set the following properties:

11 I-Logix Professional Services Ping We can create a simple Ping program as follows: Create a component Test that has a configuration Debug that uses the “Microsoft” environment and “Animation”. We should be able to debug the model in the usual way.

12 I-Logix Professional Services Using the IDF_Microsoft_NT environment Once the model works with the “Microsoft” environment, we can copy the configuration, select the IDF_Microsoft_NT environment and switch off the animation. (The IDF cannot work with animation). This environment should successfully compile / link and run

13 I-Logix Professional Services IDF_Greenhills_PPC In a similar way, the same model can run in different environments, ex: GreenHills compiler and PPC

14 I-Logix Professional Services The IDF model The IDF contains two main packages: RiC_IdfP This package contains all the classes from which the idf library will be created RiCTestP This package contains many tests that can be used to check the IDF. The names are all less that 8 characters since some 8 and 16 bit compilers can’t handle long file names :-(

15 I-Logix Professional Services RiC_IdfP Inside this package there are some global functions and three main packages: RiC_ContainersPkg This package is optional and can be selected in the IDF component. It contains the RiCString, RiCList, RiCCollection and RiCMap classes. For most applications, this package will probably not be selected. RiC_MemoryAllocationPkg The IDF has changed the way that memory allocation is done by using static pools of memory to avoid the use of malloc & free. RiC_RPkg This is the principal package that contains the main framework classes such as RiCReactive and RiCTask

16 I-Logix Professional Services RiC_ContainersPkg This package contains exactly the same classes as those found in the OXF framework. If the containers are required, then simply check the appropriate box so that they get generated. You don’t need to tick the Memory Allocation Package, it will get included automatically

17 I-Logix Professional Services Memory Allocation The memory allocation is done by the class RiCAllocator that pre-allocates three pools of memory. The size of each pool can be predetermined by setting the following type:

18 I-Logix Professional Services RiCAllocator The property CG:Event:BaseNumberOfInstances must be set to be > 0 (This is done by the profile) so that Rhapsody automatically adds a macro to allocate/free memory. The IDF redefines this macro so that whenever memory is to be created/released, the RiCAllocator is called to manage this. If there is no more memory available then malloc will be used to reallocate more memory which will be added to the appropriate pool. However if the define NO_MALLOC is set then a message is sent to the Error Handler class to alert the user.

19 I-Logix Professional Services RiC_RPkg The same classes that are in the standard OXF framework such as RiCReactive and RiCTask are in this package.

20 I-Logix Professional Services RiCErrorManager This is a new class, that manages all errors. It uses printf to send a message to standard out informing the user of any errors that occur. If the define NO_PRINT is set then the error manager does nothing. It is recommend that this class be modified to take appropriate action in case of an error.

21 I-Logix Professional Services RiCReactive This class has basically the same behaviour as for the standard OXF framework. It has the following main operations: startBehavior gen takeEvent This class uses a smaller virtual table than for the standard oxf, allowing just three operations to be defined: dispatchEvent, enterDefault & delete

22 I-Logix Professional Services RiCTask This class should really be a singleton, since in the IDF, only a single task can be created, however it must have the same interface as the RiCTask in the OXF framework so it is a class. In most cases, the execute operation sits in a loop calling RiCTask_schedule RiCTask_schedule, basically tests to see if any events are in the event queue and if they are, then it handles all of them in a similar way to how the OXF handles events. When an event is consumed, then the event/timeout is put back onto the appropriate pool.

23 I-Logix Professional Services Timeouts When a reactive class calls a tm() function on a statechart, then that class calls schedTm on the RiCTask. This causes a Timeout to be created and put onto a linked list that is managed by the RiCTmManager. The RiCTask class has an operation tick() that gets called periodically to check to see if any timeouts have expired. This code could be rewritten to be more optimised. Whenever a timeout expires, it is promoted to an event and put onto the event queue. A pool of timeouts are initially created statically and when a timeout is consumed, it is returned to the pool.

24 I-Logix Professional Services Sending an event

25 I-Logix Professional Services Receiving an event

26 I-Logix Professional Services Scheduling a timeout

27 I-Logix Professional Services Periodic Interrupt In order to allow the tm() function to be used on statecharts, a periodic interrupt must be set up so that the global function RiCTick() gets called every RIC_MS_PER_TICK. The function RiCInitTimer must be modified to setup the periodic interrupt for each new environment.

28 I-Logix Professional Services Extra files There are some extra files that get generated such as Ricppc.s Irq_ven.s … These files are for specific environments and can be removed if those environments are not being used.

29 I-Logix Professional Services Limitations Active classes and guarded operations are not allowed Animation is not allowed Simulated time model is not implemented Maximum number of consecutive null transitions has been reduced from 100 to 7 (this saves RAM)

30 I-Logix Professional Services Managing Interrupts If an ISR routine needs to send an event to a reactive class, then it needs to do something similar to how the timeouts are handled. ie: it should simply set a flag, that will be checked by RiCTask_execute. RiCTask_execute should be modified so that it checks these flags and automatically adds events to the event queue.

31 I-Logix Professional Services Future Directions It should be possible to modify the IDF so that multiple tasks are allowed, this then basically becomes a lightweight OXF and could be used for a more efficient way to adapt to small efficient OS’s on small targets.