README

/*
**             Copyright 2017 by Kvaser AB, Molndal, Sweden
**                         http://www.kvaser.com
**
** This software is dual licensed under the following two licenses:
** BSD-new and GPLv2. You may use either one. See the included
** COPYING file for details.
**
** License: BSD-new
** ==============================================================================
** Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are met:
**     * Redistributions of source code must retain the above copyright
**       notice, this list of conditions and the following disclaimer.
**     * Redistributions in binary form must reproduce the above copyright
**       notice, this list of conditions and the following disclaimer in the
**       documentation and/or other materials provided with the distribution.
**     * Neither the name of the <organization> nor the
**       names of its contributors may be used to endorse or promote products
**       derived from this software without specific prior written permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
** AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
** ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
** LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
** CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
** SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
** BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
** IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
** ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
** POSSIBILITY OF SUCH DAMAGE.
**
**
** License: GPLv2
** ==============================================================================
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 2 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software
** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
**
**
** IMPORTANT NOTICE:
** ==============================================================================
** This source code is made available for free, as an open license, by Kvaser AB,
** for use with its applications. Kvaser AB does not accept any liability
** whatsoever for any third party patent or other immaterial property rights
** violations that may result from any usage of this source code, regardless of
** the combination of source code and various applications that it can be used
** in, or with.
**
** -----------------------------------------------------------------------------
*/


- Linux drivers for Kvaser PCIeFD, PCIcan, PCIcanII, USBcanII,
  Leaf and Mhydra -

  Interface   Product                  Driver Name
 -----------+------------------------+-------------
  USB         Leaf Light               leaf
              Leaf Light v2
              Leaf SemiPro
              Leaf Professional
              Memorator Professional
              BlackBird
 -----------+------------------------+-------------
  miniPCIe    Mini PCI Express HS      leaf
              Mini PCI Express 2xHS
 -----------+------------------------+-------------
  miniPCIe    Mini PCI Express HS v2   pciefd
              Mini PCI Express 2xHS v2
 -----------+------------------------+-------------
  USB         Eagle                    mhydra
              BlackBird v2
              BlackBird Pro HS v2
              Hybrid 2xCAN/LIN
              Hybrid CAN/LIN
              Hybrid Pro 2xCAN/LIN
              Hybrid Pro CAN/LIN
              Leaf Pro HS v2
              Memorator 2xHS v2
              Memorator Light HS v2
              Memorator Pro 2xHS v2
              Memorator Pro 5xHS
              USBcan Light 4xHS
              USBcan Pro 2xHS v2
              USBcan Pro 4xHS
              USBcan Pro 5xHS
              U100
              U100P
              U100S
 -----------+------------------------+-------------
  USB         USBcanII                 usbcanII
              Memorator
 -----------+------------------------+-------------
  PCI         PCIcan                   pcican
              PCIcanx
 -----------+------------------------+-------------
  PCIe        PCIEcan HS               pcican
              PCIEcan HS/HS
 -----------+------------------------+-------------
  PCIe        PCIEcan HS v2            pciefd
              PCIEcan 2xHS v2
              PCIEcan 4xHS
 -----------+------------------------+-------------
  PCI         PC104                    pcicanII
              PC104+
              PCIcan II
              PCIcanx II
 -----------+------------------------+-------------


System requirements:

* Linux 2.6.29 or later
* Header files and compiler for kernel compilation.
  In Ubuntu 14.04 e.g. this is accomplished by issuing the command:

    "sudo apt-get install build-essential"

  On some systems you may also need to issue:

    "sudo apt-get install linux-headers-`uname -r`"

  NOTE! Having versions of the linux headers installed other than that of
        the currently running kernel may cause conflicts and faulty drivers.

* DKMS if you want to the drivers to be built whenever the kernel is upgraded.
  To install dkms on Ubuntu:

    "sudo apt-get install dkms"


Compilation:

  NOTE! Choose a path that doesn't contain any spaces for CANlib to build properly.

* To build all drivers:

    "make"

  To install all drivers:

    "sudo make install"

  Note: it is advised to call "sudo make uninstall" before replacing installed
        drivers.

  To unload and uninstall all drivers:
    "sudo make uninstall"

  To install and load, virtual and PCI drivers:
    "sudo make load"

  Note: running "sudo make load" will also cause the virtual and PCI drivers to
        be loaded at boot time. This might be bad if experimenting with the
        device drivers.

  Note: it is never required to manually install or load any modules, create or
        edit files. This is taken care of the Makefile, in the root of the
        linuxcan directory.

  Note: if there are multiple versions of linuxcan installed for different linux
        headers, it is possible to remove them all by calling "sudo make purge".

  Another way to install CANlib is by using DKMS which automatically recompiles
  and reinstalls the CANlib drivers after a kernel upgrade.

  To build and install CANlib and all drivers using DKMS:

    "make dkms"

    "sudo make dkms_install"

  Note: this requires you to have dkms installed.

  To uninstall CANlib and to unload and uninstall all linuxcan DKMS modules:

    "sudo make dkms_uninstall"

