  =========================================================================
  
  @(#) $Id: INSTALL,v 0.7.4.3 2001/02/18 09:58:23 brian Exp $
  
  =========================================================================
  
  This README is Copyright (C) 1997-2001 Brian Bidulock.
  
  All Rights Reserved.
  
  Permission is granted to make and distribute verbatim copies of this
  README file provided the copyright notice and this permission notice are
  preserved on all copies.
  
  Permission is granted to copy and distribute modified versions of this
  manual under the conditions for verbatim copying, provided that the
  entire resulting derived work is distributed under the terms of a
  permission notice identical to this one
  
  Since the Linux kernel and libraries are constantly changing, this README
  file may be incorrect or out-of-date.  The author(s) assume no
  responsibility for errors or omissions, or for damages resulting from the
  use of the information contained herein.  The author(s) may not have
  taken the same level of care in the production of this manual, which is
  licensed free of charge, as they might when working professionally.
  
  Formatted or processed versions of this manual, if unaccompanied by the
  source, must acknowledge the copyright and authors of this work.
  
  =========================================================================
  
  Modified $Date: 2001/02/18 09:58:23 $ by $Author: brian $
  
  =========================================================================


                  OPENSS7 STREAMS INSTALLATION INSTRUCTIONS
                  -----------------------------------------

  UNPACKING:

  To begin with, you should have a copy of the tarred and gzipped source in
  the file strss7-0.7.4.tgz  Unpack it with

        tar -xzvf strss7-0.7.4.tgz

  in some convenient place and it will unpack into a strss7-0.7.4 directory.


  COMPILING:

  To build the package, simply change to the unpacked strss7-0.7.4 directory
  and type:

        make

  Make will run a bash configuration script which will check to make sure that
  you have the LiS STREAMS package properly installed on your system and so
  that it knows where to find the necessary LiS include files.  Normally, the
  script just finds things and it will not need to prompt you.  If it cannot
  locate a necessary directory or file, it will prompt you for such things as
  the location of your LiS source directory and library files.

  If there are any compile errors, they are fatal.  You will have to dig into
  the Makefiles and source code if you have a problem.  On a normal Linux
  system, all should go well.

  If there are no errors, make should build all of the necessary modules and
  test programs.
  

  INSTALLATION:

  To run the test programs or load the ss7 stack for applications programs,
  you must first install the modules and development header files.  This can
  be done by merely typing (as root)

        make install
  
  If you don't like doing this a root, either use the -n option to make
  install to see what will happen first, or look at the install targets in the
  toplevel and subdirectory Makefiles.  Make install does four things:

  1)    Copies the openss7 modules to /lib/modules/$(VERSION)/misc and
        /lib/modules/misc.  These modules are

        -rwxr-xr-x  1 root  root  20306 Feb  3 03:54 streams-sdl.o
        -rwxr-xr-x  1 root  root   7286 Feb  3 03:54 streams-sdludp.o
        -rwxr-xr-x  1 root  root  22936 Feb  3 03:54 streams-sdt.o
        -rwxr-xr-x  1 root  root  72442 Feb  3 03:54 streams-sl.o

  2)    Creates several STREAMS character devices in /dev for you such
        as /dev/ss7-sdlupd0.  They all begin with ss7- as follows:

        crw-rw-rw-  1 root  root  252,   0 Feb  3 03:54 /dev/ss7-sdludp0

  3)    Appends character device aliases to your /etc/conf.modules or
        /etc/modules.conf file (whichever exists) to support kmod or
        kerneld automatic loading of the ss7 kernel modules when these
        character devices are opened.  The lines which are appended look
        like:

        alias char-major-249  streams-sls     # driver ss7 sls mux
        alias char-major-252  streams-sdludp  # driver ss7 sdl udp
        alias char-major-251  streams-sdtudp  # driver ss7 sdt udp
        alias char-major-250  streams-sludp   # driver ss7 sl  udp

  4)    Copies the development header files into the /usr/include/ss7
        directory (where you can include them with, say, <ss7/lmi.h>)
        as follows:

        -rwxr-xr-x  1 root  root   1368 Feb  3 05:00 devi.h
        -rwxr-xr-x  1 root  root   5242 Feb  3 05:00 devi_ioctl.h
        -rwxr-xr-x  1 root  root  10551 Feb  3 03:50 lmi.h
        -rwxr-xr-x  1 root  root   3321 Feb  3 03:50 lmi_ioctl.h
        -rwxr-xr-x  1 root  root   4451 Feb  3 03:50 sdli.h
        -rwxr-xr-x  1 root  root   3993 Feb  3 03:50 sdli_ioctl.h
        -rwxr-xr-x  1 root  root   8261 Feb  3 03:50 sdti.h
        -rwxr-xr-x  1 root  root   5264 Feb  3 03:50 sdti_ioctl.h
        -rwxr-xr-x  1 root  root  11972 Feb  3 03:50 sli.h
        -rwxr-xr-x  1 root  root  13134 Feb  3 03:50 sli_ioctl.h

  TEST PROGRAMS:

  There are several test programs that you can run to check that your
  installation is correct and to serve as an example for how to write a
  user-level STREAMS application based on the SS7 interfaces.  These are
  located in the strss7-0.7.4/test/ directory as follows:

        -rwxr-xr-x  1 brian  users   63145 Feb 18 08:58 test-sdludp
        -rwxr-xr-x  1 brian  users   64522 Feb 18 08:58 test-sdt
        -rwxr-xr-x  1 brian  users   76703 Feb 18 08:58 test-sl
        -rwxr-xr-x  1 brian  users  209343 Feb 18 08:58 test-q781
        -rwxr-xr-x  1 brian  users   52459 Feb 18 08:58 test-sdlacb

  test-sdludp:
      Opens two of the /dev/ss7-sdludp0 Signalling Data Link UDP emulations of
      an SS7 signalling link and exchanges messages between the two.  This
      exercises the SDL, (Signalling Data Link) level of the MTP Level 2 stack
      using the UDP emulation.  You should see things like: successful, being
      printed.

  test-sdt:
      Opens two /dev/ss7-sdludp0 ss7 links just as test-sdludp, but pushes the
      "sdt" (Signalling Data Terminal) STREAMS module onto each half and
      communicates back and forth.  You should see things like: successful,
      being printed.

  test-sl:
      Opens two /dev/ss7-sdludp0 ss7 links just as test-sdludp, but pushes
      both a "sdt" and a "sl" (Signalling Link) STREAMS module onto each half.
      The "sl" module implements the majority of the SS7 Level 2 state
      machines.  The test program send a "Power On" primitive to each link and
      then a "Start" primitive.  The links should align (after a few seconds)
      and then exchange an MSU back and forth, "Stop" the links, detach them
      and close them.  You should see things like: successful, being printed.

  test-q781:
      Opens two /dev/ss7-sdludp0 ss7 links and pushes a "sdt" and "sl" STREAMS
      module onto one half and uses the other half as a protocol tester for
      performing Q.781 conformance tests.  Running the program generates the
      output of 107 Q.781 test cases and demonstrates conformance to 97 test
      cases.  (The remaining 10 test casea are inconclusive because of the
      inability to "break Tx" on UDP.)  The two files:

        -rw-r--r--  1 brian  users  115252 Feb 18 08:51 log.shaper
        -rw-r--r--  1 brian  users  116501 Feb 18 08:39 log.tick

      show the output of my runs of the test-q781 program.

  test-acb:
      Opens two /dev/ss7-sdlacb0 real ss7 links for the ACB56 card, just as
      the UDP test programs do above.  DO NOT USE THIS TEST PROGRAM: IT IS A
      WORK IN PROGRESS.


  WHAT IF EVERYTHING GOES WRONG?

  Check to make sure that you have LiS STREAMS correctly installed on your
  system and that it can actually run.

  Hit our majordomo mailing list at openss7@openss7.org: to subscribe, send
  mail to majordomo@openss7.org with "subscribe openss7" in the body of the
  message.  Our mail archive is located on our home page at www.openss7.org.
  
  You can mail me at bidulock@openss7.org, but NO WARRANTY.

  Sat Feb  3 04:30:41 CST 2001
  Brian F. G. Bidulock
  bidulock@openss7.org
