Migrating from the MPS800 to the MPS1000 Multi-Protocol Server Support Page

  • Overview
  • Getting Started
  • Compiling the Application  
  • Two Kernel Spaces Facilitate Testing and Application Development  
  • Client Utilities  
  • Download Program (wcpLoad)  
  • Events Monitor Program (eventsClient)  
  • Nwsl Command Line Interface Utility (nwslCli)  
  • Nwsl Copy Utility (nwslCp)  
  • Conclusion

    OVERVIEW

    Moving an existing MPS800 application to the MPS1000 architecture adds many benefits including feature rich hardware, increased port density as well as increased redundancy options. This document will outline the changes necessary to update an existing MPS800 application to be compatible with both the MPS800 and MPS1000.

    One of the benefits provided through the Performance Technologies WAN protocols is the MPSapi, which is platform independent and isolates the programmer from the underlying hardware. The MPSapi interface is utilized with both the MPS800 and MPS1000 platforms, enabling quick application migration.

    The paragraphs that follow will outline steps to help migrate your Performance Technologies WAN protocol based applications from the MPS800 to the MPS1000.

    GETTING STARTED

    Customers reading this Support Guide Document are likely running an older version of a Performance Technologies WAN protocol (X.25, HDLC, Radar, or others) with the MPS800. Over the years the protocols have evolved, in many cases providing additional functionality that client applications must account for in order to be compatible with the updated WAN protocol suite.

    As with the MPS800, the MPS1000 is initially configured via a serial terminal connection through its system console port. The default settings for the MPS1000 can be found in the NexusWare® WAN Configuration Guide that is supplied on the protocol software CD.

    By default the following well known ports are defined in the MPS1000 services database and these ports must also be defined within the Host system’s services database:

            mps             48879/tcp         # TCP normal mode
            mpsxk         48880/tcp         # mpsx000 daemon
            mpsctl         48881/tcp          # mpsx000 control channel
            mpssftrst     48882/tcp         # mpsx000 soft reset daemon

    The following examples assume that the Host system’s hosts file also be updated with an entry to relate the mps1000 host name to the MPS1000 system’s IP address.

    The WAN Protocol software development environment must be installed on the Host system from the provided WAN Protocol CD as detailed in the Software and Hardware Installation Guide. As with the MPS800, a privileged account on the Host system is required in order to install the WAN Protocol software development environment. Once the WAN Protocol software is installed properly, the utilities and sample applications may now be used to connect to the MPS1000.

    The initial validation is performed through the commstats utility, as it will exercise the MPSapi and verify Ethernet connectivity to the MPS1000. The commstats utility will also provide useful information on the MPS1000 and the WAN Protocol software executing on the controller:
     

            # ./bin/commstats -s mps1000

            System Report for Server mps1000, Controller: 0

            Product code for kernel: PTI Kernel Image: RDR 810P0720.31 RC02
            The date is Thu Mar 27 07:39:18 2008
            Current system kernel version 2.6.12
            System has been alive 0 hrs 2 mins 37 secs
            Total system memory 122142720 bytes
            Free system memory 76169216 bytes
            Used system memory 45973504 bytes
            Running Kernel 0
            Vendor Id: 0x1214, Device Id: 0x3580
            Board serial number: 333762
            Geographic Address: 1
            IP device information:
                    eth0 -> IPv4 addr:147.139.241.145 Mask:255.255.255.0
                    IPv6 addr: fe80::2c0:8cff:fe18:de1d
            electrical interface per port:
                    0 - RS232 1 - RS232 2 - RS232 3 - RS232
                    4 - RS232 5 - RS232 6 - RS232 7 - RS232

    Refer to the Protocol User’s Guide contained on the software CD to run the sample applications provided with the software.

    Note: The electrical interfaces of the MPS1000 ports are software programmable via the MPSapi; whereas the MPS800 electrical interfaces are configured via hardware switch settings. Thus the MPS1000 requires a new bind parameter that specifies the selection of the electrical interface i.e. RS232, V.35, RS530 etc. Please consult the manual specific to the WAN protocol (HDLC, X.25, etc) for complete details in use on your system.

    COMPILING THE APPLICATION

    As with the MPS800, Performance Technologies provides the software library source and utilities necessary for the host side software to access the MPS1000. As stated previously, the newer WAN Protocol software contains product enhancements as well as feature updates which in some cases has led to updated structure definitions within the MPSapi. This requires older applications to be rebuilt using the updated MPS Protocol development environment’s library and header files.

    The MPSapi remains consistent across the MPS800 and MPS1000 platforms. A single host application may interface to both the MPS800 and the MPS1000. In order to ensure MPS800 compatibility with the rebuilt application the WAN Protocol modules that are downloaded and executed on the MPS800 should be based on the same core modules that are executing on the MPS1000. The version.txt file provided with both the MPS800 and MPS1000 software will provide a quick reference to the revision of the modules that comprise the two software releases. The release notes can be found in the /usr/pti/config directory, which will detail the changes made.

    The following section provides an example of migrating an existing MPS800 application, which interfaces to the MPSapi HDLC protocol, so that it may run on the MPS1000. This example is based on the original (MPS800) HDLC sample application.

    First the old application source is copied into the new WAN protocol development environment:

            # cd /usr/pti/hdlc
            # mkdir old_client
            # cp /<old installation directory>/hdlc/client/* old_client

    Note: Only the (sample) application files should be copied into the new WAN Protocol development environment, as the new WAN protocol development environment header files and MPSapi library must be used for the build process.

    Using the sample applications provides the benefit where the diff command may be used to determine the changes that will need to be incorporated into any existing applications:

            # diff old_client/hdlcrecv.c client
            1c1
            < /* @(#) hdlcrecv.c 03/05/06 Version 1.54 */
            ---
            > /* @(#) hdlcrecv.c 07/07/16 Version 1.62 */
            84a85,88
            > 27. 13-Nov-06 kls Added support for QNX6.
            > 28. 08-Jun-07 hhn Added support for timestamp options.
            > 29. 10-jul-07 hhn Multi Thread hooks in place.
            > 30. 16-jul-07 kls Added actualBaud bind parameter.
            …

    First the old example applications are rebuilt without making any changes. This yields the results:

            # cd old_client
            # make clean; make solaris
            rm -f htest hdlcrecv hdlcsend hfull *.o
            /opt/gnu/bin/gcc -I../../include -I../include -c hdlcutils.c
            hdlcutils.c: In function `hdlc_response':
            hdlcutils.c:191: `MAX_STATUS_VAL' undeclared (first use in this function)
            hdlcutils.c:191: (Each undeclared identifier is reported only once
            hdlcutils.c:191: for each function it appears in.)
            hdlcutils.c: In function `hdlc_open':
            hdlcutils.c:510: `MAX_STATUS_VAL' undeclared (first use in this function)

    From review of the updated hdlcutils.c application one can find the following change notice:

            8. 25-jul-06 mpb Make our 'MAX_STATUS_VAL' unique since mcc_api.h has
                                       its own #define for that.

    This has been defined in the updated hdlchdr.h header file:

            # grep MAX_STATUS_VAL ../include/*
            # define WAN_MAX_STATUS_VAL 12 /* Max status value */

    After the old application is changed to use the new define, the compilation is successful as shown below,

           # make clean
           rm -f htest hdlcrecv hdlcsend *.o
           # make linux
           make[1]: Entering directory `/usr/pti/hdlc/client'
           cc -DLINUX -I../../include -I../include -c hdlcutils.c
           cc -DLINUX -I../../include -I../include -o htest \
           hdlcutils.o htest.c -lMPS
           cc -DLINUX -I../../include -I../include -o hdlcrecv \
           hdlcutils.o hdlcrecv.c -lMPS
           cc -DLINUX -I../../include -I../include -o hdlcsend \
           hdlcutils.o hdlcsend.c -lMPS
           make[1]: Leaving directory `/usr/pti/hdlc/client'

    Following successful compilation the (sample) applications may be executed by following the instructions in the appropriate WAN Protocol Software User’s Guide.Testing the MPS800, MPS1000, and then test between the MPS800 and MPS1000, if desired.

    The sample applications are used to demonstrate the use of the MPSapi to send data from the client application on your Host system, to the MPS server (via TCP/IP), out the physical interface, through loopback connectors, back into the MPS server and back to the client application. The received data can be compared against the transmitted data to ensure end to end data integrity. In addition to being used in the above described loopback mode most example applications may also be used to send data between the MPS1000 and the MPS800. This compatibility testing is useful if both servers are to be maintained with the same application.

    Note: Remember that the protocol modules loaded on the MPS800 must be version compatible with the MPS1000 firmware image. You will need to contact Performance Technologies if the MPS800 files need to be updated.

    TWO KERNEL SPACES FACILITATE TESTING AND APPLICATION DEVELOPMENT

    The MPS1000 is more flexible than the MPS800 in that there are two kernel storage spaces. From the factory, the CPC358 controller used in the MPS1000 comes with kernel 0 flashed with the ordered protocol image and kernel 1 is empty. The kernel in use and its loaded image is reported in the commstats command as shown above. Having two kernel spaces can be useful in application development or when doing firmware updates. The newer firmware can be loaded to the second kernel while keeping the original firmware in the first kernel for easy roll back if necessary. Also, in case one kernel gets corrupted the card can still be booted from the other kernel and the corrupted kernel can be easily reflashed using the wcpLoad utility.

    CLIENT UTILITIES

    The new MPS1000 offers expanded utilities that make monitoring and maintaining the WAN software running on the controller much easier. The client utilities are installed in the /usr/pti/bin directory and run from the Host system as client applications. Further explanations of these utilities can be found in the NexusWare WAN Protocol Configuration Guide.

    DOWNLOAD PROGRAM (wcpLoad)

    Firmware updates on the card are a common procedure when Performance Technologies makes enhancements or bug fixes to our protocol stack. Also, customers may want to modify the image on the card, or perhaps an image has become corrupted. The wcpLoad utility allows a new image to be easily flashed down to the card.

    The original image that was flashed at the factory can be found on the CD-ROM in the images directory and can be copied to the utilities directory for flashing. With a 16-port version of the MPS1000 it is important to keep the two controllers in sync with each other. The use of the –n (no reboot) flag should be used to ensure the controller is not reset after the flash is complete. The following command line would flash kernel 1 of controller 1 with the wanStrSer8260.img in verbose mode:

           # ./bin/wcpLoad -c 1 -k 1 –s mps1000 -v -f /wanStrSer8260.img -n
           wcpLoad for controller: mps1000 (0x3580)
           Transfer of PTI Kernel Image: RDR 810P0720.31 RC02 to board in progress.
           Percent Complete 100.0%
           Image file copied to board.
           Board will now be flashed with image file. This may take a while.
           The controller will not be reset at this time. A reset must
           be performed before the new firmware can take affect.

    After flashing both the Secondary and then the Primary controller in a 16-port MPS1000 it is necessary to reset them to activate the changes. This must be done simultaneously; the following command line can be used for this purpose:

           ./bin/wcpLoad -s mps1000 -c 1 –R; ./bin/wcpLoad -s mps1000 -c 0 –R

    EVENTS MONITOR PROGRAM (eventsClient)

    The eventsClient utility uses the MPSapi to monitor all asynchronous events detected by the MPS1000. To start this utility:

    # ./bin/eventsClient -s mps1000

    To exit this utility use ctrl-c.

    NWSL COMMAND LINE INTERFACE UTILITY (nwslCli)

    The nwslCli utility provides “backdoor” access by issuing simple commands line instructions to the MPS1000 over the Ethernet interface. It is the same commands and subsequent replies that would be used as if a console were connected. The only limit of nwslCli is that no more input be required. In other words, a "vi /tmp/foo.bar" would cause nwslCli to wait forever. In any case, press <Ctrl-c> to exit the nwslCli prompt. Here is an example of using nwslCli:

    # ./bin/nwslCli -s mps1000 pti_info all
    Slot Address : 1
    Shelf Address : 31
    Switch Settings : 0x0F
    Board Type : CPC358
    Board Rev : 0
    Build Options : 0 (Rear I/O)
    Baud Rate : 9600
    CPU Type : 8260
    CPU Revision : HiP4_B.1
    CPM Microcode Revision : 0x2D
    System Clock : 66 MHz
    CPU Clock : 231 MHz
    CPM Clock : 165 MHz
    Usable Memory : 120 Mbytes
    Image Load Addr : 0x10000000
    Port A MAC addr : 00:C0:8C:18:DE:1D
    Port B MAC addr : 00:C0:8C:18:DE:9D
    Serial Number : 333762
    Image Identifier : Ser8260 PTI Kernel Image: RDR 810P0720.31 RC02
    Bootcode Revision : 810P065320 Aug 4 2003 11:35:17
    OS Version : 2.6.12
    SM bus enabled : No
    CT Reset master : Yes
    CT Bus master : Yes
    Factory Jumper : 0
    PCI Device ID : 0x3580
    PCI Vendor ID : 0x1214
    PCI Active bit : Yes
    PCI Healthy bit : Yes
    PCI Present bit : No
    PCI Enable bit : Yes
    PCI Memory size : 8 Mbytes
    PCI 66MHz bus : Yes
    PCI-X Mode : Yes
    Last reset reason : User
    CPU number : 1
    Number of CPUs : 1
    Front Ejector Switch : Closed
    bicc : L cksum:3581552736
    scc_drv : L 810s0001.A0-rc12-122709 cksum:2987752798
    fcc_drv : L cksum:3007267197
    smb_drv : L cksum:2045538995
    pcibus : L cksum:2005273792

    The nwslCli show-boot options command can also be used to retrieve kernel information:

    # ./bin/nwslCli -s mps1000 show-bootoptions
    Autoboot : On
    WDOG boot : On
    Diag Boot : Off
    Diag Flag : On
    Boot Addr : 0x10000000 (/dev/kernel0)
    PCI Aperture : 8M
    /dev/kernel0 : 0x10000000 - Ser8260 PTI Kernel Image: RDR 810P0720.31 RC02
    /dev/kernel1 : 0x10C00000 - Ser8260 PTI Kernel Image: MPTTS 815Q0356.12 RC01

    The nwslCli set-bootaddr command can be used to change the kernel that the controller will boot:

    # ./bin/nwslCli -s mps1000 set-bootaddr kernel1
    # ./bin/nwslCli -s mps1000 show-bootoptions
    Autoboot : On
    WDOG boot : On
    Diag Boot : Off
    Diag Flag : On
    Boot Addr : 0x10C00000 (/dev/kernel1)
    PCI Aperture : 8M
    /dev/kernel0 : 0x10000000 - Ser8260 PTI Kernel Image: RDR 810P0720.31 RC02
    /dev/kernel1 : 0x10C00000 - Ser8260 PTI Kernel Image: MPTTS 815Q0356.12 RC01

    Note that now the Boot Address is kernel1.

    NWSL COPY UTILITY (nwslCp)

    The nwslCp utility provides a means of transferring a file to or from the MPS1000 via the Ethernet interface. This utility can be used in getting the messages file when errors are suspected. Here is an example on controller 0:

           # ./bin/nwslCp -s mps1000 -c 0 -v -g /var/log/messages mps1000_c0.msgs

    CONCLUSION

    The first step to updating an application for MPS1000 compatibility is to perform a basic recompile under the updated WAN Protocol development environment. In some cases a few changes may need to be made to an existing application for compatibility with the MPS1000.

    The following items relate to differences of note between the MPS800 and MPS1000

    Multi-threaded applications:

    Older MPSapi – Multi-threaded applications that overlapped reads and writes between threads were tolerated, although data could be lost. This created the situation where the host side application had a potential for crashing.
    Updated MPSapi – Strictly enforces well behaved multi-threaded applications.

    IPv4 and IPv6

    The MPS1000 supports both IPv4 and IPv6 connections and the type of connection is selectable through the updated MPSopen() call (default is IPv4), whereas the MPS800 is IPv4 capable only. The full OpenRequest structure should be zero-ed out before filling in the parameters to ensure that IPv4 is selected (if desired).

    Initial firmware load:

    MPS800 uses TFTP to download its protocol software.
    MPS1000 is factory programmed with the WAN protocol software (field upgradeable via the wcpLoad utility).

    For additional assistance, please contact Performance Technologies at 585-256-0200, or e-mail us at support@pt.com.