readme.txt

linux下PCI_CAN 的驱动程序

				 README

=============================================================================
	   ADVANTECH CAN comunication cards device driver, Ver. 1.0,
		  Installation & Program Guide
		    for Linux Kernel 2.4.xx
	       Copyright (C) 2002, ADVANTECH Co, Ltd.
=============================================================================
Contents

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

-----------------------------------------------------------------------------
1. Introduction
   
   ADVANTECH CAN comunication cards device driver, Ver. 1.0,
   supports following boards.
    
    - PCI-1680	: 2 port Isolated PCI CAN-bus Card.
	 
   This driver supports Linux Kernel 2.4.xx, Intel x86  hardware 
   platform. Any problem occurs, please contact ADVANTECH at 
   [e-mail].


   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. System Requirement
   - Hardware platform: Intel x86 
   - Kernel version: 2.4.x
   - gcc version 2.72 or later

-----------------------------------------------------------------------------
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 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 /pci_can
       # tar -zxvf pci_can.tar.gz
      
   3.3 Module driver configuration
       Module driver is easiest way to install. If you prefer static driver
       installation, please skip this paragraph.
       1. Find "Makefile" in /can/pci_can/driver/, then run
          # make

	  The driver files "pci_can.o"  will be properly compiled
	  and copied to system directories respectively.

   3.4 Driver load.
       After configure your driver, you can load the driver manully or automatic
       load it at the boot time.
       1. Manully load
	  You can load the driver by following command:
	  # cd /can/pci_can/driver/
	  # insmod pci_can.o

	  This will activate the moduler driver. You can see CAN Cards found. 
	  You may run "lsmod" to check if "pci_can" is activated.

       2. Auto load driver at the boot time.
	  For the above description, you may manually execute "insmod" 
          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 rc file. We offer one "rc.can" file to simplify 
          the procedure under "pci_can/driver".
	  
	  Run following command for setting rc files.

	  # cd /can/pci_can/driver
	  # cp ./rc.can /etc/rc.d
	  # cd /etc/rc.d

	  Modify the /etc/rc.d/rc.can file, change the following line:
	  
	  insmod /can/pci_can/driver/pci_can.o
	  
	  Then modify the /etc/rc.d/rc.local,
	  Add "/etc/rc.d/rc.can" in last line, 

          Reboot and check if pci_can.o activated by "lsmod" command.
   
   3.5 Create device driver file
   	Ensure you have insert the adv_can module in the kernel(which can
   	be show by the lsmod command)
   	then use the command:
   	
   	# cd /can/pci_can/drvier
   	# ./install
   	
   	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
   	you also can get the major number of this device driver from system:
   	
   	# cat /proc/devices
   	
   	you can find the major number of the adv_can 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

   3.6 Driver rmmove.
        You can use the following command to remove the driver from the system:
	
	# rmmod pci_can


