Release Note
MPI-RTX/RTSS Package

Introduction

Welcome to the MPI-IntervalZero Real-Time Subsystem (RTSS) Support Library. The distribution was built with Visual C++ 6.0 and tested using Visual C++ V6.0. The MPI library has been ported to support the IntervalZero RTX/RTSS run-time environment version 6.5 with Windows XP only.

RTX/RTSS System Requirements

Operating Systems
The MPI-RTSS release is built to operate on Windows XP.

Visual C++ DLLs
The MPI-RTSS is built using Microsoft Visual C++ V6.0. No Microsoft Visual C++ DLLs are included with this release. The following libraries are required in order to build the MPI-RTSS library:

MPI/XMP Library
The MPI-RTSS Support package, must be used with a compatible MPI Win32 release version. See MPI Version Numbering.

RTX/RTSS DLLs
IntervalZero RTX/RTSS support has been tested on the 6.5 Release. This release assumes that RTX has already been installed. The following RTSS libraries and object files must be installed to build RTSS programs:

Debugging
There are both Debug and Release versions of the MPI-RTSS libraries. MPI-RTSS test applications can be debugged using either the Microsoft’s WinDbg.exe or NuMega’s SoftICE debugger according to the set up instructions provided by IntervalZero.

Limitations

Shared Interrupts

WARNING! Shared interrupts among ZMPs are supported with this release. However, it is required to verify the IRQs used by the ZMPs are not used by any other Windows device. Use the Device Manager (found in Control Panel -> System -> Hardware -> Device Manager) to view the resources by type. Check to make sure that the Motion Controller does not share interrupts with any other devices.

MPI RTX and Windows Applications

WARNING!
Do NOT run MPI Windows applications and MPI RTX applications simultaneously. The MPI library and the RTX library are two independent libraries. Interrupt handling, controller reset, semaphore protection, and controller read/write access is NOT supported across the RTX and Windows platforms simultaneously. If you run MPI Windows and RTX applications simultaneously, unstable and unpredictable behavior may result!

Installing the Distribution on the Host System

The MPI-RTSS installation consists of an InstallShield base distribution. All files are installed into the new subdirectories: mei\xmp\lib\WinRTSS and mei\xmp\app\WinRTSS. Key components of the distribution are:

Installation Procedure

WARNING!
If you are upgrading from a previous MPI software release, you will need to remove or archive all previous releases. This will prevent any conflicts between old and new files. To remove the previous MPI software release, select Start -> Control Panel -> Add/Remove Programs. Select the MPI Development Toolkit entry and click on the Add/Remove button. NOTE: The MPI software release can also be removed by running the MPI InstallShield and choosing the remove option.

Installation Steps

Install the appropriate MPI and RTSS sofware releases.

To startup the RTSS environment and verify basic operation, follow the steps below:

Command Line Program Execution

To execute the program coffee from the command line, after Step 6:

If there are any problems with building or execution of the sample applications, verify that the RTX/RTSS libraries are properly installed in the locations being used by Microsoft Visual C++.

The above procedure is based upon a standard installation of RTX into C:\MEI. If it was installed elsewhere, make the appropriate changes in the Project settings.

General Change History

There are two component parts to the MPI-RTSS: a Windows Application and an RTSS DLL. All RTSS applications, which access the RTSS DLL, must be executed after the DLL is already running. The RTSS DLL must be invoked with the Windows Application mpiInit.exe.

The RTSS DLL assumes a single version of the library is executing at any given time. The RTSS DLL subsumes system resources from the driver and all MPI interrupts are processed by the RTSS subsystem.

CAUTION
RTSS and standard Windows processes should NOT be executed at the same time,
although some processes are permissible. Procedures that generate interrupts from the XMP can cause unpredictable system behavior and should not be attempted.

MPI Static Library

A MPI Static library was added in version 20000913 to the WinRTSS release. The utility mpiInit.exe should be used with the -static command-line option to avoid from loading the WinRTSS support DLL into memory. The new static library is located at (C:\MEI)\XMP\lib\WinRTSS\debugStatic\mpStatic.lib.

RTX Interrupt Priority

