=============================================================================
	     ADVANTECH CAN communication cards device driver
		         Installation & Program Guide
		       for Linux Kernel 2.4.xx, 2.6.xx
	            Copyright (C) 2011, ADVANTECH Co, Ltd.
=============================================================================
Contents

1. Introduction
2. Test environment
3. System Requirement
4. Installation
5. User space program for this driver
6. Troubleshooting

-----------------------------------------------------------------------------
1. Introduction
   
   ADVANTECH CAN communication cards device driver,
   It is a migration from can4linux 3.4 and compatible with can4linux 3.4.
   The application for can4linux driver can run on advcan driver without any modification.

   Now it supports following boards.
    
    - PCM-3680          : 2 port Isolated PC/104 CAN-bus Card.
    - PCL-841           : 2 port Isolated ISA CAN bus Card.
    - TPC-662G          : 1 port Isolated ISA CAN bus Device on TPC-662G.
    - PCI-1680          : 2 port Isolated PCI CAN-bus Card.
    - PCI-1682U         : 2 port Isolated PCI CAN-bus Card.
    - MIC-3680	        : 2 port Isolated PCI CAN-bus Card.
    - UNO-2052(E)       : 2 port Isolated UNO-2052(E) onboard PCI CAN device
    - EAMB-PH07		: 1 port Isolated PCI CAN bus Card.
    - ADVANTECH GENERAL CAN PORT (1 PORT)     : 1 port Isolated PCI CAN bus Card.
    - ADVANTECH GENERAL CAN PORT (2 PORT)     : 2 port Isolated PCI CAN bus Card.
    - ADVANTECH GENERAL CAN PORT (4 PORT)     : 4 port Isolated PCI CAN bus Card.
    - ADVANTECH GENERAL CAN PORT (1 PORT, support CANopen)     : 1 port Isolated PCI CAN bus Card and support CANopen.
    - ADVANTECH GENERAL CAN PORT (2 PORT, support CANopen)     : 2 port Isolated PCI CAN bus Card and support CANopen.
    - ADVANTECH GENERAL CAN PORT (4 PORT, support CANopen)     : 4 port Isolated PCI CAN bus Card and support CANopen.

	 
   This driver supports Linux Kernel 2.4.xx, 2.6.xx, Intel x86 hardware 
   platform. Any problem occurs, please contact ADVANTECH at 
   support@ADVANTECH.com.tw.


   This driver and utilities are published in form of source code under
   GNU General Public License in this version. Please refer to GNU General
   Public License announcement in each source code file for more detail.

   In ADVANTECH's ftp sites, you may always find latest driver at
   ftp://ftp.ADVANTECH.com  or ftp://ftp.ADVANTECH.com.tw.

   This version of driver can be installed as Loadable Module (Module driver)
   Before you install the driver, please refer to hardware installation 
   procedure in the User's Manual.

2. Test environment

   +--------------------------+-------------------------+
   |  Distribution            | kernel version          | 
   +--------------------------+-------------------------+
   |	Red Hat 9             |  2.4.20-8               |  
   |	RedHat Enterprise 4   |  2.6.9-34.EL            |
   |	Redhat Enterprise 5.4 |  2.6.18-164.el5         |
   |	Fedora Core 6         |  2.6.18-1.2798.fc6      | 
   |	Fedora Core 8         |  2.6.23.1-42.fc8        |
   |	Fedora Core 9         |  2.6.25-14.fc9          |       
   |	Fedora Core 10        |  2.6.27.5-117.fc10      |
   |	Fedora Core 11        |  2.6.29.4-167.fc11      |    
   |	Fedora Core 12        |  2.6.31.5-127.fc12      |
   |    Fedora Core 13        |  2.6.33.3-85.fc13       | 
   |	Fedora Core 14        |  2.6.35.6-45.fc14       |         
   |	SUSE 10.1             |  2.6.16.13-4-default    |       
   |	SUSE 10.3             |  2.6.22.5-31-default    |      
   |	SUSE 11.2             |  2.6.31.5-0.1-desktop   |
   |	SUSE 11.3             |  2.6.34-12		|
   |	Mandriva 2010         |  2.6.31.5-desktop-1mnb  |
   |	Debian 5.0.4          |  2.6.26-2-686           |   
   |	Debian 6.0	      |  2.6.32-5-686           |     
   |	Ubuntu 8.04           |  2.6.24-19-generic      | 
   |	ubuntu 9.04           |  2.6.28-11-generic      |
   |	Ubuntu 9.10           |  2.6.31-14-generic      |
   |	Ubuntu 10.04          |  2.6.32-21-generic      |
   |	Ubuntu 10.10          |  2.6.35-22-generic      |
   +--------------------------+-------------------------+

