Release Note
MPI-RTX/RTSS Package

	Current Version
RTX/RTSS Version	7.1
MPI Version	03.04.15

Introduction

Welcome to the MPI-Ardence 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 Ardence RTX/RTSS run-time environment version 7.1 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
Ardence RTX/RTSS support has been tested on the 7.1 Release. This release assumes that RTX has already been installed. The following RTSS libraries and object files must be installed to build RTSS programs:

rtapi_rtss.lib
rtx_rtss.lib
w32_dll.lib
startCRT.obj

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

Limitations

Shared Interrupts

WARNING!
Shared interrupts are NOT supported with this release. Make sure your system is NOT sharing IRQs for the motion controller. 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 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:

Release and debug versions of the MPI-RTSS DLL’s and the associated startup file mpiInit.exe. The DLL’s are installed in mei\xmp\lib\WinRTSS in the subdirectories: Release, Debug, ReleaseStatic and DebugStatic. The files mpiInit.exe & mpidll.rtss are installed in mei\xmp\bin\Win-RTSS.
The project makefile for the MPI/XMP Sample applications for Microsoft Visual C++ V6.0. This makefile, app.dsw, is installed into mei\xmp\app\WinRTSS.
A valid installation of the appropriate version the MPI/XMP.

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.

Install the MPI-WinNT (Windows 2000/XP) software
To install the MPI-WinNT software, insert the MDK CD-ROM or download the installation package from the FTP site. Contact Kollmorgen Sales for login, filenames, and passwords. To start the set-up process, click on xx.xx.xx_WinNTSetup.exe. Follow the InstallShield instructions. The InstallShield will take care of installing the DLL and will also set the PATH environment variable to XMP\bin\WinNT for WinNT, XMP\bin\Win2000 for Win2000, and XMP\bin\WinXP for XP under the default installation directory.
Install the MPI-RTSS software
To install the MPI-RTSS software, download the installation package from the FTP site. Contact Kollmorgen Sales for login, filenames, and passwords. To start the set-up process, click on xx.xx.xx_WinRTSSx.xSetup.exe. Follow the InstallShield instructions. The InstallShield will take care of installing the RTSS libraries, sample apps, and utilities. Be sure to install the MPI-RTSS into the same directory (default is C:\mei) that the MPI-WinNT was installed. Also, make sure to use the same version xx.xx.xx for the MPI-WinNT and MPI-RTSS installations.

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

After installing RTSS (using the InstallShield), verify that the device driver is running.
Go to the Start->Settings->Control Panel window, click on System->Hardware tab->Device Manager. To verify that the driver is running, click on the Motion Controller icon. An XMP Motion Controller should be listed under Motion Controller.
Start up the MPI-RTSS DLL
Open the C:\mei\xmp\bin\winRTSS subdirectory and double-click on mpiInit.exe.
This will open the RTX/RTSS Console.
You can also verify the mpiDLL.rtss is running via the RTX SDK->RTX Tools->RTSS Task Manager.
From Microsoft Developer Studio, select Open Workspace and browse to C:\mei\xmp\app\WinRTSS
In the Files of type field, select Workspace file (*.dsw), then select app.dsw.
Verify that the directories have been set up to build with the Ardence library and include files, by selecting Tools->Options->Directories and adding:
Include Files – C:\Program Files\Ardence\RTX SDK\Include
Lib Files – C:\Program Files\Ardence\RRX SDK\Lib
In Microsoft Visual C++, set the current configuration to coffee and build it.
To execute the program coffee, use the rtssrun utility to launch the task from the command prompt. Please see the following section.

Command Line Program Execution

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

Open an MS-DOS command window.
Type: C:\> cd mei\xmp\app\WinRTSS\coffee\Release
Type: C:\mei\xmp\app\WinRTSS\coffee\Release> rtssrun coffee.rtss
coffee.rtss can also be executed from Explorer by navigating to the directory
C:\mei\xmp\app\WinRTSS\coffee\Release and double-clicking on coffee.rtss.

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 Ardence. This includes:
       - Keyboard input
       - Interfacing to device drivers directly (devIoControl())
       - Various C-library and Win32 API functions.
Please refer to the Ardence documentation for a complete list of supported functionality.

Ardence Modifications to Windows HAL (Hardware Abstraction Layer)
Ardence 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:

Go to Settings->Control Panel from the Start Menu in Windows. Open the Control Panel window.
Double-click on RTX Settings. A dialog box will display the RTX Dialog box.
Either click the Disable check-box, or enter the appropriate value into the Starvation Timeout entry box.

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 Ardence 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:

Invoking mpiDLL.rtss under RTSS
Providing initialization information
Informing the device driver that it is going into a standby state
Automatically setting RTX interrupt priority for the XMP interrupt vector

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:

reset program
flash program
VM3 program
Motion Console
Motion Scope

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:

coffee.c
motion1.c
motion2.c
event1.c
event3.c

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

Release Note MPI-RTX/RTSS Package