* To build just a single driver, go to the corresponding subdirectory:

    "make"
    "sudo ./installscript.sh"

  Note: All device drivers use the kvcommon driver. If you want to build and
        install only particular device drivers, you will first need to build and
        install the kvcommon driver from the linuxcan/common directory using the
        method above.

* To build and load just a single driver (virtual or PCI), go to the
  corresponding subdirectory:

    "make"
    "sudo ./installscript.sh load"

  Note: See the note above, regarding the kvcommon driver.

* To build with debug printouts, and include gdb debug information on generated binaries:

    "make KV_DEBUG_ON=1"

Debug levels and some other settings may be changed in config.mak.


Usage:

* USBcanII, Leaf and Mhydra will load/unload when inserting/removing the device
* For PCI-drivers (pciefd, pcican, and pcicanII), use modprobe to load and
  unload the drivers, e.g.:
    "modprobe pcican" to load pcican driver, and
    "modprobe -r pcican" unload pcican driver.
* Try examples in /usr/doc/canlib/examples/

NOTE! Please read ReleaseNotes before using the driver.


Troubleshooting:

* See doc/faq


Installed Files:

* Driver modules
----------------------------------
/lib/modules/`uname -r`/kernel/drivers/char/kvpciefd.ko     (PCIEcan)
/lib/modules/`uname -r`/kernel/drivers/char/kvpcican.ko     (PCIcan)
/lib/modules/`uname -r`/kernel/drivers/char/kvpcicanII.ko   (PCIcanII)
/lib/modules/`uname -r`/kernel/drivers/char/kvvirtualcan.ko (Virtualcan)
/lib/modules/`uname -r`/kernel/drivers/usb/misc/usbcanII.ko (USBcanII)
/lib/modules/`uname -r`/kernel/drivers/usb/misc/leaf.ko     (Leaf)
/lib/modules/`uname -r`/kernel/drivers/usb/misc/mhydra.ko   (Mhydra)

* Module setup
----------------------------------
On CentOS, RedHat, RHEL, Fedora and simlar systems, the following lines are
added to /etc/modprobe.conf, on Debian, Ubuntu, Trisquel and similar systems
they are added to /etc/modprobe.d/kvaser.conf.

for PCIEcan:

    alias pciefd kvpciefd
    install kvpciefd /usr/sbin/pciefd.sh start
    remove kvpciefd /usr/sbin/pciefd.sh stop

for PCIcan:

    alias pcican kvpcican
    install kvpcican /usr/sbin/pcican.sh start
    remove kvpcican /usr/sbin/pcican.sh stop

for PCIcan II:

    alias pcicanII kvpcicanII
    install kvpcicanII /usr/sbin/pcicanII.sh start
    remove kvpcicanII /usr/sbin/pcicanII.sh stop

for Virtualcan:

    alias virtualcan kvvirtualcan
    install kvvirtualcan /usr/sbin/virtualcan.sh start
    remove kvvirtualcan /usr/sbin/virtualcan.sh stop

In the same files, the following lines are added to blacklist SocketCAN:

    blacklist kvaser_usb
    blacklist kvaser_pci
    blacklist kvaser_pciefd

* Module loading
----------------------------------
/usr/sbin/pciefd.sh      (start/stop pciefd driver;      by modprobe or manually)
/usr/sbin/pcican.sh      (start/stop pcican driver;      by modprobe or manually)
/usr/sbin/pcicanII.sh    (start/stop pcicanII driver;    by modprobe or manually)
/usr/sbin/virtualcan.sh  (start/stop virtualcan driver;  by modprobe or manually)
/usr/sbin/usbcanII.sh    (start/stop usbcanII driver;    by udev or manually)
/usr/sbin/leaf.sh        (start/stop leaf driver;        by udev or manually)
/usr/sbin/mhydra.sh      (start/stop mhydra driver;      by udev or manually)

* Module loading at boot
----------------------------------
If the modules are installed with "sudo make load", the virtual and the PCI
drivers are added to /etc/modules-load.d/kvaser.conf. This will cause the
modules to be loaded at boot time.

* udev rules
----------------------------------
/etc/udev/rules.d/10-kvaser.rules

* Include files for canlib library
----------------------------------
/usr/include/canlib.h
/usr/include/canstat.h

* Canlib library and links
----------------------------------
/usr/lib/libcanlib.so
/usr/lib/libcanlib.so.1.1.0
/usr/lib/libcanlib.so.1

* Canlib documentation
----------------------------------
/usr/doc/canlib/HTMLhelp

* Canlib examples
----------------------------------
/usr/doc/canlib/examples

* Canlib Makefile template
----------------------------------
/usr/doc/canlib/examples/Makefile