STRIDE Wiki - User contributions [en]

STRIDE Runtime

2009-01-05T19:46:33Z

Andreo: /* Logging Services */

== 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.

Refer to [[Target Integration]] on how to integrate the STRIDE Runtime in your environment.

== 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 [[Media: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 [[Media:s2sTransport.pdf|STRIDE Host Runtime Transport Specification]] document for a more detailed description of the Host Transport Services.

=== 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.

== The Runtime Developer's Guide ==

Click [[Media:s2sRuntime.pdf|here]] to view the STRIDE Runtime Developer's Guide PDF document.

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

The Runtime Test Services (RTS) 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. 
A set of C-based APIs work equally well from '''C Test Functions''' and '''C++ Test Classes'''. Optionally, you can derive your C++ test classes from the '''STRIDE Test Base Class (srTest)''' and 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_test_flist or scl_test_cclass pragmas, and executed from the host. C-based Runtime Test Services APIs are available for use in test functions. 

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. 

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 [[Media:s2sRuntime.pdf|STRIDE 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.
*'''Messaging''' - These routines can be used to send and receive messages for logging or any other debugging purposes.
**'''srBroadcast()''': used to “broadcast” information to one or more subscribers. Each subscriber receives its own copy of the message or pointer, depending on the attributes of the payload. If there are multiple subscribers on a remote platform only one copy of the response is transmitted across the link. If there are no subscribers then the routine simply returns.
**'''srSubscribe()''': used to subscribe to a Broadcast message sent using srBroadcast. There has to be at least one subscriber for a broadcast message to be sent.

These services use the '''''sr.h''''' header file. Please refer to Chapter 3 of the [[Media:s2sRuntime.pdf|STRIDE Runtime Developer's Guide]] for more information on these APIs.

== 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.

== Other Runtime components ==

*[[GRS|Generic RTOS Services (GRS)]]
*[[SLAP|Simplified Link Application Protocol (SLAP)]]

[[Category: Reference]]

Category:SDKs

2008-12-30T19:48:56Z

Andreo:

The following topics describe our SDKs. <categorytree style="background-color: ghostwhite" mode="pages">
SDKs
</categorytree>

[[Category: Reference]]

Posix SDK

2008-12-30T19:47:19Z

Andreo: /* Target Makefile */

== Introduction ==

The Linux SDK is a platform-specific package that contains the STRIDE Runtime source and [[Target_Integration#The_Platform_Abstraction_Layer_.28PAL.29|PAL]] implementation, along with integration tools to build a stride library and a strideDaemon application. It is intended for this article to be used as a reference. '''For step-by-step instructions on using the contents of this package to create a test application that establishes messaging between the host and target device, please refer to the [[Linux Quickstart]] guide.'''

==Target Makefile==

The SDK makefile provides targets for building the [[Runtime Reference|STRIDE Runtime]] library and two executable applications - a strideDaemon (for a [[#Multiprocess_Application_Integration|multiprocess]] application environment), and an installTestApp (for running the STRIDE installation tests - see [[Verifying_Installation#Using_a_Platform_SDK|Using a Platform SDK]] for more information).

The default make target builds the STRIDE Runtime library and strideDaemon executable. When a single process runtime library is specified (see RTSINGLEPROC below), the strideDaemon is omitted. To build the installation test application, specify the '''installtest''' make target.

The '''installtest''' target compiles SCL source markup present in the Runtime source and therefore requires that the [[Build Tools]] be installed on your system and in your executable search path. Refer to the [[Linux Quickstart]] guide for an example how to build and run the install tests or the [[Linux_Baseline_Application_Integration|Linux Baseline Application Integration]] on how to integrate the installation test in a current code baseline.

===Configuration===

The behavior of the makefile can be affected by setting certain make variable parameters. For example, the following make invocation will change the value of the TOOLCHAIN and DEBUG variables when making:

make TOOLCHAIN=arm DEBUG=1

The following variable are intended to be specified or overridden as needed:

====TOOLCHAIN====

The default compiler toolchain when TOOLCHAIN is set to '''i386''' is gcc/g++/ar, which are assumed to be in your path. For any other TOOLCHAIN value, the toolchain tools are $(TOOLCHAIN)-linux-gcc/g++/ar where $(TOOLCHAIN) is replaced by the specified TOOLCHAIN setting. If your toolchain does not fit this pattern, you will need to modify the makefile or explicitly override values for CC, CPP, and AR.

====LIBRARYTYPE====

The default behavior of the makefile is to build the STRIDE Runtime as a static library. If you prefer a shared library, set this value to '.so'.

====DEBUG====

The default configuration compiles with optimization and NDEBUG defined. If you prefer debuggable binaries, set this value to 1.

====RTSINGLEPROC====

The default configuration compiles the runtime library with multiprocess support. If you don't want (or can't support) multiprocess functionality, you can disable this by explicitly setting this value to 1.

====STANDALONE_INSTALLTEST====

The default configuration, set to '''0''', builds the installTestApp as a [[#Multiprocess_Application_Integration|multiprocess]] application. When set to '''1''' the installTestApp is built as a [[#Standalone_Application_Integration|standalone]] application. 
The STANDALONE_INSTALLTEST variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is '''1''' and STANDALONE_INSTALLTEST is '''0''', this is an invalid combination and STANDALONE_INSTALLTEST will automatically be set to '''1'''.

====S2SCOPTS====

The STRIDE build process that produces the database and [[Intercept Module]] for the installation tests relies on target settings. These settings are passed as options to the stride compiler and are most conveniently stored in an options file. We provide a default options file with target settings that are appropriate for x86 Linux targets with GNU compilers -- this file is ''SDK/Linux/settings/stride.s2scompile'' in the SDK distribution.

We recommend that you make a copy of this file and adjust the settings as appropriate for your target. You can then set this variable - '''S2SCOPTS''' to the path to your settings file. This will cause the make process to use the specified target settings options instead of the default one provided in the SDK. This same settings file should ultimately be used for the STRIDE build integration with your application source code.

===S2 Build Flags===
The target Makefile sets the following Build Tool flags:

S2_BIND_FLAGS = --starting_suid=7000
S2_IM_FLAGS = --disable_access_class

The [[S2sbind#Options|s2sbind]] and [[S2sinstrument#Options|s2sinstrument]] flags are combined so that the test application only registers for test message IDs that are created in a higher range so that it doesn't conflict with other application processes.

==Target API (stride.h)==

The Linux SDK provides a simplified application interface for initializing the STRIDE subsystem and starting STRIDE messaging and IM threads. The API includes the following routines:

===srBOOL strideInit(const strideIO_t * io)===

This function initializes the STRIDE subsystem. The IO configuration is passed in as an argument. If this argument is NULL, then the process will attempt to attach to an already running runtime application (daemon) using shared memory for IPC. THis function should only be called once per application.

===srBOOL strideUninit(void)===

Terminates any threads that have been started with this API and uninitializes the STRIDE subsystem.

===srBOOL strideCreateThread(strideThreadFunc_t entry, const srCHAR * name)===

Creates a thread to be managed by the STRIDE subsystem. Threads created using this routine will be sent a palSTOP_EVENT notification (available from palWait) and should respond promptly to this event. The name parameter is used primarily for logging purposes.

===strideCreateIMThread(name)===

This is a macro that wraps the invocation of [[#strideCreateThread|strideCreateThread]] for intercept module entry point functions. Only the IM name must be provided.

===void strideExWaitForExit(void)===

This function can be called by the main application thread to block until a termination signal is received. Internally it uses the pause function to wait for signals to be delivered and then checks if termination has occurred.

===void strideExDaemonize(const char* lockFile, const char* runAs)===
This function is called by applications to deamonize the process. Both arguments are optional. The first argument specifies a lockfile path/name to use to insure that only one instance of the process is running. The second argument specifies a username to run as (setuid)

This function is optional - if you prefer to run your application as an interactive console application, do not call this function. If you are running as a daemon, we recommend that you have the PAL_LOG_TO_SYSLOG macro defined (in palcfg.h) so that PAL log messages will be sent to the syslog (this is default setting currently).

==Target Integration==

Here are a few examples of how to integrate the stride API into your application.

'''Note:''' the following code assumes that the intercept module was generated with a name of ''myintercept''. Change all references to that name in your code to the chosen intercept module name.

===Standalone Application Integration===

The following code demonstrates how to integrate your application with the STRIDE Runtime. Your application might require other logic at startup - you can integrate the following calls according to your needs. Note that this code initializes the STRIDE subsystem and assumes a single standalone process that creates the STRIDE system threads as well as application threads. The call to strideExDaemonize is optional here - remove it if you don't want you application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
strideIO_t io = {strideDEFAULT};
if (strideInit(&io) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

===Multiprocess Application Integration===

This code demonstrates how to integrate your application with the STRIDE Runtime in multiprocess mode. In this mode, the pre-packaged strideDaemon runs simultaneously with the application and provides the STRIDE IO and runtime thread initialization. The host communicates with the application process through the strideDaemon (or another STRIDE IO process). In this sample, the only difference with the preceding sample is the call to strideInit which, in this case, specifies no IO parameters which indicates to the API that the communication and runtime threads should not be started. As before, the call to strideExDaemonize is optional here - remove it if you don't want your application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
if (strideInit(NULL) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

==Linux PAL==

===PAL Configuration (palcfg.h)===
The following parameters can be configured in ''palcfg.h'' to effect the behavior of the compiled pal source files.

; PAL_USE_SERIAL_TRANSPORT : if defined, serial communication support is enabled.
; PAL_USE_TCPIP_TRANSPORT : if defined, sockets-based communication support is enabled.
; PAL_DEFAULT_DEVICE_NAME : default IO device to use.
; PAL_DEFAULT_TCP_PORT : default port for TCP communication.
; PAL_DEFAULT_SERIAL_PORT : default COM port to use for serial communication.
; PAL_DEFAULT_SERIAL_BAUDRATE : default baud rate for serial communication.
; PAL_DEFAULT_SERIAL_MODE : default data/parity/stop settings for serial communication.
; PAL_USE_POSIX_CLOCK_GETTIME or PAL_USE_GETTIMEOFDAY : indicates the time of day clock to use.
; PAL_TIMER_PERIOD : this is the fire interval for the STRIDE Runtime master timer, in milliseconds.
; PAL_MAX_THREADS : max STRIDE integrated threads that can be managed by the STRIDE API.
; PAL_MAX_TIMERS : max STRIDE timers that can be active in the system.
; PAL_USE_POSIX_TIMER or PAL_USE_INTERVAL_TIMER : indicates the timer type to use.
; PAL_CLOCKID : indicates the type of POSIX clock to use
; PAL_DELIVER_TIMER_BY_THREAD or PAL_DELIVER_TIMER_BY_SIGNAL : specify how POSIX timer signals are delivered.
; PAL_TIMER_SIGNAL_TYPE : define which signal to use for timer delivery.
; PAL_LOG_TO_SYSLOG : palLog messages will be sent to syslog if this is defined; to stdout/stderr otherwise.
; PAL_SHM_PATH : the path to use for shared memory files. Only needed if multiprocess support is enabled in srcfg.h.

[[Category: SDKs]]

Posix SDK

2008-12-30T19:46:32Z

Andreo: /* Target Makefile */

== Introduction ==

The Linux SDK is a platform-specific package that contains the STRIDE Runtime source and [[Target_Integration#The_Platform_Abstraction_Layer_.28PAL.29|PAL]] implementation, along with integration tools to build a stride library and a strideDaemon application. It is intended for this article to be used as a reference. '''For step-by-step instructions on using the contents of this package to create a test application that establishes messaging between the host and target device, please refer to the [[Linux Quickstart]] guide.'''

==Target Makefile==

The SDK makefile provides targets for building the [[Runtime Reference|STRIDE Runtime]] library and two executable applications - a strideDaemon (for a [[#Multiprocess_Application_Integration|multiprocess]] application environment), and an installTestApp (for running the STRIDE installation tests - see [[Verifying_Installation#Using_a_Platform_SDK|Using a Platform SDK]] for more information).

The default make target builds the STRIDE Runtime library and strideDaemon executable. When a single process runtime library is specified (see RTSINGLEPROC below), the strideDaemon is omitted. To build the installation test application, specify the '''installtest''' make target.

The '''installtest''' target compiles SCL source markup present in the Runtime source and therefore requires that the [[Build Tools]] be installed on your system and in your executable search path. Refer to the [[Linux Quickstart]] guide for an example how to build and run the install tests or the [[Linux_Baseline_Application_Integration]] on how to integrate the installation test in a current code baseline.

===Configuration===

The behavior of the makefile can be affected by setting certain make variable parameters. For example, the following make invocation will change the value of the TOOLCHAIN and DEBUG variables when making:

make TOOLCHAIN=arm DEBUG=1

The following variable are intended to be specified or overridden as needed:

====TOOLCHAIN====

The default compiler toolchain when TOOLCHAIN is set to '''i386''' is gcc/g++/ar, which are assumed to be in your path. For any other TOOLCHAIN value, the toolchain tools are $(TOOLCHAIN)-linux-gcc/g++/ar where $(TOOLCHAIN) is replaced by the specified TOOLCHAIN setting. If your toolchain does not fit this pattern, you will need to modify the makefile or explicitly override values for CC, CPP, and AR.

====LIBRARYTYPE====

The default behavior of the makefile is to build the STRIDE Runtime as a static library. If you prefer a shared library, set this value to '.so'.

====DEBUG====

The default configuration compiles with optimization and NDEBUG defined. If you prefer debuggable binaries, set this value to 1.

====RTSINGLEPROC====

The default configuration compiles the runtime library with multiprocess support. If you don't want (or can't support) multiprocess functionality, you can disable this by explicitly setting this value to 1.

====STANDALONE_INSTALLTEST====

The default configuration, set to '''0''', builds the installTestApp as a [[#Multiprocess_Application_Integration|multiprocess]] application. When set to '''1''' the installTestApp is built as a [[#Standalone_Application_Integration|standalone]] application. 
The STANDALONE_INSTALLTEST variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is '''1''' and STANDALONE_INSTALLTEST is '''0''', this is an invalid combination and STANDALONE_INSTALLTEST will automatically be set to '''1'''.

====S2SCOPTS====

The STRIDE build process that produces the database and [[Intercept Module]] for the installation tests relies on target settings. These settings are passed as options to the stride compiler and are most conveniently stored in an options file. We provide a default options file with target settings that are appropriate for x86 Linux targets with GNU compilers -- this file is ''SDK/Linux/settings/stride.s2scompile'' in the SDK distribution.

We recommend that you make a copy of this file and adjust the settings as appropriate for your target. You can then set this variable - '''S2SCOPTS''' to the path to your settings file. This will cause the make process to use the specified target settings options instead of the default one provided in the SDK. This same settings file should ultimately be used for the STRIDE build integration with your application source code.

===S2 Build Flags===
The target Makefile sets the following Build Tool flags:

S2_BIND_FLAGS = --starting_suid=7000
S2_IM_FLAGS = --disable_access_class

The [[S2sbind#Options|s2sbind]] and [[S2sinstrument#Options|s2sinstrument]] flags are combined so that the test application only registers for test message IDs that are created in a higher range so that it doesn't conflict with other application processes.

==Target API (stride.h)==

The Linux SDK provides a simplified application interface for initializing the STRIDE subsystem and starting STRIDE messaging and IM threads. The API includes the following routines:

===srBOOL strideInit(const strideIO_t * io)===

This function initializes the STRIDE subsystem. The IO configuration is passed in as an argument. If this argument is NULL, then the process will attempt to attach to an already running runtime application (daemon) using shared memory for IPC. THis function should only be called once per application.

===srBOOL strideUninit(void)===

Terminates any threads that have been started with this API and uninitializes the STRIDE subsystem.

===srBOOL strideCreateThread(strideThreadFunc_t entry, const srCHAR * name)===

Creates a thread to be managed by the STRIDE subsystem. Threads created using this routine will be sent a palSTOP_EVENT notification (available from palWait) and should respond promptly to this event. The name parameter is used primarily for logging purposes.

===strideCreateIMThread(name)===

This is a macro that wraps the invocation of [[#strideCreateThread|strideCreateThread]] for intercept module entry point functions. Only the IM name must be provided.

===void strideExWaitForExit(void)===

This function can be called by the main application thread to block until a termination signal is received. Internally it uses the pause function to wait for signals to be delivered and then checks if termination has occurred.

===void strideExDaemonize(const char* lockFile, const char* runAs)===
This function is called by applications to deamonize the process. Both arguments are optional. The first argument specifies a lockfile path/name to use to insure that only one instance of the process is running. The second argument specifies a username to run as (setuid)

This function is optional - if you prefer to run your application as an interactive console application, do not call this function. If you are running as a daemon, we recommend that you have the PAL_LOG_TO_SYSLOG macro defined (in palcfg.h) so that PAL log messages will be sent to the syslog (this is default setting currently).

==Target Integration==

Here are a few examples of how to integrate the stride API into your application.

'''Note:''' the following code assumes that the intercept module was generated with a name of ''myintercept''. Change all references to that name in your code to the chosen intercept module name.

===Standalone Application Integration===

The following code demonstrates how to integrate your application with the STRIDE Runtime. Your application might require other logic at startup - you can integrate the following calls according to your needs. Note that this code initializes the STRIDE subsystem and assumes a single standalone process that creates the STRIDE system threads as well as application threads. The call to strideExDaemonize is optional here - remove it if you don't want you application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
strideIO_t io = {strideDEFAULT};
if (strideInit(&io) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

===Multiprocess Application Integration===

This code demonstrates how to integrate your application with the STRIDE Runtime in multiprocess mode. In this mode, the pre-packaged strideDaemon runs simultaneously with the application and provides the STRIDE IO and runtime thread initialization. The host communicates with the application process through the strideDaemon (or another STRIDE IO process). In this sample, the only difference with the preceding sample is the call to strideInit which, in this case, specifies no IO parameters which indicates to the API that the communication and runtime threads should not be started. As before, the call to strideExDaemonize is optional here - remove it if you don't want your application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
if (strideInit(NULL) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

==Linux PAL==

===PAL Configuration (palcfg.h)===
The following parameters can be configured in ''palcfg.h'' to effect the behavior of the compiled pal source files.

; PAL_USE_SERIAL_TRANSPORT : if defined, serial communication support is enabled.
; PAL_USE_TCPIP_TRANSPORT : if defined, sockets-based communication support is enabled.
; PAL_DEFAULT_DEVICE_NAME : default IO device to use.
; PAL_DEFAULT_TCP_PORT : default port for TCP communication.
; PAL_DEFAULT_SERIAL_PORT : default COM port to use for serial communication.
; PAL_DEFAULT_SERIAL_BAUDRATE : default baud rate for serial communication.
; PAL_DEFAULT_SERIAL_MODE : default data/parity/stop settings for serial communication.
; PAL_USE_POSIX_CLOCK_GETTIME or PAL_USE_GETTIMEOFDAY : indicates the time of day clock to use.
; PAL_TIMER_PERIOD : this is the fire interval for the STRIDE Runtime master timer, in milliseconds.
; PAL_MAX_THREADS : max STRIDE integrated threads that can be managed by the STRIDE API.
; PAL_MAX_TIMERS : max STRIDE timers that can be active in the system.
; PAL_USE_POSIX_TIMER or PAL_USE_INTERVAL_TIMER : indicates the timer type to use.
; PAL_CLOCKID : indicates the type of POSIX clock to use
; PAL_DELIVER_TIMER_BY_THREAD or PAL_DELIVER_TIMER_BY_SIGNAL : specify how POSIX timer signals are delivered.
; PAL_TIMER_SIGNAL_TYPE : define which signal to use for timer delivery.
; PAL_LOG_TO_SYSLOG : palLog messages will be sent to syslog if this is defined; to stdout/stderr otherwise.
; PAL_SHM_PATH : the path to use for shared memory files. Only needed if multiprocess support is enabled in srcfg.h.

[[Category: SDKs]]

Posix SDK

2008-12-30T19:44:32Z

Andreo: /* Introduction */

== Introduction ==

The Linux SDK is a platform-specific package that contains the STRIDE Runtime source and [[Target_Integration#The_Platform_Abstraction_Layer_.28PAL.29|PAL]] implementation, along with integration tools to build a stride library and a strideDaemon application. It is intended for this article to be used as a reference. '''For step-by-step instructions on using the contents of this package to create a test application that establishes messaging between the host and target device, please refer to the [[Linux Quickstart]] guide.'''

==Target Makefile==

The SDK makefile provides targets for building the [[Runtime Reference|STRIDE Runtime]] library and two executable applications - a strideDaemon (for a [[#Multiprocess_Application_Integration|multiprocess]] application environment), and an installTestApp (for running the STRIDE installation tests - see [[Verifying_Installation#Using_a_Platform_SDK|Using a Platform SDK]] for more information).

The default make target builds the STRIDE Runtime library and strideDaemon executable. When a single process runtime library is specified (see RTSINGLEPROC below), the strideDaemon is omitted. To build the installation test application, specify the '''installtest''' make target.

The '''installtest''' target compiles SCL source markup present in the Runtime source and therefore requires that the [[Build Tools]] be installed on your system and in your executable search path. Refer to the [[Linux Quickstart]] guide for an example how to build and run the install tests.

===Configuration===

The behavior of the makefile can be affected by setting certain make variable parameters. For example, the following make invocation will change the value of the TOOLCHAIN and DEBUG variables when making:

make TOOLCHAIN=arm DEBUG=1

The following variable are intended to be specified or overridden as needed:

====TOOLCHAIN====

The default compiler toolchain when TOOLCHAIN is set to '''i386''' is gcc/g++/ar, which are assumed to be in your path. For any other TOOLCHAIN value, the toolchain tools are $(TOOLCHAIN)-linux-gcc/g++/ar where $(TOOLCHAIN) is replaced by the specified TOOLCHAIN setting. If your toolchain does not fit this pattern, you will need to modify the makefile or explicitly override values for CC, CPP, and AR.

====LIBRARYTYPE====

The default behavior of the makefile is to build the STRIDE Runtime as a static library. If you prefer a shared library, set this value to '.so'.

====DEBUG====

The default configuration compiles with optimization and NDEBUG defined. If you prefer debuggable binaries, set this value to 1.

====RTSINGLEPROC====

The default configuration compiles the runtime library with multiprocess support. If you don't want (or can't support) multiprocess functionality, you can disable this by explicitly setting this value to 1.

====STANDALONE_INSTALLTEST====

The default configuration, set to '''0''', builds the installTestApp as a [[#Multiprocess_Application_Integration|multiprocess]] application. When set to '''1''' the installTestApp is built as a [[#Standalone_Application_Integration|standalone]] application. 
The STANDALONE_INSTALLTEST variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is '''1''' and STANDALONE_INSTALLTEST is '''0''', this is an invalid combination and STANDALONE_INSTALLTEST will automatically be set to '''1'''.

====S2SCOPTS====

The STRIDE build process that produces the database and [[Intercept Module]] for the installation tests relies on target settings. These settings are passed as options to the stride compiler and are most conveniently stored in an options file. We provide a default options file with target settings that are appropriate for x86 Linux targets with GNU compilers -- this file is ''SDK/Linux/settings/stride.s2scompile'' in the SDK distribution.

We recommend that you make a copy of this file and adjust the settings as appropriate for your target. You can then set this variable - '''S2SCOPTS''' to the path to your settings file. This will cause the make process to use the specified target settings options instead of the default one provided in the SDK. This same settings file should ultimately be used for the STRIDE build integration with your application source code.

===S2 Build Flags===
The target Makefile sets the following Build Tool flags:

S2_BIND_FLAGS = --starting_suid=7000
S2_IM_FLAGS = --disable_access_class

The [[S2sbind#Options|s2sbind]] and [[S2sinstrument#Options|s2sinstrument]] flags are combined so that the test application only registers for test message IDs that are created in a higher range so that it doesn't conflict with other application processes.

==Target API (stride.h)==

The Linux SDK provides a simplified application interface for initializing the STRIDE subsystem and starting STRIDE messaging and IM threads. The API includes the following routines:

===srBOOL strideInit(const strideIO_t * io)===

This function initializes the STRIDE subsystem. The IO configuration is passed in as an argument. If this argument is NULL, then the process will attempt to attach to an already running runtime application (daemon) using shared memory for IPC. THis function should only be called once per application.

===srBOOL strideUninit(void)===

Terminates any threads that have been started with this API and uninitializes the STRIDE subsystem.

===srBOOL strideCreateThread(strideThreadFunc_t entry, const srCHAR * name)===

Creates a thread to be managed by the STRIDE subsystem. Threads created using this routine will be sent a palSTOP_EVENT notification (available from palWait) and should respond promptly to this event. The name parameter is used primarily for logging purposes.

===strideCreateIMThread(name)===

This is a macro that wraps the invocation of [[#strideCreateThread|strideCreateThread]] for intercept module entry point functions. Only the IM name must be provided.

===void strideExWaitForExit(void)===

This function can be called by the main application thread to block until a termination signal is received. Internally it uses the pause function to wait for signals to be delivered and then checks if termination has occurred.

===void strideExDaemonize(const char* lockFile, const char* runAs)===
This function is called by applications to deamonize the process. Both arguments are optional. The first argument specifies a lockfile path/name to use to insure that only one instance of the process is running. The second argument specifies a username to run as (setuid)

This function is optional - if you prefer to run your application as an interactive console application, do not call this function. If you are running as a daemon, we recommend that you have the PAL_LOG_TO_SYSLOG macro defined (in palcfg.h) so that PAL log messages will be sent to the syslog (this is default setting currently).

==Target Integration==

Here are a few examples of how to integrate the stride API into your application.

'''Note:''' the following code assumes that the intercept module was generated with a name of ''myintercept''. Change all references to that name in your code to the chosen intercept module name.

===Standalone Application Integration===

The following code demonstrates how to integrate your application with the STRIDE Runtime. Your application might require other logic at startup - you can integrate the following calls according to your needs. Note that this code initializes the STRIDE subsystem and assumes a single standalone process that creates the STRIDE system threads as well as application threads. The call to strideExDaemonize is optional here - remove it if you don't want you application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
strideIO_t io = {strideDEFAULT};
if (strideInit(&io) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

===Multiprocess Application Integration===

This code demonstrates how to integrate your application with the STRIDE Runtime in multiprocess mode. In this mode, the pre-packaged strideDaemon runs simultaneously with the application and provides the STRIDE IO and runtime thread initialization. The host communicates with the application process through the strideDaemon (or another STRIDE IO process). In this sample, the only difference with the preceding sample is the call to strideInit which, in this case, specifies no IO parameters which indicates to the API that the communication and runtime threads should not be started. As before, the call to strideExDaemonize is optional here - remove it if you don't want your application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
if (strideInit(NULL) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

==Linux PAL==

===PAL Configuration (palcfg.h)===
The following parameters can be configured in ''palcfg.h'' to effect the behavior of the compiled pal source files.

; PAL_USE_SERIAL_TRANSPORT : if defined, serial communication support is enabled.
; PAL_USE_TCPIP_TRANSPORT : if defined, sockets-based communication support is enabled.
; PAL_DEFAULT_DEVICE_NAME : default IO device to use.
; PAL_DEFAULT_TCP_PORT : default port for TCP communication.
; PAL_DEFAULT_SERIAL_PORT : default COM port to use for serial communication.
; PAL_DEFAULT_SERIAL_BAUDRATE : default baud rate for serial communication.
; PAL_DEFAULT_SERIAL_MODE : default data/parity/stop settings for serial communication.
; PAL_USE_POSIX_CLOCK_GETTIME or PAL_USE_GETTIMEOFDAY : indicates the time of day clock to use.
; PAL_TIMER_PERIOD : this is the fire interval for the STRIDE Runtime master timer, in milliseconds.
; PAL_MAX_THREADS : max STRIDE integrated threads that can be managed by the STRIDE API.
; PAL_MAX_TIMERS : max STRIDE timers that can be active in the system.
; PAL_USE_POSIX_TIMER or PAL_USE_INTERVAL_TIMER : indicates the timer type to use.
; PAL_CLOCKID : indicates the type of POSIX clock to use
; PAL_DELIVER_TIMER_BY_THREAD or PAL_DELIVER_TIMER_BY_SIGNAL : specify how POSIX timer signals are delivered.
; PAL_TIMER_SIGNAL_TYPE : define which signal to use for timer delivery.
; PAL_LOG_TO_SYSLOG : palLog messages will be sent to syslog if this is defined; to stdout/stderr otherwise.
; PAL_SHM_PATH : the path to use for shared memory files. Only needed if multiprocess support is enabled in srcfg.h.

[[Category: SDKs]]

Posix SDK

2008-12-30T00:39:06Z

Andreo:

== Introduction ==

The Linux SDK is a platform-specific package that contains the STRIDE Runtime source and [[Target_Integration#The_Platform_Abstraction_Layer_.28PAL.29|PAL]] implementation, along with integration tools to build a stride library and a strideDaemon application. It is intended for this article to be used as a reference. For step-by-step instructions on using the contents of this package to create a test application that establishes messaging between the host and target device, please refer to the [[Linux Quickstart]] guide.

==Target Makefile==

The SDK makefile provides targets for building the [[Runtime Reference|STRIDE Runtime]] library and two executable applications - a strideDaemon (for a [[#Multiprocess_Application_Integration|multiprocess]] application environment), and an installTestApp (for running the STRIDE installation tests - see [[Verifying_Installation#Using_a_Platform_SDK|Using a Platform SDK]] for more information).

The default make target builds the STRIDE Runtime library and strideDaemon executable. When a single process runtime library is specified (see RTSINGLEPROC below), the strideDaemon is omitted. To build the installation test application, specify the '''installtest''' make target.

The '''installtest''' target compiles SCL source markup present in the Runtime source and therefore requires that the [[Build Tools]] be installed on your system and in your executable search path. Refer to the [[Linux Quickstart]] guide for an example how to build and run the install tests.

===Configuration===

The behavior of the makefile can be affected by setting certain make variable parameters. For example, the following make invocation will change the value of the TOOLCHAIN and DEBUG variables when making:

make TOOLCHAIN=arm DEBUG=1

The following variable are intended to be specified or overridden as needed:

====TOOLCHAIN====

The default compiler toolchain when TOOLCHAIN is set to '''i386''' is gcc/g++/ar, which are assumed to be in your path. For any other TOOLCHAIN value, the toolchain tools are $(TOOLCHAIN)-linux-gcc/g++/ar where $(TOOLCHAIN) is replaced by the specified TOOLCHAIN setting. If your toolchain does not fit this pattern, you will need to modify the makefile or explicitly override values for CC, CPP, and AR.

====LIBRARYTYPE====

The default behavior of the makefile is to build the STRIDE Runtime as a static library. If you prefer a shared library, set this value to '.so'.

====DEBUG====

The default configuration compiles with optimization and NDEBUG defined. If you prefer debuggable binaries, set this value to 1.

====RTSINGLEPROC====

The default configuration compiles the runtime library with multiprocess support. If you don't want (or can't support) multiprocess functionality, you can disable this by explicitly setting this value to 1.

====STANDALONE_INSTALLTEST====

The default configuration, set to '''0''', builds the installTestApp as a [[#Multiprocess_Application_Integration|multiprocess]] application. When set to '''1''' the installTestApp is built as a [[#Standalone_Application_Integration|standalone]] application. 
The STANDALONE_INSTALLTEST variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is '''1''' and STANDALONE_INSTALLTEST is '''0''', this is an invalid combination and STANDALONE_INSTALLTEST will automatically be set to '''1'''.

====S2SCOPTS====

The STRIDE build process that produces the database and [[Intercept Module]] for the installation tests relies on target settings. These settings are passed as options to the stride compiler and are most conveniently stored in an options file. We provide a default options file with target settings that are appropriate for x86 Linux targets with GNU compilers -- this file is ''SDK/Linux/settings/stride.s2scompile'' in the SDK distribution.

We recommend that you make a copy of this file and adjust the settings as appropriate for your target. You can then set this variable - '''S2SCOPTS''' to the path to your settings file. This will cause the make process to use the specified target settings options instead of the default one provided in the SDK. This same settings file should ultimately be used for the STRIDE build integration with your application source code.

===S2 Build Flags===
The target Makefile sets the following Build Tool flags:

S2_BIND_FLAGS = --starting_suid=7000
S2_IM_FLAGS = --disable_access_class

The [[S2sbind#Options|s2sbind]] and [[S2sinstrument#Options|s2sinstrument]] flags are combined so that the test application only registers for test message IDs that are created in a higher range so that it doesn't conflict with other application processes.

==Target API (stride.h)==

The Linux SDK provides a simplified application interface for initializing the STRIDE subsystem and starting STRIDE messaging and IM threads. The API includes the following routines:

===srBOOL strideInit(const strideIO_t * io)===

This function initializes the STRIDE subsystem. The IO configuration is passed in as an argument. If this argument is NULL, then the process will attempt to attach to an already running runtime application (daemon) using shared memory for IPC. THis function should only be called once per application.

===srBOOL strideUninit(void)===

Terminates any threads that have been started with this API and uninitializes the STRIDE subsystem.

===srBOOL strideCreateThread(strideThreadFunc_t entry, const srCHAR * name)===

Creates a thread to be managed by the STRIDE subsystem. Threads created using this routine will be sent a palSTOP_EVENT notification (available from palWait) and should respond promptly to this event. The name parameter is used primarily for logging purposes.

===strideCreateIMThread(name)===

This is a macro that wraps the invocation of [[#strideCreateThread|strideCreateThread]] for intercept module entry point functions. Only the IM name must be provided.

===void strideExWaitForExit(void)===

This function can be called by the main application thread to block until a termination signal is received. Internally it uses the pause function to wait for signals to be delivered and then checks if termination has occurred.

===void strideExDaemonize(const char* lockFile, const char* runAs)===
This function is called by applications to deamonize the process. Both arguments are optional. The first argument specifies a lockfile path/name to use to insure that only one instance of the process is running. The second argument specifies a username to run as (setuid)

This function is optional - if you prefer to run your application as an interactive console application, do not call this function. If you are running as a daemon, we recommend that you have the PAL_LOG_TO_SYSLOG macro defined (in palcfg.h) so that PAL log messages will be sent to the syslog (this is default setting currently).

==Target Integration==

Here are a few examples of how to integrate the stride API into your application.

'''Note:''' the following code assumes that the intercept module was generated with a name of ''myintercept''. Change all references to that name in your code to the chosen intercept module name.

===Standalone Application Integration===

The following code demonstrates how to integrate your application with the STRIDE Runtime. Your application might require other logic at startup - you can integrate the following calls according to your needs. Note that this code initializes the STRIDE subsystem and assumes a single standalone process that creates the STRIDE system threads as well as application threads. The call to strideExDaemonize is optional here - remove it if you don't want you application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
strideIO_t io = {strideDEFAULT};
if (strideInit(&io) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

===Multiprocess Application Integration===

This code demonstrates how to integrate your application with the STRIDE Runtime in multiprocess mode. In this mode, the pre-packaged strideDaemon runs simultaneously with the application and provides the STRIDE IO and runtime thread initialization. The host communicates with the application process through the strideDaemon (or another STRIDE IO process). In this sample, the only difference with the preceding sample is the call to strideInit which, in this case, specifies no IO parameters which indicates to the API that the communication and runtime threads should not be started. As before, the call to strideExDaemonize is optional here - remove it if you don't want your application to run as a daemon.

<source lang="c">
#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
strideExDaemonize(NULL, NULL);
if (strideInit(NULL) != srTRUE)
return -1;

if (strideCreateIMThread(myintercept) != srTRUE)
return -1;

strideExWaitForExit();
strideUninit();
return 0;
}
</source>

==Linux PAL==

===PAL Configuration (palcfg.h)===
The following parameters can be configured in ''palcfg.h'' to effect the behavior of the compiled pal source files.

; PAL_USE_SERIAL_TRANSPORT : if defined, serial communication support is enabled.
; PAL_USE_TCPIP_TRANSPORT : if defined, sockets-based communication support is enabled.
; PAL_DEFAULT_DEVICE_NAME : default IO device to use.
; PAL_DEFAULT_TCP_PORT : default port for TCP communication.
; PAL_DEFAULT_SERIAL_PORT : default COM port to use for serial communication.
; PAL_DEFAULT_SERIAL_BAUDRATE : default baud rate for serial communication.
; PAL_DEFAULT_SERIAL_MODE : default data/parity/stop settings for serial communication.
; PAL_USE_POSIX_CLOCK_GETTIME or PAL_USE_GETTIMEOFDAY : indicates the time of day clock to use.
; PAL_TIMER_PERIOD : this is the fire interval for the STRIDE Runtime master timer, in milliseconds.
; PAL_MAX_THREADS : max STRIDE integrated threads that can be managed by the STRIDE API.
; PAL_MAX_TIMERS : max STRIDE timers that can be active in the system.
; PAL_USE_POSIX_TIMER or PAL_USE_INTERVAL_TIMER : indicates the timer type to use.
; PAL_CLOCKID : indicates the type of POSIX clock to use
; PAL_DELIVER_TIMER_BY_THREAD or PAL_DELIVER_TIMER_BY_SIGNAL : specify how POSIX timer signals are delivered.
; PAL_TIMER_SIGNAL_TYPE : define which signal to use for timer delivery.
; PAL_LOG_TO_SYSLOG : palLog messages will be sent to syslog if this is defined; to stdout/stderr otherwise.
; PAL_SHM_PATH : the path to use for shared memory files. Only needed if multiprocess support is enabled in srcfg.h.

[[Category: SDKs]]

Studio:Scl string

2008-10-22T23:56:37Z

Andreo: /* Example 1 */

= The scl_string pragma =

The scl_string pragma identifies a particular array type or pointer type as a string. The string type (ASCII or UNICODE) is derived from the element type (1-byte or 2-byte, respectively).

== Syntax ==
#pragma scl_string(type-name, max-size)

#pragma scl_string(type-name, field-name, max-size)

{| border="1" cellspacing="0" cellpadding="10" style="align:left;"
| '''Parameters'''
| '''Type'''
| '''Description'''
|-
| ''type-name''
| Type
| Name of the type that contains the array/pointer: 
* structure or union 
* the array/pointer type itself 
* function name 
If the container type is a structure or union and the array/pointer is a member, then field-name must be specified.
|-
| ''field-name [Optional]''
| Member
| Optional name of the array/pointer member contained within a structure/union, or the name of the pointer in the parameter list of a function. 
If type-name is a structure or union and the array/pointer is a member, then field-name must be specified.
|-
| ''max-size''
| Integer
| Specifies the maximum length of the string.
|}

== Examples ==

Two examples using the scl_string pragma are shown below:

=== Example 1 ===
The first example uses the scl_string pragma to define type definitions as null terminated ASCII strings.
<source lang=c>
#define MAX_STR_SIZE 100

typedef char ArrayAsAsciiString_t[MAX_STR_SIZE];
typedef char* PointerAsAsciiString_t;
#pragma scl_string( PointerAsAsciiString_t, MAX_STR_SIZE )
#pragma scl_string( ArrayAsAsciiString_t, MAX_STR_SIZE )

void GetString(char* pBuf);
#pragma scl_function(GetString)
#pragma scl_ptr(GetString, pBuf, "OUT", "PRIVATE")
#pragma scl_string(GetString, pBuf, MAX_STR_SIZE)
</source>

=== Example 2 ===
The second example uses the scl_string pragma to define a structure member and a parameter list member as null terminated ASCII strings.
<source lang=c>
#define MAX_STR_SIZE 64

/* ASCII string defined as a pointer to char */
typedef struct {
char * pointerToAsciiString;
char arrayAsAsciiString[MAX_STR_SIZE];
} Struct_t;

/* Function with an input parameter of type ASCII string */
void SetString( char * parameterAsAsciiString );
#pragma scl_function(SetString)
/* Use the scl_string pragma to define the above structure */
/* and parameter list members as null-terminated ASCII strings */
#pragma scl_string( Struct_t, pointerToAsciiString, MAX_STR_SIZE )
#pragma scl_string( Struct_t, arrayAsAsciiString, MAX_STR_SIZE )
#pragma scl_string( SetString, parameterAsAsciiString, MAX_STR_SIZE )
</source>

== See Also ==
* For additional information on scl_string, including constraints, refer to the section on scl_string in the [[Media:s2sSCLReferenceGuide.pdf|SCL Reference Guide]].

[[Category: SCL]]

Talk:Capturing Functions

2008-04-01T18:20:28Z

Andreo: New page: I would add that the function f1_scl_func_single in the scl_function_capture_one.h file I could not capture the function after opening the workspace. I got the warning: The database is ou...

I would add that the function f1_scl_func_single in the scl_function_capture_one.h file

I could not capture the function after opening the workspace. I got the warning: The database is out of date. SCL Wizard will be disabled until successful compilation. I suggest adding that you have to compile first.

The instructions to perform the exercise tell you what to do but don't tell where to get help or some hints on how to do it. If this is part of the training where and how would you get help?? What if I can’t remember how to do it or if I make a mistake. How do I undo something I did?

Talk:Scripting Multiple Interfaces

2008-04-01T18:11:00Z

Andreo: New page: The scripts are in Script Files\test\testScripts_InterfaceScripting_MultipleInterfaces and not just Script Files\test as described. I suggest adding a example of the expected output in st...

The scripts are in Script Files\test\testScripts_InterfaceScripting_MultipleInterfaces and not just Script Files\test as described.

I suggest adding a example of the expected output in studio's output tab.

What if the script does not work or the customer has problems writing the script? Where ca the customer get help?

The path or instructions on how to open the html report file should be provided.

The report should be more descriptive. I saw suites with the name f, g, and h which is not very descriptive. There is no description for the suites.

Studio:Is hyperthreading supported in STRIDE?

2007-12-18T18:23:46Z

Andreo:

Yes. The Intel hyperthreading feature, where a single processor chip will run multiple (usually dual) threads of execution, is supported in STRIDE.

[[Category:KB]]
[[Category:FAQ]]

Studio:Casting and pointers

2007-12-18T18:17:54Z

Andreo:

A cast must be applied to a pointer before anything else. In other words, you must apply scl_cast before scl_ptr, as illustrated by the following example: 
<tt>#pragma scl_function(GetUnicodeName) 
#pragma scl_cast (GetUnicodeName, name, unsigned short*) 
#pragma scl_ptr (GetUnicodeName, name, OUT, PRIVATE) 
#pragma scl_string (GetUnicodeName, name, 100)</tt>

[[Category:KB]]
[[Category:SCL]]
[[Category:Troubleshooting]]

Studio:After installing the STRIDE Runtime, what are my configuration settings?

2007-12-18T18:14:06Z

Andreo:

The Runtime configuration settings are described in the srcfg.h file, located in C:\STRIDE\runtime. Whenever you install a new version of STRIDE, you should avoid overwriting the srcfg.h file.

The correct configuration settings are as follows: 
<tt> #define srCFG_TOTAL_STIDS 15 /* 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 0 /* 1 = Search based, 0 = Index based */
#define srCFG_SUID_TABLE_SIZE 225 /* number of SUID Table entries */
#define srCFG_SUID_OVERRIDE 1 /* override (1 = enabled, 0 = disabled) */
#define srCFG_SUID_OVERRIDE_STORAGE 0 /* override registration storage allocation */ 
#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 */
</tt>

[[Category:KB]]
[[Category:FAQ]]

Studio:Working with "default" candidates

2007-12-11T23:09:12Z

Andreo:

scl_ptr_flist() serves as a "shorthand" method of declaring a "default" candidate. 
'''Note''': When using scl_ptr_flist() to define candidates, the function pointer prototypes are defined internally within STRIDE, rather than by the user. 

'''Example''' 
<tt>// function pointer typedef 
typedef void (*FPtr) (int, char); 
void foo(FPtr *pFPtr); 
void foo1(FPtr *pFPtr); 
void foo2(FPtr *pFPtr); 
void foo3(FPtr *pFPtr); 
// candidate prototypes 
void C1(int x, char y); 
void C2(int x, char y); 
void C3(int x, char y); 
// pragmatize candidate prototypes 
#pragma scl_function(C1) 
#pragma scl_function(C2) 
#pragma scl_function(C3) </tt>

'''How to declare a "default" candidate using scl_ptr_flist()''' 
There are several methods of declaring a "default" candidate using scl_ptr_flist(). Each method is explained below. 
'''Method 1: Candidate list declaration using predefined function prototypes'''
<tt>#pragma scl_function(foo) 
#pragma scl_ptr_flist(*foo.pFPtr, C1, C2, C3)</tt> 

The candidates' (C1, C2, C3) prototypes are defined and pragmatized, and proxies/stubs will be generated. In the parent function (the function that contains the function pointer PFptr) will use a for loop to search through the static table to bind the function pointer with the SMID or vice versa. The command and response payloads of the candidate functions (C1, C2, C3) can be captured via tracing.
 
'''Method 2: Candidate list declaration using shorthand method'''
<tt>#pragma scl_function(foo1) 
#pragma scl_ptr_flist(*foo1.pFPtr, "cand1") </tt>

"Default" proxies/stubs will be generated for the name in quotes in scl_ptr_flist() "cand1" in the example above. The command and response payloads of the candidate functions (e.g., "cand1") can be captured via tracing. 
 
'''Method 3: Candidate list declaration using combination of predefined functions and shorthand method'''
 
<tt>#pragma scl_function(foo2)
#pragma scl_ptr_flist(*foo2.pFPtr, "cand4", C2)</tt> 

The candidate "cand4" is interpreted by STRIDE as follows: 

<tt> void cand4(int p1, char p2); 
#pragma scl_function(cand4)</tt> 

"Default" proxies/stubs will be generated for the name in quotes in scl_ptr_flist() "cand4" in the example above. The command and response payloads of the candidate functions (e.g., "cand4") can be captured via tracing. 
 
'''Method 4: "Default" candidate declaration''' 
<tt>#pragma scl_function(foo3) 
#pragma scl_ptr_flist(*foo3.pFPtr, "def_cand")</tt> 

The candidate "def_cand" is interpreted by STRIDE as follows: 
<tt>void def_cand(int p1, char p2); 
#pragma scl_function(def_cand)</tt> 

A "default" proxy/stub will be generated for def_cand. The parent function will not use a for loop and the proxy will replace the existing function pointer in the table with the passed-in function pointer. The command and response payloads of any function prototype with the identical signature to def_cand can be captured via tracing.

[[Category:KB]]
[[Category:SCL]]

Why am I getting "unresolved external reference" errors during the linking process?

2007-12-11T23:05:43Z

Andreo:

The srIMON flag in your compiler switches may not be defined. This flag is used to include and exclude source files associated with intercept modules.

Also if you use dynamic delegate make sure that the IM.h files is included in your source file for name mangling.

[[Category:KB]]
[[Category:Troubleshooting]]

Studio:The communication/messaging model I use in my target application is not compliant with STRIDE

2007-12-11T23:00:49Z

Andreo:

The STRIDE Communication Model can be used to bridge the differences between it and the messaging model employed in your embedded application. Refer to the "Using a Remote Message Stub Thread" section of the STRIDE Runtime Developer's Guide, available through STRIDE's online help, for more information.

[[Category:KB]]
[[Category:Troubleshooting]]
[[Category:FAQ]]

Studio:Sending and receiving broadcast messages in the Runtime

2007-12-11T23:00:00Z

Andreo:

If broadcast messages are being sent from the target to the host (i.e., there are no subscribers on the target), the data must be marshalled up to the host. However, when both the broadcaster (owner) and a receiver (user) are on the target, it is more efficient to specify srST_RSP_PTR since only a pointer to the message is moved internally.

By contrast, if srST_RSP_VAL is specified, the entire message is copied before being sent.

[[Category:KB]]
[[Category:SCL]]

Studio:Is it possible to change the host trace buffer size?

2007-12-11T22:56:57Z

Andreo:

Yes. From within STRIDE Studio, click on the Property sheet (or to open it, select '''Properties''' from the '''View''' menu) and change the value in the '''Preferences -> Cache Size (KB)''' field.

[[Category:KB]]
[[Category:FAQ]]

Handling non-standard or unsupported keywords

2007-12-11T22:55:52Z

Andreo:

For example if the <tt>__inline__</tt> keyword is missing or unsupported, you can work around it by adding <tt>'__inline__='</tt> to the workspace definitions.

[[Category:KB]]
[[Category:SCL]]
[[Category:Troubleshooting]]

Studio:How to generate a preprocessor (.i) file for analysis

2007-12-11T22:55:28Z

Andreo:

'''Preprocessing individual files'''

You can run the preprocessor on one or more header files to generate .i files, which can then be used for analysis. To do this from within Studio, select one or more top-level header files, right-click, and choose '''Preprocess'''. 
'''Note''': You will need to rename the file to have a .h extension.

Only the selected files are compiled, and preprocessed (.i) files are generated for them. During the compilation, the workspace settings for #defines and include paths are in effect. Existing databases are not affected. 
'''Note''': The #include <stdarg.h> will require the workspace to have a valid pointer (usually to the Microsoft C includes directory).

[[Category:KB]]
[[Category:SCL]]
[[Category:FAQ]]
[[Category:Troubleshooting]]

Studio:How can I tell which version of a workspace is used when connected to the target at runtime?

2007-12-11T22:53:06Z

Andreo:

When working with multiple targets, you may want to determine which version of a workspace is being used at runtime. To determine the target to which you are connected, add a helper function to the Intercept Module which can return something from the target (e.g., a string whose value is a target compile-time setting) that will tell the script the kind of target to which it is connected.

You can also add a preprocessor define with a version number as part of the workspace build (not the target build). The define is not used for compilation. A script will check which preprocessor define is set and act accordingly.

[[Category:KB]]
[[Category:SCL]]

Handling non-standard or unsupported keywords

2007-12-11T22:50:20Z

Andreo:

For example if the <tt>__inline__</tt> keyword is missing or unsupported, you can work around it by adding <tt>'__inline__='</tt> to the workspace definitions.

[[Category:KB]]
[[Category:SCL]]

Studio:How does the STRIDE compiler handle zero-length arrays?

2007-12-11T22:49:45Z

Andreo:

A zero-length array embedded in the middle of a struct is treated as if it was not there (i.e., as if it was commented out). It will not allocate storage or affect alignment in the structure in any way. It will not be addressable from ascript and will not be visible in the interface or workspace view.

[[Category:KB]]
[[Category:SCL]]

Studio:Casting and pointers

2007-12-11T22:48:20Z

Andreo:

Studio:Auxiliary data

2007-12-11T22:45:07Z

Andreo:

If auxiliary data is enabled (srCFG_AUXDATA is set to 1 in srcfg.h), auxiliary data is transmitted with each message. The data you set using srSetAuxData for the particular STID is transferred with each message. Once the value is set, the same value will be transmitted with each message until you change the value.

With srGetAuxData, you can read the data. The value returned will be the one that was received with the most recent message on that STID. The auxiliary data is bidirectional, which means that there is a set of data which is sent in each direction. srSetAuxData sets the transmit auxiliary data and srGetAuxData reads the received auxiliary data. Transmit auxiliary data is accessible in a write-only manner through srSetAuxData, and receiving auxiliary data is accessible in a read-only manner through srGetAuxData.

[[Category:KB]]
[[Category:Scripting]]

Studio:Stride System Error Logging

2007-12-11T22:44:31Z

Andreo:

Acceptable error log level values are ''all, trace, debug, info, warn, error, fatal,'' and ''off''. The default is ''error''.

[[Category:KB]]
[[Category:FAQ]]

Studio:Advantages and disadvantages of "default" candidates

2007-12-11T22:42:52Z

Andreo:

The following table describes the advantages and disadvantages associated with the "default" candidate method vs. the candidate method.

{| class="wikitable", cellpadding="5"

|-

!

! '''"Default" candidate method'''

! '''Candidate method'''

|-

| '''Define and pragmatize each function prototype'''

| Not needed.

| Cumbersome if there are hundreds of candidate functions.

|-

| '''Code footprint of the generated code'''

| Only the proxy/stub of the "default" candidate is generated; thus, the code footprint is much smaller.

| The code footprint is dependent upon how many candidates are defined using the scl_ptr_flist() pragma, since a proxy/stub is generated for each candidate defined in the list.
|-

| '''Capturing of function callback command/response payloads via the trace module'''

| Any function callback command/response payloads with the identical signature can be captured.

| Only those candidate functions defined in the scl_ptr_flist() pragma can be captured.

|-

| ''' Visibility of function callbacks via the trace module'''

| The function callback being called is unknown. All of the function callbacks with the identical signature will be displayed with the "default" candidate name and SMID.

| All of the function callbacks being called are known, as long as the candidate functions were declared in the scl_ptr_flist() pragma.

|}
 
One disadvantage of using the shorthand method to define candidates in scl_ptr_flist(), as shown in Method 3 of the [[Working with "default" candidates]] topic, is that the function pointer prototypes are not defined by the user/customer, but rather by STRIDE. So, for example, if the user wants to create a proxy for foo2() with stub candidate functions C2 and "cand4" on the target, the generated IM code will give "undefined" compiler errors for "cand4". The following procedure using the header file MyHeader.h (the file containing the SCL pragmas or function prototypes) resolves this issue:
<tt>#ifdef srIMON 
void cand4(int x, char y); 
#endif </tt>

The use of the srIMON preprocessor directive allows the SDAC to compile the file without any name conflicts for "cand4", since these are already defined within STRIDE. It also allows the generated IM code to compile successfully.

'''MyFunctions.c''' 
MyFunctions.c is an example of a user-created file containing the actual code for the candidate "cand4":
<tt>void cand4(int x, char y) 
{ 
} </tt>

'''MyTest.c''' 
MyTest.c is an example of a user-created file containing a test thread that makes the call to foo2() with the appropriate function pointer callback:
<tt>#include “MyHeader.h” 
FPtr funcPtr; 
// set to cand4 
funcPtr = cand4; 
foo2(&funcPtr);</tt> 
In some instances, the candidates on the target are not known to the implementer of foo2() and the candidates may be static, so the above solution isn’t applicable. Using the “default” candidate mechanism is the perfect solution to this problem. The following example demonstrates how to do this (refer to Method 3 above):

In MyHeader.h (the file that contains the SCL pragma’s or the function prototypes), replace the following:
<tt>#pragma scl_ptr_flist(*foo2.pFPtr, “cand4”, C2)</tt> 
with:
<tt>#pragma scl_ptr_flist(*foo2.pFPtr, “default_cand”) // default candidate</tt> 

'''MyFunctions.c''' 
MyFunctions.c is an example of a user-created file containing the actual code for the candidates (unknown_cand1, unknown_cand2):
<tt>static void unknown_cand1(int x, char y) 
{ 
} 
static void unknown_cand2(int x, char y) 
{ 
} </tt>

'''MyTest.c''' 
MyTest.c is an example of a user-created file containing a test thread that makes the call to foo2() with the appropriate function pointer callback.

<tt>#include “MyHeader.h” 
FPtr funcPtr; 
// set to unknown_cand1 
funcPtr = unknown_cand1; 
foo2(&funcPtr); 
// set to unknown_cand2 
funcPtr = unknown_cand2; 
foo2(&funcPtr); </tt>

[[Category:KB]]
[[Category:SCL]]

Studio:What to do when the Perl tag file is corrupted

2007-12-11T22:36:26Z

Andreo:

If the tag file (C:\STRIDE\bin\vslick\S2Custom\StridePL.vtg) becomes corrupted, delete it.

[[Category:Scripting]]
[[Category:Troubleshootng]]

Studio:Referring to global stride objects

2007-12-11T21:48:02Z

Andreo:

The following variables are automatically injected when scripts are run in Studio, and must be referred to:

$ascript

$studio

$reporter

$panel

$testSuite

In Perl, these variables must be qualified with the namespace (main::) in order for the script to run under strictures (invoked by including use strict in your script):

{|
| '''Automatic variable''' || '''Refer to as'''
|-
| width="200pt" | $ascript || $main::ascript
|-
| $studio || $main::reporter
|-
| $reporter || $main::studio
|-
| $panel || $main::panel
|-
| $testSuite || $main::testSuite
|}

Using use strict in scripts is recommended, as it catches a number of potential errors that might otherwise go undetected. However, if strictures are not used, these global variables may be referred to without the main:: qualification.

For additional information on global variables on the target, click [[Accessing global variables|here]].

[[Category:Scripting]]

Studio:How do I access global variables?

2007-12-11T21:38:39Z

Andreo:

STRIDE allows you to call functions and send messages on the target, which is in most cases all you need for validation. However, in some cases it might be necessary to read or modify global variables or certain memory locations. If there are API functions available to access the global variables or read memory, those APIs could be exposed to STRIDE and used. If no such API calls are available, they can be added; this requires changes to the target code. Although STRIDE doesn’t directly support accessing target memory with simple helper functions, you can easily access target information without changing the target code by adding code to a header file containing SCL pragmas.

This header file would then be included in the STRIDE workspace, and therefore included in the intercept module. It would not be required to include the header file in any of the customer target code, nor would modifications to the customer code be required. Since the function is known to the intercept module and the intercept module is the only one calling the function, it could be static and therefore have no impact on the rest of the code. The following demonstrates a header file which is included in the STRIDE workspace and subsequently in the intercept module; the function is defined as static, since its scope is limited to the intercept module.

'''Example: Reading a number of bytes from the target'''

<code>static __inline__ void SCL_get_num_bytes ( void *ptr, unsigned char* data, int num_bytes)</code> 
<code>{ </code> 
<code> memcpy ( data, ptr, num_bytes ); </code> 
<code>} </code>

'''Reading and writing global data'''

Another application is to read and write global data. For example, we could have a global state variable. Either the header file which defines the global state variable could be included, or an external definition could be added to the header file. The first option is preferred; in some cases the global state variable definition could be in a .c file.

'''Example: STRIDE header file'''

<code>/* extern definition for global */</code> 
<code>extern int global_state</code> 
<code>/* helper function to set the state */</code> 
<code>static __inline__ void SCL_set_state(int state)</code> 
<code> { </code> 
<code> global_state = state; </code> 
<code> } </code> 
<code> /* helper function to get (read) the state */ </code> 
<code> static __inline__ int SCL_get_state(void) </code> 
<code> { </code> 
<code> return global_state;</code> 
<code> } </code> 

[[Category:KB]]
[[Category:Scripting]]
[[Category:SCL]]

Studio:Perl and COM

2007-12-11T21:37:18Z

Andreo:

Because of its multiplatform heritage, Perl is not a COM-aware language by default. The Win32::OLE package integrates COM with Perl, however there are some "features" of this library that might not be intuitive to Perl programmers. The most important ones are the options the library provides for error reporting (warning level). For more information see [http://search.cpan.org/~jdb/libwin32-0.26/OLE/lib/Win32/OLE.pm Win32::OLE description].

* We always recommend setting a warn level of 3. If you don't do this, COM errors won't be passed back to the script. In JScript, you always receive COM errors, so warn level 3 brings Perl in line with that behavior.
* When working with unicode the code page has to be set in order to get Perl/COM to properly pass the pchar value as a unicode character. For example Win32::OLE->Option(CP => Win32::OLE::CP_UTF8);

[[Category:Scripting]]

Studio:How to define message structures

2007-12-11T21:28:27Z

Andreo:

The following rules make it easier to process unions and select the active member(s) within a union or nested unions, as well as making it easier to transfer data between tasks.
* Have a one-to-one correlation between disciminants and union members.
* The order of enums for discriminants matches with the order of members within the union.
* In the case of nested unions, each union should have its own discriminant.
* Use inline data instead of pointers.

Below is an example:
<tt>typedef struct 
{ 
DEVICE_NAME, 
INQUIRY, 
SD, 
SECURITY, 
CONN, 
} app_opcodes_t;</tt>

The corresponding message structure is as follows:
<tt>typedef struct 
{ 
ros_hdr_t ros_hdr; 
vris_hdr_t vris_hdr; 
app_hdr_t app_hdr; 
union 
{ 
app_name_msg_t app_name_msg; 
app_inquiry_msg_t app_inquiry_msg; 
app_sd_msg_t app_sd_msg; 
app_sec_msg_t app_sec_msg; 
app_conn_msg_t app_conn_msg; 
} ros_msg 
} app_msg_t;</tt>

The first element of the union app_name_msg matches with the first enum value of DEVICE_NAME (discriminant within ros_hdr). The number and order of the discriminant values (app_opcodes_t) are the same as the union members.

If the union within the message contains other unions (nested unions), the same rule would apply. The following example demonstrates app_sec_msg_t within ros_msg:
<tt>typedef enum 
{ 
DISCOVERABLE_CFM, 
CONNECTABLE_CFM, 
SEC_AUTHORIZE_CFM, 
SEC_AUTHENTICATE_CFM, 
SEC_BOND_CFM, 
} app_prim_sec_t; 
typedef struct 
{ 
app_prim_sec_t sec_msg_rsp; 
union 
{ 
discoverable_mode discoverable_info; 
connectable_info_t connectable_info; 
authorize_info_t authorize_info; 
authenticate_info_t authenticate_info; 
user_info_input_t user_input_info; 
bond_info_t bond_info; 
} sec_msg; 
} app_sec_msg_t;</tt>

The above examples have the same number of discriminant values and union members. There is a one-to-one correlation between discriminant and union member. Having a discriminant for each union within nested unions decouples the unions and makes it more scalable and easier to maintain. The unions become independent of each other and can easily be extended.

[[Category:SCL]]

Studio:How do I start non-blocking scripts which do not use the Reporter from a Perl script?

2007-12-11T21:26:00Z

Andreo:

The reporter object is automatically instantiated when a script is started in studio. If none of the STRIDE objects need to be instantiated you can start a script extern to stride.

<tt>use Win32; 
use Win32::API; 
use Win32::Process; 
use constant WIN32_STILL_RUNNING => 259; 
my $processObject; 
my $retValue = Win32::Process::Create( 
$processObject,
$^X,
"perl PATH_TO_MY_SCRIPT ARGUMENTS",
0,
NORMAL_PRIORITY_CLASS,
".") || die Win32::FormatMessage(Win32::GetLastError());</tt>

Once you have started the process this way, you can use GetExitCode to check if it is still running, as shown in the following example:
<tt>$processObject->GetExitCode($exitCode); 
if ($exitCode == Win32_STILL_RUNNING) { 
## it is still running 
} 
else { 
## it has finished 
} </tt>

You can kill the process by using
<tt>$processObject->Kill(255);</tt>

Using the above statement forces a kill and is not a graceful way to force the process to exit. If your script is a daemon-like process, it is recommended that you use some sort of IPC mechanism (such as Win32::Event or sockets, pipes, semaphores, etc.) to force a more graceful shutdown.

[[Category:Scripting]]

Studio:How do I start non-blocking scripts which do not use the Reporter from a Perl script?

2007-12-11T21:25:29Z

Andreo:

Studio:How do I speed up scripts by caching an intermediate collection/object?

2007-12-11T21:15:17Z

Andreo:

The following example re-accesses the ascript object for each node of the Files and Item() collection. This is slow and expensive:
<tt>#enable the "makereport" property for the item we just added 
$subFolder->Files->Item($script_name)->{MakeReport} = "true"; 
#mark the script as executable or not 
$subFolder->Files->Item($script_name)->{Execute} = $entry->{executable} || 'false'; </tt>

A faster and better way is to reuse the object returned by the Add() method (which is the same one returned by the Item() method later). The change shown in the example below improved performance by over 50%:
<tt>my $file = $subFolder->Files->Add($script); 
#enable the "makereport" property for the item we just added 
$file->{MakeReport} = "true"; 
#mark the script as executable or not 
$file->{Execute} = $entry->{executable} || 'false';</tt>

[[Category:Scripting]]
[[Category:Troubleshooting]]

Studio:How do I kill a task if the window is owned by a non-killable system task?

2007-12-11T21:07:49Z

Andreo:

The following Perl script demonstrates how to "kill" a specific task:
#!c:/perl/bin/perl -w
use Win32::OLE;
use strict;
my $wshShell = Win32::OLE->new('WScript.shell');
while ($wshShell->AppActivate("Application.exe - Application Error"))
{
$wshShell->SendKeys("%{F4}");
}

Check TestUtils Perl library in C:\Stride\lib\perl\S2S for additional information on how to dismiss pop-up windows.

[[Category:Scripting]]
[[Category:Troubleshooting]]

Studio:How do I get Perl scripts to emit fatal errors when a COM error occurs?

2007-12-11T21:03:30Z

Andreo:

By default, the Win32::OLE package in Perl, which allows Perl scripts to interact with COM objects, does not emit fatal errors when a COM error occurs. In order to get Perl scripts to emit fatal errors when a COM error occurs, include the following statement in your script:

<tt>Win32::OLE::Option(Warn => 3);</tt>

This would typically be placed near the top of the script. It is our recommendation that you always use Warn Level 3.

[[Category:Scripting]]
[[Category:Troubleshooting]]

Studio:How do I extract the drive letter and use it to define the location of the Perl module?

2007-12-11T20:59:51Z

Andreo:

The following code will extract the drive letter and use it to define the location of the Perl module: 
use strict;
use File::Spec;
use vars qw($modulePath);
BEGIN
{
my($vol, undef, undef) =
File::Spec->splitpath($main::ascript->Database->Path);
$modulePath = File::Spec->catpath($vol, File::Spec->catdir('','Stride','lib', 'perl', 'S2S'));
}
use lib qq($modulePath);
use TestUtils;

A BEGIN block is evaluated as soon as it is encountered, so the $modulePath value will have a value by the time the 'use lib' statement is encountered.

If libraries are always installed on the system drive, $ENV{'SystemDrive'} can be used to determine the volume. Alternately, a registry setting or environment variable can be used.

[[Category:Scripting]]

Studio:How do I access an array in the parameter list through Perl?

2007-12-11T20:53:05Z

Andreo:

By using a simple interface such as: 
<tt>void test1(char s[10]); 
#pragma scl_function(test1)</tt> 

The following Perl script example illustrates how to access an array in the parameter list. The following example sets element 0 of s to 15.
my $test = $ascript->Functions->Item("test1")->User;
my $data = $test->ParameterList;
$data->SetProperty("s", 0, 15);
$test->Call();

Another option is to use safearray to directky copy a Perl array into an array of the parameter list. Here is an example:
my @a = (11, 12, 13, 14, 15, 16, 17, 18, 19, 20);
$user->ParameterList->a->seq_num->{SafeArray} = \@a;
$user->Call();

[[Category:Scripting]]

Studio:How do I access an array in the parameter list through Perl?

2007-12-11T20:52:02Z

Andreo:

By using a simple interface such as: 
<tt>void test1(char s[10]); 
#pragma scl_function(test1)</tt> 

The following Perl script example illustrates how to access an array in the parameter list. The following example sets element 0 of s to 15.
<tt>my $test = $ascript->Functions->Item("test1")->User; 
my $data = $test->ParameterList; 
$data->SetProperty("s", 0, 15); 
$test->Call(); </tt> 

Another option is to use safearray to directky copy a Perl array into an array of the parameter list. Here is an example:

my @a = (11, 12, 13, 14, 15, 16, 17, 18, 19, 20);
$user->ParameterList->a->seq_num->{SafeArray} = \@a;
$user->Call();

[[Category:Scripting]]

Studio:How can I check which version of STRIDE I am using from a script?

2007-12-11T20:45:48Z

Andreo:

The only way to check the STRIDE version number is to read the version information from the Windows registry.

<tt>use strict; 
use Carp; 
use Win32::TieRegistry(Delimiter => '/'); 
my $stride_version = $Registry->{"LMachine/Software/S2 Technologies/STRIDE/Version"}; 
print "STRIDE VERSION: $stride_version\n"; </tt>

The last three digits of the version string indicate the STRIDE build number (e.g, STRIDE VERSION 2.0.0602.326 indicates a build number of 326).

[[Category:Scripting]]

Studio:Can STRIDE marshal both data and pointers?

2007-12-11T20:41:40Z

Andreo:

STRIDE does not marshal both the pointer value and the data. You have to pick on of the two. If a pointer is defined as void or the scl_ptr_opaque pragma is applied the pointer value is marshaled otherwise the data the pointer points to is marshaled. Opaque pointers can be passed to other functions or helper function to retrieve the data to which it points.

[[Category:Scripting]]
[[Category:SCL]]

Studio:Can STRIDE marshal both data and pointers?

2007-12-11T20:40:52Z

Andreo:

Studio:Can I use Perl's Tk package in STRIDE?

2007-12-11T20:35:43Z

Andreo:

We recommend running the script which uses the Tk package as a separate script outside of STRIDE Studio, as there is an incompatibility with the Tk package that causes errors during execution. You should not get an error the first time you run the script, but you will get errors during every subsequent execution until you shut down Studio. This is due to a problem with initialization and the Perl engine failing to fully clean up; the Tk engine relies on the cleanup code, but since this only occurs when the engine unloads (i.e., Studio is closed), errors occur during execution.

To run the script using Tk outside of Studio, you can launch it from a script in Studio using the system command. You can also pass arguments between the scripts. Below is an example.

Script to launch the Tk script. (Note: The Tk script has to be included in the workspace script files).

use strict;
use File::Spec;

#Get path and name of perl exectuable
my $perlExe = $^X;
if ($perlExe =~ /\.dll$/i)
{
my ($vol, $dir, $file) = File::Spec->splitpath($perlExe);
$perlExe = File::Spec->catpath($vol, $dir, 'perl.exe');
}

# get the name and path of the script with the Tk library
my $tkScript= $main::studio->Workspace->Files->Item("tk.pl");
my $tkFullPath = File::Spec->catfile($tkScript->Path, $tkScript->Name);

#List of arguments for Tk script
my @options = ('"option 1"', '"option 2"', '"option 3"', '"option 4"');

#Start the script
my @data = `$perlExe \"$tkFullPath\" @options`;

#@data is the array with the return values (through STDOUT)
for (my $i=0; $i <= $#data; $i++)
{
$main::ascript->MessageBox("$data[$i]", "Element $i");
}

And here is the Tk script

#!c:/perl/bin/perl -w
use strict;
use Tk;
my $mw = MainWindow->new;
my $fileName;
FillWindow($mw, 'Choose Script to Run:',@ARGV);

MainLoop;

sub FillWindow
{
my ($window, $header,@List) = @_;
my @selected;
my $i;
$window->Label(-text => "$header")->pack;
foreach (@List)
{
push @selected, 0;
$mw->Checkbutton(-text=>"$_",-variable=>\$selected[$i])->pack;
$i++;
}
$mw -> Button(-text=>"Select", -command =>sub
{
my @selectedOptions;
for (my $i=0; $i <= $#List; $i++)
{
if ($selected[$i])
{
push @selectedOptions, $List[$i];
}
}
print STDOUT join(" \n ", @selectedOptions);
$mw -> destroy;
})->pack;

}

[[Category:Scripting]]

Studio:Are multiple callbacks possible?

2007-12-11T19:59:14Z

Andreo:

Due to the single-threaded nature of most applications, once an off-target owner function is called, the owner may not call back into it. However, multiple callbacks may be done by using a short-term local timer which may continue processing after returning control back to the application and unblocking it. If callbacks are called from different threads it is possible that multiple callbacks are called at the same time.

[[Category:Scripting]]

Studio:Can I use STRIDE if my embedded code has real-time constraints?

2007-11-29T00:11:55Z

Andreo:

The STRIDE components and architecture are tailored specifically to embedded applications, so overhead and intrusiveness are minimal. STRIDE’s target components consume very little memory and can be configured to run at lower priorities. Similarly, tracing overhead is minimized by collecting raw data on the target, and uploading tracing information at a very low priority task to the host for processing.

If tight real-time constraints are a concern, STRIDE also supports target-resident test code, which minimizes transactions or overhead over the transport. In this case, STRIDE provides a framework for automating and managing the execution of the on-target test code, and publishing the test results.

[[Category:FAQ]]

Studio:What up-front integration is required to begin using STRIDE?

2007-11-29T00:10:05Z

Andreo:

To support remotely accessing function calls, the STRIDE Runtime and Platform Abstraction Layer (PAL) components must be integrated into the target environment, including support for the available transport. S2 already has pre-ported or reference PALs available for many popular embedded RTOSes. In this case, there is only a few days of integration and verification work.

For custom or new OSes, implementing a PAL takes only a few extra days. A new PAL involves implementing 10 – 12 well-defined primitive interfaces, based on common OS services. In either case, S2 is generally involved with this process in order to ensure proper integration.

If the software architecture includes a messaging subsystem, then a custom remote message server (RMS) component is also required. S2 generally undertakes this work and delivers, integrates, and verifies the RMS with the customer. The scope of the RMS varies depending on the complexity of the messaging subsystem.

[[Category:FAQ]]
[[Category:Getting Started]]

Studio:What other techniques does STRIDE support to generate test cases?

2007-11-29T00:07:18Z

Andreo:

STRIDE’s built-in tracing provides record-and-playback capabilities, which can be leveraged to record a sequence of transactions across application interfaces, then reproduce or replay a certain scenario. This technique can also be used in conjunction with test equipment or to capture certain field conditions.

[[Category:FAQ]]

Studio:Why use a scripting language?

2007-11-29T00:05:43Z

Andreo:

Due to their interpretive nature, scripting languages are very dynamic and flexible. Test applications can be quickly implemented through scripts, and these tests can be modified, added, or deleted without requiring time-consuming target software builds. Also, for regression and continuous integration, scripts can be easily automated and executed without constantly requiring new test code to be downloaded or unloaded from the target, which in many cases is impractical or impossible.

[[Category:FAQ]]
[[Category:Scripting]]

Studio:How does STRIDE know about my APIs and messaging interfaces?

2007-11-29T00:02:53Z

Andreo:

STRIDE learns about APIs and messaging interfaces through the header files of embedded applications. To clarify ambiguities in complex interfaces, developers add pragma statements (SCL) to further specify the characteristics of interfaces and data types. STRIDE compiles through these header files and builds an XML database of the application interface signatures. These application interfaces are now remotely available to the developer through STRIDE.

[[Category:FAQ]]
[[Category:SCL]]

Studio:What software development challenges result from increased complexity?

2007-11-28T23:59:58Z

Andreo:

In working with large embedded software engineering organizations, S2 has observed that '''verifying and integrating embedded software components''' becomes a serious challenge as software complexity increases. As more features and functionality are designed into a product, more software components need to be integrated and verified. Common software strategies, such as distributed development, outsourcing, leveraging expert contractors, and third-party software, further contribute to complexity. The difficulty of integrating so many different software components, developed by so many different people, across various geographies and time zones, have a severe impact on the development process.

Ad hoc or manual approaches to software testing have become tedious and ineffective. Likewise, traditional test harness-based approaches are too difficult and limiting to apply across-the-board to embedded development. As a result, the Product Test or System Test organization is often the first to extensively exercise and vet the software as an integrated whole, and thus they detect a disproportionately high volume of defects. This wreaks havoc on the development process, leaving software engineers to face the daunting challenge of fixing an overwhelming number of defects to meet their deadline. This scenario typically results in:

* Extra test cycles and resources, adding unplanned development time and costs
* Missing or dropped features, as a tradeoff to meeting tight deadlines
* Compromised quality, hurting reputation and revenues
* Delayed product releases, resulting in competitive losses