Runtime Integration

Overview

This page discusses the first step in an overall STRIDE framework integration. The ultimate goals are to extend your target build process to:

• Incorporate the STRIDE Runtime source files in your target build
• Configure compiler settings
• Add code to target source to start and stop STRIDE runtime threads
• Incorporate the STRIDE Build Tools in your make process as a pre-compilation step

Here we incorporate the STRIDE Runtime in your target application build without tests. In the second and last step, we add the STRIDE Build Tools to the mix and hook up the test-running harnessing.

After building the target with the STRIDE Runtime in place, we will run stride from a remote host computer to verify connectivity and runtime operation.

Recommendations

The STRIDE target environment offers lots of flexibility to accommodate different target scenarios. For an initial target integration, we recommend that you pursue the simplest STRIDE configuration that will yield results. Once this configuration is successfully integrated you can make adjustments as desired.

Integrating STRIDE Into Your Target Build

To add the STRIDE Runtime to your build process, the following changes must be made:

• Secure a PAL targeted to your target operating system
• Configure the PAL I/O parameters to conform the your target hardware
• Include the STRIDE runtime source files in the software build
• Edit your target application's source code to start the runtime and I/O thread(s)

Securing a PAL

The Platform Abstraction Layer (PAL) provides the glue between the STRIDE Runtime and services offered by your OS. It is the only piece of the runtime that is customized between operating systems.

Fully tested PALs are provided for Posix and Windows, included as palcfg.h, palIO.c and palOS.c in their respective SDK.

Configuring PAL I/O parameters

If your target will communicate with the host computer via the default of TCP/IP port 8000, you can skip this step.

Otherwise, refer to palcfg.h that comes with your PAL for a list of configuration parameters.

Including the STRIDE Runtime

The STRIDE Runtime is distributed in source form. The source files are included with each SDK under "Runtime" directory. Files in that directories should be included in your target build.

If you are using an S2-supplied SDK, additional required sources can be found in the SDK's src directory:

• PAL implementation
  • palcfg.h
  • palIO.c
  • palOS.c

• Convenience functions (these wrap low-level PAL/Runtime calls)
  • stride.c
  • stride.h

• Build script
  • Makefile

The build script (Makefile) supplied with an SDK allows building of the runtime source into a library that could then be linked with the target application.

C/C++ Feature Support

By default the C source in the Runtime was written with the presumption that the target C compiler and C Runtime (CRT) library supports wchar_t, long long, long double, safe snprintf, and variadic macros

By default the C++ source in the Runtime was written with the presumption that the target C++ compiler can handle namespaces and exceptions.

If desired the user can specify different configuration by using -D compiler options:

-DsrCRT_HAS_WCHAR_T=<0|1>
-DsrCRT_HAS_LONG_LONG=<0|1>
-DsrCRT_HAS_LONG_DBL=<0|1>
-DsrCRT_HAS_SNPRINTF=<0|1>
-DsrCRT_HAS_VA_ARGS=<0|1>
-DsrCPP_HAS_NAMESPACE=<0|1> 
-DsrCPP_HAS_EXCEPTION=<0|1>

where 0=disabled and 1=enabled.

STRIDE Feature Control

Any application's source file referencing STRIDE source should be compiled with addition STRIDE_ENABLED switch (preprocessor directive):

cc -DSTRIDE_ENABLED=1 file.c

The definition of the STRIDE_ENABLED macro controls all STRIDE-related sources and macros. If undefined (or defined as zero), STRIDE-related sources are excluded and STRIDE-related macros are left undefined. This provides a simple means of including and excluding test-related entities in your production build.

Target Source Changes

Your target source must be edited to include code that initializes and uninitializes the runtime. The code is typically added to your main() function, but the only requirement is that the initialization takes place before the host computer connects and the uninitialization occurs before the process terminates.

Please refer to the standard pre-packaged SDK for examples of a startup sequence. Briefly it should be something like:

/* STRIDE runtime includes */
#include <stride.h>
 
int main(int argc, char **argv)
{
    ...
 
    /* initialize the STRIDE subsytem using default I/O */
#ifdef __cplusplus
    strideIO_t io = {strideIO_t::strideDEFAULT};
#else
    strideIO_t io = {strideDEFAULT};
#endif
    if (strideInit(&io) != srTRUE)
        return -1;
 
    /* start any IM thread */
    ...

    /* target application code here */
    ...
 
    /* stop all STRIDE threads and uninitialize STRIDE subsystem */
    strideUninit();

    return 0;   
}

If you implement a custom PAL then here is an example of the startup code using direct PAL and STRIDE Runtime API calls instead of the stride.c/.h wrappers provided by the SDK:

/* STRIDE runtime includes */
#include <palcfg.h>
#include <sr.h>

int main(int argc, char **argv)
{
    palDWORD dwRTNID;

    ...

    /* initialize the PAL handler */
    if (palOSInit() != palTRUE) 
        return -1;

    /* initialize the PAL IO handler */
    if (palIOInit(PAL_DEFAULT_DEVICE_NAME) != palTRUE) 
    {
        palOSUninit();
        return -1;
    }

    /* initialize STRIDE Runtime */
    if (srInit() != srOK)
    {
        palIOShutdown();
        srUninit();
        palOSUninit();
        return -1;
    }

    /* start the Runtime thread first */
    palDWORD dwRTNID = /* create thread with function srThread() */;
    if (dwRTNID == 0) 
    {
        palIOShutdown();
        srUninit();
        palOSUninit();
        return -1;
    }

    /* start any IM thread */
    ...

    /* target application code here */
    ...

    /* stop all IM threads */
    ...

    /* stop Runtime thread */
    palNotify(dwRTNID, palSTOP_EVENT);

    /* uninitialize STRIDE subsystem */
    palIOShutdown();
    srUninit();
    palOSUninit();

    return 0;   
}

Testing the Runtime Integration

Once the instrumented target is successfully built, start the target application. On a separate host computer, connected to the target via TCP/IP (or serial port if so configured), run stride as follows (substitute the --device option argument as needed):

stride --diagnostics --device=<device_address>

By specifying --diagnostics without also specifying a database, we instruct stride to test for connectivity with the target.

If all is well, the following will be output to the host window (the reported runtime version may be different than that shown):

Connecting to device...
  runtime version: 5.x.yy
Disconnecting from device...