Posix SDK

Introduction

The Linux SDK is a platform-specific package that contains the STRIDE Runtime source and 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 STRIDE Runtime library and two executable applications - a strideDaemon (for a multiprocess application environment), and an TestApp (for running the STRIDE diagnostics tests - see Using a Platform SDK for more information).

The default make target builds the STRIDE Runtime library. When a multiprocess runtime library is specified (see RTSINGLEPROC below), and a strideDaemon executable build as well. To build the test application, specify the testapp make target.

The testapp 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 diagnostics tests or the Linux Baseline Application Integration on how to integrate the diagnostics 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, set to 1, compiles the runtime library with no multiprocess support. If you want multiprocess functionality, you can enable this by explicitly setting this value to 0.

STANDALONE_TESTAPP

The default configuration, set to 1, builds the TestApp as a standalone application. When set to 0 the TestApp is built as a multiprocess application.
The STANDALONE_TESTAPP variable is affected by the value of RTSINGLEPROC. If RTSINGLEPROC is 1 and STANDALONE_TESTAPP is 0, this is an invalid combination and STANDALONE_TESTAPP will automatically be set to 1.

S2SCOPTS

The STRIDE build process that produces the database and Intercept Module for the test application 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 and 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, void* param)

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 for intercept module entry point functions. Only the IM name must be provided.

void strideStopThread(srDWORD id)

Signals a thread to stop (sends palSTOP_EVENT) and joins it.

void strideExWaitForExit(void)

This function can be called by the main application thread to block until a termination signal (SIGTERM) 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.

#include <stdlib.h>
#include <unistd.h>
#include <stride.h>
#include <myinterceptIMEntry.h>

int main(int argc, char **argv)
{
    /* optionally daemonize your application */
    strideExDaemonize(NULL, NULL);

    /* initialize the STRIDE subsytem using default I/O */
    strideIO_t io = {strideIO_t::strideDEFAULT};
    if (strideInit(&io) != srTRUE)
        return -1;

    /* start all IM threads */
    if (strideCreateIMThread(myintercept) != srTRUE)
        return -1;

    /* block until a termination signal is received, omit if not needed */
    strideExWaitForExit();

    /* stop all IM threads and uninitialize STRIDE subsystem */
    strideUninit();
    return 0;   
}

This sample code assumes you have generated your Intercept Module with a prefix name of myintercept.

NOTE: If you need to provide additional message processing threads, you can call strideCreateThread() for each additional thread that you wish to add (this must be called prior to strideExWaitForExit()).

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.

#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;   
}

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_SOCKET_TRANSPORT

if defined, TCP 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_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_TIMER_SIGNAL

signal to use for timer expiration.

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.

PAL_HAVE_PTHREAD_PROCESS_SHARED

the C runtime in use supports PTHREAD_PROCESS_SHARED mutex attribute. Only needed if multiprocess support is enabled in srcfg.h.

PAL_SYSV_SEM_KEY_INIT

SYS V semaphores key generation initialization id. Only needed if multiprocess support is enabled in srcfg.h.

Makefile Targets

The makefile included with the SDK supports the following targets:

all

builds the runtime library and daemon

library

builds the runtime library

daemon

builds library and--if RTSINGLEPRC is not zero--the STRIDE daemon

im

builds the STRIDE database and generates IM files

testapp

builds library, im and instrumented test application

clean

removes all generated files