Version 20000802 added the ability to set the RTX interrupt priority for the XMP interrupt vector. The RTX shared memory data structure passes the priority to platform.c from mpiInit.c. The priority is a commandline option of xmp\bin\winrtss\mpiInit.exe. The new syntax is:
      mpiInit (-priority #)
where # is any number from 0 - 127. By default the priority level is set to the highest priority level possible in RTX, which is RT_PRIORITY_MAX (127).

MPI-RTSS DLL

The MPI-RTSS DLL provides an interface to the XMP controller under RTSS. It executes from within the RTSS process environment and provides a real-time environment under Windows.

The MPI-RTSS interface to the MPI/XMP DLL is similar to the standard Windows version, but certain functionality is not supported under IntervalZero. This includes:
       - Keyboard input
       - Interfacing to device drivers directly (devIoControl())
       - Various C-library and Win32 API functions.
Please refer to the IntervalZero documentation for a complete list of supported functionality.

IntervalZero Modifications to Windows HAL (Hardware Abstraction Layer)
IntervalZero has modified the Windows HAL (Hardware Abstraction Layer) which provides the main interface between the hardware and Windows. The RTSS intercepts all interrupts from the hardware prior to passing them onto the Windows kernel.

RTX Starvation Timeout
The RTSS environment provides its own scheduler which schedules RTSS applications before Windows processes get scheduled – hence the opportunity to starve Windows processes. It is important to configure the RTSS with an appropriate starvation timeout value so that RTSS processes behave accordingly.

If the execution of a RTSS process exceeds the starvation timeout limit, assuming one is provided (it can be disabled), the RTSS process will be terminated by RTSS. Hence, not exceeding this timeout limit (or disabling it) is very important when performing system intensive real-time processing.

To adjust the RTX Starvation Timeout:

Communication between Win32 and RTSS Applications
RTX (Real-Time Extensions) supports communication between Win32 and RTSS applications.

This allows for the MPI-RTSS DLL to interface with a Win32 application, mpiInit.exe, responsible for communicating with the meixmp device driver and providing base initialization parameters. The program mpiInit.exe must be used to correctly invoke the MPI-DLL. The MPI-RTSS DLL, mpiDLL.rtss, builds two configurations:
      - Debug – multi-threaded
      - Release – multi-threaded

mpiDLL.rtss is not a Windows DLL, but an RTSS application with external entry points. The IntervalZero model provides for this type of RTSS application. The MPI-RTSS DLL has external entry points for all of the current MPI/XMP library functions. It may be called from any .rtss program which links with its library, mpiDll.lib. Note: for any .rtss program to access RTSS-DLL functions, mpiDLL.rtss must be running.

MPIInit (mpiinit.exe)

Since RTX does not provide direct access to Windows device drivers, the mpiInit.exe program has been developed to interface with the meixmp device driver when starting up the MPI-RTSS DLL.

The mpiInit.exe utility provides various functions:

The mpiInit.exe utility should be used with the -static command-line option to avoid from loading the Win- RTSS support DLL into memory. The new static library is located at (C:\MEI)\XMP\lib\WinRTSS\debug-Static\mpiStatic.lib.

The mpiDLL.rtss communicates with the meixmp Windows device driver. The
Windows device driver is still active while the MPI-RTSS DLL is executing, but the Windows driver no longer receives interrupts from the XMP controller, since these interrupts are now being intercepted by the RTSS.

Running XMP support utilities under RTX
The Windows driver is still available to communicate with the XMP or operate in a non-invasive mode while RTSS processes are executing, in certain LIMITED cases (MPI/XMP support utilities), noted below:

this makes MPI/XMP support utilities available (such as reset, flash and vm3).

The interface to mpiInit.exe is as follows:
         C:> mpiInit
For the example above, the appropriate directories and paths must be provided.

There are two versions of mpiInit.exe – debug and release. There is no explicit tie between the debug and release versions of mpiInit and the debug and release versions of mpiDll.rtss, and hence either version of mpiInit can invoke any version of mpiDll.rtss.

MPI/XMP Sample Applications

This release installs .dsw files for building the sample applications under Microsoft Visual C++ V6.0.

The .dsw files provide an interface to build from the command line using nmake –f file.dsw where file is the name of the makefile for the specific application.

The following applications have been tested to properly execute under the RTSS environment:

meiPlatformKey()
The funciton meiPlatformKey() normally waits for any key on the user’s keyboard to be pressed. However, in RTSS, meiPlatformKey() can be executed in one of two modes: MPIWaitFOREVER and MPIWaitPOLL.

The semantics have been modifed so that meiPlatformKey(MPIWaitFOREVER) returns after 10 seconds and meiPlatformKey(MPIWaitPOLL) returns after it has been called 10 times.

Application Thread Stack Size

MS Visual Studio projects for RTX have 8192 bytes allocate for the default stack size. Applications that make calls to the MPI should configure the stack allocation Reserve and Commit to 0x20000 (128 kByte) in the Project Settings:

Create Thread Stack Size

If you are using CreateThread(...) to launch a thread that will make calls to the MPI library, be sure to specify an appropriate stack size. We recommend configuring the stack size to 128 kBytes (0x20000 bytes) for the MPI library. If you do not allocate enough stack space, RTX may fail with stack overflow errors or Green Screen (GSOD) non-recoverable exception errors.

Please consult the RTX documentation for details about CreateThread(...) and stack size configuration.

Known Bugs and Issues

RTSS Resets the Machine
If an MPI application, running under Windows generates any interrupts, running mpiInit.exe will lock-up and reboot the host computer. This can be avoided by rebooting the host machine before running mpi- Init.exe after any Windows mpi Applications have been run. Motion Console and Motion Scope will not effect the execution of mpiInit.exe.

Support of File and Device I/O
RTX allows two options for file input and output (I/O). You can write to the supported file I/O functions in the Win32 API or to the supported file I/O functions in the C run-time library. The API delivers low-overhead, fast access to Windows file I/O capabilities using standard APIs. A subset of CreateFile flags are supported with file I/O. Please refer to the Reference Guide for more details. File I/O does not include support for asynchronous file operations.

Because RTSS applications have no current-directory notion, RTSS file I/O requests must use fully qualified path names, such as:

      c:\temp\MyFile.txt (for a file system object)

      \\.\MyDevice0 (for a device object)

RTSS file I/O calls are made from the Windows kernel environment: RTX actually translates Win32 names such as c:\MyFile.txt and \\.\MyDevice0 to Windows internal names \??\c:\MyFile.txt and \Device\MyDevice0, respectively. Therefore, you can use Windows internal names from your RTSS applications, although such calls fail in Win32. Using an internal Windows name lets you access a device object for which Win32 has no symbolic link, such as \Device\beep or \Device\Harddisk0\Partition1\testfile.txt.

With boot-time file I/O, you may only use paths such as \\Device\\Harddisk0\\Partition1\foo.txt because paths such as \\??\\C:\\foo.txt and C:\\foo.txt are not supported.

WARNING!
The RTSS API cannot be used to create or open files over a network. The path should be set to a file location on the local hard drive or other local device. If you try to access files over a network from RTX, the MPI will return a "File Open Error."