
                 INSTALLATION NOTES FOR THE EPCA DRIVER

RPM Notes:
   o  The file 40001450_T.src.rpm is the Linux EPCA source code rpm 
      package, to be built on any architecture.  You must have the rpm (RedHat 
      Package Manager) facility installed on your machine to use the source rpm.

   o  If building on an architecture other than Intel x86/Pentium PC, replace
      the occurances of i386 with the appropriate architecture string.  Some
      intel based distributions also use i486/i586/i686.

   o  Additional options to the rpm commands such as --replacefiles may
      be appropriate in some cases.  Please read the rpm man page for
      additional information concerning the options available to you.

   o  Existing EPCA drivers should be removed (rpm -e epca) before this
      driver is installed.  
 

1. INSTALLATION

NOTE: Kernel source MUST be installed prior to building the epca driver and 
      there should be a soft link named "linux" pointing to it.  Instructions
      for creating the soft link are included below.  Check your user 
      documentation for instructions on how to install your kernel source if
      it is not already installed.

NOTE: There is a legacy epca module that is included with most linux kernels
      that is incompatible with the current epca driver.  It MUST be removed
      before installing:
         find /lib -name epca.o
         Replace [path] in the following command with the path found above:
            mv [path]/epca.o [path]/epca.oOLD 

NOTE: In Redhat 7.x, you MUST install the kgcc RPM package before you
      attempt to install this driver.  The default compiler, gcc, is
      known to generate buggy code. If the kgcc package is not installed
      before you install this driver package the driver will be compiled
      with the default compiler.  Digi will NOT support this configuration,
      as it may operate unreliably, or could even crash your system.  This
      driver package will build by default with kgcc if it finds it in
      the path.

  This driver is distributed both as a source RPM and as a compressed tar
  file of the source.  Use one of the following sets of commands to build
  and install the package.

  Source RPM - (some systems use '/usr/src/packages' or other directories
  instead of /usr/src/redhat):

      rpm -e epca  (removes previous versions, if they exist)
      rpm -ivv 40001450_T.src.rpm
      
      -Create a soft link to your kernel source if you don't already have one.
       Replace [kernel_version] with your version: 
          cd /usr/src/
          ln -s linux-[kernel_version] linux 
      
      cd /usr/src/redhat
      rpm -bb SPECS/epca.spec
      rpm -ihv --replacefiles RPMS/i386/epca-1.57-1.i386.rpm
      
      -Verify the package was installed:
          rpm -V -vv epca
 
  Compressed Tar:

      -Create a soft link to your kernel source if you don't already have one.
       Replace [kernel_version] with your version: 
          cd /usr/src/
          ln -s linux-[kernel_version] linux 

      cd -  (change back to the directory where you placed the tar.gz file)
      tar -xzvf 40001450_T.tar.gz
      cd epca-1.57-1
      mkdir -p /usr/src/dg/epca
      cp -r * /usr/src/dg/epca/
      cd /usr/src/dg/epca
      make install


2. CONFIGURATION

  After installing the driver package, you must configure the driver.  
  This is done by running the command "digiConf".

  This will run through a series of questions about your currently
  installed Digiboards.  If you have ISA Digiboards, it will be useful
  to have all the information about the configuration of your Digi
  products, (I/O addresses, the shared memory address you wish to use,
  etc.) as the digiConf program will ask you about this information.
 

3. LOADING THE DRIVER

  In order to make the driver available for use, you must cause the driver
  to be loaded.  This can be accomplished on RedHat distributions by doing
  a "chkconfig --add epca" to enable the driver rc scripts for start and
  stop at system reboot and shutdown.  On other distributions, you should
  link the epca startup script as appropriate.  The epca installation
  package will automatically detect if your system uses "/etc/rc.d/init.d/"
  or "/etc/init.d/" but other possible locations such as "/sbin/init.d/"
  that might be used by some distributions would need to be configured
  by hand.

  To load the driver, either run run the script as appropriate.  To load
  the driver, either run the script manually (for example, on RedHat,
  "/etc/rc.d/init.d/epca start") or reboot the system.

  The driver must be configued with the boards installed before
  it will actually load. 


4. REMOVING THE EPCA DRIVER

  If you have built and installed the rpm binary package as described
  above, then you can use rpm to remove it.  Simply use the erase (-e)
  command line option:

      rpm -e -vv epca

  If you built and installed using the compressed tar, cd to the original
  extracted directory and use the command:
     
     make uninstall

  NOTE: If you currently have your EPCA driver loaded, this will try and
        automatically remove the module from your running kernel with the
        command "rmmod epca". 


5. CUSTOMIZING THE PACKAGE

  If you need to customize the Makefiles to reflect your own configuration, 
  or modify the source code, this will need to be done prior the build.
  You may want to do this to update the paths used for various files such
  as the firmware or digiConf if you are not satisified with the defaults.
  To access the Makefile, you have to first unpack the tgz file:

      rpm -ivv 40001450_T.src.rpm
      cd /usr/src/redhat
      rpm -bp SPECS/epca.spec

  The "-bp" in the options specifies that only the prep section of the
  spec file should be executed.  This will, among other things, create a 
  /usr/src/redhat/BUILD/epca-1.57-1 directory and unpack the tarfile
  there.  

  You may then make any necessary changes to the Makefile and source code
  in the unpacked source tree.

  NOTE: you might want to now save the final version of your changes 
        somewhere other than in the /usr/src/redhat tree for backup.

  NOTE: if you change the final location that any of the files in the 
        package, you will also want to update the %file list in the
        spec file /usr/src/redhat/SPECS/epca.spec.  Otherwise, RPM will
        complain that the installation was incomplete, because some files
        were not found.  You can also document your changes in the
        %description section as well as change the "Release:" and
        "Packager:" tags to identify your new package.

  There are several ways to install the driver package at this point, but
  the following is the easiest, and safest way (this will replace the
  original source code provided by the package and then build the package):

      cd /usr/src/redhat/BUILD 
      tar -cvzf ../SOURCES/epca-1.57-1.tgz epca-1.57-1/*
      cd /usr/src/redhat
      rpm -bb SPECS/epca.spec
      rpm -ihv RPMS/i386/epca-1.57-1.i386.rpm


6. DESCRIPTION OF THE RPM PROCESS

  The rpm process described in section 1 of this document has 3 basic steps:

      1 - Install the source RPM package
      2 - Build the binary RPM package from the source
      3 - Install the binary RPM package

  The first command (rpm -ivv 40001450_T.src.rpm) installs the source
  code in the SOURCES directory used by RPM (/usr/src/redhat/SOURCES) and
  the RPM specification file in the SPECS directory.  The actual source code
  is distributed as a gzipped tar file and is also available seperately.  The
  specification file (or spec file for short) is just a text file with some 
  script like commands, package information and file list.  

  The second command (rpm -bb SPECS/epca.spec) builds the binary RPM package 
  from the tarred and gzipped source file in the SOURCES directory and the
  instructions contained in the spec file.  If the build completes without
  error, you will see a message like:

      "Wrote:  /usr/src/redhat/RPMS/i386/epca-1.57-1.i386.rpm"

  The third command (rpm -ivv RPMS/i386/epca-1.57-1.i386.rpm) installs
  the generated binary RPM on the system.  This package is ONLY valid for the
  same kernel version, architecture, and SMP vs Uniprocessor as the machine 
  it was generated on.  However, if all of these factors match, the binary
  RPM can be copied elsewhere and installed without problems.
