STRIDE Wiki - User contributions [en]

Studio:Why don't Perl scripts run even when Script Engine shows Perl?

2009-01-16T18:06:25Z

Shamr:

Even when ActiveState Perl is installed and STRIDE Studio's Script Engine (Tools->Options->Script Engines) shows Perl file types (PL, PLS, PM, etc), you may not be able to run Perl scripts or not see the "Run" button on opened Perl scripts within STRIDE Studio or get a pop up box with error message "Could not identify a script engine for this file type. Please reinitialize your script engine list." One reason could be that ActiveState Perl registration is modified by another program. It is known that '''iTunes''' and '''Real Player''' take over the ownership of .pls extension used by ActiveState Perl, on which STRIDE Script Engine relies.

'''To verify the problem:'''
* Check the value for .pls extension in the registry: HKEY_CLASSES_ROOT\.pls. If the associated value is not “PerlScriptFile”, there is a registration problem.

'''To fix the problem:'''
* Run the following on command prompt:
CMD> regsvr32 c:\perl\bin\perlSE.dll
* Remove all Perl file types (PL, PLS, PM, etc) from STRIDE Studio's Script Engine (Tools->Options->Script Engines) and do a "Scan" again.

'''To verify the solution:'''
* Select each Perl files type and look for the text under the buttons that says “ActiveScript compliant”.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

Studio:Why don't Perl scripts run even when Script Engine shows Perl?

2009-01-14T18:25:18Z

Shamr: modified content slightly

Even when ActiveState Perl is installed and STRIDE Studio's Script Engine (Tools->Options->Script Engines) shows Perl file types (PL, PLS, PM, etc), you may not be able to run Perl scripts or not see the "Run" button on opened Perl scripts within STRIDE Studio or get a pop up box with error message "Could not identify a script engine for this file type. Please reinitialize your script engine list." One reason could be that ActiveState Perl registration is modified by another program. It is known that '''iTunes''' and '''Real Player''' take over the ownership of .pls extension used by ActiveState Perl, on which STRIDE Script Engine relies.

'''To verify the problem:'''
* Check the value for .pls extension in the registry: HKEY_CLASSES_ROOT\.pls. If the associated value is not “PerlScriptFile”, there is a registration problem.

'''To fix the problem:'''
* Run the following on command prompt:
CMD> regsvr32 c:\perl\bin\perlSE.dll
* Remove all Perl file types (PL, PLS, PM, etc) from Tools->Options->Script Engines and "Scan" again.

'''To verify the solution:'''
* Select each Perl files type and look for the text under the buttons that says “ActiveScript compliant”.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

STRIDE 3.0.01xx

2008-10-22T20:42:21Z

Shamr: /* 3.0.0102 */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.01xx (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

'''Important''': An upgrade to the 3.0.0102 release will require a re-issue of all license files as the underlying licensing scheme has changed. See the [[STRIDE_3.0.01xx#3.0.0102|3.0.0102 Release Notes]].

 

{| border="1"
|-
|
Note that if you are upgrading from a previous installation '''you must uninstall your existing STRIDE''' before installing version 3.0.01xx.

|}

 

= What's New =

Based on customer feedback, in this release we have made significant performance improvements as well as many key usability improvements and bug fixes.

== Performance Improvements ==

Specific improvements have been made in the following areas:

*Database loading time has been improved
*Compile times are now shorter
*Scripting operations involving function and message payloads now perform better, especially when arrays are involved
*Runtime performance has been improved by optimizing payload serialization and deserialization operations

== Usability Improvements ==

=== SCL Wizard ===

The SCL Wizard functionality in [[STRIDE Studio]] has been extended so that you can now use the tool to qualify message payloads as well as function payloads.

In addition, the following types of qualifications can now be made:

*For payloads that include function pointers, the SCL Wizard now supports qualifying the pointers as such and identifying candidate function values
*Type casts can now be specified on payload members

=== Connection Management ===

Connection management has been greatly simplified; software managing connection to the target system has been integrated into [[STRIDE Studio]] so that connections can be managed directly from there. (It is still possible to access connection management functionality without using Studio.)

The Panel program is no longer used, and there is no longer a requirement to load the database to communicate with a remote target.

==== Transport Properties ====

All transport properties can now be accessed via scripts. A new transport scripting model makes this possible.

=== STRIDE Studio Test Runner Improvements ===

The test runner in [[STRIDE Studio]] has incorporated several functional and usability improvements.

*Each runnable script and folder (Suite) in a workspace now has additional properties that allow you to optionally specify a handler script that will be executed in the case of an unhandled error (property OnError) or a timeout (property OnTimeout). A timeout value can be set for each folder.

*Each runnable folder (Suite) in a workspace now has a property (OnRunConnect) that can instruct STRIDE Studio to automatically connect to a target system before the folder is executed.

*The workspace now has a dynamic property (ExecutionState) that allows you to alter the order of script execution at runtime.

=== New Frameworks Feature ===

This version introduces [[Using Frameworks|Target Frameworks]], which provide customizable templates for workspace creation. The use of frameworks simplifies the use of STRIDE and ensures consistency across a development team.

Several [[Provided Frameworks|reference frameworks]] are included in this release, supporting the following target environments:

*[[Provided Frameworks#Windows|Windows]]
*[[Provided Frameworks#Linux|Linux]]
*[[Provided Frameworks#WinMobile|WinMobile]]
*[[Provided Frameworks#Generic|Generic]]

[[Using Packages|Packages]] are also introduced. These provide a convenient way to encapsulate SCL-annotated source code and corresponding tests for a set of interfaces.

=== Uploading Results to STRIDE Portal ===

Uploading test results from STRIDE Reporter to STRIDE Portal has been integrated into STRIDE Studio. Portal's server information can be configured from Studio's workspace properties while uploading results to Portal can be enabled or disabled via workspace context menu. If enabled, after running the workspace, a script folder or a script file, results in Report file will automatically be uploaded to the configured server.

== Build Tools ==

A set of new command line [[Build Tools]] has been implemented:

*'''Stride compiler'''
*'''Stride database binder'''
*'''Stride instrumentation generator'''

These utilities has been ported for Windows and Linux. Using them would allow seamless integration with a "make" build environment.

== Target-Based Testing ==

Target-based (xUnit-style) testing has been simplified. The new set of SCL pragmas [[Test Units]] can now be included in a source file to tell the compiler and IM generator to automatically create test harnessing code.

The automation components STRIDE.testclass, STRIDE.testunit and STRIDE.testfunction are removed.

== Runtime/PAL ==

Based on customer requirements, in this release we have made significant changes to [[Target_Integration#The STRIDE Runtime|STRIDE Runtime]] and [[Target_Integration#The Platform Abstraction Layer (PAL)|PAL]].

=== Multi-Process Targets ===

New routines and support have been added to Runtime and PAL to support multi-process targets. Changes include: implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

=== Logging (Optional) ===

Runtime and PAL use a logging routine that can optionally be implemented in PAL.

== Windows Off-Target SDK ==

A new [[Windows_Off-Target_SDK|SDK]] for implemention of Off-Target applications on Windows has been packaged. It contains a library (s2srWin.dll/lib) in which the Windows PAL, Runtime, and GRS and a set of utility scripts are prebuilt.

The '''s2shostapphrt''' library, a prebuilt verion of the Host Runtime, has been removed. Building Windows applications using the Host Runtime is not supported anymore. The '''s2shostapptrt''' library, a prebuilt version of the Target Runtime, has also been removed.

If an upgrade is performed it is strongly recommended that the above mentioned '''s2shostapp*''' libraries and their public API header (hostapp.h) be manually removed.

= Support Wiki =

This support wiki http://support.s2technologies.com is introduced with this version. You can navigate here from your web browser, or directly from STRIDE Studio; a link is provided in the Help menu.

== STRIDE Samples ==

We have created a set of [[Samples_Overview|sample workspaces]] to aid in the evaluation of STRIDE, or as a tool for learning how to apply STRIDE to different testing scenarios.

If you're new to STRIDE, or want to learn more about using the product, this is a great place to start.

= Acquiring the Software =

You can download the latest release from the S2 Technologies ftp site: ftp://ftp.s2technologies.com

To run STRIDE you will need a license. If you are not yet a customer of S2 and would like to obtain an evaluation license, email [mailto:sales@s2technologies.com S2 Sales] or call our offices at '''760-635-2345'''.

= Installing the Software =

To install STRIDE for the first time, or as an upgrade to an existing installation, please refer to [[Host Installation]].

{| border="1"
|-
|
Note: if you are upgrading from a previous installation '''you must uninstall your existing STRIDE''' before installing version 3.0.01xx.

|}

If you are new to STRIDE, we recommend that you investigate the [[Samples_Overview|New STRIDE Samples]].

= Change Details =

*The '''ascript''' API has been changed to be more robust:
**Certain deprecated methods have been eliminated.
**Some existing API methods have been modifed.
**The event model has been improved to allow greater script control.

'''Note''': Some scripts must be modified from previous versions of STRIDE to work successfully with 3.0.01xx. The necessary changes are detailed in the [[#Migration_to_3.0.01xx|Migration to 3.0.01xx]] section below.

*The '''Panel''' object is no longer available to scripts; its functionality has been moved under the '''studio''' object model. You can access this new functionality as '''studio.Connection''', however if you were formerly scripting the '''Panel''' object, you may find it is no longer necessary since:
**You can now configure your connection properties from within STRIDE Studio (from the menu select ''Tools/Target Connectivity'')
**You can now set a workspace folder property to autoconnect upon execution

*Zero is now allowed as the maximum size under certain circumstances in '''scl_string''' and '''scl_ptr_sized'''. Details of these circumstances are contained in the '''[[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]]''' document.

*'''studio.Workspace.Compiler.MicrosoftCompatibility''' has been replaced with '''studio.Workspace.Compiler.Compatibility'''. Valid values are "Generic" (generic mode), "Microsoft" (Microsoft compatibility), or "Gnu" (Gnu or Gcc compatibility).

*'''studio.Workspace.Compile()''' has been replaced with '''studio.Workspace.Build()'''. Also new methods, '''studio.Workspace.CleanBuild()''' and '''studio.Workspace.ReloadDatabase()''', have been added.

*A new property, '''Output''', has been added off the studio object. This property outputs text to the Studio message tab, similar to how '''ascript.MessageBox()''' works for certain scripts. This property contains one method, '''PrintMessage(String msg)'''. You can see an example of its use [[Debugging Helps|here]].

*A new settings group has been introduced - '''studio.Workspace.Settings.Build'''.

*'''studio.Workspace.Intercept.Path''' has been replaced with '''studio.Workspace.Intercept.SourcePath''' and '''studio.Workspace.Intercept.HeaderPath'''.

 

== Fixes ==

''This section describes defects which have been corrected in STRIDE and the customer tracking number associated with them, if any, in brackets [].''

*[1055] Not able to specifiy uppercase include directory
*[1163] Certain cases of array of pointers to discriminated unions that were not handled correctly in the ascript object have been fixed.
*[1357] The ascript '''Call()''' method, when used with RspTimeoutPeriod, only returns True if a timeout has occurred.
*[1469] Global casting using '''scl_cast''' no longer causes an intercept module compile error.
*[1539] '''ascript''' no longer returns "undefined" when calling '''function.ReturnValue''' when the captured function returns an unqualified function pointer.
*[1543] IM source file locations added to studio UI and automation
*[1564] The Studio Add files dialog has been increased from 2K bytes to 100K bytes, to allow for more files to be selected at a time.
*[1586] Support for Variadic Macros
*[1597] EDGFront crash for scl_ptr_opaque
*[1600] Pre-processor treats constant 1 always as 8-bit
*[1605] Generated Perl script generates error when run in debugger
*The following statement in Runtime files '''srtest.c''' and '''srtest.cpp''' has been changed: <tt>va_list args = 0;</tt> is now <tt>va_list args;</tt> with no initializer. This makes it portable and able to compile under Linux.
*A macro that determines the existence of '''vsnprintf()''' has been updated in '''srtest.c''' and '''srtest.cpp''' in order to make it able to compile with GCC and other non-Microsoft compilers. '''Note:''' If you are using test functions and C++ test classes, you must be using compilers that support '''vsnprintf''' (variable argument lists), which is a standard in C99 and supported in C90.
*When tracing on a STID it's possible to display trace information for messages that aren't captured (i.e. the message's SMID is not known to STRIDE). A problem could occur when STRIDE attempted to interpret the payload of these messages. This has now been fixed; hex values only are now shown in the trace view for in this situation.
*Autosense was not working properly in the editor for message payloads. This has been fixed.

== AutoScript ==

=== TestUnits Collection ===

A new TestUnits collection has been implemented. All test interfaces (specified with [[SCL_Pragmas#Test_Units | Test Unit pragmas]]) will be listed there.

=== Functions Collection ===

Interfaces specified with either the [[scl_test_class]] or [[scl_test_flist]] pragmas are not listed in the Functions collection anymore.

== PAL ==

=== Memory Management ===

To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

=== Protection using Mutex ===

Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

=== New Routines ===

*'''Memory Management'''

In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.

palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

*'''Named Mutexes'''

palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

*'''Task Synchronization'''

palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

*'''Logging'''

This is optional.

palLog() - Logging utility

=== Updated Routines ===

*Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

*Function signatures of palMemAlloc() & palMemFree() have been updated.

=== Removed Routines ===

palProtect
palUnprotect
palCriticalErr

=== Removed Modules ===

S2Mem - The memory module provided as part of PAL has been removed. If a native
operating system does not support dynamic memory, the Runtime's memory
management module ''srMem'' can be used instead of ''S2Mem''.

== Runtime ==

*STRIDE Host Release '''3.0.01xx''' is compatible with the Runtime Version '''3.00'''.
*In order to eliminate redundancy and promote an object-oriented design, "Member Methods" have been removed from srTest; only "Member Objects" exist now in srTest. In addition, accessing the functionality of Member Objects in this way is similar to accessing scripting objects through the STRIDE Reporter object model. For a detailed explanation, refer to [[Test_Units#C.2B.2B_Test_Classes|this article]] on the STRIDE Support Wiki.
*A new routine, '''srInit()''', replaces deprecated '''srInitialize()'''. Now the target will not be able to set an auto-connect with timeout.
*The '''scl_tp''' and '''scl_tp_format''' pragmas have been deprecated. The new pragmas are '''scl_tracepoint''' and '''scl_tracepoint_format'''.
*The default runtime configuration in srcfg.h now has fragmentation turned on. The srCFG_MAX_TRANSPORT_UNIT is set to 2048.
*Fixed warnings for parameter name differences in function declarations and definitions for srSubscribe(), srTracePoint(), and srQuerySMID().
*Removed unnecessary/extra response to srCONNECT_CLOSE_T_SMID message.
*The Runtime now checks for the connection before responding with a "Pong" upon receiving a "Ping."
*Introduced 40 additional system trace points to better describe internal errors.
*Reporting of the error srERR_SUB_NONE has been suppressed so that it no longer generates a target trace error.
*Trace views now always display srTraceStr() with reserved STID (srSTID_RESERVED) regardless of trace filter settings.
*srPtrSetupChild() now accepts NULL for handle (out pointer - pwHandle).
*Added a new Runtime Test Services (RTS) API '''srTestCaseSetStatusEx()''', which enables the providing of the actual return value of a numeric test method in the case of failure.
*Added two new public APIs - "Printing" APIs to display messages on Trace Views without having to specify a STID or a trace level and to set any trace filters on Trace Views. These routines support formatted strings with variable arguments. The '''srPrintInfo()''' will show as srTraceStr() with STID=0 and Level=3. The '''srPrintError()''' will show as srTraceStr() with STID=0 and the Level=1. '''Warning:''' These new APIs use vsnprintf() routine to process variable arguments. The vsnprintf() became a standard in C99 and is supported in C90.
*To support multi-process target, significant changes have been made to runtime.
*A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new public routine for Runtime Thread exit point, srThreadUninit(), has been added to sr.h & srthread.c.
*A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
*Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
*In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.
* Fixed a potential data abort issue when executing delegate code in the IM prior to Runtime being initialized.
* Runtime Test Services APIs are now thread safe.
* Fixed cancelation of remote boadcast subcribtion goes in an infinite loop.
* Fixed Runtime resource abuse when sending lots of broadcast messages.
* Added partial check for message payload corectness.

*''The following Runtime files have been modified:''

sr.h
srapi.c
srapi.h
srapirgl.c
srapirgl.h
srcfg.h
srconn.c
srconn.h
srerr.c
srib.c
srib.h
sribctrl.c
sribtr.c
sribtr.h
srmsgmar.c
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.c
srtest.h
srtestutil.c
srtestutil.h
srthread.c
srthread.h
srtime.c
srtime.h
srtp.h
srutil.h

*''The following Runtime files have been added:''

srmem.c
srmem.h

= Migration to 3.0.01xx =

Recommended steps for migration from a previous version:

== AutoScript ==

Any use of test classes through the Functions collection, like:

$main::ascript->Functions->Item("my_test_class")->User->Call();

should be converted to use the new TestUnits collection:

$main::ascript->TestUnits->Item("my_test_class")->Run();
 
=== API Changes ===

*The Support Wiki pages now contain reference help for [[AutoScript#ascript|''AutoScript'']].
*All synchronous method calls now throw exceptions in order to indicate error conditions rather than have error conditions encoded in return values.
*Asychronous method calls never throw exceptions to indicate error conditions. Instead, error conditions are delivered as a new Error object that is returned to '''ascript.WaitForEvent()'''. (Asynchronous methods are '''function.Owner.Return()''', '''function.User.CallNonBlocking()''', '''function.User.CallBypassOverrideNonBlocking()''', '''message.Owner.Broadcast()''', '''message.Owner.SendRsp()''', '''message.User.SendCmd()''', and '''message.User.SendCmdBypassOverride()''')
*If '''ascript.WaitForEvent()''' times out, an Error object is returned. Previously NULL was returned in this case.
*All objects returned by '''ascript.WaitForEvent()''' have '''Type''' and '''Name''' properties. When the '''Type''' is “Error”, the Error object has additional properties that contain further details about the error.
*All existing script syntax for designation of message payloads has been deprecated. A new syntax that allows for greater expression has been adopted. Details can be found [[Updated Message Payload Syntax|here]]. There are no syntax changes to function payloads.
*The signature for '''ascript.Initialize''' has been changed. Successful calls to '''ascript.Initialize''' now fully initialize the object.

=== End-Of-Life Methods and Properties ===

This release marks the End-Of-Life (EOL) for the listed methods and properties. A call to any of these methods or an access to any of these properties will now result in a not-implemented exception in the script making the call or access.

*ascript.Quit()
*ascript.Interfaces
*ascript.NamedEvents
*ascript.WaitForEventWithTimeout
*ascript.RspTimeoutNotifyEnabled
*ascript.CreateTimer()
*ascript.DestroyTimer()
*ascript.WaitTimeoutNotifyEnabled
*ascript.Compare_As_C_Values()
*ascript.AsyncErrorNotifyEnabled
*ascript.Function.Item().User/Owner.SMID

=== Recommended Steps for Migration From a Previous Version ===

*Search for calls to '''ascript.WaitForEvent()''' in all scripts. Previous logic to test for null indicating timeouts must be modified. '''WaitForEvent()''' now always returns an object, in the case of a timeout (or other error) an Error object is returned.
*Search for calls to '''ascript.Quit''' in all scripts. Modify the logic as necessary to exit the script by other means in place of the original '''Quit()''' call.
*Search for all asynchronous method calls (Asynchronous calls are limited to '''function.Owner.Return()''', '''function.User.CallNonBlocking()''', '''function.User.CallBypassOverrideNonBlocking()''', '''message.Owner.Broadcast()''', '''message.Owner.SendRsp()''', '''message.User.SendCmd()''', and '''message.User.SendCmdBypassOverride()'''). Modify the logic as necessary to call '''ascript.WaitForEvent()''' if errors (including timeout error) should be detected.
*If you have scripts that explicitly instantiate an '''ascript''' object (i.e. they create an object using the '''"STRIDE.ascript"''' PROGID), search for all occurrences and modify the subsequent call to '''ascript.Initialize()''' to pass the new parameter set.
*Search for all EOL'd methods and properties. Each can be replaced by setting the appropriate timeout property and handling the timeout error object delivered by WaitForEvent.

 
<div class="Section1">
{| width="100%" border="1" style="width: 100%; border-collapse: collapse;" class="MsoTableGrid"
|- style=""
| width="50%" valign="top" style="border: 1pt solid windowtext; padding: 0in 5.4pt; background: rgb(204, 255, 204) none repeat scroll 0% 50%; width: 50%; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" |
'''EOL’d''''''Method or Property'''

| width="50%" valign="top" style="border-style: solid solid solid none; border-color: windowtext windowtext windowtext -moz-use-text-color; border-width: 1pt 1pt 1pt medium; padding: 0in 5.4pt; background: rgb(204, 255, 204) none repeat scroll 0% 50%; width: 50%; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" |
'''Recommended Replacement'''

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.Quit''''''()'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Refactor script logic to exit the script by other means.

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.Interfaces'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Use ascript.Functions or ascript.Messages as appropriate.

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.NamedEvents'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Contact S2 Technologies

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.WaitForEventWithTimeout'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Use ascript.WaitForEvent() after setting desired timeout using ascript.WaitTimeoutPeriod

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.RspTimeoutNotifyEnabled'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
No longer needed. Timeout notifications are performed by returning an Error object from ascript.WaitForEvent()

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.CreateTimer''''''()'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Use ascript.Timers.Add()

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.DestroyTimer''''''()'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Use ascript.Timers.Remove()

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.WaitTimeoutNotifyEnabled'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
No longer needed. Timeout notifications are performed by returning an Error object from ascript.WaitForEvent()

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.Compare_As_C_Values''''''()'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Contact S2 Technologies

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.AsyncErrorNotifyEnabled'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
No longer needed. Error notification from asynchronous calls is performed by returning an Error object from ascript.WaitForEvent()

|- style=""
| width="50%" valign="top" style="border-style: none solid solid; border-color: -moz-use-text-color windowtext windowtext; border-width: medium 1pt 1pt; padding: 0in 5.4pt; width: 50%;" |
'''ascript.Function.Item''''''().User/Owner.SMID'''

| width="50%" valign="top" style="border-style: none solid solid none; border-color: -moz-use-text-color windowtext windowtext -moz-use-text-color; border-width: medium 1pt 1pt medium; padding: 0in 5.4pt; width: 50%;" |
Use ascript.Function.Item().User/Owner.SUID

|}
</div>

== PAL ==

Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

*Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

*Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

*Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

*Remove old routines palProtect(), palUnprotect() and palCriticalErr().

*Implement new routines palGetThreadId() and palGetProcessId().

*Implement new routine palSleep().

*Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

*If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

*Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

== Runtime ==

*Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

*Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

*If target Test Classes and Test Functions are used, change the signature to include test label in srTestCaseAddComment() and AddComment() APIs.

== Windows Applications using Windows Off-Target SDK ==

Existing Host Apps developed against the old '''hostapphrt''' and '''hostapptrt''' libraries should be updated to use the new [[Windows_Off-Target_SDK|s2srwin]] library as follows:
*replace the include of hostapp.h with include of srwin.h
*replace all calls to HostAppXXX() with srWin_XXX()
*call srWin_SetMaster() to start the runtime thread, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.
*replace srHOST preprocessor definition with srWIN32

= Minor and Patch releases =
== 3.0.0101 Patch "a" ==
* Linux version of the STRIDE [[Build Tools]] is officially introduced.
* Fixed several minor issues in [[STRIDE Studio]].

== 3.0.0101 Patch "b" ==
* Relaxed [[scl_cast]]() pragma to allow cast from any integral ptr to union of ptrs
* Fixed compile warnings in Linux PAL.
* Fixed issue in instrumentation of [[Test Units]].
* Fixed issue with UNC paths.
* Fixed several minor issues in [[STRIDE Studio]].

== 3.0.0102 ==
* Implemented new licensing scheme. Existing licenses will not work anymore and need to be reissued. Old and new licenses could co-exist at the same location.
* The syntax of [[scl_ptr]] and [[scl_ptr_sized]] pragmas has changed. Now it is required to quote the direction and usage attributes. See this [[Handling_of_pointer_attribute_tokens|page]] for details.
* [[Test_Units#Runtime_Test_Services|Runtime Test Services]] now support adding annotations per test suite.
* A complete set of [[Samples]] has been implemented.
* Fixed several minor issues in STRIDE [[Build Tools]].
* In [[STRIDE Studio]] the processing of Trace information has been optimized.
* Fixed several minor issues in [[STRIDE Studio]].
* Fixed several minor issues in [[AutoScript]].
* Updated [[Linux_PAL|PAL for Linux]] to include a generalized Linux Daemon for Runtime.
* STRIDE Host Release '''3.0.0102''' is compatible with the Runtime Versions '''3.00''' and '''3.01'''.
*''The following Runtime files have been modified:''

srconn.c
srtest.c
srtest.cpp
srtest.h

[[Category:3.0.01xx]]
[[Category:Release Notes]]

Intercept Module

2008-10-13T22:41:34Z

Shamr: /* About Intercept Modules */

== About Intercept Modules ==

Intercept Modules allow remote function calls across hardware (e.g., processor or machine) or software (operating system) platform boundaries. Intercept Modules are target-based components that are created as a step in the STRIDE build process (see the [[Build Tools|Build Tools]] page). The Intercept Module, or IM, is created based on selected interfaces or test units that have been "captured", or identified through a subset of SCL pragmas that tag interfaces as candidates for remote function calls. Once created, the generated code is then compiled, linked and run along with the target application. 

 

The [[s2sinstrument]] executable, or alternatively, the Intercept Module Wizard in Studio generate the code for an intercept module for selected functions or test units. Generation can be tailored to include different instrumentation details for each function.

 Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:

*The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
*The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
*The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

 

The following examples describe integration and testing situations that would require generation of one or more intercept modules:

*To call a function on the target platform from the host, you must generate an intercept module containing a '''stub''' and include it in the target build.
*To call a function on the host platform from a function on the target, you must generate an intercept module containing a '''proxy''' and include it in the target build.
*To trace on that function resides wholly on the target (e.g., both the called and the calling functions are co-located on the target platform), you must generate an intercept module containing a '''tracing delegate''' and include it in the target build.
*To be able to dynamically "move" a function back and forth between host and target platforms during integration and testing without rebuilding the target application, you must generate an intercept module containing a '''dynamic delegate''' and include it in the target build. 

 

== Stubs, Proxies, and Delegates ==

Target instrumentation is handled via stubs, proxies, and delegates, each of which provide distinct functionality. 

 

[[Image:PROXYSTUB.gif|center]]

 

=== Stub ===

A stub is required in order to call a function, f(), on the target from the host.

The stub performs two main tasks:

*Provides a handler for incoming host invocations and transparently converts them into local calls to f().
*Captures the return and output values of the local call and transmits them back to the host.

When a proxy and a stub exist for a given function, the stub is never on the same platform as the proxy.

 

=== Proxy ===

A proxy is required in order to transparently intercept a target call to a function, f(), and remote the call to a host implementation of f().

The proxy performs two main tasks:

*Intercepts local calls to f() and transfers the call, along with parameter data, to the host implementation.
*Captures the host response containing return values and output data, and transparently returns the information to the local caller. 

When a proxy and a stub exist for a given function, the stub is never on the same platform as a proxy. When more than one proxy exists for a given function, each proxy must be located on a different platform.

 '''Note:''' A stub and a proxy cannot simultaneously coexist for the same function. Only one can be used for any given test configuration.

 

=== Delegate ===

A delegate is a specialized type of proxy. A delegate can perform the following tasks:

*Transparently trace all calls to a method, f(), whose implementation resides on the target. All calls and parameter data can be captured and recorded. This type of delegate is called a '''Tracing Delegate'''.
*Transparently route calls to either a target- or host-based implementation of f(). This routing is dynamic and controlled by the host. This type of delegate is called a '''Dynamic Delegate'''.

A Tracing Delegate intercepts calls to f() and records tracing information such as time, input parameters, etc. before passing control to the local implementation of f(). Upon the return from f(), the delegate again records tracing information before passing control back to the caller. The delegate inserts itself between the caller and the callee in order to capture tracing information.

A Dynamic Delegate inserts itself between the caller and the callee in the same way as a Tracing Delegate, but its logic is different. In addition to recording tracing information, it contains logic to check certain state information to determine whether to route the call to a host implementation (and override the owner) of f(), or to allow the call to proceed to the local implementation (owner) of f().

'''Note:''' A Dynamic Delegate is always a Tracing Delegate, but depending upon instructions you give the Intercept Module Wizard, a Tracing Delegate may or may not be a Dynamic Delegate. 

==== Delegate Options ====

==== ''Owner/User'' ====

To insert a delegate between a user (calling) function and owner (called) function, you must choose how function [[Name Mangling|name mangling]] will be handled. Name mangling describes the automatic source transformation required for a delegate to insert itself between caller and callee. There are two options for handling name mangling, one of which must be chosen when using delegates: 

#A call to a function f() is transformed to "__imf()” to allow the delegate to intercept the call. This is referred to as '''user mangling'''.
#The implemention of f() can be transformed to "__imf()”. This is referred to as '''owner mangling'''. 

See the [[Name Mangling|Understanding Name Mangling]] page for a detailed explanation of name mangling and how it is used. 

==== ''Implicit/Explicit'' ====

A delegate may have either implicit or explicit mangling incorporated into it. By default, implicit mangling is used; this means that selected routines will be mangled using a [[#Group_ID|Group ID]]. If explicit mangling is used, you must explicitly mangle selected routines using the explicit macro "'''imDELEGATE('''''<function_name>''''')'''". For detailed information about implicit and explicit mangling, including examples, click [[Name Mangling|here]].

==== ''Group ID'' ====

A Group ID assigns a special symbolic constant, declared in the Intercept Module delegate mangling header file (xxxIM.h), that can be used by the preprocessor to mangle a subset of routines; successful use of Group ID(s) assumes that each source file (e.g., FuncA.c and FuncB.c) has its own header file (e.g., FuncA.h and FuncB.h). A Group ID can be defined within the source file or defined as a compiler input parameter. The default Group ID(s) used by the [[s2sinstrument]] executable or the Intercept Module Wizard in Studio can be overridden with your own Group ID(s). Name mangling conflicts can be resolved using the Group ID(s). 

 '''See also'''

*[[Name Mangling|Understanding Name Mangling]]
*'''[[Integrating the Intercept Module (IM)|Integrating the Intercept Module (IM)]]''' for directions on how to generate an IM and add it to your target build
*[[S2sinstrument|Using s2sinstrument to generate an Intercept Module]]

[[Category:Reference]]

Main Page

2008-10-13T22:39:06Z

Shamr: added IM reference

Welcome to the S2 Technologies™ '''STRIDE'''™''' 3.0 Support Wiki'''.

All contributions are welcome and encouraged. Please read '''[[Help:How to add a topic|How to add a topic]]''' and '''[[Help:Contents|Help]]''' pages for guidelines and instructions on editing. You must '''[[Special:Userlogin|log in or create an account]]''' before you can edit a page.

Please select a topic or category heading below, or enter a search string in the Search field to the left.

----

 

{| class="FCK__ShowTableBorders"
|-
|
|}

{| class="FCK__ShowTableBorders"
|-
| valign="top" |
{| class="FCK__ShowTableBorders" style="border-right: rgb(187,204,204) 1px solid; border-top: rgb(187,204,204) 1px solid; vertical-align: top; border-left: rgb(187,204,204) 1px solid; border-bottom: rgb(187,204,204) 1px solid" cellspacing="5" cellpadding="2"
|-
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Installation|Installation]]           
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Reference|Reference]]         
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Samples|Samples]] 
|-
| valign="top" |
*[[Host_Installation|Host Installation]]
*[[Build_Integration|Build Integration]]
*[[Target_Integration|Target Integration]]
*[[Verifying Installation|Verification]]



| valign="top" |
<ul>
<li>[[Reference Overview|Overview]]</li>
<li>[[Runtime Reference|Runtime]]</li>
<li>[[Build Tools|Build Tools]]</li>
<li>[[SCL_Pragmas|SCL Pragmas]]</li>
<li>[[Intercept Module|Intercept Module]]</li>
<li>[[AutoScript|AutoScript]]</li>
<li>[[Reporter|Reporter]]</li>
<li>[[STRIDE_Studio|Studio]]</li>
<li>[[Windows Off-Target SDK]]</li>
<li><categorytree mode=pages depth=0>Utilities</categorytree></li>
</ul>



| valign="top" |
*[[Hello_Stride_Sample|Hello Stride]]
*[[Test_Unit_Samples|Test Units]]
*[[Test_Script_Samples|Test Scripts]]
*[[SCL_Samples|SCL]]
*[[Intercept_Module_Sample|Intercept Module]]

|-
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Practice|Practice]]
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Application Notes|Notes]]
! style="border-right: rgb(163,176,191) 1px solid; padding-right: 0.4em; border-top: rgb(163,176,191) 1px solid; padding-left: 0.4em; font-weight: bold; font-size: 120%; background: rgb(206,223,242) 0% 50%; padding-bottom: 0.2em; margin: 0pt; border-left: rgb(163,176,191) 1px solid; color: rgb(0,0,0); padding-top: 0.2em; border-bottom: rgb(163,176,191) 1px solid; text-align: left; -moz-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial" | [[:Category:Release Notes|Release Notes]]
|-
| valign="top" |

*[[:Category:Frameworks|Frameworks]]



| valign="top" |
<categorytree mode="all" hideroot="on">Application Notes</categorytree> 

| valign="top" |
*[[STRIDE 2.1.00xx|STRIDE 2.1.00xx (D Street)]]
*[[STRIDE 3.0.01xx|STRIDE 3.0.01xx (StoneSteps)]]

|}

|}

Studio:Scl msg

2008-09-30T07:03:40Z

Shamr: /* Example 1 */ fixed SMID

= The scl_msg pragma =

The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique [[#The_STRIDE_Unique_ID_.28SUID.29|STRIDE Identifier (SUID)]] with message attributes to create a STRIDE Message Id (SMID). The SMID is then associated with command and/or response payload type definitions.

== Syntax ==

#pragma scl_msg(SMID)

#pragma scl_msg(SMID, cmd-payload)

#pragma scl_msg(SMID, rsp-payload)

#pragma scl_msg(SMID, cmd-payload, rsp-payload)

#pragma scl_msg(SMID, void, rsp-payload)

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| ''SMID''
| Integer
| SUID + attributes from which the message type and other properties are determined
|-
| ''cmd-payload ''
| Integer
| Optional name of the data type for the command payload. If omitted, then: 
The message is a one-way command or a two-way message, and the User sends an empty payload to the Owner, 
-or- 
The message is a one-way response or a broadcast and is sent from Owner to User(s). 
The SMID attributes determine the behavior.
|-
| ''rsp-payload''
| Integer
| Optional name of the data type for the response payload. If omitted then: 
The message is a one-way response or a two-way message, and the Owner is responding with an empty payload to the User, 
-or- 
The message is a one-way command.
|-
| ''void''
|
| This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload).
|}

== Notes ==
* The SMID must be a non-parameterized macro name that resolves to an integer constant expression. The macro name will become the name of the message and cannot collide with the name of any other name or function.
* The SMID, cmd-payload, rsp-payload, and cmd-payload rsp-payload must all be integer constant expressions that evaluate to a number in the range of 0 — 232 - 1 and follow the rules for a SMID.
* In order to describe a two-way message with only a return payload, the type void is allowed only in the command position in a two-way message:

#pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse);

== The STRIDE Message ID (SMID) ==
The SMID is a 32-bit structure consisting of a unique ID and a set of message attributes. The SCM defines the [[#The_STRIDE_Unique_ID_.28SUID.29|SUID]] portion as the first 24 bits of the SMID (bits 0 — 23), allowing unique identifiers up to 16,777,215. The message attributes use the highest 8 bits of the SMID (bits 24 — 31).

Each SCL-compliant message within the system must be assigned a unique message ID.
[[Image: SUID_attributes.gif|center]]

=== SMID Attributes ===
The attributes are used to declare the message type, describe how to send the option payload and indicate, if applicable, the pointer memory usage attribute for the payload. The attributes, shown below, are the message type (MT), send type for command (STc), send type for response (STr), pointer usage for command (PUc), pointer usage for response (PUr), and Access Class (AC).
[[Image:SMID_attributes_format.gif|center]]

=== Message Type (MT) Attributes ===
The Message Type (MT) attribute defines the type of message being used for communication between the owner and user. The following values are used for different message types:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| One-way command
|-
| 01
| One-way response
|-
| 10
| Two-way command-response
|-
| 11
| Broadcast message
|}

=== Send Type for Command (STc) Attributes ===

The Send Type (ST) attribute is used to indicate how to transmit the payload. There are two ways to send the payload: by value or by pointer. The STRIDE Runtime is required to use the ST attribute when determining whether to route locally or remotely across platform boundaries. The following tables describe the ST attribute settings:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

=== Send Type for Response (STr) Attributes ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

'''Note:''' When a command or response does not contain a payload, the ST attribute is set to zero (0).

When a payload is passed by pointer, a Pointer Usage (PU) attribute is required. The PU attribute indicates if the payload is using '''pool memory''' or '''private memory'''. When the PU attribute indicates '''pool''', the SCM requires that the memory be allocated from the common pool being used by the system. When the PU attribute indicates '''private''', the STRIDE Runtime environment makes no assumptions on how the payload memory is being managed between the Owner and User when they are executing on the same target platform. If the payload crosses platform boundaries, however, the Runtime is required to dynamically allocate memory from the common pool. The temporary memory that is allocated is used to hold the payload, and the address of the memory is passed to the reader. Once the reader returns the message memory to the Runtime, the temporary memory is automatically freed. The original memory from the sender is not affected or synchronized with the other platform.

The PU attributes are listed below:

=== Pointer Usage for Command (PUc) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Pointer Usage for Response (PUr) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Access Class (AC) Attributes ===
The Access Class (AC) attribute ensures that the intercept module will not register each SUID, and function calls with no registered owner will be routed to the intercept module STID.

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| Message
|-
| 01
| Function
|-
| 10
| Reserved
|-
| 11
| System/Application
|}

The following is an excerpt of the installed header file, ''sr.h'', showing the definitions of the SMID attributes:

/* Message Types (MT) */
#define srMT_ONE_CMD 0x00000000
#define srMT_ONE_RSP 0x01000000
#define srMT_TWO 0x02000000
#define srMT_BRD 0x03000000

/* Abbreviations MT */
#define srMT_ONE srMT_ONE_CMD
#define srMT_ONEc srMT_ONE_CMD
#define srMT_ONEr srMT_ONE_RSP

/* Send Type for Command (ST_CMD) */
#define srST_CMD_PTR 0x00000000
#define srST_CMD_VAL 0x04000000

/* Send Type for Response (ST_RSP) */
#define srST_RSP_PTR 0x00000000
#define srST_RSP_VAL 0x08000000

/* Pointer Usage for Command (PU_CMD) */
#define srPU_CMD_POL 0x00000000
#define srPU_CMD_PRI 0x10000000

/* Pointer Usage for Response (PU_RSP) */
#define srPU_RSP_POL 0x00000000
#define srPU_RSP_PRI 0x20000000

/* Access Class (AC) */
#define srAC_MSG 0x00000000
#define srAC_FUNCTION 0x40000000
#define srAC_SYS 0x80000000

Refer to the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf STRIDE Runtime Developer's Guide]] for additional information and usage of these definitions.

== The STRIDE Unique ID (SUID) ==
The SUID is a unique 24-bit value used to identify interfaces such as remote function calls and messages. A SUID is required when using a two-way message in order to identify the message user and allow the response payload to be routed correctly. The message user provides this unique ID to the STRIDE Runtime, which in turn sends it to the message owner. The message owner is then required to supply this same unique ID when sending a response back to the STRIDE Runtime, so that the response payload can be routed correctly.

== Examples ==

Five examples of the scl_msg pragma are shown below:

# The [[#Example_1|first example]] uses the scl_msg pragma to define a set of messages without payloads.
# The [[#Example_2|second example]] uses the scl_msg pragma to define a one-way command and a two-way command/response. Both messages are defined with a command payload.
# The [[#Example_3|third example]] uses the scl_msg pragma to define a one-way-response, a two-way command/response and a broadcast response; all with message payloads.
# The [[#Example_4|fourth example]] uses the scl_msg pragma to define a two-way command/response with associated payloads.
# The [[#Example_5|fifth example]] uses the scl_msg pragma and the void parameter to define a two-way command/response with a response payload and an empty command payload.

=== Example 1 ===

/* STRIDE Message IDs (SMIDs) defining messages without payloads */
/* SUID = 1, Message Type = One-way Command */
#define OneWayCmd 1 | srMT_ONEc
/* SUID = 2, Message Type = One-way Response */
#define OneWayRsp 2 | srMT_ONEr
/* SUID = 3, Message Type = Two-way Command/Response */
#define TwoWayMsg 3 | srMT_TWO
/* SUID = 4, Message Type = Broadcast Response */
#define BrdCstRsp 4 | srMT_BRD

/* Use the scl_msg pragma to identify the four messages without payloads */
#pragma scl_msg(OneWayCmd)
#pragma scl_msg(OneWayRsp)
#pragma scl_msg(TwoWayMsg)
#pragma scl_msg(BrdCstRsp)

=== Example 2 ===

/* STRIDE Message IDs (SMIDs) defining messages with command payloads. */
/* SUID = 1, Message Type = One-way Command, */
/* Command Send Type = By Pointer, Pointer Memory Usage = Private */
#define OneWayCmd 1 | srMT_ONEc | srST_CMD_PTR | srPU_CMD_PRI
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_CMD_VAL

/* Structure defining the command payload used with both messages */
typedef struct {
int f1;
char f2;
} CmdPayload_t;

/* Use the scl_msg pragma to associate the command payload with both SMIDs */
#pragma scl_msg(OneWayCmd, CmdPayload_t)
#pragma scl_msg(TwoWayMsg, CmdPayload_t)

=== Example 3 ===

/* STRIDE Message IDs (SMIDs) defining messages with response payloads. */
/* SUID = 1, Message Type = One-way Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define OneWayRsp 1 | srMT_ONEr | srST_RSP_PTR | srPU_RSP_POL
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = No Payload, Response Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_RSP_VAL
/* SUID = 3, Message Type = Broadcast Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define BrdCstRsp 3 | srMT_BRD | srST_RSP_PTR | srPU_RSP_POL

/* Structure defining the response payload used with the messages */
typedef struct {
int f1;
char f2;
} RspPayload_t;

/* Use the scl_msg pragma to associate the payload with each of the SMIDs */
#pragma scl_msg( OneWayRsp, RspPayload_t )
#pragma scl_msg( TwoWayMsg, RspPayload_t )
#pragma scl_msg( BrdCstRsp, RspPayload_t )

=== Example 4 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with a command and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_CMD_VAL | srST_RSP_VAL

/* Structure defining the command payload for the message */
typedef struct {
int f1;
char f2;
} CmdPayload_p;

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, CmdPayload_p, RspPayload_r )

=== Example 5 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with no command payload and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_RSP_VAL

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, void, RspPayload_r )

== See Also ==
* The [[SCL_Structure|SCL Structure]] page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs.

[[Category: SCL_Reference]]

Studio:Scl msg

2008-09-30T07:02:59Z

Shamr: /* Example 2 */ fixed SMID

= The scl_msg pragma =

The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique [[#The_STRIDE_Unique_ID_.28SUID.29|STRIDE Identifier (SUID)]] with message attributes to create a STRIDE Message Id (SMID). The SMID is then associated with command and/or response payload type definitions.

== Syntax ==

#pragma scl_msg(SMID)

#pragma scl_msg(SMID, cmd-payload)

#pragma scl_msg(SMID, rsp-payload)

#pragma scl_msg(SMID, cmd-payload, rsp-payload)

#pragma scl_msg(SMID, void, rsp-payload)

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| ''SMID''
| Integer
| SUID + attributes from which the message type and other properties are determined
|-
| ''cmd-payload ''
| Integer
| Optional name of the data type for the command payload. If omitted, then: 
The message is a one-way command or a two-way message, and the User sends an empty payload to the Owner, 
-or- 
The message is a one-way response or a broadcast and is sent from Owner to User(s). 
The SMID attributes determine the behavior.
|-
| ''rsp-payload''
| Integer
| Optional name of the data type for the response payload. If omitted then: 
The message is a one-way response or a two-way message, and the Owner is responding with an empty payload to the User, 
-or- 
The message is a one-way command.
|-
| ''void''
|
| This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload).
|}

== Notes ==
* The SMID must be a non-parameterized macro name that resolves to an integer constant expression. The macro name will become the name of the message and cannot collide with the name of any other name or function.
* The SMID, cmd-payload, rsp-payload, and cmd-payload rsp-payload must all be integer constant expressions that evaluate to a number in the range of 0 — 232 - 1 and follow the rules for a SMID.
* In order to describe a two-way message with only a return payload, the type void is allowed only in the command position in a two-way message:

#pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse);

== The STRIDE Message ID (SMID) ==
The SMID is a 32-bit structure consisting of a unique ID and a set of message attributes. The SCM defines the [[#The_STRIDE_Unique_ID_.28SUID.29|SUID]] portion as the first 24 bits of the SMID (bits 0 — 23), allowing unique identifiers up to 16,777,215. The message attributes use the highest 8 bits of the SMID (bits 24 — 31).

Each SCL-compliant message within the system must be assigned a unique message ID.
[[Image: SUID_attributes.gif|center]]

=== SMID Attributes ===
The attributes are used to declare the message type, describe how to send the option payload and indicate, if applicable, the pointer memory usage attribute for the payload. The attributes, shown below, are the message type (MT), send type for command (STc), send type for response (STr), pointer usage for command (PUc), pointer usage for response (PUr), and Access Class (AC).
[[Image:SMID_attributes_format.gif|center]]

=== Message Type (MT) Attributes ===
The Message Type (MT) attribute defines the type of message being used for communication between the owner and user. The following values are used for different message types:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| One-way command
|-
| 01
| One-way response
|-
| 10
| Two-way command-response
|-
| 11
| Broadcast message
|}

=== Send Type for Command (STc) Attributes ===

The Send Type (ST) attribute is used to indicate how to transmit the payload. There are two ways to send the payload: by value or by pointer. The STRIDE Runtime is required to use the ST attribute when determining whether to route locally or remotely across platform boundaries. The following tables describe the ST attribute settings:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

=== Send Type for Response (STr) Attributes ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

'''Note:''' When a command or response does not contain a payload, the ST attribute is set to zero (0).

When a payload is passed by pointer, a Pointer Usage (PU) attribute is required. The PU attribute indicates if the payload is using '''pool memory''' or '''private memory'''. When the PU attribute indicates '''pool''', the SCM requires that the memory be allocated from the common pool being used by the system. When the PU attribute indicates '''private''', the STRIDE Runtime environment makes no assumptions on how the payload memory is being managed between the Owner and User when they are executing on the same target platform. If the payload crosses platform boundaries, however, the Runtime is required to dynamically allocate memory from the common pool. The temporary memory that is allocated is used to hold the payload, and the address of the memory is passed to the reader. Once the reader returns the message memory to the Runtime, the temporary memory is automatically freed. The original memory from the sender is not affected or synchronized with the other platform.

The PU attributes are listed below:

=== Pointer Usage for Command (PUc) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Pointer Usage for Response (PUr) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Access Class (AC) Attributes ===
The Access Class (AC) attribute ensures that the intercept module will not register each SUID, and function calls with no registered owner will be routed to the intercept module STID.

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| Message
|-
| 01
| Function
|-
| 10
| Reserved
|-
| 11
| System/Application
|}

The following is an excerpt of the installed header file, ''sr.h'', showing the definitions of the SMID attributes:

/* Message Types (MT) */
#define srMT_ONE_CMD 0x00000000
#define srMT_ONE_RSP 0x01000000
#define srMT_TWO 0x02000000
#define srMT_BRD 0x03000000

/* Abbreviations MT */
#define srMT_ONE srMT_ONE_CMD
#define srMT_ONEc srMT_ONE_CMD
#define srMT_ONEr srMT_ONE_RSP

/* Send Type for Command (ST_CMD) */
#define srST_CMD_PTR 0x00000000
#define srST_CMD_VAL 0x04000000

/* Send Type for Response (ST_RSP) */
#define srST_RSP_PTR 0x00000000
#define srST_RSP_VAL 0x08000000

/* Pointer Usage for Command (PU_CMD) */
#define srPU_CMD_POL 0x00000000
#define srPU_CMD_PRI 0x10000000

/* Pointer Usage for Response (PU_RSP) */
#define srPU_RSP_POL 0x00000000
#define srPU_RSP_PRI 0x20000000

/* Access Class (AC) */
#define srAC_MSG 0x00000000
#define srAC_FUNCTION 0x40000000
#define srAC_SYS 0x80000000

Refer to the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf STRIDE Runtime Developer's Guide]] for additional information and usage of these definitions.

== The STRIDE Unique ID (SUID) ==
The SUID is a unique 24-bit value used to identify interfaces such as remote function calls and messages. A SUID is required when using a two-way message in order to identify the message user and allow the response payload to be routed correctly. The message user provides this unique ID to the STRIDE Runtime, which in turn sends it to the message owner. The message owner is then required to supply this same unique ID when sending a response back to the STRIDE Runtime, so that the response payload can be routed correctly.

== Examples ==

Five examples of the scl_msg pragma are shown below:

# The [[#Example_1|first example]] uses the scl_msg pragma to define a set of messages without payloads.
# The [[#Example_2|second example]] uses the scl_msg pragma to define a one-way command and a two-way command/response. Both messages are defined with a command payload.
# The [[#Example_3|third example]] uses the scl_msg pragma to define a one-way-response, a two-way command/response and a broadcast response; all with message payloads.
# The [[#Example_4|fourth example]] uses the scl_msg pragma to define a two-way command/response with associated payloads.
# The [[#Example_5|fifth example]] uses the scl_msg pragma and the void parameter to define a two-way command/response with a response payload and an empty command payload.

=== Example 1 ===

/* STRIDE Message IDs (SMIDs) defining messages without payloads */
/* SUID = 1, Message Type = One-way Command */
#define OneWayCmd 1 | srMT_ONEc
/* SUID = 2, Message Type = One-way Response */
#define OneWayRsp 2 | srMT_ONEr
/* SUID = 3, Message Type = Two-way Command/Response */
#define TwoWayMsg 3 | srMT_TWO
/* SUID = 4, Message Type = Broadcast Response */
#define BrdCstRsp 4 | srMT_BRD

/* Use the scl_msg pragma to identify the four messages without payloads */
#pragma scl_msg(1)
#pragma scl_msg(2)
#pragma scl_msg(3)
#pragma scl_msg(4)

=== Example 2 ===

/* STRIDE Message IDs (SMIDs) defining messages with command payloads. */
/* SUID = 1, Message Type = One-way Command, */
/* Command Send Type = By Pointer, Pointer Memory Usage = Private */
#define OneWayCmd 1 | srMT_ONEc | srST_CMD_PTR | srPU_CMD_PRI
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_CMD_VAL

/* Structure defining the command payload used with both messages */
typedef struct {
int f1;
char f2;
} CmdPayload_t;

/* Use the scl_msg pragma to associate the command payload with both SMIDs */
#pragma scl_msg(OneWayCmd, CmdPayload_t)
#pragma scl_msg(TwoWayMsg, CmdPayload_t)

=== Example 3 ===

/* STRIDE Message IDs (SMIDs) defining messages with response payloads. */
/* SUID = 1, Message Type = One-way Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define OneWayRsp 1 | srMT_ONEr | srST_RSP_PTR | srPU_RSP_POL
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = No Payload, Response Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_RSP_VAL
/* SUID = 3, Message Type = Broadcast Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define BrdCstRsp 3 | srMT_BRD | srST_RSP_PTR | srPU_RSP_POL

/* Structure defining the response payload used with the messages */
typedef struct {
int f1;
char f2;
} RspPayload_t;

/* Use the scl_msg pragma to associate the payload with each of the SMIDs */
#pragma scl_msg( OneWayRsp, RspPayload_t )
#pragma scl_msg( TwoWayMsg, RspPayload_t )
#pragma scl_msg( BrdCstRsp, RspPayload_t )

=== Example 4 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with a command and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_CMD_VAL | srST_RSP_VAL

/* Structure defining the command payload for the message */
typedef struct {
int f1;
char f2;
} CmdPayload_p;

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, CmdPayload_p, RspPayload_r )

=== Example 5 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with no command payload and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_RSP_VAL

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, void, RspPayload_r )

== See Also ==
* The [[SCL_Structure|SCL Structure]] page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs.

[[Category: SCL_Reference]]

Studio:Scl msg

2008-09-30T07:02:23Z

Shamr: /* Example 3 */ fixed SMID

= The scl_msg pragma =

The scl_msg pragma allows the user to define a messaging interface. Messages are defined by combining a Unique [[#The_STRIDE_Unique_ID_.28SUID.29|STRIDE Identifier (SUID)]] with message attributes to create a STRIDE Message Id (SMID). The SMID is then associated with command and/or response payload type definitions.

== Syntax ==

#pragma scl_msg(SMID)

#pragma scl_msg(SMID, cmd-payload)

#pragma scl_msg(SMID, rsp-payload)

#pragma scl_msg(SMID, cmd-payload, rsp-payload)

#pragma scl_msg(SMID, void, rsp-payload)

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| ''SMID''
| Integer
| SUID + attributes from which the message type and other properties are determined
|-
| ''cmd-payload ''
| Integer
| Optional name of the data type for the command payload. If omitted, then: 
The message is a one-way command or a two-way message, and the User sends an empty payload to the Owner, 
-or- 
The message is a one-way response or a broadcast and is sent from Owner to User(s). 
The SMID attributes determine the behavior.
|-
| ''rsp-payload''
| Integer
| Optional name of the data type for the response payload. If omitted then: 
The message is a one-way response or a two-way message, and the Owner is responding with an empty payload to the User, 
-or- 
The message is a one-way command.
|-
| ''void''
|
| This is a special parameter which can only be used if the message is a command/response and there is only a response payload (i.e., no command payload).
|}

== Notes ==
* The SMID must be a non-parameterized macro name that resolves to an integer constant expression. The macro name will become the name of the message and cannot collide with the name of any other name or function.
* The SMID, cmd-payload, rsp-payload, and cmd-payload rsp-payload must all be integer constant expressions that evaluate to a number in the range of 0 — 232 - 1 and follow the rules for a SMID.
* In order to describe a two-way message with only a return payload, the type void is allowed only in the command position in a two-way message:

#pragma scl_msg (TWO_WAY_CMD_SMID, void, TResponse);

== The STRIDE Message ID (SMID) ==
The SMID is a 32-bit structure consisting of a unique ID and a set of message attributes. The SCM defines the [[#The_STRIDE_Unique_ID_.28SUID.29|SUID]] portion as the first 24 bits of the SMID (bits 0 — 23), allowing unique identifiers up to 16,777,215. The message attributes use the highest 8 bits of the SMID (bits 24 — 31).

Each SCL-compliant message within the system must be assigned a unique message ID.
[[Image: SUID_attributes.gif|center]]

=== SMID Attributes ===
The attributes are used to declare the message type, describe how to send the option payload and indicate, if applicable, the pointer memory usage attribute for the payload. The attributes, shown below, are the message type (MT), send type for command (STc), send type for response (STr), pointer usage for command (PUc), pointer usage for response (PUr), and Access Class (AC).
[[Image:SMID_attributes_format.gif|center]]

=== Message Type (MT) Attributes ===
The Message Type (MT) attribute defines the type of message being used for communication between the owner and user. The following values are used for different message types:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| One-way command
|-
| 01
| One-way response
|-
| 10
| Two-way command-response
|-
| 11
| Broadcast message
|}

=== Send Type for Command (STc) Attributes ===

The Send Type (ST) attribute is used to indicate how to transmit the payload. There are two ways to send the payload: by value or by pointer. The STRIDE Runtime is required to use the ST attribute when determining whether to route locally or remotely across platform boundaries. The following tables describe the ST attribute settings:

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

=== Send Type for Response (STr) Attributes ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pointer
|-
| 1
| Value
|}

'''Note:''' When a command or response does not contain a payload, the ST attribute is set to zero (0).

When a payload is passed by pointer, a Pointer Usage (PU) attribute is required. The PU attribute indicates if the payload is using '''pool memory''' or '''private memory'''. When the PU attribute indicates '''pool''', the SCM requires that the memory be allocated from the common pool being used by the system. When the PU attribute indicates '''private''', the STRIDE Runtime environment makes no assumptions on how the payload memory is being managed between the Owner and User when they are executing on the same target platform. If the payload crosses platform boundaries, however, the Runtime is required to dynamically allocate memory from the common pool. The temporary memory that is allocated is used to hold the payload, and the address of the memory is passed to the reader. Once the reader returns the message memory to the Runtime, the temporary memory is automatically freed. The original memory from the sender is not affected or synchronized with the other platform.

The PU attributes are listed below:

=== Pointer Usage for Command (PUc) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Pointer Usage for Response (PUr) Attribute ===

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 0
| Pool
|-
| 1
| Private
|}

=== Access Class (AC) Attributes ===
The Access Class (AC) attribute ensures that the intercept module will not register each SUID, and function calls with no registered owner will be routed to the intercept module STID.

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| 00
| Message
|-
| 01
| Function
|-
| 10
| Reserved
|-
| 11
| System/Application
|}

The following is an excerpt of the installed header file, ''sr.h'', showing the definitions of the SMID attributes:

/* Message Types (MT) */
#define srMT_ONE_CMD 0x00000000
#define srMT_ONE_RSP 0x01000000
#define srMT_TWO 0x02000000
#define srMT_BRD 0x03000000

/* Abbreviations MT */
#define srMT_ONE srMT_ONE_CMD
#define srMT_ONEc srMT_ONE_CMD
#define srMT_ONEr srMT_ONE_RSP

/* Send Type for Command (ST_CMD) */
#define srST_CMD_PTR 0x00000000
#define srST_CMD_VAL 0x04000000

/* Send Type for Response (ST_RSP) */
#define srST_RSP_PTR 0x00000000
#define srST_RSP_VAL 0x08000000

/* Pointer Usage for Command (PU_CMD) */
#define srPU_CMD_POL 0x00000000
#define srPU_CMD_PRI 0x10000000

/* Pointer Usage for Response (PU_RSP) */
#define srPU_RSP_POL 0x00000000
#define srPU_RSP_PRI 0x20000000

/* Access Class (AC) */
#define srAC_MSG 0x00000000
#define srAC_FUNCTION 0x40000000
#define srAC_SYS 0x80000000

Refer to the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf STRIDE Runtime Developer's Guide]] for additional information and usage of these definitions.

== The STRIDE Unique ID (SUID) ==
The SUID is a unique 24-bit value used to identify interfaces such as remote function calls and messages. A SUID is required when using a two-way message in order to identify the message user and allow the response payload to be routed correctly. The message user provides this unique ID to the STRIDE Runtime, which in turn sends it to the message owner. The message owner is then required to supply this same unique ID when sending a response back to the STRIDE Runtime, so that the response payload can be routed correctly.

== Examples ==

Five examples of the scl_msg pragma are shown below:

# The [[#Example_1|first example]] uses the scl_msg pragma to define a set of messages without payloads.
# The [[#Example_2|second example]] uses the scl_msg pragma to define a one-way command and a two-way command/response. Both messages are defined with a command payload.
# The [[#Example_3|third example]] uses the scl_msg pragma to define a one-way-response, a two-way command/response and a broadcast response; all with message payloads.
# The [[#Example_4|fourth example]] uses the scl_msg pragma to define a two-way command/response with associated payloads.
# The [[#Example_5|fifth example]] uses the scl_msg pragma and the void parameter to define a two-way command/response with a response payload and an empty command payload.

=== Example 1 ===

/* STRIDE Message IDs (SMIDs) defining messages without payloads */
/* SUID = 1, Message Type = One-way Command */
#define OneWayCmd 1 | srMT_ONEc
/* SUID = 2, Message Type = One-way Response */
#define OneWayRsp 2 | srMT_ONEr
/* SUID = 3, Message Type = Two-way Command/Response */
#define TwoWayMsg 3 | srMT_TWO
/* SUID = 4, Message Type = Broadcast Response */
#define BrdCstRsp 4 | srMT_BRD

/* Use the scl_msg pragma to identify the four messages without payloads */
#pragma scl_msg(1)
#pragma scl_msg(2)
#pragma scl_msg(3)
#pragma scl_msg(4)

=== Example 2 ===

/* STRIDE Message IDs (SMIDs) defining messages with command payloads. */
/* SUID = 1, Message Type = One-way Command, */
/* Command Send Type = By Pointer, Pointer Memory Usage = Private */
#define OneWayCmd 1 | srMT_ONEc | srST_CMD_PTR | srPU_CMD_PRI
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_CMD_VAL

/* Structure defining the command payload used with both messages */
typedef struct {
int f1;
char f2;
} CmdPayload_t;

/* Use the scl_msg pragma to associate the command payload with both SMIDs */
#pragma scl_msg(1, CmdPayload_t)
#pragma scl_msg(2, CmdPayload_t)

=== Example 3 ===

/* STRIDE Message IDs (SMIDs) defining messages with response payloads. */
/* SUID = 1, Message Type = One-way Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define OneWayRsp 1 | srMT_ONEr | srST_RSP_PTR | srPU_RSP_POL
/* SUID = 2, Message Type = Two-way Command/Response, */
/* Command Send Type = No Payload, Response Send Type = By Value */
#define TwoWayMsg 2 | srMT_TWO | srST_RSP_VAL
/* SUID = 3, Message Type = Broadcast Response, */
/* Response Send Type = By Pointer, Pointer Memory Usage = Pool */
#define BrdCstRsp 3 | srMT_BRD | srST_RSP_PTR | srPU_RSP_POL

/* Structure defining the response payload used with the messages */
typedef struct {
int f1;
char f2;
} RspPayload_t;

/* Use the scl_msg pragma to associate the payload with each of the SMIDs */
#pragma scl_msg( OneWayRsp, RspPayload_t )
#pragma scl_msg( TwoWayMsg, RspPayload_t )
#pragma scl_msg( BrdCstRsp, RspPayload_t )

=== Example 4 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with a command and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_CMD_VAL | srST_RSP_VAL

/* Structure defining the command payload for the message */
typedef struct {
int f1;
char f2;
} CmdPayload_p;

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, CmdPayload_p, RspPayload_r )

=== Example 5 ===

#include <sr.h>
/* STRIDE Message ID (SMID) defining a two-way message with */
/* with no command payload and a response payload. */
/* SUID = 1, Message Type = Two-way Command/Response, */
/* Command Send Type = By Value, Response Send Type = By Value */
#define TwoWayMsg 1 | srMT_TWO | srST_RSP_VAL

/* Structure defining the response payload for the message */
typedef struct {
short f1;
float f2;
} RspPayload_r;

/* Use the scl_msg pragma to associate both payloads with the SMID */
#pragma scl_msg ( TwoWayMsg, void, RspPayload_r )

== See Also ==
* The [[SCL_Structure|SCL Structure]] page for more information on the format of the STRIDE Unique ID (SUID), and SMIDs.

[[Category: SCL_Reference]]

Studio:Why don't Perl scripts run even when Script Engine shows Perl?

2008-09-24T18:50:34Z

Shamr:

Even when ActiveState Perl is installed and STRIDE Script Engine (Tools->Options->Script Engines) shows Perl file types (PL, PLS, PM, etc), you may not be able to run Perl scripts or see "Run" button on opened Perl scripts within Studio. One of the reasons could be that ActiveState Perl registration has been modified by another program. It is known that iTunes and RealPlayer take over the ownership of .pls extension used by ActiveState Perl, on which STRIDE Script Engine relies.

'''To verify the problem:'''
* Check the value for .pls extension in the registry: HKEY_CLASSES_ROOT\.pls. If the associated value is not “PerlScriptFile”, there is a registration problem.

'''To fix the problem:'''
* Run the following on command prompt:
CMD> regsvr32 c:\perl\bin\perlSE.dll
* Remove all Perl file types (PL, PLS, PM, etc) from Tools->Options->Script Engines and "Scan" again.

'''To verify the solution:'''
* Select each Perl files type and look for the text under the buttons that says “ActiveScript compliant”.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

Studio:Why don't Perl scripts run even when Script Engine shows Perl?

2008-09-24T18:49:46Z

Shamr: added new page for Perl registration issue with .pls

Even when ActiveState Perl is installed and STRIDE Script Engine (Tools->Options->Script Engines) shows Perl file types (PL, PLS, PM, etc), you may not be able to run Perl scripts or see "Run" button on opened Perl scripts within Studio. One of the reasons could be that ActiveState Perl registration has been modified by another program. It is known that iTunes and RealPlayer take over the ownership of .pls extension used by ActiveState Perl, on which STRIDE Script Engine relies.

To verify the problem:
* Check the value for .pls extension in the registry: HKEY_CLASSES_ROOT\.pls. If the associated value is not “PerlScriptFile”, there is a registration problem.

To fix the problem:
* Run the following on command prompt:
CMD> regsvr32 c:\perl\bin\perlSE.dll
* Remove all Perl file types (PL, PLS, PM, etc) from Tools->Options->Script Engines and "Scan" again.

To verify the solution:
* Select each Perl files type and look for the text under the buttons that says “ActiveScript compliant”.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

Studio:Script execution error messages

2008-09-24T18:14:18Z

Shamr: version

If an error similar to the following occurs when trying to execute a script

...[.\Scripter.cpp:450] ERROR - [TID:604] [PID:2524] Execution of script "[script name].pl" failed - state <1>, error 0x80040154: Class not registered

it is an internal error reported when STRIDE is unable to start the script engine. Generally, it is the result of a problem during the Perl installation or a version of Perl that is not COM-compliant (e.g., Cgywin Perl) or is incompatible with STRIDE.

Verify that you have the required version of [http://www.s2technologies.com/wiki/index.php?title=Host_Installation#Perl ActiveState Perl] installed; it may be necessary to reinstall it. Once you have done this, from Studio's '''Tools->Options''' menu, click '''Scan'''.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

Studio:Script execution error messages

2008-09-23T00:01:54Z

Shamr:

If an error similar to the following occurs when trying to execute a script

...[.\Scripter.cpp:450] ERROR - [TID:604] [PID:2524] Execution of script "[script name].pl" failed - state <1>, error 0x80040154: Class not registered

it is an internal error reported when STRIDE is unable to start the script engine. Generally, it is the result of a problem during the Perl installation or a version of Perl that is not COM-compliant (e.g., Cgywin Perl) or is incompatible with STRIDE.

Verify that you have an ActiveState version of Perl 5.8 or newer installed; it may be necessary to reinstall it. Once you have done this, from Studio's '''Tools->Options''' menu, click '''Scan'''.

[[Category:Perl Info]]
[[Category:Troubleshooting]]

Test CClass Sample

2008-09-19T18:54:35Z

Shamr: /* 02_02_RuntimeServices_Dynamic */ SCR 8998

== Introduction ==
The Test CClass Samples are part of the [[Test_Unit_Samples|STRIDE Test Unit Samples]]. The CClass naming convention implies a C struct that is acting like a class object for the purpose of test unit development. The Test CClass Samples pertain to implementing test units in the C language that appear to act like test classes. If you are using C++, you will want to use the [[Test_Class_Sample|Test Class Samples]] for simplicity. The Test CClass functionality is predominantly for legacy systems that have not switched over to C++. However, the Test CClass functionality is not restricted from compiling C++ environment as well.
 
The following content relates to the sample files and workspaces installed in ''%STRIDE_DIR%\Samples\TestUnits\TestCClass''. This sample consists of a [http://en.wikipedia.org/wiki/Microsoft_Visual_Studio Visual Studio] workspace for building an [[Windows_Off-Target_Apps| windows target application]], sample [[Test Units|scl_test_cclass]] source code, and a STRIDE workspace for doing more advanced test CClass execution.

== Getting Started ==
To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version installed, you should be able to open this solution (it will be automatically upgraded if necessary). If you do not have any version of Visual Studio, it is recommended that you install the current free version of [http://en.wikipedia.org/wiki/Visual_Studio_Express Visual Studio Express].

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated. The rebuilding will produce a STRIDE database, intercept module source files, and an off-target simulator application that incorporates the test class source.

Once the build is complete, perform the following steps to run the test CClasss in the workspace:

# launch the off-target simulator, TestCClass.exe. This will run in a standard console window.
# open a command prompt window and change to this sample's directory.
# at the command prompt, run the command <tt>'''TestUnitRun.pl -v'''</tt>. This will execute all of the test units in the workspace and open a browser to display the results.
# quit the TestCClass.exe application by typing 'q' in its console window.

== Sample Test CClass ==
Now that you have built the off-target simulator and executed the test CClasss it contains, you can take time to peruse the test CClass source and the corresponding results that each produces. This section provides a brief description for each.

=== Basic Examples ===
These examples cover the simplest, easiest way to code a STRIDE test CClass. These examples use simple [http://en.wikipedia.org/wiki/Plain_Old_Data_Structures POD] return types to indicate status and do not annotate the tests with any rich information (such as comments).

==== 01_01_Basic_Simple ====
Demonstrates passing and failing tests using the four primary POD types that we can infer status from (int, short, and char). The bool POD type is allowed, but only in C++ mode.

==== 01_02_Basic_Fixtures ====
Shows how to use [[Test_Units#Pragmas_for_Test_Units|setup]] and [[Test_Units#Pragmas_for_Test_Units|teardown]] fixtures. The setup and teardown methods are called immediately before and after the execution of each test method, respectively.

==== 01_03_Basic_Constructors ====
Demonstrates how scl_test_cclass may be used with parameterized constructors. These arguments can be passed using our ascript scripting model for test units.

=== Runtime Services Examples ===
These examples cover basic usage of our Runtime Test Services API (as declared in srtest.h).

==== 02_01_RuntimeServices_Simple ====
Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to set status, [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]] to add a comment, and srTEST_ADD_COMMENT_WITH_LOCATION to add a comment that automatically includes line and file information.

==== 02_02_RuntimeServices_Dynamic ====
Shows how to use [[Test_Units#srTestSuiteAddSuite|srTestSuiteAddSuite]], [[Test_Units#srTestSuiteAddTest|srTestSuiteAddTest]], [[Test_Units#srTestSuiteAddAnnotation|srTestSuiteAddAnnotation]], and [[Test_Units#srTestAnnotationAddComment|srTestAnnotationAddComment]] for dynamic suite, test case, and annotation creation in the context of a single test method.

==== 02_03_RuntimeServices_Override ====
Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to override the status that would otherwise be inferred from the return value.

==== 02_04_RuntimeServices_VarComment ====
Demonstrates the use of [http://en.wikipedia.org/wiki/Printf printf] style format strings with [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]].

== Test CClass Execution ==
This sample demonstrates two different techniques for executing test classes.

=== Commandline Execution ===
Command line execution for test CClasss is done using the [[Test_Runners#TestUnitRun.pl|TestUnitRun]] utility. Here are several examples with specific syntax to execute scl_test_cclass tests. All of these commands can be invoked from a standard command shell and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your TestCClass.exe application running in order for the runner to be able to initiate a connection to the target simulator. In addition, you should verify that your %STRIDE_DIR%\bin\transport.cfg file is using the TCP transport to connect to port 8000 (these are the default settings when the product is installed).

==== Simple execution of all test units ====
The following command executes all of the test units found in the STRIDE database you have previously generated. For the purpose of this sample, since there is only one database, the -d parameter is not strictly needed, but we show it here for completeness.

TestUnitRun.pl -d TestCClass.sidb

This command executes all Test Units found in the database in descending alpha-numeric sort order. Any Test CClass initialization arguments are given default values (typically zero or NULL).

When you run this command, you should see the following:

Attempting connection using [Sockets (S2)(debug)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Simple...
Running Test Basic_Fixtures...
Running Test Basic_Constructors...
Running Test RuntimeServices_Simple...
Running Test RuntimeServices_Dynamic...
Running Test RuntimeServices_Override...
Running Test RuntimeServices_VarComment...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 17
Failed: 7
In Progress: 1
Not Applicable: 1
...in 10 suites.
***************************************************************************

==== Execution based on an order file ====
TestUnitRun can optionally base its execution on simple text file input. We have provided a simple order file, ''RunSimple.txt'', which specifies a subset of all the scl_test_cclass tests in this sample. This order file also shows how to create subsuites in the final output by using the special '''{suitepath}''' syntax, as described in [[Test_Runners#Usage|the usage section]].

TestUnitRun.pl -d TestCClass.sidb -o RunSimple.txt

...and will produce this output:

Attempting connection using [Sockets (S2)(debug)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Simple...
Running Test RuntimeServices_Simple...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 8
Failed: 4
In Progress: 1
Not Applicable: 1
...in 4 suites.
***************************************************************************

==== Execution based on file system order ====
TestUnitRun can also try to infer execution order and suite hierarchy from filesystem organization. If you have organized your test CClass source files (only the files that contain the scl_test_CClass pragma matter here) in a filesystem hierarchy that you want to mimic in your tests, you can specify a root of a directory tree that contains the relevant test CClass source. TestUnitRun will walk the directory structure and determine order and hierarchy of tests based on the directory structure. To see an example of this in action, you can execute this command with the sample:

TestUnitRun.pl -d TestCClass.sidb -f Tests

This will cause the runner to examine the Tests subdirectory structure and build a hierarchy of tests based on that directory tree. Subdirectories will map to suites in the final report. Here is the output for this example:

Attempting connection using [Sockets (S2)(debug)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Simple...
Running Test Basic_Fixtures...
Running Test Basic_Constructors...
Running Test RuntimeServices_Simple...
Running Test RuntimeServices_Dynamic...
Running Test RuntimeServices_Override...
Running Test RuntimeServices_VarComment...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestCClass\TestCClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 17
Failed: 7
In Progress: 1
Not Applicable: 1
...in 10 suites.
***************************************************************************

=== Workspace-based Execution ===
We also provide a sample STRIDE workspace that demonstrates the use of script execution with STRIDE Studio to manage test order and hierarchy. This workspace was created using [[WorkspaceSetup.pl]] and the [[Provided_Frameworks#WindowsTestApp|WindowsTestApp framework]]. The setup and teardown folders provided basic infrastructure scripts that start/stop the simulator application (TestCClass.exe) and to manage traceviews used for [[Runtime_Reference#Logging_Services|srPrint]] message collection. The scripts that drive the testing are in the workspace '''test''' folder. What follows is a brief description for each.

==== RunAll ====
This folder contains a single script that iterates through the entire collection of test units and executes them one at a time. The order of execution will be in descending alpabetical order (on name) since we explictly called the [[AutoScript#ascript.TestUnits|ArrangeBy]] collection method.

==== Run Individual ====
This folder shows how to use individual scripts to execute test classes. Each script takes the very simple form:

ascript.TestUnits.Item('''TEST_CClass_NAME''').Run();

..where '''TEST_CClass_NAME''' is the name of the scl_test_cclass test you want to run. You can then use the Studio tree control to change the order and hierarchy of each item by moving the scripts and creating folders. The sample contains individual scripts for a few of the sample scl_test_cclass tests - you are free to move, add, or delete any items as you experiment with the workspace.

[[Category: Samples]]

Test Class Sample

2008-09-19T18:53:17Z

Shamr: /* 03_02_srTest_Dynamic */ SCR 8998

==Introduction==

The following content relates to the sample files and workspaces installed in ''%STRIDE_DIR%\Samples\TestUnits\TestClass''. This sample consists of a [http://en.wikipedia.org/wiki/Microsoft_Visual_Studio Visual Studio] workspace for building an [[Windows_Off-Target_Apps| windows target application]], sample [[Test Units|test class]] source code, and a STRIDE workspace for doing more advanced test class execution.

==Getting Started==

To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version of Visual Studio installed, you should be able to open this solution and it will be automatically upgraded if necessary. If you do not currently have any version of Visual Studio, we recommend that you install the current free (as in beer) version of [http://en.wikipedia.org/wiki/Visual_Studio_Express Visual Studio Express].

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated and will produce a STRIDE database, intercept module source files, and an off-target simulator application that incorporates the test class source.

Once the build is complete, perform the following steps to run the test classes in the workspace:

# launch the off-target simulator, TestClass.exe. This will run in a standard console window.
# open a command prompt window and change to this sample's directory.
# at the command prompt, run the command <tt>'''TestUnitRun.pl -v'''</tt>. This will execute all of the test units in the workspace and open a browser to display the results.
# quit the TestClass.exe application by typing 'q' in its console window.

==Sample Test Classes==

Now that you have built the windows target application and executed the test classes it contains, you can take time to peruse the test class source and the corresponding results that each produces. This section provides a brief description for each.

''NOTE:'' each of the example test classes is grouped in namespace corresponding to its top-level category (e.g. ''Basic'' or ''Runtime Services''). This is something we have chosen to do for organizational purposes only -- it is '''not''' a general requirement that test classes be placed into namespaces.

===Basic Examples===

These examples cover the simplest, easiest way to code a STRIDE test class. These examples use simple [http://en.wikipedia.org/wiki/Plain_Old_Data_Structures POD] return types to indicate status and do not annotate the tests with any rich information (such as comments).

====01_01_Basic_Simple====

Demonstrates passing and failing tests using the four primary POD types that we can infer status from (int, bool, short, and char).

====01_02_Basic_Fixtures====

Shows how to use [[Test_Units#Pragmas_for_Test_Units|setup and teardown]] fixtures. The setup and teardown methods are called immediately before and after the execution of each test method, respectively.

====01_03_Basic_Exceptions====

Demonstrates how exceptions thrown from a test method are caught by our intercept module and noted in the results. Any exception that is caught by the harness is assumed to indicate failure.

====01_04_Basic_Constructors====

Demonstrates how test classes may have non-trivial constructors. These arguments can be passed using our [[AutoScript#ascript.TestUnits|ascript scripting model]] for test units.

===Runtime Services Examples===

These examples cover basic usage of our Runtime Test Services API (as declared in srtest.h).

====02_01_RuntimeServices_Simple====

Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to set status, [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]] to add a comment, and srTEST_ADD_COMMENT_WITH_LOCATION to add a comment that automatically includes line and file information.

====02_02_RuntimeServices_Dynamic====

Shows how to use [[Test_Units#srTestSuiteAddSuite|srTestSuiteAddSuite]], [[Test_Units#srTestSuiteAddTest|srTestSuiteAddTest]], [[Test_Units#srTestSuiteAddAnnotation|srTestSuiteAddAnnotation]], and [[Test_Units#srTestAnnotationAddComment|srTestAnnotationAddComment]] for dynamic suite, test, and annotation creation in the context of a single test method.

====02_03_RuntimeServices_Override====

Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to override the status that would otherwise be inferred from the return value.

====02_04_RuntimeServices_VarComment====

Demonstrates the use of [http://en.wikipedia.org/wiki/Printf printf] style format strings with [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]].

===srTest Examples===

These examples show to how to use the [[Test_Units#C.2B.2B_Test_Classes|stride::srTest]] base class for your test classes. When you publicly inherit from srTest, you get access to default testCase and testSuite members and their associated methods.

====03_01_srTest_Simple====

Demonstrates the use of [[Test_Units#SetStatus|testCase.setStatus]] to set the status for test cases.

====03_02_srTest_Dynamic====

Shows how to use [[Test_Units#AddSuite|testSuite.AddSuite]], [[Test_Units#AddTest|testSuite.AddTest]], [[Test_Units#AddAnnotation|testSuite.AddAnnotation]], and [[Test_Units#AddAnnotation.AddComment|testSuite.AddAnnotation.AddComment]] for dynamic suite, test case, and annotation creation within the context of one test method.

==Test Class Execution==

This sample demonstrates two different techniques for executing test classes.

===Command Line Execution===

Command line execution for test classes is done using the [[Test_Runners#TestUnitRun.pl|TestUnitRun utility]]. Here are several examples of specific syntax to execute test classes. All of these commands can be invoked from a standard [http://en.wikipedia.org/wiki/Command_Prompt_(Windows) command shell] (or other shell of your choosing) and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your TestClass.exe application running in order for the runner to be able to initiate a connection to the target simulator. In addition, you should verify that your %STRIDE_DIR%\bin\transport.cfg file is using the TCP transport to connect to port 8000 (these are the default settings when the product is installed).

====Simple execution of all test units====

The following command executes all of the test units found in the STRIDE database you have previously generated. For the purpose of this sample, since there is only one database, the -d parameter is not strictly needed, but we show it here for completeness.

TestUnitRun.pl -d TestClass.sidb

This command executes all Test Units found in the database in descending alpha-numeric sort order. Any Test Class initialization arguments are given default values (typically zero or NULL).

When you run this command, you should see console output like:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Constructors...
Running Test Basic::Exceptions...
Running Test Basic::Fixtures...
Running Test Basic::Simple...
Running Test RuntimeServices::Dynamic...
Running Test RuntimeServices::Override...
Running Test RuntimeServices::Simple...
Running Test RuntimeServices::VarComment...
Running Test srTest::Dynamic...
Running Test srTest::Simple...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 28
Failed: 12
In Progress: 2
Not Applicable: 2
...in 12 suites.
***************************************************************************

====Execution based on an order file====

TestUnitRun can optionally base its execution on simple text file input. We have provided a simple order file, ''RunSimple.txt'', which specifies a subset of all the Test Classes in this sample. This order file also shows how to create subsuites in the final output by using the special '''{suitepath}''' syntax, as described in [[Test_Runners#Usage|the usage section]].

TestUnitRun.pl -d TestClass.sidb -o RunSimple.txt

...and will produce this output:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Simple...
Running Test RuntimeServices::Simple...
Running Test srTest::Simple...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 13
Failed: 6
In Progress: 2
Not Applicable: 2
...in 6 suites.
***************************************************************************

====Execution based on filesystem order====

TestUnitRun can also try to infer execution order and suite hierarchy from filesystem organization. If you have organized your test class source files (only the files that contain the scl_test_class pragma matter here) in a filesystem hierarchy that you want to mimic in your tests, you can specify a root of a directory tree that contains the relevant test class source. TestUnitRun will walk the directory structure and determine order and hierarchy of tests based on the directory structure. To see an example of this in action, you can execute this command with the sample:

TestUnitRun.pl -d TestClass.sidb -f Tests

This will cause the runner to examine the Tests subdirectory structure and build a hierarchy of tests based on that directory tree. Subdirectories will map to suites in the final report. Here is the output for this example:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Simple...
Running Test Basic::Fixtures...
Running Test Basic::Exceptions...
Running Test Basic::Constructors...
Running Test RuntimeServices::Simple...
Running Test RuntimeServices::Dynamic...
Running Test RuntimeServices::Override...
Running Test RuntimeServices::VarComment...
Running Test srTest::Simple...
Running Test srTest::Dynamic...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 28
Failed: 12
In Progress: 2
Not Applicable: 2
...in 15 suites.
***************************************************************************

===Workspace-Based Execution===

We also provide a sample STRIDE workspace that demonstrates the use of script execution with STRIDE Studio to manage test order and hierarchy. This workspace was created using [[WorkspaceSetup.pl]] and the [[Provided_Frameworks#WindowsTestApp|WindowsTestApp framework]]. The setup and teardown folders provide basic infrastructure scripts that start/stop the simulator application (TestClass.exe) and to manage traceviews used for [[Runtime_Reference#Logging_Services|srPrint]] message collection. The scripts that drive the testing are in the workspace '''test''' folder. What follows is a brief description for each.

====RunAll====

This folder contains a single script that iterates through the entire collection of test units and executes them one at a time. The order of execution will be in descending alpabetical order (on name) since we explictly called the [[AutoScript#ascript.TestUnits|ArrangeBy]] collection method.

====CallConstructor====

This folder contains a simple script example that shows how to invoke test classes with constructor arguments. In this example, the Basic::Constructors test class is executed twice with different initialization (constructor) arguments both times.

====Run Individual====

This folder shows how to use individual scripts to execute test classes. Each script takes the very simple form:

ascript.TestUnits.Item('''TEST_CLASS_NAME''').Run();

..where '''TEST_CLASS_NAME''' is the name of the test class you want to run. You can then use the Studio tree control to change the order and hierarchy of each item by moving the scripts and creating folders. The sample contains individual scripts for a few of the sample test classes - you are free to move, add, or delete any items as you experiment with the workspace.

[[Category: Samples]]

Test Class Sample

2008-09-19T18:47:26Z

Shamr: /* 02_02_RuntimeServices_Dynamic */ SCR 8998

==Introduction==

The following content relates to the sample files and workspaces installed in ''%STRIDE_DIR%\Samples\TestUnits\TestClass''. This sample consists of a [http://en.wikipedia.org/wiki/Microsoft_Visual_Studio Visual Studio] workspace for building an [[Windows_Off-Target_Apps| windows target application]], sample [[Test Units|test class]] source code, and a STRIDE workspace for doing more advanced test class execution.

==Getting Started==

To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version of Visual Studio installed, you should be able to open this solution and it will be automatically upgraded if necessary. If you do not currently have any version of Visual Studio, we recommend that you install the current free (as in beer) version of [http://en.wikipedia.org/wiki/Visual_Studio_Express Visual Studio Express].

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated and will produce a STRIDE database, intercept module source files, and an off-target simulator application that incorporates the test class source.

Once the build is complete, perform the following steps to run the test classes in the workspace:

# launch the off-target simulator, TestClass.exe. This will run in a standard console window.
# open a command prompt window and change to this sample's directory.
# at the command prompt, run the command <tt>'''TestUnitRun.pl -v'''</tt>. This will execute all of the test units in the workspace and open a browser to display the results.
# quit the TestClass.exe application by typing 'q' in its console window.

==Sample Test Classes==

Now that you have built the windows target application and executed the test classes it contains, you can take time to peruse the test class source and the corresponding results that each produces. This section provides a brief description for each.

''NOTE:'' each of the example test classes is grouped in namespace corresponding to its top-level category (e.g. ''Basic'' or ''Runtime Services''). This is something we have chosen to do for organizational purposes only -- it is '''not''' a general requirement that test classes be placed into namespaces.

===Basic Examples===

These examples cover the simplest, easiest way to code a STRIDE test class. These examples use simple [http://en.wikipedia.org/wiki/Plain_Old_Data_Structures POD] return types to indicate status and do not annotate the tests with any rich information (such as comments).

====01_01_Basic_Simple====

Demonstrates passing and failing tests using the four primary POD types that we can infer status from (int, bool, short, and char).

====01_02_Basic_Fixtures====

Shows how to use [[Test_Units#Pragmas_for_Test_Units|setup and teardown]] fixtures. The setup and teardown methods are called immediately before and after the execution of each test method, respectively.

====01_03_Basic_Exceptions====

Demonstrates how exceptions thrown from a test method are caught by our intercept module and noted in the results. Any exception that is caught by the harness is assumed to indicate failure.

====01_04_Basic_Constructors====

Demonstrates how test classes may have non-trivial constructors. These arguments can be passed using our [[AutoScript#ascript.TestUnits|ascript scripting model]] for test units.

===Runtime Services Examples===

These examples cover basic usage of our Runtime Test Services API (as declared in srtest.h).

====02_01_RuntimeServices_Simple====

Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to set status, [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]] to add a comment, and srTEST_ADD_COMMENT_WITH_LOCATION to add a comment that automatically includes line and file information.

====02_02_RuntimeServices_Dynamic====

Shows how to use [[Test_Units#srTestSuiteAddSuite|srTestSuiteAddSuite]], [[Test_Units#srTestSuiteAddTest|srTestSuiteAddTest]], [[Test_Units#srTestSuiteAddAnnotation|srTestSuiteAddAnnotation]], and [[Test_Units#srTestAnnotationAddComment|srTestAnnotationAddComment]] for dynamic suite, test, and annotation creation in the context of a single test method.

====02_03_RuntimeServices_Override====

Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to override the status that would otherwise be inferred from the return value.

====02_04_RuntimeServices_VarComment====

Demonstrates the use of [http://en.wikipedia.org/wiki/Printf printf] style format strings with [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]].

===srTest Examples===

These examples show to how to use the [[Test_Units#C.2B.2B_Test_Classes|stride::srTest]] base class for your test classes. When you publicly inherit from srTest, you get access to default testCase and testSuite members and their associated methods.

====03_01_srTest_Simple====

Demonstrates the use of [[Test_Units#SetStatus|testCase.setStatus]] to set the status for test cases.

====03_02_srTest_Dynamic====

Shows how to use [[Test_Units#AddSuite|testSuite.AddSuite]] and [[Test_Units#AddTest|testSuite.AddTest]] for dynamic suite and test case creation within the context of one test method.

==Test Class Execution==

This sample demonstrates two different techniques for executing test classes.

===Command Line Execution===

Command line execution for test classes is done using the [[Test_Runners#TestUnitRun.pl|TestUnitRun utility]]. Here are several examples of specific syntax to execute test classes. All of these commands can be invoked from a standard [http://en.wikipedia.org/wiki/Command_Prompt_(Windows) command shell] (or other shell of your choosing) and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your TestClass.exe application running in order for the runner to be able to initiate a connection to the target simulator. In addition, you should verify that your %STRIDE_DIR%\bin\transport.cfg file is using the TCP transport to connect to port 8000 (these are the default settings when the product is installed).

====Simple execution of all test units====

The following command executes all of the test units found in the STRIDE database you have previously generated. For the purpose of this sample, since there is only one database, the -d parameter is not strictly needed, but we show it here for completeness.

TestUnitRun.pl -d TestClass.sidb

This command executes all Test Units found in the database in descending alpha-numeric sort order. Any Test Class initialization arguments are given default values (typically zero or NULL).

When you run this command, you should see console output like:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Constructors...
Running Test Basic::Exceptions...
Running Test Basic::Fixtures...
Running Test Basic::Simple...
Running Test RuntimeServices::Dynamic...
Running Test RuntimeServices::Override...
Running Test RuntimeServices::Simple...
Running Test RuntimeServices::VarComment...
Running Test srTest::Dynamic...
Running Test srTest::Simple...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 28
Failed: 12
In Progress: 2
Not Applicable: 2
...in 12 suites.
***************************************************************************

====Execution based on an order file====

TestUnitRun can optionally base its execution on simple text file input. We have provided a simple order file, ''RunSimple.txt'', which specifies a subset of all the Test Classes in this sample. This order file also shows how to create subsuites in the final output by using the special '''{suitepath}''' syntax, as described in [[Test_Runners#Usage|the usage section]].

TestUnitRun.pl -d TestClass.sidb -o RunSimple.txt

...and will produce this output:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Simple...
Running Test RuntimeServices::Simple...
Running Test srTest::Simple...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 13
Failed: 6
In Progress: 2
Not Applicable: 2
...in 6 suites.
***************************************************************************

====Execution based on filesystem order====

TestUnitRun can also try to infer execution order and suite hierarchy from filesystem organization. If you have organized your test class source files (only the files that contain the scl_test_class pragma matter here) in a filesystem hierarchy that you want to mimic in your tests, you can specify a root of a directory tree that contains the relevant test class source. TestUnitRun will walk the directory structure and determine order and hierarchy of tests based on the directory structure. To see an example of this in action, you can execute this command with the sample:

TestUnitRun.pl -d TestClass.sidb -f Tests

This will cause the runner to examine the Tests subdirectory structure and build a hierarchy of tests based on that directory tree. Subdirectories will map to suites in the final report. Here is the output for this example:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic::Simple...
Running Test Basic::Fixtures...
Running Test Basic::Exceptions...
Running Test Basic::Constructors...
Running Test RuntimeServices::Simple...
Running Test RuntimeServices::Dynamic...
Running Test RuntimeServices::Override...
Running Test RuntimeServices::VarComment...
Running Test srTest::Simple...
Running Test srTest::Dynamic...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestClass\TestClass.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 28
Failed: 12
In Progress: 2
Not Applicable: 2
...in 15 suites.
***************************************************************************

===Workspace-Based Execution===

We also provide a sample STRIDE workspace that demonstrates the use of script execution with STRIDE Studio to manage test order and hierarchy. This workspace was created using [[WorkspaceSetup.pl]] and the [[Provided_Frameworks#WindowsTestApp|WindowsTestApp framework]]. The setup and teardown folders provide basic infrastructure scripts that start/stop the simulator application (TestClass.exe) and to manage traceviews used for [[Runtime_Reference#Logging_Services|srPrint]] message collection. The scripts that drive the testing are in the workspace '''test''' folder. What follows is a brief description for each.

====RunAll====

This folder contains a single script that iterates through the entire collection of test units and executes them one at a time. The order of execution will be in descending alpabetical order (on name) since we explictly called the [[AutoScript#ascript.TestUnits|ArrangeBy]] collection method.

====CallConstructor====

This folder contains a simple script example that shows how to invoke test classes with constructor arguments. In this example, the Basic::Constructors test class is executed twice with different initialization (constructor) arguments both times.

====Run Individual====

This folder shows how to use individual scripts to execute test classes. Each script takes the very simple form:

ascript.TestUnits.Item('''TEST_CLASS_NAME''').Run();

..where '''TEST_CLASS_NAME''' is the name of the test class you want to run. You can then use the Studio tree control to change the order and hierarchy of each item by moving the scripts and creating folders. The sample contains individual scripts for a few of the sample test classes - you are free to move, add, or delete any items as you experiment with the workspace.

[[Category: Samples]]

Test Function List Sample

2008-09-19T18:43:04Z

Shamr: /* 02_02_RuntimeServices_Dynamic */ SCR 8998

== Introduction ==
The Test Function List Samples are part of the [[Test_Unit_Samples|STRIDE Test Unit Samples]]. Function Lists are abbreviated as 'FList' in both pragmas (as in scl_test_flist) and documentation. The Test FList Samples pertain to test units that contain lists of functions to be executed. The Test FList functionality is designed to be used for the C language (although it is not restricted from compilation in a C++ environment as well).
 
The following content relates to the sample files and workspaces installed in ''%STRIDE_DIR%\Samples\TestUnits\TestFList''. This sample consists of a [http://en.wikipedia.org/wiki/Microsoft_Visual_Studio Visual Studio] workspace for building an [[Windows_Off-Target_Apps| windows target application]], sample [[Test Units|scl_test_flist]] source code, and a STRIDE workspace for doing more advanced test function list execution.

== Getting Started ==
To begin, open the Visual Studio Solution file in the sample directory. This solution (and corresponding project) were created for Visual Studio 2005. If you have a later version installed, you should be able to open this solution (it will be automatically upgraded if necessary). If you do not have any version of Visual Studio, we recommend you install the current free version of [http://en.wikipedia.org/wiki/Visual_Studio_Express Visual Studio Express].

Once you have successfully opened the solution, rebuild it. The build process has custom STRIDE build rules integrated, The rebuilding will produce a STRIDE database, intercept module source files, and an [[Windows_Off-Target_Apps| windows target application]] that incorporates the test class source.

Once the build is complete, perform the following steps to run the test flists in the workspace:

# launch the windows target application, TestFList.exe. This will run in a standard console window.
# open a command prompt window and change to this sample's directory.
# at the command prompt, run the command <tt>'''TestUnitRun.pl -v'''</tt>. This will execute all of the test units in the workspace and open a browser to display the results.
# quit the TestFList.exe application by typing 'q' in its console window.

== Sample Test FLists ==
Now that you have built the off-target simulator and executed the test flists it contains, you can take time to peruse the test flist source and the corresponding results that each produces. This section provides a brief description for each.

=== Basic Examples ===
These examples cover the simplest, easiest way to code STRIDE scl_test_flist functionality. These examples use simple [http://en.wikipedia.org/wiki/Plain_Old_Data_Structures POD] return types to indicate status and do not annotate the tests with any rich information (such as comments).

==== 01_01_Basic_Simple ====
Demonstrates passing and failing tests using the primary POD types that we can infer status from (int, bool, short, and char). The bool POD type is only accepted in C++ mode.

==== 01_02_Basic_Fixtures ====
Shows how to use [[Test_Units#Pragmas_for_Test_Units|setup]] and [[Test_Units#Pragmas_for_Test_Units|teardown]] fixtures. The setup and teardown methods are called immediately before and after the execution of each test method, respectively.

=== Runtime Services Examples ===
These examples cover basic usage of our Runtime Test Services API (as declared in srtest.h).

==== 02_01_RuntimeServices_Simple ====
Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to set status, [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]] to add a comment, and srTEST_ADD_COMMENT_WITH_LOCATION to add a comment that automatically includes line and file information.

==== 02_02_RuntimeServices_Dynamic ====
Shows how to use [[Test_Units#srTestSuiteAddSuite|srTestSuiteAddSuite]], [[Test_Units#srTestSuiteAddTest|srTestSuiteAddTest]], [[Test_Units#srTestSuiteAddAnnotation|srTestSuiteAddAnnotation]], and [[Test_Units#srTestAnnotationAddComment|srTestAnnotationAddComment]] for dynamic suite, test, and annotation creation in the context of a single test method.

==== 02_03_RuntimeServices_Override ====
Shows how to use [[Test_Units#srTestCaseSetStatus|srTestCaseSetStatus]] to override the status that would otherwise be inferred from the return value.

==== 02_04_RuntimeServices_VarComment ====
Demonstrates the use of [http://en.wikipedia.org/wiki/Printf printf] style format strings with [[Test_Units#srTestCaseAddComment|srTestCaseAddComment]].

== Test FList Execution ==
This sample demonstrates two different techniques for executing scl_test_flist code.

=== Commandline Execution ===
Command line execution for test flists is done using the [[Test_Runners#TestUnitRun.pl|TestUnitRun]] utility. Here are several examples of specific syntax to execute function lists. All of these commands can be invoked from a standard command shell and the arguments shown assume that the commands are executed with the sample's directory as the starting directory. You must have your TestFList.exe application running in order for the runner to be able to initiate a connection to the target simulator. In addition, you should verify that your %STRIDE_DIR%\bin\transport.cfg file is using the TCP transport to connect to port 8000 (these are the default settings when the product is installed).

==== Simple execution of all test units ====
The following command executes all of the test units found in the STRIDE database you have previously generated. For the purpose of this sample, since there is only one database, the -d parameter is not strictly needed, but we show it here for completeness.

TestUnitRun.pl -d TestFList.sidb

This command executes all Test Units found in the database in descending alpha-numeric sort order. Any Test FList initialization arguments are given default values (typically zero or NULL).

When you run this command, you should see the following:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Fixtures...
Running Test Basic_Simple...
Running Test RuntimeServices_Dynamic...
Running Test RuntimeServices_Override...
Running Test RuntimeServices_Simple...
Running Test RuntimeServices_VarComment...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 17
Failed: 6
In Progress: 1
Not Applicable: 1
...in 7 suites.
***************************************************************************

==== Execution based on an order file ====
TestUnitRun can optionally base its execution on simple text file input. We have provided a simple order file, ''RunSimple.txt'', which specifies a subset of all the function list tests in this sample. This order file also shows how to create subsuites in the final output by using the special '''{suitepath}''' syntax, as described in [[Test_Runners#Usage|the usage section]].

TestUnitRun.pl -d TestFList.sidb -o RunSimple.txt

...and will produce this output:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Simple...
Running Test Basic_Fixtures...
Running Test RuntimeServices_Simple...
Running Test RuntimeServices_Dynamic...
Running Test RuntimeServices_Override...
Running Test RuntimeServices_VarComment...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 17
Failed: 6
In Progress: 1
Not Applicable: 1
...in 9 suites.
***************************************************************************

==== Execution based on file system order ====
TestUnitRun can also try to infer execution order and suite hierarchy from filesystem organization. If you have organized your function list test source files (only the files that contain the scl_test_flist pragma matter here) in a filesystem hierarchy that you want to mimic in your tests, you can specify a root of a directory tree that contains the relevant test flist source. TestUnitRun will walk the directory structure and determine order and hierarchy of tests based on the directory structure. To see an example of this in action, you can execute this command with the sample:

TestUnitRun.pl -d TestFList.sidb -f Tests

This will cause the runner to examine the Tests subdirectory structure and build a hierarchy of tests based on that directory tree. Subdirectories will map to suites in the final report. Here is the output for this example:

Attempting connection using [Sockets (S2)] transport ...
Connected to device.
Initializing STRIDE database objects...
Done.
Running Test Basic_Simple...
Running Test Basic_Fixtures...
Running Test RuntimeServices_Simple...
Running Test RuntimeServices_Dynamic...
Running Test RuntimeServices_Override...
Running Test RuntimeServices_VarComment...
Disconnected from device.
Test Results saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.xml
Test Report saved to C:\STRIDE\Samples\TestUnits\TestFList\TestFList.html
***************************************************************************
Results Summary
***************************************************************************
Passed: 17
Failed: 6
In Progress: 1
Not Applicable: 1
...in 9 suites.
***************************************************************************

=== Workspace-based Execution ===
We also provide a sample STRIDE workspace that demonstrates the use of script execution with STRIDE Studio to manage test order and hierarchy. This workspace was created using [[WorkspaceSetup.pl]] and the [[Provided_Frameworks#WindowsTestApp|WindowsTestApp framework]]. The setup and teardown folders provided basic infrastructure scripts that start/stop the simulator application (TestFList.exe) and to manage traceviews used for [[Runtime_Reference#Logging_Services|srPrint]] message collection. The scripts that drive the testing are in the workspace '''test''' folder. What follows is a brief description for each.

==== RunAll ====
This folder contains a single script that iterates through the entire collection of test units and executes them one at a time. The order of execution will be in descending alpabetical order (on name) since we explictly called the [[AutoScript#ascript.TestUnits|ArrangeBy]] collection method.

==== Run Individual ====
This folder shows how to use individual scripts to execute scl_test_flist tests. Each script takes the very simple form:

ascript.TestUnits.Item('''TEST_FLIST_NAME''').Run();

..where '''TEST_FLIST_NAME''' is the name of the scl_test_flist test you want to run. You can then use the Studio tree control to change the order and hierarchy of each item by moving the scripts and creating folders. The sample contains individual scripts for a few of the sample scl_test_flist tests - you are free to move, add, or delete any items as you experiment with the workspace.

[[Category: Samples]]

Test Units Overview

2008-09-19T16:35:02Z

Shamr: /* srTestAnnotationAddComment */

== Introduction ==

STRIDE enables testing of C/C++ code through the use of xUnit-style test units. Test units can be written by developers, captured using an SCL pragma, and executed from the host. STRIDE facilitates the execution of some or all of the test units by automatically creating entry points for the execution of test units on the target.

== Using test units ==

=== Prerequisites ===

see [[Host_Installation#Third Party Components|Perl requirements]].

===How to get started (Overview)===

The required steps to get started with writing test units are as follows:

<ol>
<li>Create a new Studio workspace (or open an existing one).</li>
<li>Set the workspace to compile in C++ mode (In Studio, choose Tools->Settings->Compile as Cpp).</li>
<li>Write a test unit. You may create a C++ test class or a C test function as your test unit. Click '''[[Test_Units#Test_Unit_Requirements|here]]''' for more information on creating test units.</li>
To implement a test unit as a test class:
<pre>
#include <srtest.h>

class Simple {
public:
int test1(void) { return 0;} // PASS
int test2(void) { return 23;} // FAIL <>0
};

#pragma scl_test_class(Simple)
</pre>
Or, as a test function:
<pre>
#ifdef __cplusplus
extern "C" {
#endif

int test1(void)
{
return 0; // PASS
}

int test1(void)
{
return 23; // FAIL <>0
}

#pragma scl_test_flist("Simple", test1, test2)

#ifdef __cplusplus
}
#endif
</pre>

<li>Compile the workspace & review the '''Simple''' interface in the Studio Interface tab</li>
<li>Create a script to generate the Intercept Module(IM) '''after''' the compilation step.
:For the simple STUB generation required for test unit execution, you can use the following code (perl syntax)</li>
<pre>
use strict;
use Win32::OLE qw(in);
Win32::OLE->Option(Warn => 3);
my $intercept = $main::studio->Workspace->Intercept;
$intercept->{Path} = $main::studio->Workspace->Path;
$intercept->{Name} = $main::studio->Workspace->Name;
map {$intercept->Item($_)->{Stub} = 1} (0..($intercept->Count - 1));
$intercept->Create();
</pre>
<li>Optionally add custom scripts to automate the building and executing your application. Refer to [[Using Frameworks]] for more information regarding building and executing tests with a target device.</li>
<li>Ensure that the Studio workspace include path contains the location to all of your test unit declaration (header) files.</li>
<li>Once you have created one or more test units, ensure the following:
:* Workspace is compiled and saved
:* Intercept Module is generated (Stubs for all Test Units)
:* Target application re-built
:* Target application downloaded & started
:* STRIDE Connected to Target
</li>

<li>If your application is running, you can start executing test units.
:* You can test-execute individual test units interactively using the '''Studio interface''' view. To do this, open the user interface view corresponding to the test unit you would like to execute, then call it. The return values will indicate how many tests produced each of four (4) result types. Furthermore, the input to the entry point will allow you to select all methods for execution (the default) or individual methods via a dropdown list of enumerated values.
:* Once you are confident that the test units are behaving as expected, you can generate one or more execution scripts using the '''Script Wizard'''. Sample '''[[templates]]''' for executing test unit entry points are provided in the %STRIDE_DIR%\templates\Script Wizard directory.
:* When writing scripts to execute test units, the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection is a powerful tool for test unit execution and reporting, and for obtaining test results.</li>
<li>For integration with larger regression test workspaces, we recommend that developers check in their test unit code and, optionally, the template-generated scripts that can be used to execute their test units.</li>
</ol>

===Pragmas for Test Units===
STRIDE supports three pragmas for capturing and qualifying test units:

*'''<code>scl_test_class ( class )</code>''': Declares a test class as captured. Once captured, STRIDE will generate the appropriate code for executing the test methods in the class. See the [[scl_test_class|scl_test_class page]] for more information.
*'''<code>scl_test_flist ( test-unit-name , test-function-name { , test-function-name } )</code>''': Declares a test unit as captured, by the specified test-unit-name. One or more functions (test methods) are associated with the test unit. Once captured, STRIDE will generate the appropriate code for executing the associated test methods. See the [[scl_test_flist|scl_test_flist page]] for more information.
*'''<code>scl_test_setup ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a setup fixture for the test unit. If specified, the setup method will be called before the execution of each test method. See the [[scl_test_setup|scl_test_setup page]] for more information.
*'''<code>scl_test_teardown ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a teardown fixture for the test unit. If specified, the teardown method will be called after the execution of each test method. See the [[scl_test_teardown|scl_test_teardown page]] for more information.

== Test Unit Requirements ==

Several variations on typical xUnit-style test units are supported. The additional supported features include:

*Test status can be set using STRIDE Runtime APIs ''or'' by specifying simple return types for test methods.
*Simple return types: 0 = PASS; <> 0 = FAIL
*void return type with no explict status setting is assumed PASS
*Test writers can create additional child suites and tests at runtime by using Runtime APIs.
*We do not rely on exceptions for reporting of status.

The STRIDE test class framework has the following requirements of each test class:

*The test class must have a suitable default (no-argument) constructor.
*The test class must have one or more public methods suitable as test methods. Allowable test methods always take no arguments (void) and return either void or simple integer types (int, short, long, char or bool). At this time, we do not allow typedef types or macros for the return values specification.
*the scl_test_class pragma must be applied to the class.

=== Simple example using return values for status ===
==== Using a Test Class ====

#include <srtest.h>

class Simple {
public:
int tc_Int_ExpectPass(void) {return 0;}
int tc_Int_ExpectFail(void) {return -1;}
bool tc_Bool_ExpectPass(void) {return true;}
bool tc_Bool_ExpectFail(void) {return false;}
};
#ifdef _SCL
#pragma scl_test_class(Simple)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

int tf_Int_ExpectPass(void) {return 0;}
int tf_Int_ExpectFail(void) {return -1;}
bool tf_Bool_ExpectPass(void) {return true;}
bool tf_Bool_ExpectFail(void) {return false;}
#ifdef _SCL
#pragma scl_test_flist("Simple", tf_Int_ExpectPass, tf_Int_ExpectFail, tf_Bool_ExpectPass, tf_Bool_ExpectFail)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using runtime test service APIs ===
==== Using a Test Class ====
#include <srtest.h>

class RuntimeServices_basic {
public:
void tc_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
};
#ifdef _SCL
#pragma scl_test_class(RuntimeServices_basic)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

void tf_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tf_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tf_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
#ifdef _SCL
#pragma scl_test_flist("RuntimeServices_basic", tf_ExpectPass, tf_ExpectFail, tf_ExpectInProgress)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using srTest base class ===

#include <srtest.h>

class MyTest : public stride::srTest {
public:
void tc_ExpectPass(void)
{
testCase.AddComment("this test should pass");
testCase.SetStatus(srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
testCase.AddComment("this test should fail");
testCase.SetStatus(srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
testCase.AddComment("this test should be in progress");
}
int tc_ChangeMyName(void)
{
testCase.AddComment("this test should have name = MyChangedName");
testCase.SetName("MyChangedName");
return 0;
}
int tc_ChangeMyDescription(void)
{
testCase.AddComment("this test should have a description set");
testCase.SetDescription("this is my new description");
return 0;
}
};
#ifdef _SCL
#pragma scl_test_class(MyTest)
#endif

== Runtime Test Services ==

The Runtime Test Services (declared in srTest.h) are a set of APIs in the STRIDE Runtime that facilitate the writing of target based test code. These APIs make up an optional portion of the STRIDE Runtime and can be used to communicate additional information about tests to the host based reporting mechanism. These APIs also allow target test code to create additional test suites and test cases dynamically at runtime.

There are 2 alternate ways of accessing these APIs: through C-based functions, or through a C++ base class from which you may derive your C++ test class. These are discussed below in C Test Functions, and C++ Test Classes sections below.

=== C Test Functions ===

The following C APIs are provided:

*'''<code>srTestSuiteAddSuite</code>''': creates an additional sub-suite at runtime.
*'''<code>srTestSuiteSetName</code>''': sets the name of the specified suite.
*'''<code>srTestSuiteSetDescription</code>''': sets the description of the specified suite.
*'''<code>srTestSuiteAddTest</code>''': creates an additional test case at runtime.
*'''<code>srTestCaseSetName</code>''': sets the name of the specified test case.
*'''<code>srTestCaseSetDescription</code>''': sets the description of the specified test case.
*'''<code>srTestCaseAddComment</code>''': adds a comment to the specified test case.
*'''<code>srTestCaseSetStatus</code>''': explicitly sets the status for the specified test case.
*'''<code>srTestSuiteAddAnnotation</code>''': creates an annotation at runtime.
*'''<code>srTestAnnotationAddComment</code>''': adds a comment to the specified annotation.

==== srTestSuiteAddSuite ====
'''Prototype'''
srTestSuiteHandle_t srTestSuiteAddSuite(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddSuite() routine is used to add a new test suite to the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test suite is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test suite. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
|srTestSuiteHandle_t
| Handle of the newly created test suite. srTEST_SUITE_INVALID indicates failure to create test suite.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_addSuite(void)
{
srTestSuiteHandle_t subSuite =
srTestSuiteAddSuite(srTEST_SUITE_DEFAULT, "tf Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addSuite)
#endif

==== srTestSuiteSetName ====
'''Prototype'''
srWORD srTestSuiteSetName(srTestSuiteHandle_t tTestSuite, const srCHAR * szName)

'''Description'''
The srTestSuiteSetName() routine is used to set the name of the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setName(void)
{
srTestSuiteSetName(srTEST_SUITE_DEFAULT, "Setting name for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setName)
#endif

==== srTestSuiteSetDescription ====
'''Prototype'''
srWORD srTestSuiteSetDescription(srTestSuiteHandle_t tTestSuite, const srCHAR * szDescr)

'''Description'''
The srTestSuiteSetDescription() routine is used to set the description of the specified test
suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setDescription(void)
{
srTestSuiteSetDescription(srTEST_SUITE_DEFAULT,
"Setting description for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setDescription)
#endif

==== srTestSuiteAddTest ====
'''Prototype'''
srTestCaseHandle_t srTestSuiteAddTest(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddTest() routine is used to add a new test case to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test case is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test case. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCaseHandle_t
| Handle of the newly created test case. srTEST_CASE_INVALID indicates failure to create test case.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addTest(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
srTestCaseHandle_t test = srTestSuiteAddTest(srTEST_SUITE_DEFAULT,
strm.str().c_str());
srTEST_ADD_COMMENT_WITH_LOCATION(test, "this is a dynamic test case");
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addTest)
#endif

==== srTestCaseSetName ====
'''Prototype'''
srWORD srTestCaseSetName(srTestCaseHandle_t tTestCase, const srCHAR *szName)

'''Description'''
The srTestCaseSetName() routine is used to set set the name of the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfcase_setName(void)
{
srTestCaseSetName(srTEST_CASE_DEFAULT, "Setting name for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setName)
#endif

==== srTestCaseSetDescription ====
'''Prototype'''
srWORD srTestCaseSetDescription(srTestCaseHandle_t tTestCase, const srCHAR * szDescr)

'''Description'''
The srTestCaseSetDescription() routine is used to set the description of the specified test
case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setDescription(void)
{
srTestCaseSetDescription(srTEST_CASE_DEFAULT,
"Setting description for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setDescription)
#endif

==== srTestCaseAddComment ====
'''Prototype'''
srWORD srTestCaseAddComment(srTestCaseHandle_t tTestCase, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestCaseAddComment() routine is used to add a comment (aka a log) to be
reported with the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_addComment(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_addComment)
#endif

==== srTestCaseSetStatus ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration)

'''Description'''
The srTestCaseSetStatus() routine is used to set the result of test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input
| The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatus(void)
{
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatus)
#endif

==== srTestCaseSetStatusEx ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration, srLONG lExtendedFailureCode)

'''Description'''
The srTestCaseSetStatusEx() routine is used to set the result of test case and allow
specification of an extendedFailureCode.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test. dwDuration Input The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|-
| lExtendedFailureCode
| Input
| The Stride framework uses the extendedFailureCode to capture the numeric results of test method when the test method fails via a numeric (non-void, nonbool) return type.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatusEx(void)
{
srTestCaseSetStatusEx(srTEST_CASE_DEFAULT, srTEST_FAIL, 0, -5);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatusEx)
#endif

==== srTestSuiteAddAnnotation ====
'''Prototype'''
srTestAnnotationHandle_t srTestSuiteAddAnnotation(rTestSuiteHandle_t tParent, srTestAnnotationLevel_e eLevel, const srCHAR * szName, const srCHAR * szDescr)

'''Description'''
The srTestSuiteAddAnnotation() routine is used to add a new annotation to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new annotation is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of annotation. If null, the default host naming scheme will be used.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of annotation. If null, description will be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotationHandle_t
| HHandle of the newly created annotation. srTEST_ANNOTATION_INVALID indicates failure to create annotation.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addAnnotation)
#endif

==== srTestAnnotationAddComment ====
'''Prototype'''
srWORD srTestAnnotationAddComment(srTestAnnotationHandle_t tTestAnnotation, const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestAnnotationAddComment() routine is used to add a comment (aka a log) to be reported with the specified annotation.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestAnnotation
| Input
| Handle to an annotation created using srTestSuiteAddAnnotation.
|-
| szLabel
| Input
| Pointer to a null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuiteAnnotation _ addComment(void)
{
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
“annot”,
“annot description”);
srTestAnnotationAddComment(annot,
srNULL,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuiteAnnotation_addComment)
#endif

=== C++ Test Classes ===
The Runtime Test Services APIs work equally well from C test functions and C++ test classes. If, however, you choose to derive your C++ test classes from the STRIDE Runtime base class, ''srTest'', then you will have access to member objects in srTest and their methods that provide the same functionality as the C API. The srTest base class provides two Member Objects, via which you can access functionality:

'''''Member Objects''''':

*''testSuite'', which has methods:
**'''<code>AddSuite</code>'''
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddTest</code>'''
**'''<code>AddAnnotation</code>'''
**'''<code>AddAnnotation.AddComment</code>'''
*''testCase'', which has methods:
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddComment</code>'''
**'''<code>SetStatus</code>'''

''''' Methods of Member Object testSuite '''''
==== AddSuite ====
'''Prototype'''
srTestSuite AddSuite(const srCHAR * szName = srNULL)

'''Description'''
The AddSuite method is used to add a new test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
|szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test suite. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestSuite
| Newly created test suite class.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
stride::srTestSuite suite = testSuite.AddSuite("tc Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetName(void);
}; 
void srtest_class::suiteSetName(void)
{
testSuite.SetName("Setting name for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetDescription(void);
}; 
void srtest_class::suiteSetDescription(void)
{
testSuite.SetDescription("Setting description for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddTest ====
'''Prototype'''
srTestCase AddTest(const srCHAR * szName = srNULL)

'''Description'''
The AddTest method is used to add a new test case to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test case. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCase
| Newly created test case class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
stride::srTestCase tc = testSuite.AddTest(strm.str().c_str());
tc.AddComment("this is a dynamic test case");
tc.SetStatus(srTEST_PASS);
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation ====
'''Prototype'''
srTestAnnoation AddAnnotation(srTestAnnotationLevel_e eLevel, const srCHAR * szName = srNULL, const srCHAR * szDescr = srNULL)

'''Description'''
The AddAnnotation method is used to add a new annotation to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of annotation. If empty, the default host naming scheme will be used.
|-
| szDescr
| Input (Optional)
| Pointer to null-terminated string that represents the description of annotation. If empty, the description will be blank.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotation
| Newly created annotation class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddAnnotation(void);
}; 
void srtest_class::suiteAddAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation.AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to an annotation created under a test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szLabel
| Input
| Pointer to null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void suiteAnnotationAddComment(void);
}; 
void srtest_class::suiteAnnotationAddComment(void)
{
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
“annot”,
“annot description”);
ta.AddComment("this comment on annotation should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

''''' Methods of Member Object testCase '''''

==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetName(void);
}; 
void srtest_class::caseSetName(void)
{
testCase.SetName("Setting name for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetDescription(void);
}; 
void srtest_class::caseSetDescription(void)
{
testCase.SetDescription("Setting description for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseAddComment(void);
}; 
void srtest_class::caseAddComment(void)
{
testCase.AddComment("this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetStatus ====
'''Prototype'''
srWORD SetStatus(srTestStatus_e eStatus, srDWORD dwDuration = 0)

'''Description'''
The SetStatus method is used to set the result of the default test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input (Optional)
| The duration of the test in clock ticks. The default is 0.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetStatus(void);
}; 
void srtest_class::caseSetStatus(void)
{
testCase.SetStatus(srTEST_INPROGRESS, 0);
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

Refer to the Reference Guide or the Runtime Developers Guide, both available in the STRIDE Online Help, for detailed information about any of these functions.

== Scripting a Test Unit ==

To automate the execution and reporting of a Test Unit a script is required. Scripts can be written by hand or automatically generated using the Script Wizard and a corresponding template script. A scripting tool for executing a test unit is the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection. An [[AutoScript#ascript.TestUnits.Item|Ascript TestUnit]] object assembles all of the reporting information for the test unit and its corresponding test methods.

*Require useage of the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection
*Can be written by hand (refer below)
*Can leverage [[Templates|Templates]] via the Script Wizard
*Order of multiple test units dictated by SUID assignment

 

=== JScript example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

// Ensure test unit exists
if (ascript.TestUnits.Item("Simple") != null )
ascript.TestUnits.Item("Simple").Run();

=== Perl example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

my $tu = $main::ascript->TestUnits->Item("Simple");
if (defined $tu) {
$tu->Run();
}

=== JScript example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

var Units = ["Simple1","Simple2"];

// iterate through each function
for (i in Units)
{
var tu = ascript.TestUnits.Item(Units[i]);
if ( tu != null )
tu.Run();
}

=== Perl example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

# initialize an array with all selected function names
my @UnitNames = ("Simple1","Simple2");
foreach (@UnitNames) {
my $tu = $main::ascript->TestUnits->Item($_->[1]);
die "TestUnit not found: $_->[1]\n" unless (defined $tu);
$tu->Run();
}

[[Category:Reference]]

STRIDE Runtime

2008-09-19T01:32:50Z

Shamr: /* C++ Test Classes */

== Overview ==

The STRIDE Runtime routes messages both within and between platform boundaries and manages the conversion of interface data as it crosses from one platform to another. This "transparent messaging" model means that your test cases can be located on one platform (e.g., as a script running off-target) and your code on another (on-target).

The STRIDE Runtime is a combination of processes and libraries that provide services for messaging, remote function calls, and tracing while providing seamless connectivity between the target application and the host operating system. The STRIDE Runtime standardizes how threads and applications communicate with each other, independent of the platform on which they are executing, which eliminates the need to integrate new software on the target hardware. Developers can then incrementally integrate embedded software on a combination of the desktop environment and the target hardware, providing more control over integration and testing. New software functionality under development can be simulated on the desktop environment while the software using this new functionality can run on the target hardware. The tremendous flexibility gained by allowing developers to choose how to integrate different software components and target platforms allows developers to detect integration and testing issues and correct defects much earlier in the development process.

 

[[Image:Runtime Overview.jpg|600px|center|Overview of the STRIDE Runtime]]

 The Runtime components consist of:

*The '''PAL (Platform Abstraction Layer)''' - provides a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. It consists of a small set of functions that provide a virtual link between the target operating system and the STRIDE Runtime. The PAL functionality, defined in the ''pal.h'' header file, allows the STRIDE Runtime to transmit and receive packets of data (called I-blocks) using the platform’s transport mechanism.

*The '''Host Transport Layer and Object Model''' - a server process and set of APIs that connects the Transport DLL to the STRIDE Runtime, providing indirect access to the target from host-side scripts and STRIDE applications. The Host Transport Services are defined in the ''transport.h'' header file. The Transport Server process is is accessed through the set of interfaces defined for the ''STRIDE.transport'' COM server.

*The '''Runtime APIs''' - a public API set, defined in the ''sr.h'' header file, available for programmers to integrate into their target application code. These APIs support messaging, remote function calls, and tracing between the target application and host operating system.

*The '''Intercept Module''' - generated code that facilitates remote function calls between the host and target. The IM code links to the target application; it implements '''stubs '''to allow remote function calls from the host to target-resident functions, and '''proxies '''that intercept target function calls and remotes them to a host implementation of the function. The IM can contain logic to dynamically switch target-based function calls to either host-resident or target-resident implementations, and capture tracing information, through '''delegates'''.

Additionally, groups of Runtime APIs provide test unit logging and services, and a software development kit is available for creating windows-based target applications. Each is briefly described here, with links provided for more detail.

 

== The Platform Abstraction Layer ==

The Platform Abstraction Layer, or PAL, defines the set of OS functionality required by the platform to support the STRIDE Runtime. The “pal.h” header file provided with the STRIDE installation defines the PAL functionality. The PAL also defines functionality required by the STRIDE Runtime to transmit and receive packets of data (called I-blocks) using the platform’s transport mechanism. These PAL routines enable the STRIDE Runtime to be installed on diverse environments without changing its internal design. 

Refer to the [[Platform Abstraction Layer|Platform Abstraction Layer]] page and the [[http://www.s2technologies.com/pdf/s2sPAL.pdf PAL Specification]] document for a more detailed description of the PAL and its interfaces.

 

== The Host Transport Services ==

The Host Transport Services define an interface that enables the STRIDE Runtime on your target to send data to and receive data from the target. The STRIDE Transport Server connects the Transport DLL to the STRIDE Runtime running on the host platform, thus providing indirect access to the target from STRIDE Studio, Autoscript, and other STRIDE applications. Several common transports are already supported within the STRIDE Transport Server, including serial and TCP/IP.

[[Image:Transport diagram.gif|center|Host Transport Services Diagram]]

The Host Transport Services are defined in "transport.h" and each Transport DLL must implement the interfaces derived from the IStrideTransport class.

Refer to the [[http://www.s2technologies.com/pdf/s2sTransport.pdf Host Runtime Transport Specification]] document for a more detailed description of the Host Transport Services.

 

== The Intercept Module ==

The [[Intercept Module]] page provides details of the Intercept Module concept. 

The [[Name Mangling]] page provides more background on the use of name mangling when implementing delegates within an Intercept Module.

 

== The Runtime Developer's Guide ==

Click [[http://www.s2technologies.com/pdf/s2sRuntime.pdf here]] to view the STRIDE Runtime Developer's Guide PDF document.

 

== Public Services ==

 

=== Runtime Test Services (RTS) ===

 The Runtime Test Services (RTS) are a set of C-based APIs in the STRIDE Runtime that facilitate the writing of target based test code. These APIs make up an optional portion of the STRIDE Runtime and can be used to communicate additional information about tests to the host based reporting mechanism. These APIs also allow target test code to create additional test suites and test cases dynamically at runtime. These C-based APIs work equally well from '''C Test Functions''' and '''C++ Test Classes'''. If, however, you choose to derive your C++ test classes from the '''STRIDE Runtime Base Class (srTest)''', then you will have access to member objects in the srTest class and its methods that provide the same functionality as the C APIs. 

 

==== C Test Functions ====

C test functions enable testing of C code similarily to xUnit-style testing. Test functions can be written by users, captured using the scl_function pragma, and executed from the host. C-based Runtime Test Services APIs are available for use in test functions. 

'''C-based Runtime Test Services APIs provided:'''

*'''srTestSuiteAddSuite''': creates an additional sub-suite at runtime.
*'''srTestSuiteSetName''': sets the name of the specified suite.
*'''srTestSuiteSetDescription''': sets the description of the specified suite.
*'''srTestSuiteAddTest''': creates an additional test case at runtime.
*'''srTestCaseSetName''': sets the name of the specified test case.
*'''srTestCaseSetDescription''': sets the description of the specified test case.
*'''srTestCaseAddComment''': adds a comment to the specified test case.
*'''srTestCaseSetStatus''': explicitly sets the status for the specified test case.
*'''srTestCaseSetStatusEx''': explicitly sets the status for the specified test case and allows specification of an extended failure code.
*'''srTestSuiteAddAnnotation: creates an annotation at runtime.
*'''srTestAnnotationAddComment: adds a comment to the specified annotation.

 

==== C++ Test Classes ====

C++ test classes enable testing of C++ code similarily to xUnit-style testing. Test classes can be written by users, captured using scl_test_class, scl_test_setup and scl_test_teardown pragmas, and executed from the host. C-based Runtime Test Services APIs as well as C++ Runtime Base Class are available for use in test classes. 

'''Member objects of srTest base class:'''

*'''testSuite '''member object provides following methods:
**'''AddSuite''': creates an additional sub-suite at runtime.
**'''SetName''': sets the name of the specified suite.
**'''SetDescription''': sets the description of the specified suite.
**'''AddTest''': creates an additional test case at runtime.
**'''AddAnnotation
**'''AddAnnotation.AddComment

*'''testCase '''member object provides following methods:
**'''SetName''': sets the name of the specified test case.
**'''SetDescription''': sets the description of the specified test case.
**'''AddComment''': adds a comment to the specified test case.
**'''SetStatus''': explicitly sets the status for the specified test case.

 These services use the '''''srtest.h''''' header file. Please refer to the '''[[Test_Units#Runtime_Test_Services|Test Units page]]''', or Chapter 4 of the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf Runtime Developer's Guide]] for more information on these APIs. 

 

=== Logging Services ===

The following are the categories available in the Runtime API for logging, that is, collecting and/or displaying, information at the host runtime environment:

*'''Setup and Shutdown'''
**'''srCreateSTID()''': used to allocate resources required to send and receive trace and print messages that implement the following APIs.
**'''srDeleteSTID()''': used to free STRIDE Runtime resources previously allocated for an STID.

*'''Tracing''' - Tracing routines are used by target applications for information collection and display by the host runtime environment.
**'''srTracePoint()''': used to output a data structure to the tracing window on the host.
**'''srTraceStr()''': used to output a string to the tracing window.

*'''Printing''' - These routines are used by applications to log or display messages on Trace Views on the host.
**'''srPrintInfo()''': used to output a formatted string with variable arguments to be displayed at information level filtering.
**'''srPrintError()''': used to output a formatted string with variable arguments to be displayed at error level filtering.

These services use the '''''sr.h''''' header file. Please refer to Chapter 3 of the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf Runtime Developer's Guide]] for more information on these APIs. 

 

== The Windows Off-Target SDK ==

The STRIDE development environment provides a way for you to build and execute your application and test code off-target, on a Windows host platform. This provides a faster way to test and validate your code since it does not require you to build your target application and re-image the device.

The Windows Off-Target SDK consists of: 

*The Target Runtime, PAL and [[GRS|GRS]] packaged in the s2srwin.lib and s2srwin.dll files, installed in the STRIDE\lib and STRIDE\bin directories.

*The public APIs for these components, available through header files installed in the STRIDE\inc directory. These include:
**sr.h
**srwin.h
**grs.h
**pal.h

*Utility script components that facilitate building and executing off-target applications on Windows hosts:
**[[STRIDE.vsbuild|STRIDE.vsbuild]]
**[[STRIDE.windowsprocess|STRIDE.windowsprocess]]

These components are written in the Perl scripting language and therefore require that Perl be installed. See [[Host_Installation#Third Party Requirements|Perl requirements]] for more information. 

Development of off-target applications using the SDK resources is discussed in more detail in the [[Windows Off-Target Apps|Windows Off-Target Apps]] page.

== The Transport Server Object Model ==

The Transport Server is an out-of-process COM server that provides connection management, loopback and diagnostic features. It can be accessed by clients through the STRIDE.transport Program ID. The Transport Server API is defined in the [[Transport Server Component|Transport Server Object Model]] page.

[[Category: Reference]]

Test Units Overview

2008-09-19T01:01:34Z

Shamr: /* AddAnnotation.AddComment */

== Introduction ==

STRIDE enables testing of C/C++ code through the use of xUnit-style test units. Test units can be written by developers, captured using an SCL pragma, and executed from the host. STRIDE facilitates the execution of some or all of the test units by automatically creating entry points for the execution of test units on the target.

== Using test units ==

=== Prerequisites ===

see [[Host_Installation#Third Party Components|Perl requirements]].

===How to get started (Overview)===

The required steps to get started with writing test units are as follows:

<ol>
<li>Create a new Studio workspace (or open an existing one).</li>
<li>Set the workspace to compile in C++ mode (In Studio, choose Tools->Settings->Compile as Cpp).</li>
<li>Write a test unit. You may create a C++ test class or a C test function as your test unit. Click '''[[Test_Units#Test_Unit_Requirements|here]]''' for more information on creating test units.</li>
To implement a test unit as a test class:
<pre>
#include <srtest.h>

class Simple {
public:
int test1(void) { return 0;} // PASS
int test2(void) { return 23;} // FAIL <>0
};

#pragma scl_test_class(Simple)
</pre>
Or, as a test function:
<pre>
#ifdef __cplusplus
extern "C" {
#endif

int test1(void)
{
return 0; // PASS
}

int test1(void)
{
return 23; // FAIL <>0
}

#pragma scl_test_flist("Simple", test1, test2)

#ifdef __cplusplus
}
#endif
</pre>

<li>Compile the workspace & review the '''Simple''' interface in the Studio Interface tab</li>
<li>Create a script to generate the Intercept Module(IM) '''after''' the compilation step.
:For the simple STUB generation required for test unit execution, you can use the following code (perl syntax)</li>
<pre>
use strict;
use Win32::OLE qw(in);
Win32::OLE->Option(Warn => 3);
my $intercept = $main::studio->Workspace->Intercept;
$intercept->{Path} = $main::studio->Workspace->Path;
$intercept->{Name} = $main::studio->Workspace->Name;
map {$intercept->Item($_)->{Stub} = 1} (0..($intercept->Count - 1));
$intercept->Create();
</pre>
<li>Optionally add custom scripts to automate the building and executing your application. Refer to [[Using Frameworks]] for more information regarding building and executing tests with a target device.</li>
<li>Ensure that the Studio workspace include path contains the location to all of your test unit declaration (header) files.</li>
<li>Once you have created one or more test units, ensure the following:
:* Workspace is compiled and saved
:* Intercept Module is generated (Stubs for all Test Units)
:* Target application re-built
:* Target application downloaded & started
:* STRIDE Connected to Target
</li>

<li>If your application is running, you can start executing test units.
:* You can test-execute individual test units interactively using the '''Studio interface''' view. To do this, open the user interface view corresponding to the test unit you would like to execute, then call it. The return values will indicate how many tests produced each of four (4) result types. Furthermore, the input to the entry point will allow you to select all methods for execution (the default) or individual methods via a dropdown list of enumerated values.
:* Once you are confident that the test units are behaving as expected, you can generate one or more execution scripts using the '''Script Wizard'''. Sample '''[[templates]]''' for executing test unit entry points are provided in the %STRIDE_DIR%\templates\Script Wizard directory.
:* When writing scripts to execute test units, the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection is a powerful tool for test unit execution and reporting, and for obtaining test results.</li>
<li>For integration with larger regression test workspaces, we recommend that developers check in their test unit code and, optionally, the template-generated scripts that can be used to execute their test units.</li>
</ol>

===Pragmas for Test Units===
STRIDE supports three pragmas for capturing and qualifying test units:

*'''<code>scl_test_class ( class )</code>''': Declares a test class as captured. Once captured, STRIDE will generate the appropriate code for executing the test methods in the class. See the [[scl_test_class|scl_test_class page]] for more information.
*'''<code>scl_test_flist ( test-unit-name , test-function-name { , test-function-name } )</code>''': Declares a test unit as captured, by the specified test-unit-name. One or more functions (test methods) are associated with the test unit. Once captured, STRIDE will generate the appropriate code for executing the associated test methods. See the [[scl_test_flist|scl_test_flist page]] for more information.
*'''<code>scl_test_setup ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a setup fixture for the test unit. If specified, the setup method will be called before the execution of each test method. See the [[scl_test_setup|scl_test_setup page]] for more information.
*'''<code>scl_test_teardown ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a teardown fixture for the test unit. If specified, the teardown method will be called after the execution of each test method. See the [[scl_test_teardown|scl_test_teardown page]] for more information.

== Test Unit Requirements ==

Several variations on typical xUnit-style test units are supported. The additional supported features include:

*Test status can be set using STRIDE Runtime APIs ''or'' by specifying simple return types for test methods.
*Simple return types: 0 = PASS; <> 0 = FAIL
*void return type with no explict status setting is assumed PASS
*Test writers can create additional child suites and tests at runtime by using Runtime APIs.
*We do not rely on exceptions for reporting of status.

The STRIDE test class framework has the following requirements of each test class:

*The test class must have a suitable default (no-argument) constructor.
*The test class must have one or more public methods suitable as test methods. Allowable test methods always take no arguments (void) and return either void or simple integer types (int, short, long, char or bool). At this time, we do not allow typedef types or macros for the return values specification.
*the scl_test_class pragma must be applied to the class.

=== Simple example using return values for status ===
==== Using a Test Class ====

#include <srtest.h>

class Simple {
public:
int tc_Int_ExpectPass(void) {return 0;}
int tc_Int_ExpectFail(void) {return -1;}
bool tc_Bool_ExpectPass(void) {return true;}
bool tc_Bool_ExpectFail(void) {return false;}
};
#ifdef _SCL
#pragma scl_test_class(Simple)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

int tf_Int_ExpectPass(void) {return 0;}
int tf_Int_ExpectFail(void) {return -1;}
bool tf_Bool_ExpectPass(void) {return true;}
bool tf_Bool_ExpectFail(void) {return false;}
#ifdef _SCL
#pragma scl_test_flist("Simple", tf_Int_ExpectPass, tf_Int_ExpectFail, tf_Bool_ExpectPass, tf_Bool_ExpectFail)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using runtime test service APIs ===
==== Using a Test Class ====
#include <srtest.h>

class RuntimeServices_basic {
public:
void tc_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
};
#ifdef _SCL
#pragma scl_test_class(RuntimeServices_basic)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

void tf_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tf_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tf_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
#ifdef _SCL
#pragma scl_test_flist("RuntimeServices_basic", tf_ExpectPass, tf_ExpectFail, tf_ExpectInProgress)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using srTest base class ===

#include <srtest.h>

class MyTest : public stride::srTest {
public:
void tc_ExpectPass(void)
{
testCase.AddComment("this test should pass");
testCase.SetStatus(srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
testCase.AddComment("this test should fail");
testCase.SetStatus(srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
testCase.AddComment("this test should be in progress");
}
int tc_ChangeMyName(void)
{
testCase.AddComment("this test should have name = MyChangedName");
testCase.SetName("MyChangedName");
return 0;
}
int tc_ChangeMyDescription(void)
{
testCase.AddComment("this test should have a description set");
testCase.SetDescription("this is my new description");
return 0;
}
};
#ifdef _SCL
#pragma scl_test_class(MyTest)
#endif

== Runtime Test Services ==

The Runtime Test Services (declared in srTest.h) are a set of APIs in the STRIDE Runtime that facilitate the writing of target based test code. These APIs make up an optional portion of the STRIDE Runtime and can be used to communicate additional information about tests to the host based reporting mechanism. These APIs also allow target test code to create additional test suites and test cases dynamically at runtime.

There are 2 alternate ways of accessing these APIs: through C-based functions, or through a C++ base class from which you may derive your C++ test class. These are discussed below in C Test Functions, and C++ Test Classes sections below.

=== C Test Functions ===

The following C APIs are provided:

*'''<code>srTestSuiteAddSuite</code>''': creates an additional sub-suite at runtime.
*'''<code>srTestSuiteSetName</code>''': sets the name of the specified suite.
*'''<code>srTestSuiteSetDescription</code>''': sets the description of the specified suite.
*'''<code>srTestSuiteAddTest</code>''': creates an additional test case at runtime.
*'''<code>srTestCaseSetName</code>''': sets the name of the specified test case.
*'''<code>srTestCaseSetDescription</code>''': sets the description of the specified test case.
*'''<code>srTestCaseAddComment</code>''': adds a comment to the specified test case.
*'''<code>srTestCaseSetStatus</code>''': explicitly sets the status for the specified test case.
*'''<code>srTestSuiteAddAnnotation</code>''': creates an annotation at runtime.
*'''<code>srTestAnnotationAddComment</code>''': adds a comment to the specified annotation.

==== srTestSuiteAddSuite ====
'''Prototype'''
srTestSuiteHandle_t srTestSuiteAddSuite(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddSuite() routine is used to add a new test suite to the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test suite is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test suite. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
|srTestSuiteHandle_t
| Handle of the newly created test suite. srTEST_SUITE_INVALID indicates failure to create test suite.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_addSuite(void)
{
srTestSuiteHandle_t subSuite =
srTestSuiteAddSuite(srTEST_SUITE_DEFAULT, "tf Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addSuite)
#endif

==== srTestSuiteSetName ====
'''Prototype'''
srWORD srTestSuiteSetName(srTestSuiteHandle_t tTestSuite, const srCHAR * szName)

'''Description'''
The srTestSuiteSetName() routine is used to set the name of the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setName(void)
{
srTestSuiteSetName(srTEST_SUITE_DEFAULT, "Setting name for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setName)
#endif

==== srTestSuiteSetDescription ====
'''Prototype'''
srWORD srTestSuiteSetDescription(srTestSuiteHandle_t tTestSuite, const srCHAR * szDescr)

'''Description'''
The srTestSuiteSetDescription() routine is used to set the description of the specified test
suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setDescription(void)
{
srTestSuiteSetDescription(srTEST_SUITE_DEFAULT,
"Setting description for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setDescription)
#endif

==== srTestSuiteAddTest ====
'''Prototype'''
srTestCaseHandle_t srTestSuiteAddTest(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddTest() routine is used to add a new test case to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test case is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test case. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCaseHandle_t
| Handle of the newly created test case. srTEST_CASE_INVALID indicates failure to create test case.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addTest(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
srTestCaseHandle_t test = srTestSuiteAddTest(srTEST_SUITE_DEFAULT,
strm.str().c_str());
srTEST_ADD_COMMENT_WITH_LOCATION(test, "this is a dynamic test case");
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addTest)
#endif

==== srTestCaseSetName ====
'''Prototype'''
srWORD srTestCaseSetName(srTestCaseHandle_t tTestCase, const srCHAR *szName)

'''Description'''
The srTestCaseSetName() routine is used to set set the name of the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfcase_setName(void)
{
srTestCaseSetName(srTEST_CASE_DEFAULT, "Setting name for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setName)
#endif

==== srTestCaseSetDescription ====
'''Prototype'''
srWORD srTestCaseSetDescription(srTestCaseHandle_t tTestCase, const srCHAR * szDescr)

'''Description'''
The srTestCaseSetDescription() routine is used to set the description of the specified test
case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setDescription(void)
{
srTestCaseSetDescription(srTEST_CASE_DEFAULT,
"Setting description for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setDescription)
#endif

==== srTestCaseAddComment ====
'''Prototype'''
srWORD srTestCaseAddComment(srTestCaseHandle_t tTestCase, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestCaseAddComment() routine is used to add a comment (aka a log) to be
reported with the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_addComment(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_addComment)
#endif

==== srTestCaseSetStatus ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration)

'''Description'''
The srTestCaseSetStatus() routine is used to set the result of test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input
| The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatus(void)
{
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatus)
#endif

==== srTestCaseSetStatusEx ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration, srLONG lExtendedFailureCode)

'''Description'''
The srTestCaseSetStatusEx() routine is used to set the result of test case and allow
specification of an extendedFailureCode.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test. dwDuration Input The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|-
| lExtendedFailureCode
| Input
| The Stride framework uses the extendedFailureCode to capture the numeric results of test method when the test method fails via a numeric (non-void, nonbool) return type.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatusEx(void)
{
srTestCaseSetStatusEx(srTEST_CASE_DEFAULT, srTEST_FAIL, 0, -5);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatusEx)
#endif

==== srTestSuiteAddAnnotation ====
'''Prototype'''
srTestAnnotationHandle_t srTestSuiteAddAnnotation(rTestSuiteHandle_t tParent, srTestAnnotationLevel_e eLevel, const srCHAR * szName, const srCHAR * szDescr)

'''Description'''
The srTestSuiteAddAnnotation() routine is used to add a new annotation to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new annotation is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of annotation. If null, the default host naming scheme will be used.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of annotation. If null, description will be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotationHandle_t
| HHandle of the newly created annotation. srTEST_ANNOTATION_INVALID indicates failure to create annotation.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addAnnotation)
#endif

==== srTestAnnotationAddComment ====
'''Prototype'''
srWORD srTestAnnotationAddComment(srTestAnnotationHandle_t tTestAnnotation, const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestAnnotationAddComment() routine is used to add a comment (aka a log) to be reported with the specified annotation.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestAnnotation
| Input
| Handle to an annotation created using srTestSuiteAddAnnotation.
|-
| szLabel
| Input
| Pointer to a null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuiteAnnotation _ addComment(void)
{
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
“annot”,
“annot description”);
srTestAnnotationAddComment(annot,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuiteAnnotation_addComment)
#endif

=== C++ Test Classes ===
The Runtime Test Services APIs work equally well from C test functions and C++ test classes. If, however, you choose to derive your C++ test classes from the STRIDE Runtime base class, ''srTest'', then you will have access to member objects in srTest and their methods that provide the same functionality as the C API. The srTest base class provides two Member Objects, via which you can access functionality:

'''''Member Objects''''':

*''testSuite'', which has methods:
**'''<code>AddSuite</code>'''
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddTest</code>'''
**'''<code>AddAnnotation</code>'''
**'''<code>AddAnnotation.AddComment</code>'''
*''testCase'', which has methods:
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddComment</code>'''
**'''<code>SetStatus</code>'''

''''' Methods of Member Object testSuite '''''
==== AddSuite ====
'''Prototype'''
srTestSuite AddSuite(const srCHAR * szName = srNULL)

'''Description'''
The AddSuite method is used to add a new test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
|szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test suite. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestSuite
| Newly created test suite class.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
stride::srTestSuite suite = testSuite.AddSuite("tc Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetName(void);
}; 
void srtest_class::suiteSetName(void)
{
testSuite.SetName("Setting name for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetDescription(void);
}; 
void srtest_class::suiteSetDescription(void)
{
testSuite.SetDescription("Setting description for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddTest ====
'''Prototype'''
srTestCase AddTest(const srCHAR * szName = srNULL)

'''Description'''
The AddTest method is used to add a new test case to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test case. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCase
| Newly created test case class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
stride::srTestCase tc = testSuite.AddTest(strm.str().c_str());
tc.AddComment("this is a dynamic test case");
tc.SetStatus(srTEST_PASS);
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation ====
'''Prototype'''
srTestAnnoation AddAnnotation(srTestAnnotationLevel_e eLevel, const srCHAR * szName = srNULL, const srCHAR * szDescr = srNULL)

'''Description'''
The AddAnnotation method is used to add a new annotation to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of annotation. If empty, the default host naming scheme will be used.
|-
| szDescr
| Input (Optional)
| Pointer to null-terminated string that represents the description of annotation. If empty, the description will be blank.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotation
| Newly created annotation class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddAnnotation(void);
}; 
void srtest_class::suiteAddAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation.AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to an annotation created under a test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szLabel
| Input
| Pointer to null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void suiteAnnotationAddComment(void);
}; 
void srtest_class::suiteAnnotationAddComment(void)
{
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
“annot”,
“annot description”);
ta.AddComment("this comment on annotation should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

''''' Methods of Member Object testCase '''''

==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetName(void);
}; 
void srtest_class::caseSetName(void)
{
testCase.SetName("Setting name for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetDescription(void);
}; 
void srtest_class::caseSetDescription(void)
{
testCase.SetDescription("Setting description for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseAddComment(void);
}; 
void srtest_class::caseAddComment(void)
{
testCase.AddComment("this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetStatus ====
'''Prototype'''
srWORD SetStatus(srTestStatus_e eStatus, srDWORD dwDuration = 0)

'''Description'''
The SetStatus method is used to set the result of the default test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input (Optional)
| The duration of the test in clock ticks. The default is 0.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetStatus(void);
}; 
void srtest_class::caseSetStatus(void)
{
testCase.SetStatus(srTEST_INPROGRESS, 0);
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

Refer to the Reference Guide or the Runtime Developers Guide, both available in the STRIDE Online Help, for detailed information about any of these functions.

== Scripting a Test Unit ==

To automate the execution and reporting of a Test Unit a script is required. Scripts can be written by hand or automatically generated using the Script Wizard and a corresponding template script. A scripting tool for executing a test unit is the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection. An [[AutoScript#ascript.TestUnits.Item|Ascript TestUnit]] object assembles all of the reporting information for the test unit and its corresponding test methods.

*Require useage of the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection
*Can be written by hand (refer below)
*Can leverage [[Templates|Templates]] via the Script Wizard
*Order of multiple test units dictated by SUID assignment

 

=== JScript example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

// Ensure test unit exists
if (ascript.TestUnits.Item("Simple") != null )
ascript.TestUnits.Item("Simple").Run();

=== Perl example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

my $tu = $main::ascript->TestUnits->Item("Simple");
if (defined $tu) {
$tu->Run();
}

=== JScript example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

var Units = ["Simple1","Simple2"];

// iterate through each function
for (i in Units)
{
var tu = ascript.TestUnits.Item(Units[i]);
if ( tu != null )
tu.Run();
}

=== Perl example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

# initialize an array with all selected function names
my @UnitNames = ("Simple1","Simple2");
foreach (@UnitNames) {
my $tu = $main::ascript->TestUnits->Item($_->[1]);
die "TestUnit not found: $_->[1]\n" unless (defined $tu);
$tu->Run();
}

[[Category:Reference]]

Test Units Overview

2008-09-19T01:00:14Z

Shamr: /* Runtime Test Services */ SCR 8998

== Introduction ==

STRIDE enables testing of C/C++ code through the use of xUnit-style test units. Test units can be written by developers, captured using an SCL pragma, and executed from the host. STRIDE facilitates the execution of some or all of the test units by automatically creating entry points for the execution of test units on the target.

== Using test units ==

=== Prerequisites ===

see [[Host_Installation#Third Party Components|Perl requirements]].

===How to get started (Overview)===

The required steps to get started with writing test units are as follows:

<ol>
<li>Create a new Studio workspace (or open an existing one).</li>
<li>Set the workspace to compile in C++ mode (In Studio, choose Tools->Settings->Compile as Cpp).</li>
<li>Write a test unit. You may create a C++ test class or a C test function as your test unit. Click '''[[Test_Units#Test_Unit_Requirements|here]]''' for more information on creating test units.</li>
To implement a test unit as a test class:
<pre>
#include <srtest.h>

class Simple {
public:
int test1(void) { return 0;} // PASS
int test2(void) { return 23;} // FAIL <>0
};

#pragma scl_test_class(Simple)
</pre>
Or, as a test function:
<pre>
#ifdef __cplusplus
extern "C" {
#endif

int test1(void)
{
return 0; // PASS
}

int test1(void)
{
return 23; // FAIL <>0
}

#pragma scl_test_flist("Simple", test1, test2)

#ifdef __cplusplus
}
#endif
</pre>

<li>Compile the workspace & review the '''Simple''' interface in the Studio Interface tab</li>
<li>Create a script to generate the Intercept Module(IM) '''after''' the compilation step.
:For the simple STUB generation required for test unit execution, you can use the following code (perl syntax)</li>
<pre>
use strict;
use Win32::OLE qw(in);
Win32::OLE->Option(Warn => 3);
my $intercept = $main::studio->Workspace->Intercept;
$intercept->{Path} = $main::studio->Workspace->Path;
$intercept->{Name} = $main::studio->Workspace->Name;
map {$intercept->Item($_)->{Stub} = 1} (0..($intercept->Count - 1));
$intercept->Create();
</pre>
<li>Optionally add custom scripts to automate the building and executing your application. Refer to [[Using Frameworks]] for more information regarding building and executing tests with a target device.</li>
<li>Ensure that the Studio workspace include path contains the location to all of your test unit declaration (header) files.</li>
<li>Once you have created one or more test units, ensure the following:
:* Workspace is compiled and saved
:* Intercept Module is generated (Stubs for all Test Units)
:* Target application re-built
:* Target application downloaded & started
:* STRIDE Connected to Target
</li>

<li>If your application is running, you can start executing test units.
:* You can test-execute individual test units interactively using the '''Studio interface''' view. To do this, open the user interface view corresponding to the test unit you would like to execute, then call it. The return values will indicate how many tests produced each of four (4) result types. Furthermore, the input to the entry point will allow you to select all methods for execution (the default) or individual methods via a dropdown list of enumerated values.
:* Once you are confident that the test units are behaving as expected, you can generate one or more execution scripts using the '''Script Wizard'''. Sample '''[[templates]]''' for executing test unit entry points are provided in the %STRIDE_DIR%\templates\Script Wizard directory.
:* When writing scripts to execute test units, the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection is a powerful tool for test unit execution and reporting, and for obtaining test results.</li>
<li>For integration with larger regression test workspaces, we recommend that developers check in their test unit code and, optionally, the template-generated scripts that can be used to execute their test units.</li>
</ol>

===Pragmas for Test Units===
STRIDE supports three pragmas for capturing and qualifying test units:

*'''<code>scl_test_class ( class )</code>''': Declares a test class as captured. Once captured, STRIDE will generate the appropriate code for executing the test methods in the class. See the [[scl_test_class|scl_test_class page]] for more information.
*'''<code>scl_test_flist ( test-unit-name , test-function-name { , test-function-name } )</code>''': Declares a test unit as captured, by the specified test-unit-name. One or more functions (test methods) are associated with the test unit. Once captured, STRIDE will generate the appropriate code for executing the associated test methods. See the [[scl_test_flist|scl_test_flist page]] for more information.
*'''<code>scl_test_setup ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a setup fixture for the test unit. If specified, the setup method will be called before the execution of each test method. See the [[scl_test_setup|scl_test_setup page]] for more information.
*'''<code>scl_test_teardown ( test-unit-name , method-name )</code>''': [optional] Declares a member method to be a teardown fixture for the test unit. If specified, the teardown method will be called after the execution of each test method. See the [[scl_test_teardown|scl_test_teardown page]] for more information.

== Test Unit Requirements ==

Several variations on typical xUnit-style test units are supported. The additional supported features include:

*Test status can be set using STRIDE Runtime APIs ''or'' by specifying simple return types for test methods.
*Simple return types: 0 = PASS; <> 0 = FAIL
*void return type with no explict status setting is assumed PASS
*Test writers can create additional child suites and tests at runtime by using Runtime APIs.
*We do not rely on exceptions for reporting of status.

The STRIDE test class framework has the following requirements of each test class:

*The test class must have a suitable default (no-argument) constructor.
*The test class must have one or more public methods suitable as test methods. Allowable test methods always take no arguments (void) and return either void or simple integer types (int, short, long, char or bool). At this time, we do not allow typedef types or macros for the return values specification.
*the scl_test_class pragma must be applied to the class.

=== Simple example using return values for status ===
==== Using a Test Class ====

#include <srtest.h>

class Simple {
public:
int tc_Int_ExpectPass(void) {return 0;}
int tc_Int_ExpectFail(void) {return -1;}
bool tc_Bool_ExpectPass(void) {return true;}
bool tc_Bool_ExpectFail(void) {return false;}
};
#ifdef _SCL
#pragma scl_test_class(Simple)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

int tf_Int_ExpectPass(void) {return 0;}
int tf_Int_ExpectFail(void) {return -1;}
bool tf_Bool_ExpectPass(void) {return true;}
bool tf_Bool_ExpectFail(void) {return false;}
#ifdef _SCL
#pragma scl_test_flist("Simple", tf_Int_ExpectPass, tf_Int_ExpectFail, tf_Bool_ExpectPass, tf_Bool_ExpectFail)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using runtime test service APIs ===
==== Using a Test Class ====
#include <srtest.h>

class RuntimeServices_basic {
public:
void tc_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
};
#ifdef _SCL
#pragma scl_test_class(RuntimeServices_basic)
#endif

==== Using a Test Function ====
#include <srtest.h>

#ifdef __cplusplus
extern "C" {
#endif

void tf_ExpectPass(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should pass");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
}
void tf_ExpectFail(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should fail");
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_FAIL, 0);
}
void tf_ExpectInProgress(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT, "this test should be in progress");
}
#ifdef _SCL
#pragma scl_test_flist("RuntimeServices_basic", tf_ExpectPass, tf_ExpectFail, tf_ExpectInProgress)
#endif

#ifdef __cplusplus
}
#endif

=== Simple example using srTest base class ===

#include <srtest.h>

class MyTest : public stride::srTest {
public:
void tc_ExpectPass(void)
{
testCase.AddComment("this test should pass");
testCase.SetStatus(srTEST_PASS, 0);
}
void tc_ExpectFail(void)
{
testCase.AddComment("this test should fail");
testCase.SetStatus(srTEST_FAIL, 0);
}
void tc_ExpectInProgress(void)
{
testCase.AddComment("this test should be in progress");
}
int tc_ChangeMyName(void)
{
testCase.AddComment("this test should have name = MyChangedName");
testCase.SetName("MyChangedName");
return 0;
}
int tc_ChangeMyDescription(void)
{
testCase.AddComment("this test should have a description set");
testCase.SetDescription("this is my new description");
return 0;
}
};
#ifdef _SCL
#pragma scl_test_class(MyTest)
#endif

== Runtime Test Services ==

The Runtime Test Services (declared in srTest.h) are a set of APIs in the STRIDE Runtime that facilitate the writing of target based test code. These APIs make up an optional portion of the STRIDE Runtime and can be used to communicate additional information about tests to the host based reporting mechanism. These APIs also allow target test code to create additional test suites and test cases dynamically at runtime.

There are 2 alternate ways of accessing these APIs: through C-based functions, or through a C++ base class from which you may derive your C++ test class. These are discussed below in C Test Functions, and C++ Test Classes sections below.

=== C Test Functions ===

The following C APIs are provided:

*'''<code>srTestSuiteAddSuite</code>''': creates an additional sub-suite at runtime.
*'''<code>srTestSuiteSetName</code>''': sets the name of the specified suite.
*'''<code>srTestSuiteSetDescription</code>''': sets the description of the specified suite.
*'''<code>srTestSuiteAddTest</code>''': creates an additional test case at runtime.
*'''<code>srTestCaseSetName</code>''': sets the name of the specified test case.
*'''<code>srTestCaseSetDescription</code>''': sets the description of the specified test case.
*'''<code>srTestCaseAddComment</code>''': adds a comment to the specified test case.
*'''<code>srTestCaseSetStatus</code>''': explicitly sets the status for the specified test case.
*'''<code>srTestSuiteAddAnnotation</code>''': creates an annotation at runtime.
*'''<code>srTestAnnotationAddComment</code>''': adds a comment to the specified annotation.

==== srTestSuiteAddSuite ====
'''Prototype'''
srTestSuiteHandle_t srTestSuiteAddSuite(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddSuite() routine is used to add a new test suite to the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test suite is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test suite. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
|srTestSuiteHandle_t
| Handle of the newly created test suite. srTEST_SUITE_INVALID indicates failure to create test suite.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_addSuite(void)
{
srTestSuiteHandle_t subSuite =
srTestSuiteAddSuite(srTEST_SUITE_DEFAULT, "tf Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addSuite)
#endif

==== srTestSuiteSetName ====
'''Prototype'''
srWORD srTestSuiteSetName(srTestSuiteHandle_t tTestSuite, const srCHAR * szName)

'''Description'''
The srTestSuiteSetName() routine is used to set the name of the specified test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setName(void)
{
srTestSuiteSetName(srTEST_SUITE_DEFAULT, "Setting name for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setName)
#endif

==== srTestSuiteSetDescription ====
'''Prototype'''
srWORD srTestSuiteSetDescription(srTestSuiteHandle_t tTestSuite, const srCHAR * szDescr)

'''Description'''
The srTestSuiteSetDescription() routine is used to set the description of the specified test
suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestSuite
| Input
| Handle to a test suite. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test suite. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuite_setDescription(void)
{
srTestSuiteSetDescription(srTEST_SUITE_DEFAULT,
"Setting description for default suite");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_setDescription)
#endif

==== srTestSuiteAddTest ====
'''Prototype'''
srTestCaseHandle_t srTestSuiteAddTest(srTestSuiteHandle_t tParent, const srCHAR * szName)

'''Description'''
The srTestSuiteAddTest() routine is used to add a new test case to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new test case is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of test case. If null, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCaseHandle_t
| Handle of the newly created test case. srTEST_CASE_INVALID indicates failure to create test case.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addTest(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
srTestCaseHandle_t test = srTestSuiteAddTest(srTEST_SUITE_DEFAULT,
strm.str().c_str());
srTEST_ADD_COMMENT_WITH_LOCATION(test, "this is a dynamic test case");
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addTest)
#endif

==== srTestCaseSetName ====
'''Prototype'''
srWORD srTestCaseSetName(srTestCaseHandle_t tTestCase, const srCHAR *szName)

'''Description'''
The srTestCaseSetName() routine is used to set set the name of the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szName
| Input
| Pointer to a null-terminated string representing the name of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfcase_setName(void)
{
srTestCaseSetName(srTEST_CASE_DEFAULT, "Setting name for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setName)
#endif

==== srTestCaseSetDescription ====
'''Prototype'''
srWORD srTestCaseSetDescription(srTestCaseHandle_t tTestCase, const srCHAR * szDescr)

'''Description'''
The srTestCaseSetDescription() routine is used to set the description of the specified test
case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of test case. Cannot be null.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setDescription(void)
{
srTestCaseSetDescription(srTEST_CASE_DEFAULT,
"Setting description for default case");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setDescription)
#endif

==== srTestCaseAddComment ====
'''Prototype'''
srWORD srTestCaseAddComment(srTestCaseHandle_t tTestCase, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestCaseAddComment() routine is used to add a comment (aka a log) to be
reported with the specified test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_addComment(void)
{
srTestCaseAddComment(srTEST_CASE_DEFAULT,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_addComment)
#endif

==== srTestCaseSetStatus ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration)

'''Description'''
The srTestCaseSetStatus() routine is used to set the result of test case.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input
| The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatus(void)
{
srTestCaseSetStatus(srTEST_CASE_DEFAULT, srTEST_PASS, 0);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatus)
#endif

==== srTestCaseSetStatusEx ====
'''Prototype'''
srWORD srTestCaseSetStatus(srTestCaseHandle_t tTestCase, srTestStatus_e eStatus, srDWORD dwDuration, srLONG lExtendedFailureCode)

'''Description'''
The srTestCaseSetStatusEx() routine is used to set the result of test case and allow
specification of an extendedFailureCode.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestCase
| Input
| Handle to a test case. srTEST_CASE_DEFAULT can be used for the default test case.
|-
| eStatus
| Input
| Result of the test. dwDuration Input The duration of the test in clock ticks. Using “0” allows the STRIDE Runtime (Intercept Module) to set the time automatically.
|-
| lExtendedFailureCode
| Input
| The Stride framework uses the extendedFailureCode to capture the numeric results of test method when the test method fails via a numeric (non-void, nonbool) return type.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|}
 
'''Example'''
#include "srtest.h"
void tfcase_setStatusEx(void)
{
srTestCaseSetStatusEx(srTEST_CASE_DEFAULT, srTEST_FAIL, 0, -5);
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfcase_setStatusEx)
#endif

==== srTestSuiteAddAnnotation ====
'''Prototype'''
srTestAnnotationHandle_t srTestSuiteAddAnnotation(rTestSuiteHandle_t tParent, srTestAnnotationLevel_e eLevel, const srCHAR * szName, const srCHAR * szDescr)

'''Description'''
The srTestSuiteAddAnnotation() routine is used to add a new annotation to the specified test suite.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tParent
| Input
| Handle to the parent test suite to which new annotation is to be added. srTEST_SUITE_DEFAULT can be used for the default test suite.
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input
| Pointer to a null-terminated string that represents the name of annotation. If null, the default host naming scheme will be used.
|-
| szDescr
| Input
| Pointer to a null-terminated string representing the description of annotation. If null, description will be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotationHandle_t
| HHandle of the newly created annotation. srTEST_ANNOTATION_INVALID indicates failure to create annotation.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream>
void tfsuite_addAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuite_addAnnotation)
#endif

==== srTestAnnotationAddComment ====
'''Prototype'''
srWORD srTestAnnotationAddComment(srTestAnnotationHandle_t tTestAnnotation, const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The srTestAnnotationAddComment() routine is used to add a comment (aka a log) to be reported with the specified annotation.

 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| tTestAnnotation
| Input
| Handle to an annotation created using srTestSuiteAddAnnotation.
|-
| szLabel
| Input
| Pointer to a null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to a null-terminated string, which can be formatted, representing the comment. Cannot be null.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
void tfsuiteAnnotation _ addComment(void)
{
srTestAnnotationHandle_t annot =
srTestSuiteAddAnnotation(srTEST_SUITE_DEFAULT,
srTEST_ANNOTATION_LEVEL_ERROR,
“annot”,
“annot description”);
srTestAnnotationAddComment(annot,
"this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_flist(“testfunc”, tfsuiteAnnotation_addComment)
#endif

=== C++ Test Classes ===
The Runtime Test Services APIs work equally well from C test functions and C++ test classes. If, however, you choose to derive your C++ test classes from the STRIDE Runtime base class, ''srTest'', then you will have access to member objects in srTest and their methods that provide the same functionality as the C API. The srTest base class provides two Member Objects, via which you can access functionality:

'''''Member Objects''''':

*''testSuite'', which has methods:
**'''<code>AddSuite</code>'''
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddTest</code>'''
**'''<code>AddAnnotation</code>'''
**'''<code>AddAnnotation.AddComment</code>'''
*''testCase'', which has methods:
**'''<code>SetName</code>'''
**'''<code>SetDescription</code>'''
**'''<code>AddComment</code>'''
**'''<code>SetStatus</code>'''

''''' Methods of Member Object testSuite '''''
==== AddSuite ====
'''Prototype'''
srTestSuite AddSuite(const srCHAR * szName = srNULL)

'''Description'''
The AddSuite method is used to add a new test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
|szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test suite. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestSuite
| Newly created test suite class.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
stride::srTestSuite suite = testSuite.AddSuite("tc Sub Suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetName(void);
}; 
void srtest_class::suiteSetName(void)
{
testSuite.SetName("Setting name for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test suite. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h"
class srtest_class : public stride::srTest
{
public:
void suiteSetDescription(void);
}; 
void srtest_class::suiteSetDescription(void)
{
testSuite.SetDescription("Setting description for suite");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddTest ====
'''Prototype'''
srTestCase AddTest(const srCHAR * szName = srNULL)

'''Description'''
The AddTest method is used to add a new test case to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of test case. If empty, the default host naming scheme will be used.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestCase
| Newly created test case class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddSuite(void);
}; 
void srtest_class::suiteAddSuite(void)
{
const std::string prefix("dynamic test case ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strm;
strm << prefix << count;
stride::srTestCase tc = testSuite.AddTest(strm.str().c_str());
tc.AddComment("this is a dynamic test case");
tc.SetStatus(srTEST_PASS);
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation ====
'''Prototype'''
srTestAnnoation AddAnnotation(srTestAnnotationLevel_e eLevel, const srCHAR * szName = srNULL, const srCHAR * szDescr = srNULL)

'''Description'''
The AddAnnotation method is used to add a new annotation to test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eLevel
| Input
| Annotation level. Cannot be empty.
|-
| szName
| Input (Optional)
| Pointer to null-terminated string that represents the name of annotation. If empty, the default host naming scheme will be used.
|-
| szDescr
| Input (Optional)
| Pointer to null-terminated string that represents the description of annotation. If empty, the description will be blank.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srTestAnnotation
| Newly created annotation class.
|}
 
'''Example'''
#include "srtest.h"
#include <sstream> 
class srtest_class : public stride::srTest
{
public:
void suiteAddAnnotation(void);
}; 
void srtest_class::suiteAddAnnotation(void)
{
const std::string prefixName("annotation ");
const std::string prefixDescr("description of annotation ");
for (int count = 0; count < 5; ++count)
{
std::stringstream strmName;
std::stringstream strmDescr;
strmName << prefixName << count;
strmDescr << prefixDescr << count;
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
strmName.str().c_str(),
strmDescr.str().c_str());
}
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddAnnotation.AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szLabel, const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to an annotation created under a test suite.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szLabel
| Input
| Pointer to null-terminated string for the label. If null, the default label will be applied.
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void suiteAnnotationAddComment(void);
}; 
void srtest_class::suiteAnnotationAddComment(void)
{
stride::srTestAnnotation ta =
testSuite.AddAnnotation(srTEST_ANNOTATION_LEVEL_INFO,
“annot”,
“annot description”);
ta.AddComment("this comment on annotation should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

''''' Methods of Member Object testCase '''''
==== SetName ====
'''Prototype'''
srWORD SetName(const srCHAR * szName)

'''Description'''
The SetName method is used to set the name of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szName
| Input
| Pointer to null-terminated string representing the name of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetName(void);
}; 
void srtest_class::caseSetName(void)
{
testCase.SetName("Setting name for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetDescription ====
'''Prototype'''
srWORD SetDescription(const srCHAR * szDescr)

'''Description'''
The SetDescription method is used to set the description of test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szDescr
| Input
| Pointer to null-terminated string representing the description of test case. Cannot be empty.
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetDescription(void);
}; 
void srtest_class::caseSetDescription(void)
{
testCase.SetDescription("Setting description for case");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== AddComment ====
'''Prototype'''
srWORD AddComment(const srCHAR * szFmtComment, ...)

'''Description'''
The AddComment method is used to add a comment to test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| szFmtComment
| Input
| Pointer to null-terminated string, which can be formatted, representing the comment. Cannot be empty.
|-
| ...
| Input (Optional)
| Variable argument list to format the comment szFmtComment.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srERR
| Null string passed in.
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle passed in.
|-
| srTEST_WARN_STR_TRUNCATED
| String passed in was too large and was truncated.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseAddComment(void);
}; 
void srtest_class::caseAddComment(void)
{
testCase.AddComment("this comment should print %s", "A STRING");
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

==== SetStatus ====
'''Prototype'''
srWORD SetStatus(srTestStatus_e eStatus, srDWORD dwDuration = 0)

'''Description'''
The SetStatus method is used to set the result of the default test case.
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| eStatus
| Input
| Result of the test.
|-
| dwDuration
| Input (Optional)
| The duration of the test in clock ticks. The default is 0.
|}
|}
 
{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Return Value'''
| ''' Description'''
|-
| srOK
| Success
|-
| srTEST_ERR_HANDLE_INVALID
| Invalid handle.
|}
 
'''Example'''
#include "srtest.h" 
class srtest_class : public stride::srTest
{
public:
void caseSetStatus(void);
}; 
void srtest_class::caseSetStatus(void)
{
testCase.SetStatus(srTEST_INPROGRESS, 0);
} 
#ifdef _SCL
#pragma scl_test_class(srtest_class)
#endif

Refer to the Reference Guide or the Runtime Developers Guide, both available in the STRIDE Online Help, for detailed information about any of these functions.

== Scripting a Test Unit ==

To automate the execution and reporting of a Test Unit a script is required. Scripts can be written by hand or automatically generated using the Script Wizard and a corresponding template script. A scripting tool for executing a test unit is the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection. An [[AutoScript#ascript.TestUnits.Item|Ascript TestUnit]] object assembles all of the reporting information for the test unit and its corresponding test methods.

*Require useage of the [[AutoScript#ascript.TestUnits|AutoScript TestUnits]] collection
*Can be written by hand (refer below)
*Can leverage [[Templates|Templates]] via the Script Wizard
*Order of multiple test units dictated by SUID assignment

 

=== JScript example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

// Ensure test unit exists
if (ascript.TestUnits.Item("Simple") != null )
ascript.TestUnits.Item("Simple").Run();

=== Perl example for a single test unit ===

The following example script is used to harness a test unit that has been captured using #pragma scl_test_class(Simple).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

my $tu = $main::ascript->TestUnits->Item("Simple");
if (defined $tu) {
$tu->Run();
}

=== JScript example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

var Units = ["Simple1","Simple2"];

// iterate through each function
for (i in Units)
{
var tu = ascript.TestUnits.Item(Units[i]);
if ( tu != null )
tu.Run();
}

=== Perl example for multiple test units ===

The following example script is used to harness two test units that have been captured using #pragma scl_test_class(Simple1) and #pragma scl_test_class(Simple2).

 

use strict;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);

# initialize an array with all selected function names
my @UnitNames = ("Simple1","Simple2");
foreach (@UnitNames) {
my $tu = $main::ascript->TestUnits->Item($_->[1]);
die "TestUnit not found: $_->[1]\n" unless (defined $tu);
$tu->Run();
}

[[Category:Reference]]

STRIDE Runtime

2008-09-19T00:21:10Z

Shamr: /* Runtime Test Services (RTS) */

== Overview ==

The STRIDE Runtime routes messages both within and between platform boundaries and manages the conversion of interface data as it crosses from one platform to another. This "transparent messaging" model means that your test cases can be located on one platform (e.g., as a script running off-target) and your code on another (on-target).

The STRIDE Runtime is a combination of processes and libraries that provide services for messaging, remote function calls, and tracing while providing seamless connectivity between the target application and the host operating system. The STRIDE Runtime standardizes how threads and applications communicate with each other, independent of the platform on which they are executing, which eliminates the need to integrate new software on the target hardware. Developers can then incrementally integrate embedded software on a combination of the desktop environment and the target hardware, providing more control over integration and testing. New software functionality under development can be simulated on the desktop environment while the software using this new functionality can run on the target hardware. The tremendous flexibility gained by allowing developers to choose how to integrate different software components and target platforms allows developers to detect integration and testing issues and correct defects much earlier in the development process.

 

[[Image:Runtime Overview.jpg|600px|center|Overview of the STRIDE Runtime]]

 The Runtime components consist of:

*The '''PAL (Platform Abstraction Layer)''' - provides a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. It consists of a small set of functions that provide a virtual link between the target operating system and the STRIDE Runtime. The PAL functionality, defined in the ''pal.h'' header file, allows the STRIDE Runtime to transmit and receive packets of data (called I-blocks) using the platform’s transport mechanism.

*The '''Host Transport Layer and Object Model''' - a server process and set of APIs that connects the Transport DLL to the STRIDE Runtime, providing indirect access to the target from host-side scripts and STRIDE applications. The Host Transport Services are defined in the ''transport.h'' header file. The Transport Server process is is accessed through the set of interfaces defined for the ''STRIDE.transport'' COM server.

*The '''Runtime APIs''' - a public API set, defined in the ''sr.h'' header file, available for programmers to integrate into their target application code. These APIs support messaging, remote function calls, and tracing between the target application and host operating system.

*The '''Intercept Module''' - generated code that facilitates remote function calls between the host and target. The IM code links to the target application; it implements '''stubs '''to allow remote function calls from the host to target-resident functions, and '''proxies '''that intercept target function calls and remotes them to a host implementation of the function. The IM can contain logic to dynamically switch target-based function calls to either host-resident or target-resident implementations, and capture tracing information, through '''delegates'''.

Additionally, groups of Runtime APIs provide test unit logging and services, and a software development kit is available for creating windows-based target applications. Each is briefly described here, with links provided for more detail.

 

== The Platform Abstraction Layer ==

The Platform Abstraction Layer, or PAL, defines the set of OS functionality required by the platform to support the STRIDE Runtime. The “pal.h” header file provided with the STRIDE installation defines the PAL functionality. The PAL also defines functionality required by the STRIDE Runtime to transmit and receive packets of data (called I-blocks) using the platform’s transport mechanism. These PAL routines enable the STRIDE Runtime to be installed on diverse environments without changing its internal design. 

Refer to the [[Platform Abstraction Layer|Platform Abstraction Layer]] page and the [[http://www.s2technologies.com/pdf/s2sPAL.pdf PAL Specification]] document for a more detailed description of the PAL and its interfaces.

 

== The Host Transport Services ==

The Host Transport Services define an interface that enables the STRIDE Runtime on your target to send data to and receive data from the target. The STRIDE Transport Server connects the Transport DLL to the STRIDE Runtime running on the host platform, thus providing indirect access to the target from STRIDE Studio, Autoscript, and other STRIDE applications. Several common transports are already supported within the STRIDE Transport Server, including serial and TCP/IP.

[[Image:Transport diagram.gif|center|Host Transport Services Diagram]]

The Host Transport Services are defined in "transport.h" and each Transport DLL must implement the interfaces derived from the IStrideTransport class.

Refer to the [[http://www.s2technologies.com/pdf/s2sTransport.pdf Host Runtime Transport Specification]] document for a more detailed description of the Host Transport Services.

 

== The Intercept Module ==

The [[Intercept Module]] page provides details of the Intercept Module concept. 

The [[Name Mangling]] page provides more background on the use of name mangling when implementing delegates within an Intercept Module.

 

== The Runtime Developer's Guide ==

Click [[http://www.s2technologies.com/pdf/s2sRuntime.pdf here]] to view the STRIDE Runtime Developer's Guide PDF document.

 

== Public Services ==

 

=== Runtime Test Services (RTS) ===

 The Runtime Test Services (RTS) are a set of C-based APIs in the STRIDE Runtime that facilitate the writing of target based test code. These APIs make up an optional portion of the STRIDE Runtime and can be used to communicate additional information about tests to the host based reporting mechanism. These APIs also allow target test code to create additional test suites and test cases dynamically at runtime. These C-based APIs work equally well from '''C Test Functions''' and '''C++ Test Classes'''. If, however, you choose to derive your C++ test classes from the '''STRIDE Runtime Base Class (srTest)''', then you will have access to member objects in the srTest class and its methods that provide the same functionality as the C APIs. 

 

==== C Test Functions ====

C test functions enable testing of C code similarily to xUnit-style testing. Test functions can be written by users, captured using the scl_function pragma, and executed from the host. C-based Runtime Test Services APIs are available for use in test functions. 

'''C-based Runtime Test Services APIs provided:'''

*'''srTestSuiteAddSuite''': creates an additional sub-suite at runtime.
*'''srTestSuiteSetName''': sets the name of the specified suite.
*'''srTestSuiteSetDescription''': sets the description of the specified suite.
*'''srTestSuiteAddTest''': creates an additional test case at runtime.
*'''srTestCaseSetName''': sets the name of the specified test case.
*'''srTestCaseSetDescription''': sets the description of the specified test case.
*'''srTestCaseAddComment''': adds a comment to the specified test case.
*'''srTestCaseSetStatus''': explicitly sets the status for the specified test case.
*'''srTestCaseSetStatusEx''': explicitly sets the status for the specified test case and allows specification of an extended failure code.
*'''srTestSuiteAddAnnotation: creates an annotation at runtime.
*'''srTestAnnotationAddComment: adds a comment to the specified annotation.

 

==== C++ Test Classes ====

C++ test classes enable testing of C++ code similarily to xUnit-style testing. Test classes can be written by users, captured using scl_test_class, scl_test_setup and scl_test_teardown pragmas, and executed from the host. C-based Runtime Test Services APIs as well as C++ Runtime Base Class are available for use in test classes. 

'''Member objects of srTest base class:'''

*'''testSuite '''member object provides following methods:
**'''AddSuite''': creates an additional sub-suite at runtime.
**'''SetName''': sets the name of the specified suite.
**'''SetDescription''': sets the description of the specified suite.
**'''AddTest''': creates an additional test case at runtime.
**'''AddAnnotation
**'''AddAnnotation.AddComment

*'''testCase '''member object provides following methods:
**'''SetName''': sets the name of the specified test case.
**'''SetDescription''': sets the description of the specified test case.
**'''AddComment''': adds a comment to the specified test case.
**'''SetStatus''': explicitly sets the status for the specified test case.

 These services use the '''''srtest.h''''' header file. Please refer to the [[Test_Units#Runtime_Test_Services|Test Units page]], or Chapter 4 of the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf Runtime Developer's Guide]] for more information on these APIs. 

 

=== Logging Services ===

The following are the categories available in the Runtime API for logging, that is, collecting and/or displaying, information at the host runtime environment:

*'''Setup and Shutdown'''
**'''srCreateSTID()''': used to allocate resources required to send and receive trace and print messages that implement the following APIs.
**'''srDeleteSTID()''': used to free STRIDE Runtime resources previously allocated for an STID.

*'''Tracing''' - Tracing routines are used by target applications for information collection and display by the host runtime environment.
**'''srTracePoint()''': used to output a data structure to the tracing window on the host.
**'''srTraceStr()''': used to output a string to the tracing window.

*'''Printing''' - These routines are used by applications to log or display messages on Trace Views on the host.
**'''srPrintInfo()''': used to output a formatted string with variable arguments to be displayed at information level filtering.
**'''srPrintError()''': used to output a formatted string with variable arguments to be displayed at error level filtering.

These services use the '''''sr.h''''' header file. Please refer to Chapter 3 of the [[http://www.s2technologies.com/pdf/s2sRuntime.pdf Runtime Developer's Guide]] for more information on these APIs. 

 

== The Windows Off-Target SDK ==

The STRIDE development environment provides a way for you to build and execute your application and test code off-target, on a Windows host platform. This provides a faster way to test and validate your code since it does not require you to build your target application and re-image the device.

The Windows Off-Target SDK consists of: 

*The Target Runtime, PAL and [[GRS|GRS]] packaged in the s2srwin.lib and s2srwin.dll files, installed in the STRIDE\lib and STRIDE\bin directories.

*The public APIs for these components, available through header files installed in the STRIDE\inc directory. These include:
**sr.h
**srwin.h
**grs.h
**pal.h

*Utility script components that facilitate building and executing off-target applications on Windows hosts:
**[[STRIDE.vsbuild|STRIDE.vsbuild]]
**[[STRIDE.windowsprocess|STRIDE.windowsprocess]]

These components are written in the Perl scripting language and therefore require that Perl be installed. See [[Host_Installation#Third Party Requirements|Perl requirements]] for more information. 

Development of off-target applications using the SDK resources is discussed in more detail in the [[Windows Off-Target Apps|Windows Off-Target Apps]] page.

== The Transport Server Object Model ==

The Transport Server is an out-of-process COM server that provides connection management, loopback and diagnostic features. It can be accessed by clients through the STRIDE.transport Program ID. The Transport Server API is defined in the [[Transport Server Component|Transport Server Object Model]] page.

[[Category: Reference]]

Studio:Integrating the Intercept Module (IM)

2008-09-17T19:32:50Z

Shamr: /* Linux Implementation */

== About Intercept Modules ==
Intercept Modules allow remote function calls across hardware (e.g., processor or machine) or software (operating system) platform boundaries. Intercept Modules are target-based components that are created as a step in the STRIDE build process. The [[Intercept Module|Intercept Module]], or IM, is created based on selected interfaces or test units that have been "captured", or identified through a subset of SCL pragmas that tag interfaces as candidates for remote function calls. Once created, the generated code is then compiled, linked and run along with the target application.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Target Integration#The STRIDE Runtime |Runtime]] and the [[Target Integration#The Platform Abstraction Layer (PAL)| PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the srThread and IMStubRead threads ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet for Linux, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

=== Linux Implementation ===
This code snippet for Linux also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf(stdout, "TestAgent exiting.\n");
for (i = sizeof(_threads)/sizeof(_threads[0]); i > 0; i--)
{
if (_threads[i-1] != 0)
{
palNotify(_threads[i-1], palSTOP_EVENT);
pthread_join(_threads[i-1], NULL);
pthread_detach(_threads[i-1]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/****************************************************************************
* Main entry point
***************************************************************************/
#ifdef __cplusplus
extern "C"
#endif
int main(int argc, char **argv)
{
int i = 0;
pthread_t *ioThread = NULL;

// Set termination signals handling
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);

// Initialize PAL. It will return palFALSE if it fails
if (palInit(&ioThread) == palFALSE)
{
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Initialize Runtime
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Initialize GRS
if (grsInit() != grsTRUE) {
palLog(palLOG_LEVEL_ERROR, "grsInit FAILED");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Start the Runtime thread first
pthread_create(&_threads[i++], NULL, _threadFunc, (void*)srThread);

// Start the IM stub read thread
// The name of the stub read function is defined by the makefile
pthread_create(&_threads[i++], NULL, _threadFunc, (void*)strideIMStubThread);
// __STRIDE_FRAMEWORK_CUSTOM_INIT_BODY__

pthread_join(*ioThread, NULL);

_cleanup();

return 0;
}
</source>

=== Windows Implementation ===
This code snippet for Windows is based on using the Win32 API calls.

<source lang="c">
#include "stdafx.h"
#include <windows.h>
#include <commctrl.h>

#include <sr.h>
#include <palcfg.h>
#include "MyProjectIMEntry.h"

static bool bUseSerial = false;

struct ThreadInfo
{
HANDLE handle;
DWORD id;
};

typedef void (*_ThreadFunc_t)( void );

static DWORD WINAPI _threadFunc(LPVOID param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return 0;
}

int _tmain(int argc, _TCHAR* argv[])
{
ThreadInfo threads[15] = {{NULL, 0}};
int i = 0;

// Initialize the PAL
if (palOSInit() != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palOSInit FAILED.");
return -1;
}

pal_io_config_t cfg;
pal_prot_t protocol;
if (bUseSerial) {
protocol = PAL_PROT_SERIAL;
cfg.u.serial.BaudRate = PAL_SERIAL_BAUDRATE;
cfg.u.serial.ByteSize = PAL_SERIAL_BYTESIZE;
cfg.u.serial.ComPort = PAL_SERIAL_PORT;
cfg.u.serial.Parity = PAL_SERIAL_PARITY;
cfg.u.serial.StopBits = PAL_SERIAL_STOPBITS;
}
else {
protocol = PAL_PROT_TCP;
cfg.u.tcp.Port = PAL_DEFAULT_TCP_PORT;
}

// Initialize tcp transport
if (palIOInit(protocol, &cfg) != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palIOInit FAILED.");
return -1;
}

// Initialize Runtime
if (srInit() != srOK) {
palLog(palLOG_LEVEL_ERROR, "srInit FAILED.");
return -1;
}

// Start the Runtime thread first
threads[i].handle = CreateThread(NULL, 0, _threadFunc, srThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for Runtime Thread.");
return -1;
}

// Start the IM stub read thread
threads[i].handle = CreateThread(NULL, 0, _threadFunc, MyProjectIMStubThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for IM Thread.");
return -1;
}

// Wait for Runtime thread
WaitForSingleObject(threads[0].handle, INFINITE);

fprintf (stdout, "TestAgent exiting.\n");
for (i = sizeof(threads)/sizeof(threads[0]); i > 0; i--)
{
if (threads[i-1].handle != NULL)
{
palNotify(threads[i-1].id, palSTOP_EVENT);
WaitForSingleObject(threads[i-1].handle, INFINITE);
CloseHandle(threads[i-1].handle);
}
}

srUninit();
palOSUninit();
return 0;
}
</source>

[[Category: Installation]]

Studio:Integrating the Intercept Module (IM)

2008-09-04T19:03:30Z

Shamr: /* Linux Implementation */

== About Intercept Modules ==
Intercept Modules allow remote function calls across hardware (e.g., processor or machine) or software (operating system) platform boundaries. Intercept Modules are target-based components that are created as a step in the STRIDE build process. The [[Intercept Module|Intercept Module]], or IM, is created based on selected interfaces or test units that have been "captured", or identified through a subset of SCL pragmas that tag interfaces as candidates for remote function calls. Once created, the generated code is then compiled, linked and run along with the target application.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Target Integration#The STRIDE Runtime |Runtime]] and the [[Target Integration#The Platform Abstraction Layer (PAL)| PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the srThread and IMStubRead threads ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet for Linux, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

=== Linux Implementation ===
This code snippet for Linux also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf(stdout, "TestAgent exiting.\n");
for (i = sizeof(_threads)/sizeof(_threads[0]); i > 0; i--)
{
if (_threads[i-1] != 0)
{
palNotify(_threads[i-1], palSTOP_EVENT);
pthread_join(_threads[i-1], NULL);
pthread_detach(_threads[i-1]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/****************************************************************************
* Main entry point
***************************************************************************/
#ifdef __cplusplus
extern "C"
#endif
int main(int argc, char **argv)
{
int i = 0;
pthread_t *ioThread = NULL;

// Set termination signals handling
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);

// Initialize PAL. It will return palFALSE if it fails
if (palInit(&ioThread) == palFALSE)
{
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Initialize Runtime
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Initialize GRS
if (grsInit() != grsTRUE) {
palLog(palLOG_LEVEL_ERROR, "grsInit FAILED");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

// Start the Runtime thread first
pthread_create(&_threads[i++], NULL, _threadFunc, (void*)srThread);

// Start the IM stub read thread
// The name of the stub read function is defined by the makefile
pthread_create(&_threads[i++], NULL, _threadFunc, (void*)strideIMStubThread);
// __STRIDE_FRAMEWORK_CUSTOM_INIT_BODY__

int joinStatus = pthread_join(*ioThread, NULL);

_cleanup();

return 0;
}
</source>

=== Windows Implementation ===
This code snippet for Windows is based on using the Win32 API calls.

<source lang="c">
#include "stdafx.h"
#include <windows.h>
#include <commctrl.h>

#include <sr.h>
#include <palcfg.h>
#include "MyProjectIMEntry.h"

static bool bUseSerial = false;

struct ThreadInfo
{
HANDLE handle;
DWORD id;
};

typedef void (*_ThreadFunc_t)( void );

static DWORD WINAPI _threadFunc(LPVOID param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return 0;
}

int _tmain(int argc, _TCHAR* argv[])
{
ThreadInfo threads[15] = {{NULL, 0}};
int i = 0;

// Initialize the PAL
if (palOSInit() != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palOSInit FAILED.");
return -1;
}

pal_io_config_t cfg;
pal_prot_t protocol;
if (bUseSerial) {
protocol = PAL_PROT_SERIAL;
cfg.u.serial.BaudRate = PAL_SERIAL_BAUDRATE;
cfg.u.serial.ByteSize = PAL_SERIAL_BYTESIZE;
cfg.u.serial.ComPort = PAL_SERIAL_PORT;
cfg.u.serial.Parity = PAL_SERIAL_PARITY;
cfg.u.serial.StopBits = PAL_SERIAL_STOPBITS;
}
else {
protocol = PAL_PROT_TCP;
cfg.u.tcp.Port = PAL_DEFAULT_TCP_PORT;
}

// Initialize tcp transport
if (palIOInit(protocol, &cfg) != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palIOInit FAILED.");
return -1;
}

// Initialize Runtime
if (srInit() != srOK) {
palLog(palLOG_LEVEL_ERROR, "srInit FAILED.");
return -1;
}

// Start the Runtime thread first
threads[i].handle = CreateThread(NULL, 0, _threadFunc, srThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for Runtime Thread.");
return -1;
}

// Start the IM stub read thread
threads[i].handle = CreateThread(NULL, 0, _threadFunc, MyProjectIMStubThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for IM Thread.");
return -1;
}

// Wait for Runtime thread
WaitForSingleObject(threads[0].handle, INFINITE);

fprintf (stdout, "TestAgent exiting.\n");
for (i = sizeof(threads)/sizeof(threads[0]); i > 0; i--)
{
if (threads[i-1].handle != NULL)
{
palNotify(threads[i-1].id, palSTOP_EVENT);
WaitForSingleObject(threads[i-1].handle, INFINITE);
CloseHandle(threads[i-1].handle);
}
}

srUninit();
palOSUninit();
return 0;
}
</source>

[[Category: Installation]]

Platform Abstraction Layer

2008-06-24T22:39:00Z

Shamr: /* PAL Operating System (OS) Services */

The PAL, or Platform Abstraction Layer, enables the STRIDE Runtime to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.

== PAL Concepts ==
This section describes the basic concepts of the PAL and the system services it must provide.

=== Function Registration ===
Typically, the STRIDE Runtime calls PAL functions; however, there are some functions in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL dependencies on the STRIDE Runtime, these functions are accessed through a function registration process initiated by the STRIDE Runtime at startup. You write the registration routine called by the Runtime. This registration routine passes in the address of the STRIDE Runtime function to be registered as the input parameter, and stores the address of the STRIDE Runtime function in your own function variable, which is actually a pointer to a function. You can then call the registered function using your function pointer variable.

The registered STRIDE Runtime functions allow you to complete such tasks as delivering a received I block to the Runtime, checking the number of I-blocks the Runtime has ready to send out, or signalling the Runtime that your transport is ready for the next I-block. It is not necessary for the PAL to know the details of these Runtime functions.

=== Task Synchronization / Event Notification ===
Unique information is required by an operating system to notify a thread of a pending event. This information can be a simple index into a table, an address to a thread control block, the address of a semaphore or one of a number of other implementations. Although each implementation may be different, a unique notifier is necessary for each thread. The STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same NID to notify the thread of a pending STRIDE event.

An additional piece of information included with the notify routine is a box ID, which is the ID of the mailbox where the message is delivered.

Support for sharing of the synchronization object among multiple applications should be ensured in case of multi-process target is enabled.

=== Protection using Mutex ===
The STRIDE Runtime needs to protect critical and shared data structures from multiple, simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. The PAL requires implementing protection using Mutexes that can be created and, in case of multi-process target is enabled, used with a unique name by any STRIDE Runtime module or PAL itself. The STRIDE Runtime guarantees that calls to palMutexLock() will not be nested.

=== Timer Administration ===
The STRIDE Runtime requires that at least one timer be available. When a timer is created, a callback is registered so that the STRIDE Runtime can be notified of timer expirations. A user parameter, provided when the timer is created, is passed to the callback when it gets called. If several timers share a callback routine, this user parameter can be used to identify which timer expired. The STRIDE Runtime can also stop, start and delete timers.

Because the STRIDE Runtime also has the need to timestamp trace log data, a routine that returns the system time, palGetTime(), is also part of the PAL. This routine is not associated with timers.

=== Memory Allocation ===
The STRIDE Runtime dynamically allocates memory for messages and trace log storage. The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically and then return it to the system.

The Runtime uses palMemSegmentOpen() and palMemSegmentClose() to create, open and close memory segments. In case of single process target, these routines can simply allocate dynamic memory as in normal memory allocation routines.

To support multi-process target, the STRIDE Runtime requires dynamic and configurable memory allocated through palMemAlloc() and static internal memory allocated directly through palMemSegmentOpen() to be shared memory.

In case of multi-process target, palMemAlloc() and palMemFree() routines can simply call the STRIDE Runtime’s Memory Management module srMem, which is in turn dependent on palMemSegmentOpen() and palMemSegmentClose() routines.

=== Transport Services ===
The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into and out of the STRIDE Runtime on your target platform. These routines handle the buffering and transferring of data to and from your transport mechanism. The PAL also contains registration routines that allow for STRIDE Runtime routines to be called by the PAL.

The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport. The STRIDE Runtime calls the palOut() routine whenever it needs to send out an I-block.

Your transport calls the routine registered with the palOutRdyReg() routine when the transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not call the palOut() routine until you call the registered function. In this way, you can control the flow of transmitted I-blocks.
When a complete I-block has been received by your transport, the routine registered with the palInReg() routine should be called to put the received I-block into the STRIDE Runtime.

In some cases it is useful to know when the transmit path is not being requested. Your transport mechanism can check the number of I-blocks the STRIDE Runtime has ready for transmission by calling the routine registered with the palOutPndReg() routine.

=== Host Services ===
The PAL also provides a way for the STRIDE Runtime to support your transport protocol
on the desktop. A Windows® DLL linked to STRIDE Studio enables these host
services. The DLL allows your data to be received and transmitted using your transport

== PAL Organization ==

This section explains the two categories of PAL services that support the STRIDE Runtime, as
well as the files used to implement these services on your target.

=== PAL Services ===
The PAL services include the following:
* Operating System (OS) Services
* Input/Output (IO) Services

=== PAL Operating System Services ===
The PAL Operating System (OS) Services are the routines that enable the STRIDE Runtime to work with the operating system on your target platform. In order to write your PAL OS services you must have detailed knowledge of how your operating system handles thread synchronization, timers, mutexes, dynamic memory, shared memory, and notification. The PAL OS services make the features of your operating system available to the STRIDE Runtime.

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Synchronization'''
|-
| palCreateNID || Create a Notification Identifier (NID)
|-
| palDeleteNID || Delete a Notification Identifier (NID)
|-
| palCreateRFCProxyNID || Create the RFC Proxy Notification Identifier (NID)
|-
| palDeleteRFCProxyNID || Delete the RFC Proxy Notification Identifier (NID)
|-
| palWait || Wait for an event
|-
| palNotify || Signal a thread that an event is pending
|-
| palGetThreadId || Return current thread Id
|-
| palGetProcessId || Return current process Id
|-
| palSleep || Suspend the execution of the current thread
|-
|colspan="2" | '''Timers'''
|-
| palTimerCreate || Create a timer
|-
| palTimerDelete || Delete a timer
|-
| palTimerStart || Start a timer
|-
| palTimerStop || Stop a timer
|-
| palGetTime || Return system time (e.g., tick count)
|-
|colspan="2" | '''Mutex'''
|-
| palMutexInit || Initialize a mutex object
|-
| palMutexDestroy || Destroy a mutex object
|-
| palMutexLock || Lock a mutex object
|-
| palMutexUnlock || Unlock a mutex object
|-
|colspan="2" | '''Memory Management'''
|-
| palMemAlloc || Allocate a block of dynamic memory
|-
| palMemFree || Free a block of dynamic memory
|-
| palMemSegmentOpen || Create/open memory segments
|-
| palMemSegmentClose || Close memory segments
|}

=== PAL Input/Output Services ===
The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to
work with different data transport mechanisms. These routines enable your transport to
send and receive data between the host and the target.

The IO services have also been defined to allow the target platform to control how
memory is managed and the rate of data exchange. See Appendix A beginning on page
121 for definitions of the header file functions

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Transmit'''
|-
| PalOutPndReg || Query the current output queue of the Runtime
|-
| PalOutRdyReg || Identify the transport as ready to receive data
|-
| PalOut || Send data to the host platform
|-
|colspan="2" | '''Receive'''
|-
| PalInReg || Data extracted from the transport and identified for the STRIDE Runtime
|}

== Integrating the PAL ==

=== PAL Operating System (OS) Services ===
The '''[[Platform Abstraction Layer|PAL]]''' OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:
* Task protection and synchronization (e.g. mutexes)
* Periodic Timers
* Get Time Stamp
* Memory Management
By convention, these services are implemented in a file called palOS.c.

=== PAL Transport (I/O) Services ===
The [[Integrating STRIDE#The_Host_Transport|Host Transport]] implement the host peer of the I/O services between the Host and Target. Most of the pre-packaged PALs below provide both a serial and a TCP/IP transport.

On the Target side, the Transport is usually implemented in file palIO.c.

On the Host side, STRIDE Studio provides menus and automation methods to manage your target connection.

;What about USB?: S2 does not yet provide a native USB transport. If you wish to use one of our pre-packaged transports, then the USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB. Google "USBNet" to locate a driver for your systems.
;What if I need a custom transport?: A custom transport can be readily written to your specific needs. Please refer to the ''STRIDE Host Transport Specification'' document that is installed with STRIDE for information on creating custom Transport DLLs for the host. Your PAL implementation will need to implement the target side of the custom communication. More information on the Transport Wizard can be found in the ''STRIDE Developer's Guide'' in Online Help.

=== Using a Pre-Packaged PAL ===
S2 can provide a ready made PAL for many common operating systems. Most contain support for both a serial and a TCP/IP transport. Select the optional '''runtime''' section when installing STRIDE to get the currently supported PALs installed on your machine, or [http://www.s2technologies.com/contact.html contact us] for help in obtaining a PAL for other platforms.

=== Creating your own PAL ===
The PAL enables STRIDE to be completely agnostic to the underlying operating system and hardware. In fact, an operating system is not really required, so long as the PAL can provide the needed services.

If there is no pre-packaged PAL for your system, you can use an existing one as a starting point, or even write a new one from scratch. Past experience has shown that a PAL can usually be implemented in about two days.

More information on creating a custom PAL, including a custom Transport can be found in the Online Help and in the ''Platform Abstraction Layer (PAL) Specification'' which can be found in C:\STRIDE\doc\s2sPAL.pdf. S2's System's Engineers are also available to assist you with this task.

=== PAL Resource Requirements ===
Most PALs require a reader task to monitor the Transport input data stream.

PAL memory usage is limited to a few dozen bytes for table and control block storage. The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.

=== PAL Initialization ===
There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM. However, over time the convention of providing a ''palInit()'' function has developed. All of the Pre-Packaged PAL use this convention and their ''palInit()'' function must be called before any other STRIDE Runtime function.

If you roll your own PAL, it is recommended that you maintain this convention.

[[Category: Deploying STRIDE]]
[[Category:STRIDE Runtime]]

Platform Abstraction Layer

2008-06-24T22:38:25Z

Shamr: /* PAL Organization */

The PAL, or Platform Abstraction Layer, enables the STRIDE Runtime to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.

== PAL Concepts ==
This section describes the basic concepts of the PAL and the system services it must provide.

=== Function Registration ===
Typically, the STRIDE Runtime calls PAL functions; however, there are some functions in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL dependencies on the STRIDE Runtime, these functions are accessed through a function registration process initiated by the STRIDE Runtime at startup. You write the registration routine called by the Runtime. This registration routine passes in the address of the STRIDE Runtime function to be registered as the input parameter, and stores the address of the STRIDE Runtime function in your own function variable, which is actually a pointer to a function. You can then call the registered function using your function pointer variable.

The registered STRIDE Runtime functions allow you to complete such tasks as delivering a received I block to the Runtime, checking the number of I-blocks the Runtime has ready to send out, or signalling the Runtime that your transport is ready for the next I-block. It is not necessary for the PAL to know the details of these Runtime functions.

=== Task Synchronization / Event Notification ===
Unique information is required by an operating system to notify a thread of a pending event. This information can be a simple index into a table, an address to a thread control block, the address of a semaphore or one of a number of other implementations. Although each implementation may be different, a unique notifier is necessary for each thread. The STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same NID to notify the thread of a pending STRIDE event.

An additional piece of information included with the notify routine is a box ID, which is the ID of the mailbox where the message is delivered.

Support for sharing of the synchronization object among multiple applications should be ensured in case of multi-process target is enabled.

=== Protection using Mutex ===
The STRIDE Runtime needs to protect critical and shared data structures from multiple, simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. The PAL requires implementing protection using Mutexes that can be created and, in case of multi-process target is enabled, used with a unique name by any STRIDE Runtime module or PAL itself. The STRIDE Runtime guarantees that calls to palMutexLock() will not be nested.

=== Timer Administration ===
The STRIDE Runtime requires that at least one timer be available. When a timer is created, a callback is registered so that the STRIDE Runtime can be notified of timer expirations. A user parameter, provided when the timer is created, is passed to the callback when it gets called. If several timers share a callback routine, this user parameter can be used to identify which timer expired. The STRIDE Runtime can also stop, start and delete timers.

Because the STRIDE Runtime also has the need to timestamp trace log data, a routine that returns the system time, palGetTime(), is also part of the PAL. This routine is not associated with timers.

=== Memory Allocation ===
The STRIDE Runtime dynamically allocates memory for messages and trace log storage. The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically and then return it to the system.

The Runtime uses palMemSegmentOpen() and palMemSegmentClose() to create, open and close memory segments. In case of single process target, these routines can simply allocate dynamic memory as in normal memory allocation routines.

To support multi-process target, the STRIDE Runtime requires dynamic and configurable memory allocated through palMemAlloc() and static internal memory allocated directly through palMemSegmentOpen() to be shared memory.

In case of multi-process target, palMemAlloc() and palMemFree() routines can simply call the STRIDE Runtime’s Memory Management module srMem, which is in turn dependent on palMemSegmentOpen() and palMemSegmentClose() routines.

=== Transport Services ===
The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into and out of the STRIDE Runtime on your target platform. These routines handle the buffering and transferring of data to and from your transport mechanism. The PAL also contains registration routines that allow for STRIDE Runtime routines to be called by the PAL.

The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport. The STRIDE Runtime calls the palOut() routine whenever it needs to send out an I-block.

Your transport calls the routine registered with the palOutRdyReg() routine when the transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not call the palOut() routine until you call the registered function. In this way, you can control the flow of transmitted I-blocks.
When a complete I-block has been received by your transport, the routine registered with the palInReg() routine should be called to put the received I-block into the STRIDE Runtime.

In some cases it is useful to know when the transmit path is not being requested. Your transport mechanism can check the number of I-blocks the STRIDE Runtime has ready for transmission by calling the routine registered with the palOutPndReg() routine.

=== Host Services ===
The PAL also provides a way for the STRIDE Runtime to support your transport protocol
on the desktop. A Windows® DLL linked to STRIDE Studio enables these host
services. The DLL allows your data to be received and transmitted using your transport

== PAL Organization ==

This section explains the two categories of PAL services that support the STRIDE Runtime, as
well as the files used to implement these services on your target.

=== PAL Services ===
The PAL services include the following:
* Operating System (OS) Services
* Input/Output (IO) Services

=== PAL Operating System Services ===
The PAL Operating System (OS) Services are the routines that enable the STRIDE Runtime to work with the operating system on your target platform. In order to write your PAL OS services you must have detailed knowledge of how your operating system handles thread synchronization, timers, mutexes, dynamic memory, shared memory, and notification. The PAL OS services make the features of your operating system available to the STRIDE Runtime.

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Synchronization'''
|-
| palCreateNID || Create a Notification Identifier (NID)
|-
| palDeleteNID || Delete a Notification Identifier (NID)
|-
| palCreateRFCProxyNID || Create the RFC Proxy Notification Identifier (NID)
|-
| palDeleteRFCProxyNID || Delete the RFC Proxy Notification Identifier (NID)
|-
| palWait || Wait for an event
|-
| palNotify || Signal a thread that an event is pending
|-
| palGetThreadId || Return current thread Id
|-
| palGetProcessId || Return current process Id
|-
| palSleep || Suspend the execution of the current thread
|-
|colspan="2" | '''Timers'''
|-
| palTimerCreate || Create a timer
|-
| palTimerDelete || Delete a timer
|-
| palTimerStart || Start a timer
|-
| palTimerStop || Stop a timer
|-
| palGetTime || Return system time (e.g., tick count)
|-
|colspan="2" | '''Mutex'''
|-
| palMutexInit || Initialize a mutex object
|-
| palMutexDestroy || Destroy a mutex object
|-
| palMutexLock || Lock a mutex object
|-
| palMutexUnlock || Unlock a mutex object
|-
|colspan="2" | '''Memory Management'''
|-
| palMemAlloc || Allocate a block of dynamic memory
|-
| palMemFree || Free a block of dynamic memory
|-
| palMemSegmentOpen || Create/open memory segments
|-
| palMemSegmentClose || Close memory segments
|}

=== PAL Input/Output Services ===
The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to
work with different data transport mechanisms. These routines enable your transport to
send and receive data between the host and the target.

The IO services have also been defined to allow the target platform to control how
memory is managed and the rate of data exchange. See Appendix A beginning on page
121 for definitions of the header file functions

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Transmit'''
|-
| PalOutPndReg || Query the current output queue of the Runtime
|-
| PalOutRdyReg || Identify the transport as ready to receive data
|-
| PalOut || Send data to the host platform
|-
|colspan="2" | '''Receive'''
|-
| PalInReg || Data extracted from the transport and identified for the STRIDE Runtime
|}

== Integrating the PAL ==

=== PAL Operating System (OS) Services ===
The '''[[Platform Abstraction Layer|PAL]]''' OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:
* Task protection and synchronization (e.g. semaphores)
* Periodic Timers
* Get Time Stamp
* Memory Management
By convention, these services are implemented in a file called palOS.c.

=== PAL Transport (I/O) Services ===
The [[Integrating STRIDE#The_Host_Transport|Host Transport]] implement the host peer of the I/O services between the Host and Target. Most of the pre-packaged PALs below provide both a serial and a TCP/IP transport.

On the Target side, the Transport is usually implemented in file palIO.c.

On the Host side, STRIDE Studio provides menus and automation methods to manage your target connection.

;What about USB?: S2 does not yet provide a native USB transport. If you wish to use one of our pre-packaged transports, then the USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB. Google "USBNet" to locate a driver for your systems.
;What if I need a custom transport?: A custom transport can be readily written to your specific needs. Please refer to the ''STRIDE Host Transport Specification'' document that is installed with STRIDE for information on creating custom Transport DLLs for the host. Your PAL implementation will need to implement the target side of the custom communication. More information on the Transport Wizard can be found in the ''STRIDE Developer's Guide'' in Online Help.

=== Using a Pre-Packaged PAL ===
S2 can provide a ready made PAL for many common operating systems. Most contain support for both a serial and a TCP/IP transport. Select the optional '''runtime''' section when installing STRIDE to get the currently supported PALs installed on your machine, or [http://www.s2technologies.com/contact.html contact us] for help in obtaining a PAL for other platforms.

=== Creating your own PAL ===
The PAL enables STRIDE to be completely agnostic to the underlying operating system and hardware. In fact, an operating system is not really required, so long as the PAL can provide the needed services.

If there is no pre-packaged PAL for your system, you can use an existing one as a starting point, or even write a new one from scratch. Past experience has shown that a PAL can usually be implemented in about two days.

More information on creating a custom PAL, including a custom Transport can be found in the Online Help and in the ''Platform Abstraction Layer (PAL) Specification'' which can be found in C:\STRIDE\doc\s2sPAL.pdf. S2's System's Engineers are also available to assist you with this task.

=== PAL Resource Requirements ===
Most PALs require a reader task to monitor the Transport input data stream.

PAL memory usage is limited to a few dozen bytes for table and control block storage. The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.

=== PAL Initialization ===
There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM. However, over time the convention of providing a ''palInit()'' function has developed. All of the Pre-Packaged PAL use this convention and their ''palInit()'' function must be called before any other STRIDE Runtime function.

If you roll your own PAL, it is recommended that you maintain this convention.

[[Category: Deploying STRIDE]]
[[Category:STRIDE Runtime]]

Platform Abstraction Layer

2008-06-24T22:33:53Z

Shamr: /* PAL Concepts */

The PAL, or Platform Abstraction Layer, enables the STRIDE Runtime to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.

== PAL Concepts ==
This section describes the basic concepts of the PAL and the system services it must provide.

=== Function Registration ===
Typically, the STRIDE Runtime calls PAL functions; however, there are some functions in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL dependencies on the STRIDE Runtime, these functions are accessed through a function registration process initiated by the STRIDE Runtime at startup. You write the registration routine called by the Runtime. This registration routine passes in the address of the STRIDE Runtime function to be registered as the input parameter, and stores the address of the STRIDE Runtime function in your own function variable, which is actually a pointer to a function. You can then call the registered function using your function pointer variable.

The registered STRIDE Runtime functions allow you to complete such tasks as delivering a received I block to the Runtime, checking the number of I-blocks the Runtime has ready to send out, or signalling the Runtime that your transport is ready for the next I-block. It is not necessary for the PAL to know the details of these Runtime functions.

=== Task Synchronization / Event Notification ===
Unique information is required by an operating system to notify a thread of a pending event. This information can be a simple index into a table, an address to a thread control block, the address of a semaphore or one of a number of other implementations. Although each implementation may be different, a unique notifier is necessary for each thread. The STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same NID to notify the thread of a pending STRIDE event.

An additional piece of information included with the notify routine is a box ID, which is the ID of the mailbox where the message is delivered.

Support for sharing of the synchronization object among multiple applications should be ensured in case of multi-process target is enabled.

=== Protection using Mutex ===
The STRIDE Runtime needs to protect critical and shared data structures from multiple, simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. The PAL requires implementing protection using Mutexes that can be created and, in case of multi-process target is enabled, used with a unique name by any STRIDE Runtime module or PAL itself. The STRIDE Runtime guarantees that calls to palMutexLock() will not be nested.

=== Timer Administration ===
The STRIDE Runtime requires that at least one timer be available. When a timer is created, a callback is registered so that the STRIDE Runtime can be notified of timer expirations. A user parameter, provided when the timer is created, is passed to the callback when it gets called. If several timers share a callback routine, this user parameter can be used to identify which timer expired. The STRIDE Runtime can also stop, start and delete timers.

Because the STRIDE Runtime also has the need to timestamp trace log data, a routine that returns the system time, palGetTime(), is also part of the PAL. This routine is not associated with timers.

=== Memory Allocation ===
The STRIDE Runtime dynamically allocates memory for messages and trace log storage. The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically and then return it to the system.

The Runtime uses palMemSegmentOpen() and palMemSegmentClose() to create, open and close memory segments. In case of single process target, these routines can simply allocate dynamic memory as in normal memory allocation routines.

To support multi-process target, the STRIDE Runtime requires dynamic and configurable memory allocated through palMemAlloc() and static internal memory allocated directly through palMemSegmentOpen() to be shared memory.

In case of multi-process target, palMemAlloc() and palMemFree() routines can simply call the STRIDE Runtime’s Memory Management module srMem, which is in turn dependent on palMemSegmentOpen() and palMemSegmentClose() routines.

=== Transport Services ===
The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into and out of the STRIDE Runtime on your target platform. These routines handle the buffering and transferring of data to and from your transport mechanism. The PAL also contains registration routines that allow for STRIDE Runtime routines to be called by the PAL.

The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport. The STRIDE Runtime calls the palOut() routine whenever it needs to send out an I-block.

Your transport calls the routine registered with the palOutRdyReg() routine when the transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not call the palOut() routine until you call the registered function. In this way, you can control the flow of transmitted I-blocks.
When a complete I-block has been received by your transport, the routine registered with the palInReg() routine should be called to put the received I-block into the STRIDE Runtime.

In some cases it is useful to know when the transmit path is not being requested. Your transport mechanism can check the number of I-blocks the STRIDE Runtime has ready for transmission by calling the routine registered with the palOutPndReg() routine.

=== Host Services ===
The PAL also provides a way for the STRIDE Runtime to support your transport protocol
on the desktop. A Windows® DLL linked to STRIDE Studio enables these host
services. The DLL allows your data to be received and transmitted using your transport

== PAL Organization ==

This section explains the two categories of PAL services that support the STRIDE Runtime, as
well as the files used to implement these services on your target.

=== PAL Services ===
The PAL services include the following:
* Operating System (OS) Services
* Input/Output (IO) Services

=== PAL Operating System Services ===
The PAL Operating System (OS) Services are the routines that enable the STRIDE
Runtime to work with the operating system on your target platform. In order to write your
PAL OS services you must have detailed knowledge of how your operating system
handles thread synchronization, timers, critical sections, dynamic memory, and
notification. The PAL OS services make the features of your operating system available
to the STRIDE Runtime. All of the functions described here must be fully implemented in your PAL.

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Synchronization'''
|-
| palCreateNID || Create a Notification Identifier (NID)
|-
| palDeleteNID || Delete a Notification Identifier (NID)
|-
| palCreateRFCProxyNID || Create the RFC Proxy Notification Identifier (NID)
|-
| palDeleteRFCProxyNID || Delete the RFC Proxy Notification Identifier (NID)
|-
| palWait || Wait for an event
|-
| palNotify || Signal a thread that an event is pending
|-
|colspan="2" | '''Timers'''
|-
| palTimerCreate || Create a timer
|-
| palTimerDelete || Delete a timer
|-
| palTimerStart || Start a timer
|-
| palTimerStop || Stop a timer
|-
| palGetTime || Return system time (e.g., tick count)
|-
|colspan="2" | '''Critical Section'''
|-
| palProtect || Begin critical section
|-
| palUnprotect || End critical section
|-
|colspan="2" | '''Memory'''
|-
| palMemAlloc || Allocate a block of dynamic memory
|-
| palMemFree || Free a block of dynamic memory
|}

=== PAL Input/Output Services ===
The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to
work with different data transport mechanisms. These routines enable your transport to
send and receive data between the host and the target.

The IO services have also been defined to allow the target platform to control how
memory is managed and the rate of data exchange. See Appendix A beginning on page
121 for definitions of the header file functions

{|class="wikitable" border="2" style="margin:1em auto 1em"
! Function Name !! Description
|-
|colspan="2" | '''Transmit'''
|-
| PalOutPndReg || Query the current output queue of the Runtime
|-
| PalOutRdyReg || Identify the transport as ready to receive data
|-
| PalOut || Send data to the host platform
|-
|colspan="2" | '''Receive'''
|-
| PalInReg || Data extracted from the transport and identified for the STRIDE Runtime
|}

== Integrating the PAL ==

=== PAL Operating System (OS) Services ===
The '''[[Platform Abstraction Layer|PAL]]''' OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:
* Task protection and synchronization (e.g. semaphores)
* Periodic Timers
* Get Time Stamp
* Memory Management
By convention, these services are implemented in a file called palOS.c.

=== PAL Transport (I/O) Services ===
The [[Integrating STRIDE#The_Host_Transport|Host Transport]] implement the host peer of the I/O services between the Host and Target. Most of the pre-packaged PALs below provide both a serial and a TCP/IP transport.

On the Target side, the Transport is usually implemented in file palIO.c.

On the Host side, STRIDE Studio provides menus and automation methods to manage your target connection.

;What about USB?: S2 does not yet provide a native USB transport. If you wish to use one of our pre-packaged transports, then the USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB. Google "USBNet" to locate a driver for your systems.
;What if I need a custom transport?: A custom transport can be readily written to your specific needs. Please refer to the ''STRIDE Host Transport Specification'' document that is installed with STRIDE for information on creating custom Transport DLLs for the host. Your PAL implementation will need to implement the target side of the custom communication. More information on the Transport Wizard can be found in the ''STRIDE Developer's Guide'' in Online Help.

=== Using a Pre-Packaged PAL ===
S2 can provide a ready made PAL for many common operating systems. Most contain support for both a serial and a TCP/IP transport. Select the optional '''runtime''' section when installing STRIDE to get the currently supported PALs installed on your machine, or [http://www.s2technologies.com/contact.html contact us] for help in obtaining a PAL for other platforms.

=== Creating your own PAL ===
The PAL enables STRIDE to be completely agnostic to the underlying operating system and hardware. In fact, an operating system is not really required, so long as the PAL can provide the needed services.

If there is no pre-packaged PAL for your system, you can use an existing one as a starting point, or even write a new one from scratch. Past experience has shown that a PAL can usually be implemented in about two days.

More information on creating a custom PAL, including a custom Transport can be found in the Online Help and in the ''Platform Abstraction Layer (PAL) Specification'' which can be found in C:\STRIDE\doc\s2sPAL.pdf. S2's System's Engineers are also available to assist you with this task.

=== PAL Resource Requirements ===
Most PALs require a reader task to monitor the Transport input data stream.

PAL memory usage is limited to a few dozen bytes for table and control block storage. The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.

=== PAL Initialization ===
There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM. However, over time the convention of providing a ''palInit()'' function has developed. All of the Pre-Packaged PAL use this convention and their ''palInit()'' function must be called before any other STRIDE Runtime function.

If you roll your own PAL, it is recommended that you maintain this convention.

[[Category: Deploying STRIDE]]
[[Category:STRIDE Runtime]]

Studio:Integrating the Intercept Module (IM)

2008-06-24T22:09:25Z

Shamr: /* Starting the IMStubRead thread */

== Intercept Module Files and their purpose ==
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:
* The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
* The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
* The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

These filenames are all prepended by the name you give the IM when it is generated. For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".

== Configuring and generating an Intercept Module ==
You can either generate the IM via STRIDE Studio's Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.

The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
<source lang="perl">
# Build the workspace database
$main::studio->Workspace->Build();

# Intercept Module (IM) name and path constants
my $IM_FILE_NAME = "MyProject";
my $IM_LOCATION_PATH = $main::studio->Workspace->Path;

# Create a reference to the workspace IM object
my $IM = $main::studio->Workspace->Intercept;

# Local variables
my ($i, $fx);

# Reset all of the IM configuration settings to off and
# reset the delegate group Id's to their default name.
$IM->Reset();

# Setup the IM name and path
$IM->{Name} = $IM_FILE_NAME;
$IM->{SourcePath} = $IM_LOCATION_PATH;
$IM->{HeaderPath} = $IM_LOCATION_PATH;

# For each interface in the IM collection
for ($i=0; $i < $IM->Count(); $i++)
{
# reference the ith interface;
$fx = $IM->Item($i);

$fx->{Stub} = 1; # configure as stub
# and delegate
$fx->Delegate->{Owner} = 1; # mangle from owner's perspective
$fx->Delegate->{Explicit} = 1; # implicit name mangling
$fx->Delegate->{Dynamic} = 1; # enable dynamic interception
}

# Create IM files.
$IM->Create();
</source>

Note in the above script how the IM name and output directory were defined. In this case, all three files are created in the same directory as the STRIDE workspace. The resulting Intercept Module file must then be compiled and built with the rest of your target code.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Integrating the STRIDE Runtime into a Target|Runtime]] and the [[Integrating the Platform Abstract Layer (PAL)|PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the srThread and IMStubRead threads ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet for Linux, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

This code snippet for Linux also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

== Linux Implementation ==
<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf(stdout, "TestAgent exiting.\n");
for (i = sizeof(_threads)/sizeof(_threads[0]); i > 0; i--)
{
if (_threads[i-1] != 0)
{
palNotify(_threads[i-1], palSTOP_EVENT);
pthread_join(_threads[i-1], NULL);
pthread_detach(_threads[i-1]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/* A function to start the STRIDE threads */
void STRIDEstartup()
{
/* Set termination signals handling */
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);
(void) signal(SIGHUP, _terminate);

/* Initialize PAL. It will return palFALSE if it fails
(This will open the transport to the host) */
if (palInit() == palFALSE) {
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

/* Initialize Runtime */
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
exit(1);
}

/* Start the Runtime thread first */
pthread_create(&_threads[0], NULL, _threadFunc, (void*)srThread);

/* Start the IM stub read thread */
pthread_create(&_threads[1], NULL, _threadFunc, (void*)MyProjectIMStubThread);

/* Wait for Runtime thread */
pthread_join(_threads[0], NULL);

_cleanup();

return 0;
}
</source>

This code snippet for Windows is based on using the Win32 API calls.

== Windows Implementation ==
<source lang="c">
#include "stdafx.h"
#include <windows.h>
#include <commctrl.h>

#include <sr.h>
#include <palcfg.h>
#include "MyProjectIMEntry.h"

static bool bUseSerial = false;

struct ThreadInfo
{
HANDLE handle;
DWORD id;
};

typedef void (*_ThreadFunc_t)( void );

static DWORD WINAPI _threadFunc(LPVOID param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return 0;
}

int _tmain(int argc, _TCHAR* argv[])
{
ThreadInfo threads[15] = {{NULL, 0}};
int i = 0;

// Initialize the PAL
if (palOSInit() != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palOSInit FAILED.");
return -1;
}

pal_io_config_t cfg;
pal_prot_t protocol;
if (bUseSerial) {
protocol = PAL_PROT_SERIAL;
cfg.u.serial.BaudRate = PAL_SERIAL_BAUDRATE;
cfg.u.serial.ByteSize = PAL_SERIAL_BYTESIZE;
cfg.u.serial.ComPort = PAL_SERIAL_PORT;
cfg.u.serial.Parity = PAL_SERIAL_PARITY;
cfg.u.serial.StopBits = PAL_SERIAL_STOPBITS;
}
else {
protocol = PAL_PROT_TCP;
cfg.u.tcp.Port = PAL_DEFAULT_TCP_PORT;
}

// Initialize tcp transport
if (palIOInit(protocol, &cfg) != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palIOInit FAILED.");
return -1;
}

// Initialize Runtime
if (srInit() != srOK) {
palLog(palLOG_LEVEL_ERROR, "srInit FAILED.");
return -1;
}

// Start the Runtime thread first
threads[i].handle = CreateThread(NULL, 0, _threadFunc, srThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for Runtime Thread.");
return -1;
}

// Start the IM stub read thread
threads[i].handle = CreateThread(NULL, 0, _threadFunc, MyProjectIMStubThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for IM Thread.");
return -1;
}

// Wait for Runtime thread
WaitForSingleObject(threads[0].handle, INFINITE);

fprintf (stdout, "TestAgent exiting.\n");
for (i = sizeof(threads)/sizeof(threads[0]); i > 0; i--)
{
if (threads[i-1].handle != NULL)
{
palNotify(threads[i-1].id, palSTOP_EVENT);
WaitForSingleObject(threads[i-1].handle, INFINITE);
CloseHandle(threads[i-1].handle);
}
}

srUninit();
palOSUninit();
return 0;
}
</source>

[[Category: Intercept Modules]]

STRIDE 3.0.01xx

2008-06-24T00:17:07Z

Shamr: /* Change Details */ SCR 8880

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Target-Based Testing==
The Target-based testing has been expanded with a new pragma scl_test_flist(). When included in the source code the compiler and the IM generator will automatically create test harnessing code.

On a higher level the test pragmas (scl_test_class and scl_test_flist) has been grouped in [[Test Units]] category. A new TestUnits collection has been added to AutoScript.

The automation components STRIDE.testclass, STRIDE.testunit and STRIDE.testfunction are removed.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.

The '''s2shostapphrt''' libriary, a prebuild verion of the Host Runtime, has been removed. Building Windows applications using the Host Runtime is not supported anymore. The '''s2shostapptrt''' libriary, a prebuild version of the Target Runtime, has been removed.

If an upgrade is performed it is srongly recommented that the above mentioned '''s2shostapp*''' libraries and the their public API header (hostapp.h) be manually removed.

=Change Details=

==Fixes==
''This section describes defects which have been corrected in STRIDE and the customer tracking number associated with them, if any, in brackets [].''
* [1055] Not able to specifiy uppercase include directory
* [1543] IM source file locations added to studio UI and automation
* [1586] Support for Variadic Macros
* [1597] EDGFront crash for scl_ptr_opaque
* [1600] Pre-processor treats constant 1 always as 8-bit

==AutoScript==

===TestUnits Collection===
A new TestUnits collection has been implemented. All test interfaces (specified with scl_test_class and scl_test_flist) will be listed there.

===Functions Collection===
Interfaces specified with scl_test_class pragma are not listed in the Functions collection anymore.

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime (Beta 1)==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
* In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

==Runtime (Beta 2)==
* A new public routine for Runtime Thread exit point, srThreadUninit(), has been added to sr.h & srthread.c.
* Fixed a compiler warning in srmem.c.
* Fixed a potential data abort issue when executing delegate code in the IM prior to Runtime being initialized.

*'' The following Runtime files have been modified:
sr.h
srcfg.h
srconn.c
srmem.c
srthread.c

==Runtime (Beta 3)==
* Runtime Test Services APIs are now thread safe.

*'' The following Runtime files have been modified:
srapi.c
srapi.h
srtest.c

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==AutoScript==
Any use of test classes through the Functions collection, like:

$main::ascript->Functions->Item("my_test_class")->User->Call();

should be converted to use the new TestUnits collection:

$main::ascript->TestUnits->Item("my_test_class")->Run();

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

* If target Test Classes and Test Functions are used, change the signature to include test label in srTestCaseAddComment() and AddComment() APIs.

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-20T22:47:49Z

Shamr: /* Runtime (Beta 2) */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Target-Based Testing==
The Target-based testing has been expanded with a new pragma scl_test_flist(). When included in the source code the compiler and the IM generator will automatically create test harnessing code.

On a higher level the test pragmas (scl_test_class and scl_test_flist) has been grouped in [[Test Units]] category. A new TestUnits collection has been added to AutoScript.

The automation components STRIDE.testclass, STRIDE.testunit and STRIDE.testfunction are removed.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.

The '''s2shostapphrt''' libriary, a prebuild verion of the Host Runtime, has been removed. Building Windows applications using the Host Runtime is not supported anymore. The '''s2shostapptrt''' libriary, a prebuild version of the Target Runtime, has been removed.

If an upgrade is performed it is srongly recommented that the above mentioned '''s2shostapp*''' libraries and the their public API header (hostapp.h) be manually removed.

=Change Details=

==Fixes==
''This section describes defects which have been corrected in STRIDE and the customer tracking number associated with them, if any, in brackets [].''
* [1055] Not able to specifiy uppercase include directory
* [1543] IM source file locations added to studio UI and automation
* [1586] Support for Variadic Macros
* [1597] EDGFront crash for scl_ptr_opaque
* [1600] Pre-processor treats constant 1 always as 8-bit

==AutoScript==

===TestUnits Collection===
A new TestUnits collection has been implemented. All test interfaces (specified with scl_test_class and scl_test_flist) will be listed there.

===Functions Collection===
Interfaces specified with scl_test_class pragma are not listed in the Functions collection anymore.

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime (Beta 1)==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
* In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

==Runtime (Beta 2)==
* A new public routine for Runtime Thread exit point, srThreadUninit(), has been added to sr.h & srthread.c.
* Fixed a compiler warning in srmem.c.
* Fixed a potential data abort issue when executing delegate code in the IM prior to Runtime being initialized.

*'' The following Runtime files have been modified:
sr.h
srcfg.h
srconn.c
srmem.c
srthread.c

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==AutoScript==
Any use of test classes through the Functions collection, like:

$main::ascript->Functions->Item("my_test_class")->User->Call();

should be converted to use the new TestUnits collection:

$main::ascript->TestUnits->Item("my_test_class")->Run();

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

* If target Test Classes and Test Functions are used, change the signature to include test label in srTestCaseAddComment() and AddComment() APIs.

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

Studio:Integrating the Intercept Module (IM)

2008-06-20T22:29:49Z

Shamr: /* Windows Implementation */

== Intercept Module Files and their purpose ==
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:
* The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
* The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
* The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

These filenames are all prepended by the name you give the IM when it is generated. For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".

== Configuring and generating an Intercept Module ==
You can either generate the IM via STRIDE Studio's Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.

The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
<source lang="perl">
# Build the workspace database
$main::studio->Workspace->Build();

# Intercept Module (IM) name and path constants
my $IM_FILE_NAME = "MyProject";
my $IM_LOCATION_PATH = $main::studio->Workspace->Path;

# Create a reference to the workspace IM object
my $IM = $main::studio->Workspace->Intercept;

# Local variables
my ($i, $fx);

# Reset all of the IM configuration settings to off and
# reset the delegate group Id's to their default name.
$IM->Reset();

# Setup the IM name and path
$IM->{Name} = $IM_FILE_NAME;
$IM->{SourcePath} = $IM_LOCATION_PATH;
$IM->{HeaderPath} = $IM_LOCATION_PATH;

# For each interface in the IM collection
for ($i=0; $i < $IM->Count(); $i++)
{
# reference the ith interface;
$fx = $IM->Item($i);

$fx->{Stub} = 1; # configure as stub
# and delegate
$fx->Delegate->{Owner} = 1; # mangle from owner's perspective
$fx->Delegate->{Explicit} = 1; # implicit name mangling
$fx->Delegate->{Dynamic} = 1; # enable dynamic interception
}

# Create IM files.
$IM->Create();
</source>

Note in the above script how the IM name and output directory were defined. In this case, all three files are created in the same directory as the STRIDE workspace. The resulting Intercept Module file must then be compiled and built with the rest of your target code.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Integrating the STRIDE Runtime into a Target|Runtime]] and the [[Integrating the Platform Abstract Layer (PAL)|PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the IMStubRead thread ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet for Linux, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

This code snippet for Linux also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

== Linux Implementation ==
<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf(stdout, "TestAgent exiting.\n");
for (i = sizeof(_threads)/sizeof(_threads[0]); i > 0; i--)
{
if (_threads[i-1] != 0)
{
palNotify(_threads[i-1], palSTOP_EVENT);
pthread_join(_threads[i-1], NULL);
pthread_detach(_threads[i-1]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/* A function to start the STRIDE threads */
void STRIDEstartup()
{
/* Set termination signals handling */
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);
(void) signal(SIGHUP, _terminate);

/* Initialize PAL. It will return palFALSE if it fails
(This will open the transport to the host) */
if (palInit() == palFALSE) {
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

/* Initialize Runtime */
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
exit(1);
}

/* Start the Runtime thread first */
pthread_create(&_threads[0], NULL, _threadFunc, (void*)srThread);

/* Start the IM stub read thread */
pthread_create(&_threads[1], NULL, _threadFunc, (void*)MyProjectIMStubThread);

/* Wait for Runtime thread */
pthread_join(_threads[0], NULL);

_cleanup();

return 0;
}
</source>

This code snippet for Windows is based on using the Win32 API calls.

== Windows Implementation ==
<source lang="c">
#include "stdafx.h"
#include <windows.h>
#include <commctrl.h>

#include <sr.h>
#include <palcfg.h>
#include "MyProjectIMEntry.h"

static bool bUseSerial = false;

struct ThreadInfo
{
HANDLE handle;
DWORD id;
};

typedef void (*_ThreadFunc_t)( void );

static DWORD WINAPI _threadFunc(LPVOID param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return 0;
}

int _tmain(int argc, _TCHAR* argv[])
{
ThreadInfo threads[15] = {{NULL, 0}};
int i = 0;

// Initialize the PAL
if (palOSInit() != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palOSInit FAILED.");
return -1;
}

pal_io_config_t cfg;
pal_prot_t protocol;
if (bUseSerial) {
protocol = PAL_PROT_SERIAL;
cfg.u.serial.BaudRate = PAL_SERIAL_BAUDRATE;
cfg.u.serial.ByteSize = PAL_SERIAL_BYTESIZE;
cfg.u.serial.ComPort = PAL_SERIAL_PORT;
cfg.u.serial.Parity = PAL_SERIAL_PARITY;
cfg.u.serial.StopBits = PAL_SERIAL_STOPBITS;
}
else {
protocol = PAL_PROT_TCP;
cfg.u.tcp.Port = PAL_DEFAULT_TCP_PORT;
}

// Initialize tcp transport
if (palIOInit(protocol, &cfg) != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palIOInit FAILED.");
return -1;
}

// Initialize Runtime
if (srInit() != srOK) {
palLog(palLOG_LEVEL_ERROR, "srInit FAILED.");
return -1;
}

// Start the Runtime thread first
threads[i].handle = CreateThread(NULL, 0, _threadFunc, srThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for Runtime Thread.");
return -1;
}

// Start the IM stub read thread
threads[i].handle = CreateThread(NULL, 0, _threadFunc, MyProjectIMStubThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for IM Thread.");
return -1;
}

// Wait for Runtime thread
WaitForSingleObject(threads[0].handle, INFINITE);

fprintf (stdout, "TestAgent exiting.\n");
for (i = sizeof(threads)/sizeof(threads[0]); i > 0; i--)
{
if (threads[i-1].handle != NULL)
{
palNotify(threads[i-1].id, palSTOP_EVENT);
WaitForSingleObject(threads[i-1].handle, INFINITE);
CloseHandle(threads[i-1].handle);
}
}

srUninit();
palOSUninit();
return 0;
}
</source>

[[Category: Intercept Modules]]

Studio:Integrating the Intercept Module (IM)

2008-06-20T22:28:36Z

Shamr: /* Starting the IMStubRead thread */

== Intercept Module Files and their purpose ==
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:
* The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
* The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
* The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

These filenames are all prepended by the name you give the IM when it is generated. For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".

== Configuring and generating an Intercept Module ==
You can either generate the IM via STRIDE Studio's Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.

The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
<source lang="perl">
# Build the workspace database
$main::studio->Workspace->Build();

# Intercept Module (IM) name and path constants
my $IM_FILE_NAME = "MyProject";
my $IM_LOCATION_PATH = $main::studio->Workspace->Path;

# Create a reference to the workspace IM object
my $IM = $main::studio->Workspace->Intercept;

# Local variables
my ($i, $fx);

# Reset all of the IM configuration settings to off and
# reset the delegate group Id's to their default name.
$IM->Reset();

# Setup the IM name and path
$IM->{Name} = $IM_FILE_NAME;
$IM->{SourcePath} = $IM_LOCATION_PATH;
$IM->{HeaderPath} = $IM_LOCATION_PATH;

# For each interface in the IM collection
for ($i=0; $i < $IM->Count(); $i++)
{
# reference the ith interface;
$fx = $IM->Item($i);

$fx->{Stub} = 1; # configure as stub
# and delegate
$fx->Delegate->{Owner} = 1; # mangle from owner's perspective
$fx->Delegate->{Explicit} = 1; # implicit name mangling
$fx->Delegate->{Dynamic} = 1; # enable dynamic interception
}

# Create IM files.
$IM->Create();
</source>

Note in the above script how the IM name and output directory were defined. In this case, all three files are created in the same directory as the STRIDE workspace. The resulting Intercept Module file must then be compiled and built with the rest of your target code.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Integrating the STRIDE Runtime into a Target|Runtime]] and the [[Integrating the Platform Abstract Layer (PAL)|PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the IMStubRead thread ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet for Linux, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

This code snippet for Linux also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

== Linux Implementation ==
<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf(stdout, "TestAgent exiting.\n");
for (i = sizeof(_threads)/sizeof(_threads[0]); i > 0; i--)
{
if (_threads[i-1] != 0)
{
palNotify(_threads[i-1], palSTOP_EVENT);
pthread_join(_threads[i-1], NULL);
pthread_detach(_threads[i-1]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/* A function to start the STRIDE threads */
void STRIDEstartup()
{
/* Set termination signals handling */
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);
(void) signal(SIGHUP, _terminate);

/* Initialize PAL. It will return palFALSE if it fails
(This will open the transport to the host) */
if (palInit() == palFALSE) {
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

/* Initialize Runtime */
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
exit(1);
}

/* Start the Runtime thread first */
pthread_create(&_threads[0], NULL, _threadFunc, (void*)srThread);

/* Start the IM stub read thread */
pthread_create(&_threads[1], NULL, _threadFunc, (void*)MyProjectIMStubThread);

/* Wait for Runtime thread */
pthread_join(_threads[0], NULL);

_cleanup();

return 0;
}
</source>

This code snippet for Windows is based on using the Win32 API calls.

== Windows Implementation ==
<source lang="c">
// TestAgent.cpp : Defines the entry point for the console application.
//

#include "stdafx.h"
#include <windows.h>
#include <commctrl.h>

#include <sr.h>
#include <palcfg.h>
#include "MyProjectIMEntry.h"

static bool bUseSerial = false;

struct ThreadInfo
{
HANDLE handle;
DWORD id;
};

typedef void (*_ThreadFunc_t)( void );

static DWORD WINAPI _threadFunc(LPVOID param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return 0;
}

int _tmain(int argc, _TCHAR* argv[])
{
ThreadInfo threads[15] = {{NULL, 0}};
int i = 0;

// Initialize the PAL
if (palOSInit() != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palOSInit FAILED.");
return -1;
}

pal_io_config_t cfg;
pal_prot_t protocol;
if (bUseSerial) {
protocol = PAL_PROT_SERIAL;
cfg.u.serial.BaudRate = PAL_SERIAL_BAUDRATE;
cfg.u.serial.ByteSize = PAL_SERIAL_BYTESIZE;
cfg.u.serial.ComPort = PAL_SERIAL_PORT;
cfg.u.serial.Parity = PAL_SERIAL_PARITY;
cfg.u.serial.StopBits = PAL_SERIAL_STOPBITS;
}
else {
protocol = PAL_PROT_TCP;
cfg.u.tcp.Port = PAL_DEFAULT_TCP_PORT;
}

// Initialize tcp transport
if (palIOInit(protocol, &cfg) != palTRUE) {
palLog(palLOG_LEVEL_ERROR, "palIOInit FAILED.");
return -1;
}

// Initialize Runtime
if (srInit() != srOK) {
palLog(palLOG_LEVEL_ERROR, "srInit FAILED.");
return -1;
}

// Start the Runtime thread first
threads[i].handle = CreateThread(NULL, 0, _threadFunc, srThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for Runtime Thread.");
return -1;
}

// Start the IM stub read thread
threads[i].handle = CreateThread(NULL, 0, _threadFunc, MyProjectIMStubThread, 0, &threads[i].id);
if (!threads[i++].handle) {
palLog(palLOG_LEVEL_ERROR, "CreateThread FAILED for IM Thread.");
return -1;
}

// Wait for Runtime thread
WaitForSingleObject(threads[0].handle, INFINITE);

fprintf (stdout, "TestAgent exiting.\n");
for (i = sizeof(threads)/sizeof(threads[0]); i > 0; i--)
{
if (threads[i-1].handle != NULL)
{
palNotify(threads[i-1].id, palSTOP_EVENT);
WaitForSingleObject(threads[i-1].handle, INFINITE);
CloseHandle(threads[i-1].handle);
}
}

srUninit();
palOSUninit();
return 0;
}
</source>

[[Category: Intercept Modules]]

Studio:Integrating the Intercept Module (IM)

2008-06-19T17:43:00Z

Shamr: /* Starting the IMStubRead thread */

== Intercept Module Files and their purpose ==
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:
* The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
* The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
* The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

These filenames are all prepended by the name you give the IM when it is generated. For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".

== Configuring and generating an Intercept Module ==
You can either generate the IM via STRIDE Studio's Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.

The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
<source lang="perl">
# Build the workspace database
$main::studio->Workspace->Build();

# Intercept Module (IM) name and path constants
my $IM_FILE_NAME = "MyProject";
my $IM_LOCATION_PATH = $main::studio->Workspace->Path;

# Create a reference to the workspace IM object
my $IM = $main::studio->Workspace->Intercept;

# Local variables
my ($i, $fx);

# Reset all of the IM configuration settings to off and
# reset the delegate group Id's to their default name.
$IM->Reset();

# Setup the IM name and path
$IM->{Name} = $IM_FILE_NAME;
$IM->{SourcePath} = $IM_LOCATION_PATH;
$IM->{HeaderPath} = $IM_LOCATION_PATH;

# For each interface in the IM collection
for ($i=0; $i < $IM->Count(); $i++)
{
# reference the ith interface;
$fx = $IM->Item($i);

$fx->{Stub} = 1; # configure as stub
# and delegate
$fx->Delegate->{Owner} = 1; # mangle from owner's perspective
$fx->Delegate->{Explicit} = 1; # implicit name mangling
$fx->Delegate->{Dynamic} = 1; # enable dynamic interception
}

# Create IM files.
$IM->Create();
</source>

Note in the above script how the IM name and output directory were defined. In this case, all three files are created in the same directory as the STRIDE workspace. The resulting Intercept Module file must then be compiled and built with the rest of your target code.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Integrating the STRIDE Runtime into a Target|Runtime]] and the [[Integrating the Platform Abstract Layer (PAL)|PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the IMStubRead thread ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then becomes the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

This code snippet also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf (stdout, "TestAgent exiting.\n");
for (i = 0; i < sizeof(_threads)/sizeof(_threads[0]); i++)
{
if (_threads[i] != 0)
{
palNotify(_threads[i], palSTOP_EVENT);
pthread_join(_threads[i], NULL);
pthread_detach(_threads[i]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/* A function to start the STRIDE threads */
void STRIDEstartup()
{
/* Set termination signals handling */
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);
(void) signal(SIGHUP, _terminate);

/* Initialize PAL. It will return palFALSE if it fails
(This will open the transport to the host) */
if (palInit() == palFALSE) {
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

/* Initialize Runtime */
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
exit(1);
}

/* Start the Runtime thread */
pthread_create (&_threads[0], NULL, _threadFunc, (void*)srThread);

/* Start the IM stub read thread */
pthread_create (&_threads[1], NULL, _threadFunc, (void*)MyProjectIMStubThread);

pthread_join(_threads[0], NULL);

_cleanup();

return 0;
}
</source>

[[Category: Intercept Modules]]

Studio:Integrating the Intercept Module (IM)

2008-06-19T00:19:22Z

Shamr: /* Starting the IMStubRead thread */

== Intercept Module Files and their purpose ==
The Intercept Module is generated by STRIDE Studio for the specific set of function interfaces you select. Three files are created, each prepended with the name of the Intercept Module that you gave it when it was created:
* The Intercept Module source file (''imname'''''IM.c''' or ''imname'''''IM.cpp''') This file contains the code that allows the ''remoting'' of functions so that they can be accessed by the Target and Host.
* The Delegate Mangling header file (''imname'''''IM.h''') This file must be included in all of your C files that are using Delegates (Dynamic or Tracing). It contains macros that will mangle the appropriate function names so that they can be intercepted and routed through the IM. When used, it must be the last file <tt>#include</tt>'d in the source. Also, it is only required if the C file uses Delegates. Stubs and Proxy functions do not require this file
* The IM Entry point header file (''imname'''''IMEntry.h''') This file contains the prototypes for the external entry points into the IM. It is needed only by the function that starts the IM Stub Read Thread.

These filenames are all prepended by the name you give the IM when it is generated. For example, if you call the IM "MyProject", then the resulting filenames will be "MyProjectIM.c", "MyProjectIM.h", and "MyProjectIMEntry.h".

== Configuring and generating an Intercept Module ==
You can either generate the IM via STRIDE Studio's Intercept Module Wizard, or you can utilize scripts to automatically configure and generate the IM files. These files will contain Studio-based configuration definitions. In addition, the script used for configuration will denote in which context the IM runtime functions are to be executed.

The script can execute automatically so that the Intercept Module is built as part of the test automation framework, as shown in the following example. The IM generation script should open a Studio workspace, optionally compile the workspace and save the database (if needed), then configure and create the IM as shown in the following Perl example:
<source lang="perl">
# Compile and save the workspace database
$main::studio->Workspace->CompileAll();
$main::studio->Workspace->Save();

# Intercept Module (IM) name and path constants
my $IM_FILE_NAME = "MyProject";
my $IM_LOCATION_PATH = $main::studio->Workspace->Path;

# Create a reference to the workspace IM object
my $IM = $main::studio->Workspace->Intercept;

# Local variables
my ($i, $fx);

# Reset all of the IM configuration settings to off and
# reset the delegate group Id's to their default name.
$IM->Reset();

# Setup the IM name and path
$IM->{Name} = $IM_FILE_NAME;
$IM->{Path} = $IM_LOCATION_PATH;

# For each interface in the IM collection
for ($i=0; $i < $IM->Count(); $i++)
{
# reference the ith interface;
$fx = $IM->Item($i);

$fx->{Stub} = 1; # configure as stub
# and delegate
$fx->Delegate->{Owner} = 1; # mangle from owner's perspective
$fx->Delegate->{Explicit} = 1; # implicit name mangling
$fx->Delegate->{Dynamic} = 1; # enable dynamic interception
}

# Create IM files.
$IM->Create();
</source>

Note in the above script how the IM name and output directory were defined. In this case, all three files are created in the same directory as the STRIDE workspace. The resulting Intercept Module file must then be compiled and built with the rest of your target code.

== Activating the Intercept Module ==
=== Compiling the IM ===
To compile the IM, you must define the macro '''srIMON''' when you compile the IM.c file or any file that includes one of the headers. This "turns on" the intercept feature. For example:
cc -c -IC:\STRIDE\inc -DsrIMON MyProjectIM.c

Notice that the IM.c and IMEntry.h files reference header files in the STRIDE installation directory. The build must include this directory when compiling either of these files. The Delegate (IM.h) header file does not have any dependencies on this directory.

=== IM Resource Requirements ===
The Intercept Module is usually run as a separate task, and therefore has some
resource requirements that are in addition to those of the [[Integrating the STRIDE Runtime into a Target|Runtime]] and the [[Integrating the Platform Abstract Layer (PAL)|PAL]]. One of these is the task resource itself. Another is space for the task stack.

The required task stack size if difficult to predict since it is dependent on the underlying system and on the data that is passed through function arguments. A stack size between 2-4K would be a good starting point.

=== Starting the IMStubRead thread ===
The IM must be started ''after'' the Runtime and Transport have been initialized, but before any intercepted calls can be made. Failure to do this before making an intercepted call can crash or hang the target.

This code snippet, based on using the POSIX call pthread_create() to start a task (your OS may use a different call), demonstrates how to initialize the PAL and the Runtime, start the IM, then become the Runtime message processing loop. Note that this code assumes that it will become the Runtime thread's message processing loop (because srThread() will never return unless thread is stopped or killed). The comments note that this could instead create a second task for the Runtime and return.

This code snippet also handles termination signals based on POSIX APIs in signal.h in order to cleanly shut down the target and clean up resources. This is required if multi-process target is enabled in the Runtime, especially for Linux OS.

<source lang="c">
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>

/* STRIDE runtime includes */
#include <sr.h>
/* The OS PAL configuration file */
#include <palcfg.h>

/* Intercept Module includes */
#include "MyProjectIMEntry.h"

extern palBOOL palInit();
extern palBOOL palUninit();

/* The IM message handler ("MyProject" is the IM name) */
extern void MyProjectIMStubThread();

/* Thread handling */
typedef void (*_ThreadFunc_t)( void );

void* _threadFunc(void* param)
{
if (param)
{
_ThreadFunc_t proc = (_ThreadFunc_t)param;
proc();
}

return NULL;
}

static pthread_t _threads[15] = {0};

/* Termination signals handling */
void _cleanup(void)
{
int i = 0;

fprintf (stdout, "TestAgent exiting.\n");
for (i = 0; i < sizeof(_threads)/sizeof(_threads[0]); i++)
{
if (_threads[i] != 0)
{
palNotify(_threads[i], palSTOP_EVENT);
pthread_join(_threads[i], NULL);
pthread_detach(_threads[i]);
}
}

srUninit();
palUninit();
}

volatile sig_atomic_t termination_in_progress = 0;

void _terminate(int sig)
{
/* Since this handler is established for more than one kind of signal,
it might still get invoked recursively by delivery of some other kind
of signal. Use a static variable to keep track of that. */
if (termination_in_progress)
raise (sig);
termination_in_progress = 1;

/* cleanup */
_cleanup();

/* Now reraise the signal. We reactivate the signal's
default handling, which is to terminate the process.
We could just call exit or abort,
but reraising the signal sets the return status
from the process correctly. */
signal (sig, SIG_DFL);
raise (sig);
}

/* A function to start the STRIDE threads */
void STRIDEstartup()
{
int i = 0;

/* Set termination signals handling */
(void) signal(SIGABRT, _terminate);
(void) signal(SIGTERM, _terminate);
(void) signal(SIGINT, _terminate);
(void) signal(SIGQUIT, _terminate);
(void) signal(SIGHUP, _terminate);

/* Initialize PAL. It will return palFALSE if it fails
(This will open the transport to the host) */
if (palInit() == palFALSE) {
palLog(palLOG_LEVEL_ERROR, "PAL Initialization failed.");
palLog(palLOG_LEVEL_ERROR, "Quitting.");
exit(1);
}

/* Initialize Runtime */
if (srInit() != srOK)
{
palLog(palLOG_LEVEL_ERROR, "srInit failed.");
exit(1);
}

/* Start the Runtime thread */
pthread_create (&_threads[i++], NULL, _threadFunc, (void*)srThread);

/* Start the IM stub read thread */
pthread_create (&_threads[i++], NULL, _threadFunc, (void*)MyProjectIMStubThread);

_cleanup();

return 0;
}
</source>

[[Category: Intercept Modules]]

STRIDE 3.0.01xx

2008-06-18T20:04:47Z

Shamr: /* Runtime */ SCR 8636

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime (Beta 1)==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
* In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

==Runtime (Beta 2)==
* A new public routine for Runtime Thread exit point, srThreadUninit(), has been added to sr.h & srthread.c.
* Fixed a compiler warning in srmem.c.

*'' The following Runtime files have been modified:
sr.h
srcfg.h
srmem.c
srthread.c

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

* If target Test Classes and Test Functions are used, change the signature to include test label in srTestCaseAddComment() and AddComment() APIs.

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-18T19:56:38Z

Shamr: /* Runtime */ SCR 8891

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
* In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

* If target Test Classes and Test Functions are used, change the signature to include test label in srTestCaseAddComment() and AddComment() APIs.

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-18T19:53:01Z

Shamr: /* Runtime */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.
* In target Test Classes and Test Functions, added capability to specify the comment label in srTestCaseAddComment() and AddComment() APIs.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtest.c
srtest.cpp
srtest.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

Studio:After installing the STRIDE Runtime, what are my configuration settings?

2008-06-17T22:44:28Z

Shamr: updated

The Runtime configuration settings are described in the '''srcfg.h''' file, located in '''C:\STRIDE\runtime'''. (This file is installed only when the runtime files are requested as part of the STRIDE install.)

If you have made changes to the default settings, you should avoid overwriting the file.

The default configuration settings are as follows: 
<Source lang="c">

/* Messaging */
#define srCFG_TOTAL_STIDS 16 /* number of STRIDE Transact IDs in system */
#define srCFG_TOTAL_SUBCS 20 /* total number of subscribers at one time */
#define srCFG_TOTAL_PTRS 30 /* total number of pointer entries */
#define srCFG_SUID_TABLE_TYPE 1 /* 1 = Search based, 0 = Index based */
#define srCFG_SUID_TABLE_SIZE 225 /* number of SUID Table entries */
#define srCFG_TOTAL_SUIDS_QUED 50 /* total number of SUIDS queued at one time */
#define srCFG_STID_NAME_SIZE 15 /* max size of a STRIDE Transact ID name */
#define srCFG_SUID_OVERRIDE 1 /* override (1 = enabled, 0 = disabled) */
#define srCFG_SUID_OVERRIDE_STORAGE 0 /* override registration storage allocation */

/* Tracing */
#define srCFG_TRACING_ENABLED 1 /* tracing enabled (1=enabled, 0=disabled) */
#define srCFG_TOTAL_TRACING_MEMORY 4096 /* number of bytes allocated for tracing */
#define srCFG_TRACEBUFFER_MAX_SIZE 1000 /* max size of a single trace buffer */
#define srCFG_TRACEBUFFER_WAKEUP_TIME 100 /* number of milliseconds between sending */

/* Time Stamp */
#define srCFG_TIMESTAMP_UNITS 1 /* 0 = microsecs, 1 = Millisecs, 2 = secs */
#define srCFG_TIMESTAMP_DURATION 1 /* number of TimeStamp Units per Tick */

/* Auxiliary Data */
#define srCFG_AUXDATA 0 /* Use Auxiliary Data (1=Yes, 0=No) */

/* Transport Settings */
#define srCFG_MAX_TRANSPORT_UNIT 2048 /* 0=No Fragmentation, Number=Fragment Size */
#define srCFG_DEFAULT_TRANSPORT_STATE 1 /* 1=Transport Ready, 0=Transport Not Ready */

/* Connection Settings */
#define srCFG_CONNECTION_TIMEOUT 5000 /* connection timeout (1=enabled, 0=disabled)*/

/* RFC (Remote Function Call) Settings */
#define srCFG_RFC_ENABLED 1 /* RFC enabled (1=Yes, 0=No) */
#define srCFG_RFC_PMM 1 /* RFC pool memory management */
/* - (0=None, 1=Recovery, 2=Reallocation) */
#define srCFG_RFC_PAL_PMM 0 /* PAL pool memory management (1=Yes, 0=No) */

/* Memory Management Settings */
#define srCFG_MEMORY_MANAGEMENT 0 /* memory management (1=enabled, 0=disabled) */

#if srCFG_MEMORY_MANAGEMENT
#define srCFG_MEMORY_BLOCK_SIZE_SMALL 30 /* size of a small memory block */
#define srCFG_MEMORY_BLOCK_SIZE_MEDIUM 100 /* size of a medium memory block */
#define srCFG_MEMORY_BLOCK_SIZE_LARGE 500 /* size of a large memory block */
#define srCFG_MEMORY_BLOCK_SIZE_LARGE2 1000 /* size of a large2 memory block */
#define srCFG_MEMORY_BLOCK_SIZE_LARGE3 10000 /* size of a large3 memory block */
#define srCFG_MEMORY_BLOCK_SIZE_HUGE 0xFFFF /* size of a huge memory block */

#define srCFG_MEMORY_BLOCK_MAX_SMALL 5000 /* max number of small memory blocks */
#define srCFG_MEMORY_BLOCK_MAX_MEDIUM 250 /* max number of medium memory blocks */
#define srCFG_MEMORY_BLOCK_MAX_LARGE 250 /* max number of large memory blocks */
#define srCFG_MEMORY_BLOCK_MAX_LARGE2 100 /* max number of large2 memory blocks */
#define srCFG_MEMORY_BLOCK_MAX_LARGE3 50 /* max number of large3 memory blocks */
#define srCFG_MEMORY_BLOCK_MAX_HUGE 50 /* max number of huge memory blocks */
#endif /* srCFG_MEMORY_MANAGEMENT */

/* Multi-Process Settings */
#define srCFG_MULTI_PROC_TARGET 0 /* multi-process target (1=enabled, 0=disabled)*/

/* Variable Arguments */
#define srCFG_VAR_ARGS_ENABLED 1 /* variable arguments (1=enabled, 0=disabled)*/

/* Debug Settings */
#define srCFG_ERROR_CHECK_LEVEL 2 /* levels(0,1,2), none(0) */

</Source>

[[Category:STRIDE Runtime]]
[[Category:STRIDE Runtime Configuration]]

STRIDE 3.0.01xx

2008-06-17T17:53:56Z

Shamr: /* Migration to 2.1.0301 */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 3.0.0101=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

Main Page

2008-06-17T17:52:14Z

Shamr:

Welcome to the S2 Technologies™ '''STRIDE'''™''' Support Wiki'''.

All contributions are welcome and encouraged. Please read '''[[Help:How to add a topic|How to add a topic]]''' and '''[[Help:Contents|Help]]''' pages for guidelines and instructions on editing. You must '''[[Special:Userlogin|log in or create an account]]''' before you can edit a page.

Please select a topic or category heading below, or enter a search string in the Search field to the left.

----

{|
{|
| valign="top" |
{|cellpadding="2" cellspacing="5" style="vertical-align:top;border:1px solid #bcc"
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Deploying STRIDE|Deploying STRIDE]]
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Test Utilities|Test Utilities]]
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Frameworks|Frameworks]]
|-
| valign="top"|
* [[Installing STRIDE]]
* [[Integrating STRIDE]]
* [[Verifying Installation]]
* [[Proof of Concept]]
* [[Framework| Framework]]
* [[Training]]
| valign="top"|
* [[Host Apps]]
* [[Test Classes]]
* [[Test Functions]]
* [[Test Runners]]
* [[:Category:Components|Components]]
* [[Templates]]
* [[Other Utilities]]
| valign="top"|
* [[Using Frameworks]]
* [[Creating Frameworks]]
* [[Provided Frameworks]]
* [[Using Packages]]
* [[Creating Packages]]
* [[Provided Packages]]

|-
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Training|Training]]
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Application Notes|Application Notes]]
! style="margin:0;background:#cedff2;font-size:120%;font-weight:bold;border:1px solid #a3b0bf;text-align:left;color:#000;padding:0.2em 0.4em;" | [[:Category:Release Notes|Release Notes]]
|-
| valign="top" |
*[[Overview]]
*[[STRIDE Quick Start]]
*[[Target Test Code]]
*[[Interface Instrumentation]]
*[[Intercept Module Settings]]
*[[Test Scripts]]
| valign="top"|
<categorytree mode="all" hideroot="on">Application Notes</categorytree>


| valign="top"|
* [[STRIDE 2.1.00xx | STRIDE 2.1.00xx (D Street)]]
* [[STRIDE 2.1.0201 | STRIDE 2.1.02xx (Moonlight)]]
* [[STRIDE 3.0.0101 | STRIDE 3.0.01xx (StoneSteps)]]
|}
|}
|-

STRIDE 3.0.01xx

2008-06-17T17:51:26Z

Shamr: STRIDE 2.1.0301 moved to STRIDE 3.0.0101

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-17T17:48:49Z

Shamr: /* Runtime */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''3.0.0101''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-17T17:44:30Z

Shamr: /* Removed / Old Routines */

'''Release Notes'''

This page documents the changes in STRIDE version 3.0.0101 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

==Windows Off-Target SDK==
A new SDK for implemention of Off-Target applications on Windows has been packaged. It contains prebuild in a library (s2srWin.dll/lib) Windows PAL, Runtime, and GRS and a set of utility scripts.
The '''s2shostapphrt''' libriary that previously packaged the Host Runtime has been removed. Building Windows applications using the Host Runtime is not supported anymore.
The '''s2shostapptrt''' libriary that previously packaged the Target Runtime has been removed.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Windows Applications using Windows Off-Target SDK==
* The new '''s2srwin.lib''' has public API, pulished in a header srwin.h, containing the following set of routines:
srWin_SetMaster() - Sets the application as the master and initializes the Stride Runtime thread. In a multi-process environment only one application should make this call.
srWin_AddThread() - Adds additional message processing threads to the application.
srWin_Run() - Starts the processing and will not return until it has been signaled via keyboard key or CTRL-C.
srWin_SetPortTCP() - Overrides the TCP port number (default: 8000) to which the application will bind for the purpose of accepting connections.
srWin_SetPortSerial() - Overrides the COM port number (default: 1) to which the application will bind for the purpose of accepting connections.
* Existing Host Apps developed against the old hostapphrt and hostapptrt libraries should be updated to as follows:
** replace the include of hostapp.h with include of srwin.h
** replace all calls to HostAppXXX() with srWin_XXX()
** call srWin_SetMaster() to start the runtime thred, srThread, before calling srWin_Run(). Within a multi-process target, only one process (the master) calls this routine.

STRIDE 3.0.01xx

2008-06-12T23:38:53Z

Shamr: SCR 8891 initial

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen() - Open/create memory segment
palMemSegmentClose() - Close memory segment

* '''Named Mutexes'''
palMutexInit() - Initialize a mutex object
palMutexDestroy() - Destroy a mutex object
palMutexLock() - Lock a mutex object
palMutexUnlock() - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId() - Get current thread Id
palGetProcessId() - Get current process Id
palSleep() - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog() - Logging utility

===Updated Routines===
* Function signatures and functionalities of palWait() & palNotify() have been updated.

palWait() - now takes in an in/out pointer for events notification
palNotify() - mail box Id has been updated to notify any event including mail box Ids.

* Function signatures of palMemAlloc() & palMemFree() have been updated.

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Modules===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support event notifications and in case of multi-process target is enabled, sharing of the synchronization objects among multiple processors.

* If your PAL uses ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

* Edit '''srcfg.h''' file to configure the new target connection timeout setting (srCFG_CONNECTION_TIMEOUT).

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, '''HostAppSetMaster()''', has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-06-05T23:04:38Z

Shamr:

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=

==Build Tools==
A set of new command line build tools has been implemented:
* '''Stride compiler'''
* '''Stride database binder'''
* '''Stride instrumantation generator'''
These utilities has been ported for Windows and Linux. Using them would allow seamless integration with "make" like build environment.

==Runtime/PAL==
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of memory management and shared memory, protecting using named Mutex objects, synchronization of multiple processors and multiple threads, and usage of current process and thread IDs.

===Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=

==PAL==

===Memory Management===
To support multi-process target, memory management support for dynamic, configurable, and internal static memory has been implemented in Runtime. Runtime makes PAL calls to acquire memory segments and manages the memory according to runtime configurations set by user. In case of multi-process target is enabled, these memory will be shared among multiple applications, and PAL should implement shared memory.

===Protection using Mutex===
Runtime now uses named mutex objects to protect critical data from multiple and simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. Runtime makes PAL calls to obtain and control mutex objects.

===New Routines===
* '''Memory Management'''
In case of multi-process target, recommended approach is to use Memory-Mapped Files to implement memory segments.
palMemSegmentOpen - Open/create memory segment
palMemSegmentClose - Close memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

===Removed Module===
S2Mem - Memory module provided as part of PAL has been removed. If native OS does not support dynamic memory, Runtime's memory management module ''srMem'' can be used instead of ''S2Mem''.

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* A new module, srMem, for Memory Management has been added. Its new routines, _srMem_Allocate() & _srMem_Free(), will be used in PAL's palMemAlloc() & palMemFree() in case of multi-process target is enabled.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palMemSegmentOpen() & palMemSegmentClose(). In case of multi-process target, these routines should implement shared memory using memory-mapped files.

* Runtime now can manage dynamic, configurable, and internal static memory. In case of multi-process target, update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free(). In case of single-process target, you can simply allocate dynamic memory according to your Operating System. If you are upgrading, you can simply leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* If your PAL was using ''S2Mem'' routines for dynamic memory, you should use new Runtime module ''srMem''. Update palMemAlloc() to call _srMem_Allocate() and palMemFree() to call _srMem_Free().

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the new memory management (srCFG_MEMORY_MANAGEMENT) and multi-process target (srCFG_MULTI_PROC_TARGET) settings. By default, memory management and multi-process target are disabled. If you enable multi-process target you also need to enable memory management and configure the sizes and the maximum number of memory blocks. New Runtime module ''srMem'' uses these configurations to allocate and manage memory segments.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, '''HostAppSetMaster()''', has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-29T19:25:54Z

Shamr: /* Runtime */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime Version '''3.00'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the shared memory management. By default, shared memory is disabled. If you enable shared memory, you also need to configure the sizes and maximum number of shared memory blocks. New Runtime module ''srmem'' uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, '''HostAppSetMaster()''', has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-29T19:21:24Z

Shamr: /* Host Apps using Target Runtime lib s2shostapptrt */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime versions '''3.0'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the shared memory management. By default, shared memory is disabled. If you enable shared memory, you also need to configure the sizes and maximum number of shared memory blocks. New Runtime module ''srmem'' uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, '''HostAppSetMaster()''', has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-29T19:20:51Z

Shamr: /* Runtime */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime versions '''3.0'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit '''srcfg.h''' file to configure the shared memory management. By default, shared memory is disabled. If you enable shared memory, you also need to configure the sizes and maximum number of shared memory blocks. New Runtime module ''srmem'' uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, HostAppSetMaster(), has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-29T19:19:47Z

Shamr: /* Runtime */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime versions '''3.0'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit srcfg.h file to configure the shared memory management. By default, shared memory is disabled. If you enable shared memory, you also need to configure the sizes and maximum number of shared memory blocks. New Runtime module ''srmem'' uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, HostAppSetMaster(), has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-28T23:45:22Z

Shamr: /* PAL */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime versions '''3.0'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to '''''Platform Abstraction Layer (PAL) Specification''''' for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit srcfg.h file to configure the shared memory management. By default, shared memory is disabled. If you decide to enable shared memory, you also need to configure the sizes and max number of memory blocks. New runtime module srmem uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, HostAppSetMaster(), has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.

STRIDE 3.0.01xx

2008-05-28T23:44:26Z

Shamr: /* PAL */

'''Release Notes'''

This page documents the changes in STRIDE version 2.1.0301 (code name ''StoneSteps'').

Please review this information before upgrading from an earlier version.

=What's New=
Based on customer requirements, in this release we have made significant changes to [[Integrating STRIDE#The STRIDE Runtime|STRIDE Runtime]] and [[Integrating STRIDE#The Platform Abstraction Layer (PAL)|PAL]].

===Multi-Process Targets / Shared Memory===
New routines and support have been added to Runtime and PAL to support multi-process target. Changes include implementation of shared memory, protecting using named Mutex objects, synchronization of multiple processors ands multiple threads, and usage of current process and thread IDs.

===Runtime Logging (Optional)===
Runtime and PAL use a logging routine that can optionally be implemented in PAL.

=Change Details=
===Shared Memory===
To support multi-process target, shared memory support for dynamic and static pool memory has been implemented in Runtime. Runtime makes PAL calls to acquire shared memory and manages the memory according to runtime configurations set by user.

===Protection using Mutex===
Runtime now uses named mutex objects to protect shared resources between multiple processors and multiple threads. Runtime makes PAL calls to obtain and control mutex objects.

==PAL==

===New Routines===
* '''Shared Memory Management'''
Recommended approach is to use Memory-Mapped Files to implement shared memory.
palOpenSharedMem - Open/Create shared memory segment
palCloseSharedMem - Close shared memory segment

* '''Named Mutexes'''
palMutexInit - Initialize a mutex object
palMutexDestroy - Destroy a mutex object
palMutexLock - Lock a mutex object
palMutexUnlock - Unlock a mutex object

* '''Task Synchronization'''
palGetThreadId - Get current thread Id
palGetProcessId - Get current process Id
palSleep - Suspend the execution of the current thread

* '''Logging'''
This is optional.
palLog - Logging utility

===Updated Routines===
Function signatures of palMemAlloc() & palMemFree() have been updated.
palMemAlloc - now returns a void pointer
palMemFree - now takes in a void pointer as input

===Removed / Old Routines===
palProtect
palUnprotect
palCriticalErr

==Runtime==

* STRIDE Host Release '''2.1.0301''' is compatible with the Runtime versions '''3.0'''.
* To support multi-process target, significant changes have been made to runtime.
* A new public routine, srUninit(), has been added to sr.h & srapi.c.
* To use in PAL for shared dynamic pool memory, new routines, _srMem_Allocate() & _srMem_Free(), have been added as part of new runtime files srmem.h & srmem.c.
* Calls to palProtect() & palUnprotect() have been replaced by new routines _srProtect() & _srUnprotect(), in which the implementation uses its own mutex object that calls PAL's mutex routines.

*'' The following Runtime files have been modified:
sr.h
srapi.c
srconn.c
srconn.h
srib.c
srib.h
sribtr.c
sribtr.h
srmsgptr.c
srmsgptr.h
srmsgque.c
srmsgque.h
srmsgrt.c
srmsgrt.h
srmsgsub.c
srmsgsub.h
srstid.c
srstid.h
srsuid.c
srsuid.h
srtime.c
srtime.h

*'' The following Runtime files have been added:
srmem.c
srmem.h

=Migration to 2.1.0301=
Recommended steps for migration from a previous version:

==PAL==
Please refer to Platform Abstraction Layer (PAL) Specification for detailed information on new APIs. You may also refer to Linux implementation of PAL, which has been updated with new routines.

* Implement new shared memory routines, palOpenSharedMem() & palCloseSharedMem(), using memory-mapped files.

* Runtime now manages shared dynamic pool memory. Update palMemAlloc() to simply call _srMem_Allocate() and palMemFree() to simply call _srMem_Free() for the shared memory case. For the non-shared case, you can leave the current implementation as it is.

* Implement new mutex routines, palMutexInit(), palMutexDestroy(), palMutexLock() & palMutexUnlock, to handle any named mutex objects. It is recommended to implement a separate code for shared memory case if it is necessary.

* Remove old routines palProtect(), palUnprotect() and palCriticalErr().

* Implement new routines palGetThreadId() and palGetProcessId().

* Implement new routine palSleep().

* Update synchronization routines, palCreateNID(), palDeleteNID(), palWait() & palNotify(), to support sharing of the synchronization objects among multiple processors if shared memory management is enabled.

* Optionally, implement new routine palLog() as a logging utility for PAL and Runtime.

==Runtime==
* Edit srcfg.h file to configure the shared memory management. By default, shared memory is disabled. If you decide to enable shared memory, you also need to configure the sizes and max number of memory blocks. New runtime module srmem uses these configurations to allocate and manage shared dynamic pool memory.

==Host Apps using Target Runtime lib s2shostapptrt==
* A new routine, HostAppSetMaster(), has been added to s2shostapptrt library. This routine needs to be called from the application that should be starting the runtime thread, srThread, before calling HostAppRun(). Usually within a multi-process target, the ''master'' process or the ''daemon'' calls this routine.