-----------------------------------------------------------------------------
4. User space program for this driver
   
   4.1 Include file
   	  To program for this driver, the user must include the 
   	  "./driver/adv_can.h" head file. You also can copy this head 
   	  file to your owner work dirctory and include it.
   
   4.2 Message and CAN device struct
 
 	CAN message struct used to send or recieve a message to or from the driver:
 	
	typedef struct { 
        	unsigned char ff;     /*infomation of frame, 0 for sff, 128 for eff*/
  		unsigned char rtr;     /*remore frame*/
        	unsigned int  id;       /* message id */
		unsigned char dlen;     /* message length */
        	unsigned char data[8];  /* message */
	} can_msg_t;
	
	CAN device struct used to setup the option of the hardware, such as
	baud rate and other value.
	
	typedef struct {
        	unsigned char accode[4];   /* access code */
        	unsigned char accmask[4];  /* access mask */
		unsigned char speed;       /* baud rate */
		unsigned char interruptmask;
		unsigned char protocol;	   /*protocol*/
		unsigned char filtertype;    /* filter type */
	}CAN_STRUCT;
	
   4.3 Command
   	  This driver can accept the following command, both of these two command
   	  can be translated to the driver use the ioctl() method:
   	  
   	  IOCTL_SET_CAN
   	  	setup the hardware use a CAN_STRUCT, eg:
   	  	ioctl(fd,IOCTL_SET_CAN,&can);
   	  IOCTL_RESET_CAN
   	  	reset the hardware, eg:
   	  	ioctl(fd, IOCTL_RESET_CAN, NULL);
   	    
   4.4 Access to the driver
   
   	  4.4.1 Device driver file
   	  	Device file is used to access the device. In the userspace, 
   	  	the only way to access the device is through the device file.
   	  	For this driver, it has two device file, "/dev/can0" for 
   	  	channel 1 and "/dev/can1" for channel 0. The hardware can be
   	  	controled through access these two device file, use the method
   	  	such as open(), close(), read(), write() and ioctl().
   
   	  4.4.1 Open
   	  	Before access the device file, you need to open it.
   	  	Just open the "/dev/can0" or "/dev/can1" as the nomal file.
   	  
   	  4.4.2 Reset and setup the hardware
   	  	After open the device file, you need to reset and setup the
   	  	device through ioctl command as following. 
		note: the data field of setup struct is different up to protocol.
   	  	
		set to 2.0A protocol:		

			ioctl(fd, IOCTL_RESET_CAN, NULL);
  
			can.accode[0]=0x0;      
			can.accmask[0]=0xff;    
			can.protocol=CAN_PROTOCOL_20A;
			can.speed=CAN_125K;		/* baud	rate 125Kbps */
 			
			ioctl(fd,IOCTL_SET_CAN,&can);
		
		set to 2.0B protocol:		

		        ioctl(fd, IOCTL_RESET_CAN, NULL);
  
			for(int i=0;i<4;i++) can.accode[i]=0x0;      
			for(int i=0;i<4;i++) can.accmask[i]=0xff;    
			can.protocol=CAN_PROTOCOL_20B;
			can.speed=CAN_125K;		/* baud	rate 125Kbps */
 			can.filtertype = 0;
	  		ioctl(fd,IOCTL_SET_CAN,&can);
  		  		

  	  4.4.3 Send and recieve message
   	  	You can use the standard i/o function(read(), writer()) to read
   	  	and write a message to the driver:
   	  	
		case protocol 2.0A:		

		     msg.id = 0x15;		    
		     msg.info = 0;
		     msg.dlen = 8;
		     for(i=0;i<8;i++)
			msg.data[i] = data[i];
    
		     write(fd, &msg, CAN_MSG_LEN);
		case protocol 2.0B:

		     msg.id = 0x15;
		     msg.info = PELICAN_SFF;
		     msg.dlen = 8;
		     for(i=0;i<8;i++)
			msg.data[i] = data[i];
    
		     write(fd, &msg, CAN_MSG_LEN);
    		
    	  4.4.4 Close
    	  	Remember to close the device file which has been open before exit
    	  	from the program, other wise, the device driver module will can't
    	  	be removed from kernel. Juse use the close() function to close it.
   
   	  4.4.5 The program following
   	  	The must be control in order:
   	  	
   	  			open()
   	  			  |
   	  			  |
   	  			reset
   	  			  |
   	  			  |
   	  			setup
   	  			  |
   	  		    read(),write()	  
   	  		          |
   	  		          |
   	  		        close()
   	  		        
   	There are two example program "send.c" and "receive.c". They will be found
   	in ./pci_can/test directory. 
   	The "send.c" program show how to send a message to a refer port.
   	The "receive.c" program show how to recieve a message from a port.
   	You can complie them use:

   	# cd /can/pci_can/test
   	# make 
	# ./send        0       a        s 
			|       |	 |----frame(s for SFF, e for EFF, r for RTR, x for SFF and RTR, y for EFF and RTR)
   			|       |---- the CAN protocol, a or b, a for 2.0A b for 2.0B
   			|---------- the portnum
 	# ./receive     1       a
			|       |
   			|       |---- the CAN protocol, a or b, a for 2.0A b for 2.0B
   			|---------- the portnum
  
-----------------------------------------------------------------------------
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.


   Error msg:
   pci_can.o: init_module: No such device
   Hit: insmod errors can be caused by incorrect module parameters, 
   includeing invalid IO or IRQ parameters
   Solution:
   The driver can find the hardware use the given io and irq parameters,
   check the hardware install to ensure the correct io and irq parameters.