Runtime Integration

Overview

This page discuses the first step in an overall STRIDE integration effort. 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
• Add steps to your target build process to:
  • Run the STRIDE Build Tools as a pre-compilation step, and
  • 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 Linux and Windows, included as palcfg.h, palIO.c and palOS.c in their respective SDKs. Other PALs are also available or under development. Please contact S2 for availability.

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 Sources

The STRIDE Runtime sources are distributed in source form. The source files are available as a stand-alone package and are also included with each flavor of SDK package.

The runtime sources are supplied in three directories:

GRS

Generic RTOS Services

Runtime

STRIDE Runtime

SLAP

Simplified Link-layer Application Protocol

Files in each of these 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 STRIDE 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, and variable arguments (va_list, va_start, va_end...)

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

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_VAR_ARGS=<0|1>
-DsrCPP_HAS_NAMESPACE=<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 Platform SDKs 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 */
  strideIO_t io = {strideDEFAULT};
/* for C++ use
  strideIO_t io = {strideIO_t::strideDEFAULT};
*/
  if (strideInit(&io) != srTRUE)
    return -1;
 
  /* start any IM thread */
  ...

  /* target application code here */
  ...
 
  /* block until a termination signal is received, omit if not needed */
  strideExWaitForExit();
 
  /* 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:

/* 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 */
  ...

  /* block until a termination signal is received, omit if not needed */
  ...

  /* 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), and 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: 4.1.xx
Disconnecting from device...