3. System Requirement
   - Hardware platform: Intel x86 
   - Kernel version: 2.4.xx, 2.6.xx
   - gcc version 2.72 or later

4. Installation

   4.1 Hardware installation

       Just install the card into your computer, please refer to hardware
       installation procedure in the User's Manual.
       (If in UNO2052(E),this step does not need)
     
   4.2 Driver files and device naming convention

       The driver file may be obtained from ftp, CD-ROM or floppy disk. The
       first step, anyway, is to copy driver file "adv_can.tar.gz" into 
       specified directory. e.g. /can. The execute commands as below.

       # cd /workdir
       # tar -zxvf advcan_source_vx.xx.tar.gz
      
   4.3 Build Linux kernel module driver
       Module driver is easiest way to install. If you prefer static driver
       installation, please skip this paragraph. In this part, both build 
       method for 2.4 & 2.6 kernel are introduced.

       4.3.1 Build driver for 2.6 kernel with the current running kernel source
          Find "Makefile" in /workdir/advcan/driver/, then run
          # make

	   The driver files "advcan.ko"  will be properly compiled.

          Run following command to install the builded driver to the property
          system directory.
          # make install

       4.3.2 Build driver for 2.4 kernel with the current running kernel source
          Find "Makefile-2.4" in /workdir/advcan/driver/, then run
          # make

	       The driver files "advcan.o"  will be properly compiled.

          Run following command to install the builded driver to the property
          system directory.
          # make install

       4.3.3 Build a module with the user refered kernel source tree
          In section 4.3.1 & 4.3.2, we build the kernel driver with the system 
          running kernel source tree, if you want to use a different kernel
          source tree, you must refer the "SOURCE" envirnment variable.

          # make SOURCE=/path/to/your/own/kernel/source
          
   4.4 Load driver
       After configure your driver, you can load the driver manually or automatic
       Load it at the boot time.
       4.4.1. Manully load
	    You can load the driver by following command:
	    # cd /workdir/advcan/driver/

            For 2.6 kernel
            # insmod advcan.ko

            For 2.4 kernel
	    # insmod advcan.o

       This will activate the moduler driver. You can see CAN Cards found. 
       You may run "lsmod" to check if "advcan_pci" is activated.
       
       You can also load the driver by following command:

	    # cd /workdir/advcan/driver/
            # make install

       4.4.2. Auto load driver at the boot time.
	  For the above description, you may manually execute "insmod" 
          of "make install"to activate this driver. 
          However, it's better to have a boot time configuration to 
          eliminate manual operation. Boot time configuration can be 
          achieved by add script to boot up script file. 
	       
          Example for FC6 (use PCI-1680):
          Edit the /etc/rc.d/rc.local file.
 
	        #vi /etc/rc.d/rc.local

	  Add the following script in the end of file,

          	modprobe advcan
          	CAN_MAJOR=`awk '$2=="advcan" {print $1}' /proc/devices`
          	mknod /dev/can0 c $CAN_MAJOR 0
          	mknod /dev/can1 c $CAN_MAJOR 1
          	chmod 666 /dev/can0
          	chmod 666 /dev/can1 

          Reboot and check if advcan activated by "lsmod" command.


   4.5 Create device driver file
   	Ensure you have inserted the advcan module in the kernel (which can
   	be show by the lsmod command)
   	then use the command:
   	
   	# cd /workdir/advcan/drvier
        # make nodes
   	
   	Check the created device file:
   	
   	#ls -l /dev/can*
   	crw-r--r--   1 root    root     254,   0 Jun 15 15:32 /dev/can0
   	crw-r--r--   1 root    root     254,   1 Jun 15 15:32 /dev/can1
   					                     |     |	
   					                     |     |---- the minor number
   					                     |---------- the major number, dynamic
   	you also can get the major number of this device driver from system:
   	
   	# cat /proc/devices
   	
   	you can find the major number of the advcan device driver, and ensure
   	the major number displayed use ls command is as same as the major get 
   	from system. Other wise use the following command to create the correct
   	device driver file:
   	
   	# mknod /dev/can0 c 254 0
   	# mknod /dev/can1 c 254 1
   			     |-----the major number which get from system

   4.6 Driver rmmove.
       You can use the following command to remove the driver from the system,
	
	# rmmod advcan
        
        or 

	# cd /workdir/advcan/drvier
        # make uninstall
    
   4.7 Configure device
       You can use the configure utils the configure the CAN device.
       the configure tool is in driver/utils folder and the configure file is in driver/etc/

       config PCI device( PCI-1680,MIC-3680,UNO-2052(E) ):
           # cd /workdir/pci_can/driver/utils
           #./cansetup ../etc/advpci.conf
        
       config ISA device(PCM-3680)
           # cd /workdir/pci_can/driver/utils
           #./cansetup ../etc/advisa.conf

       The configuration information will be written to the /proc/sys/Can/.
       You can use the following command to view the current configuration:
       #grep . /proc/sys/Can/*
        
       make sure you configuration is correct when you do any operation to the device. 
       If advpci.conf or advisa.conf don't correspond with you device's setting,please modify it.
        
       You can also to use echo command to configure you driver

       Note: if you device is PCI bus type, don't modify the value in  
       /proc/sys/Can/Base and /proc/sys/Can/IRQ
               
