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

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

-----------------------------------------------------------------------------
1. Introduction
   
   ADVANTECH CAN communication cards device driver,
   It is a migration from can4linux 3.5.7 and compatible with can4linux 3.5.7
   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.
	- PCM-3680I	        : 2 port Isolated PCI CAN-bus Card.
    - PCL-841           : 2 port Isolated ISA CAN bus Card.
    - PCI-1680          : 2 port Isolated PCI CAN-bus Card.
	- PCIE-1680         : 2 port Isolated PCI CAN-bus Card.
    - MIC-3680	        : 2 port Isolated PCI CAN-bus Card.


   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.

   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. System Requirement

   - Hardware platform: Intel x86 
   - Kernel version: 2.4.xx, 2.6.xx and newer
   
	It is tested in follow systems:

Supported distribution
 ------------------------------------------ -------------- ----------------
|             Distribution                 |     Kernel version            |
 ------------------------------------------ -------------------------------
|  Ubuntu 12.04/14.04/15.10/18.04(Desktop) |      3.2/3.13/4.2/4.15.0      |
 ------------------------------------------ -------------------------------
|  Redhat Enterprise Linux Server 7.2      |         3.10.0                |
 ------------------------------------------ -------------------------------
|  OpenSUSE 15.0                           |         4.12.14               |
 ------------------------------------------ -------------------------------
|  Debian 9.5                              |         4.9.0                 |
 ------------------------------------------ -------------------------------
|  CentOS 7.6                              |         3.10.0                |
 ------------------------------------------ -------------------------------

   It is strongly recommended that the user do a complete install of all 
   components to ensure that this driver works correctly.
   

3. Installation

   3.1 Hardware installation
       Just install the card into your computer, please refer to hardware
       installation procedure in the User's Manual.
       
     
   3.2 Driver files and device naming convention
       The driver file may be obtained from ftp, CD-ROM or www.advantech.com. The
       first step, anyway, is to copy driver file "advcan_source_vx.xx.tar.gz" into 
       specified directory. e.g. /can. Then execute commands to decompress as below.

       # cd /workdir
       # tar -zxvf advcan_source_vx.xx.tar.gz
      
   3.3 Compile and install CAN Linux driver
       Module driver is easiest way to compile. In this part, both build 
       method for 2.4, 2.6 and newer kernel are introduced.

       3.3.1 Build driver for 2.4 ,2.6 and newer 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
          
   3.4 Load driver
	  In some linux distributions or when you use ISA CAN device(PCM-3680),
	  after you run "make install" to install the driver,
	  it only take effect in this booting and the driver can not load automaticcally when reboot.
	  You need to run "make install"to install this driver every time when system boot up. 
          However, it's better to have a boot time configuration to 
          eliminate manual operation. 

          For Advantech PCI CAN devies,in general Linux distributions, 
          you can let the OS load the driver automaticcally by run the following command:
	    # cd /workdir/advcan/driver/
            # make install

	  Reboot you device, if the above way do not take effect, or your CAN device is ISA device(PCM-3680),
	  you may add script to boot up script file as follows:
	       
          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.


   3.5 Create device driver file
   	Ensure you have inserted the advcan module in the kernel (which can
   	be show by the lsmod command)


	Use ls command to see whether the CAN device name is create in /dev
	#ls -l /dev/can*

	If node device list, you need to create the CAN device manually as follows:
   	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

	You can also add the script to boot up script file.

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

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

       Config PCI device( PCI-1680,PCIE-1680,PCM-3680I,MIC-3680... ):
       Generally,We suggest to you that you do not configure the PCI device, the PCI device will be configured by driver automaticlly.
           # cd /workdir/advcan/driver/utils
           #./cansetup ../etc/advpci.conf
       
       PCM-3680 must config as follows.
       You should moddify the PCM3680.conf file according to IRQ and Base address setting in PCM-3680 card.
       About PCM-3680 IRQ and Base address setting, please refer to PCM-3680 hardware user manual.
       config ISA device(PCM-3680):
           # cd /workdir/advcan/driver/utils
           #./cansetup ../etc/PCM3680.conf

       The configuration information will be written to the /proc/sys/dev/Can/.
       You can use the following command to view the current configuration:
       #grep . /proc/sys/dev/Can/*
        
       make sure you configuration is correct when you do any operation to the device. 
       If the .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 your CAN device is PCI bus type, don't modify the value in  
       /proc/sys/dev/Can/Base and /proc/sys/dev/Can/IRQ.

       If you use PCI CAN card and ISA CAN card in one computer/Device, 
       The CAN driver will assign the device name to PCI CAN card from can0, So when you config the ISA CAN card, 
       You should modify the config file and avoid configuring the ports that have been used by PCI CAN device.
       For examples:
       There are 2 PCI-1680( One PCI-1680 has 2 CAN ports,totle 4 ports)cards and 1 PCM-3680(One PCM-3680 has 2 CAN port) card in one computer,
       When load the CAN driver, can0,can1,can2,can3 will be used by 2 PCI-1680 cards, So PCM-3680 can not use can0~can3, it should use can3, can4......
       So when you config the PCM-3680,you must the modify the ./diver/etc/PCM3680.conf  
       from 
       		......
		# Channel 0
		########################################

		Base_0=0xda000
		Irq_0=5
		Baud_0=125
		AccMask_0=0xffffffff
		AccCode_0=0xffffffff
		Timeout_0=100
		Outc_0=0xda

		# Channel 1
		########################################

		Base_1=0xda200
		Irq_1=7
		Baud_1=125
		AccMask_1=0xffffffff
		AccCode_1=0xffffffff
		Timeout_1=100
		Outc_1=0xda

		......

       to 
		......

		# Channel 0
		########################################

		Base_4=0xda000
		Irq_4=5
		Baud_4=125
		AccMask_4=0xffffffff
		AccCode_4=0xffffffff
		Timeout_4=100
		Outc_0=0xda

		# Channel 1
		########################################

		Base_5=0xda200
		Irq_5=7
		Baud_5=125
		AccMask_5=0xffffffff
		AccCode_5=0xffffffff
		Timeout_5=100
		Outc_5=0xda
		......

               
4. User space program for this driver
   
   4.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.
   
   4.2 Examples Reference
       These are some simple examples to test the communication between two CAN channels.

        4.2.1 receive
	      polling or nonblocking mode to receive message,date received are stored to
	      logfile.txt,thus it is convinient to check them. 
        4.2.2 transmit
	      polling mode to transmit message
        4.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.
        4.2.4 transmit-select
	      simple transmit using the select() call. Press enter to stop transmit and another
	      enter to resume transmit.
        4.2.5 send_ioctl
	      simple transmit using the SEND ioctl command 
        4.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
        4.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
        4.2.8 showstat
	      very simple and basic driver test.
        4.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
        4.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.

5. 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.