5. User space program for this driver
   
   5.1 Include file
        To program for this driver, the user must include the 
        "can4linux.h" head file. You also can copy this head 
        file to your owner work directory and include it.
   
   5.2 Examples Reference
       These are some simple examples to test the communication between two CAN channels.

        5.2.1 receive
	      polling or nonblocking mode to receive message,date received are stored to
	      logfile.txt,thus it is convinient to check them. 
        5.2.2 transmit
	      polling mode to transmit message
        5.2.3 receive-select
	      simple receiving using the select() call to wait for CAN messages
	      date received are stored to logfile.txt,thus it is convinient to check them.
        5.2.4 transmit-select
	      simple transmit using the select() call. Press enter to stop transmit and another
	      enter to resume transmit.
        5.2.5 send_ioctl
	      simple transmit using the SEND ioctl command 
        5.2.6 baud
              simple driver test: change the bit rate
              the change itself stays after program is finished.
              you can check it by read
              cat /proc/sys/Can/Baud
              before and after using this command
        5.2.7 acceptance
	      simple driver test: change the message filter with ioctl()
	      the change itself stays after program is finished.
	      you can check it by read
	      cat /proc/sys/Can/AccCode /proc/sys/Can/AccMask
	      before and after using this command
        5.2.8 ctest
	      very simple and basic driver test:  read a message every sleep ms
        5.2.9 singlefilter
	      In this example, when set accept code to only accept the message which id = 10 and rtr = 0"
	      using /dev/can0 device to accept message 
	      using /dev/can1 to transmit message
        5.2.10 selfreception
	      self reception example
	      when you run this example, you should run another receive example 
	      to receive the message transmit by selfreception and at the same time, selfreception will 
	      also receive the message transmit by itself.

6. Troubleshooting

   The boot time error mesages and solutions are stated as clearly as
   possible. If all the possible solutions fail, please contact our technical
   support team to get more help.
