Minor driver readme install instructions update for recent GNU/Linux distributions.

[lincan.git] / lincan / README

diff --git a/lincan/README b/lincan/README
index 0c89a19b5d2ad7a2e422a763c0fb2b1904f5b189..eee58429bba343171e9c4000e5d3dc363bfb2b35 100644 (file)
--- a/lincan/README
+++ b/lincan/README
@@ -1,19 +1,18 @@
 
 

-               Linux CAN Driver (LinCAN) version 0.3.3
+               Linux CAN Driver (LinCAN) version 0.3.5
+               part of OrtCAN project <http://ortcan.sourceforge.net/>

                Pavel Pisa <pisa@cmp.felk.cvut.cz>
                Pavel Pisa <pisa@cmp.felk.cvut.cz>

-                       OCERA team member <http://www.ocera.org>
-                       Real-time Systems Laboratory <http://rtlab.felk.cvut.cz/>
-                       Department of Control Engineering, FEE CTU
-
+               Department of Control Engineering (DCE) FEE CTU <http://dce.fel.cvut.cz/en/>
+               DCE Real-Time Systems group CAN resources  <http://rtime.felk.cvut.cz/can/>

 
 INTRODUCTION
 ============
 The LinCAN is an implementation of the Linux CAN-bus device driver supporting
 more CAN controller chips and many CAN interface boards. Its development
 
 INTRODUCTION
 ============
 The LinCAN is an implementation of the Linux CAN-bus device driver supporting
 more CAN controller chips and many CAN interface boards. Its development

-has long history already. The OCERA version of the driver has new better
+has long history already. The OCERA/OrtCAN version of the driver has new better

 designed internal structure, adds new features (as support for open by multiple
 applications, select system call) and other enhancements.
 designed internal structure, adds new features (as support for open by multiple
 applications, select system call) and other enhancements.

-  
+

 The driver consist of four main layers:
   - chip level manipulation routines
   - board specific support
 The driver consist of four main layers:
   - chip level manipulation routines
   - board specific support


@@ -28,8 +27,11 @@ The driver originates in The Linux Lab Project
   http://www.llp.fu-berlin.de/
 then it has been first rewritten by Arnaud Westenberg
   http://home.wanadoo.nl/arnaud/
   http://www.llp.fu-berlin.de/
 then it has been first rewritten by Arnaud Westenberg
   http://home.wanadoo.nl/arnaud/

-now it is developed and maintained as part of OCERA framework
+The driver code undergone major redesign in a frame of the OCERA IST project

   http://www.ocera.org/
   http://www.ocera.org/

+Actual driver version is maintained togther with other CAN/CANopen
+components as part of the OrtCAN project
+  http://ortcan.sourceforge.net/

 
 I am unable to contact previous maintainer Arnaud Westenberg
 (arnaud@wanadoo.nl). If you know something about him, I like
 
 I am unable to contact previous maintainer Arnaud Westenberg
 (arnaud@wanadoo.nl). If you know something about him, I like


@@ -82,15 +84,14 @@ lincan-0.3.3        Some more fixes of SJA1000 buss-of recovery,
                tested up to 2.6.17 (rc4). Minimal chip info in /proc/can.
                Support for NSI CAN PCI contributed by Eric Pennamen.
 
                tested up to 2.6.17 (rc4). Minimal chip info in /proc/can.
                Support for NSI CAN PCI contributed by Eric Pennamen.
 

-               
+lincan-0.3.4   Some more fixes of SJA1000 buss-of recovery,
+(March 2009)   Many enhancements and fixes. Tested up to 2.6.28 Linux kernel.
+
+lincan-0.3.5   Make system updates to build under latest Linux kernels,
+(October 2011) LinCAN core builds and tested with 2.6.35 and 3.0 Linux kernels.
+

 The actual version of driver have been latest tested it with
 The actual version of driver have been latest tested it with

-  - PC104 Advantech PCM3680 dual channel board on 2.4 RT-Linux enabled kernel
-  - PiKRON ISA card on 2.4.and 2.6 Linux kernels
-  - PiKRON CAN extension board for PiMCX1 ARM BCC on 2.6 Linux kernels
-  - BfaD DIMM PC card on 2.4 RT-Linux enabled kernel
-  - KVASER pcican-q on 2.6 Linux kernel
-  - MICROSPACE msmcan on 2.4 Linux and RT-Linux enabled kernel
-  - Unicontrols PCAN ("unican"),PCAN-PCI ("unican-pci"), VCAN  ("unican-vme")
+  - KVASER pcican-q on 2.6 and 3.0 Linux kernel

   - EMS CPC-PCI cards ("ems_cpcpci")
   - virtual board tested on all systems as wel
 It takes more time to test driver with more cards.
   - EMS CPC-PCI cards ("ems_cpcpci")
   - virtual board tested on all systems as wel
 It takes more time to test driver with more cards.


@@ -101,35 +102,24 @@ variants is prepared in the sources.
 SOURCES AND URLs
 ================
 
 SOURCES AND URLs
 ================
 

-The LinCAN driver component page at OCERA web site
-(not updated to the new version yet)
+The actual driver version, development sources and mailing list
+can be found on OrtCAN project pages

 
 

-  http://www.ocera.org/download/components/WP7/lincan-0.3.1.html
-  
-List of related communication components
-  
-  http://www.ocera.org/download/components/WP7/index.html
+  http://ortcan.sourceforge.net/

 
 

-The obtaining LinCAN and other CAN related components
-from OCERA CVS repository at SourceForge
+Please send comments, bug-fixes and enhancements directly to
+Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OrtCAN discussion
+forums <http://sourceforge.net/projects/ortcan/forums> 
+and or mailinglist found on OrtCAN project page.

 
 

-  EXTCVS=":pserver:anonymous@cvs.ocera.sourceforge.net:/cvsroot/ocera"
-  cvs -d$EXTCVS login
-  cvs -z3 -d$EXTCVS co ocera/components/comm/can
-  
-Web access into CVS
+The original LinCAN driver component page at OCERA web site
+(not updated to the new version yet)

 
 

-  http://ocera.cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ocera/ocera/components/comm/can/lincan/
+  http://www.ocera.org/download/components/WP7/lincan-0.3.1.html

 
 

-Experimental directory at maintainer's (Pavel Pisa's) pages 
+List of related communication components

 
 

-  http://cmp.felk.cvut.cz/~pisa/can/
-  http://cmp.felk.cvut.cz/~pisa/can/lincan-YYMMDD.tar.gz
-  
-Please send comments, bug-fixes and enhancements directly to
-Pavel Pisa <pisa@cmp.felk.cvut.cz> or to OCERA discussion
-forum <https://sourceforge.net/forum/forum.php?forum_id=170893> 
-and lists <ocera-development@lists.sourceforge.net>
+  http://www.ocera.org/download/components/WP7/index.html

 
 Driver documentation can be found at
 
 
 Driver documentation can be found at
 


@@ -144,83 +134,105 @@ COMPILATION of LinCAN releases
 ==============================
 
 Just type 'make' at the command line and driver module should compile
 ==============================
 
 Just type 'make' at the command line and driver module should compile

-without errors for current running kernel. 
+without errors for current running kernel.

 
 

-More information can be found in driver documentation at
+More detailed information can be found in driver documentation at
+  http://ortcan.sourceforge.net/lincan/
+Local maintainer site holds some usesfull information as well

   http://cmp.felk.cvut.cz/~pisa/can/
   http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf
   http://cmp.felk.cvut.cz/~pisa/can/
   http://cmp.felk.cvut.cz/~pisa/can/lincandoc-X.Y.pdf

-  
-Some releases use experimental OMK make system, which requires
+
+The LinCAN releases use OMK make system, which requires

 recent GNU make program version 3.81beta1 and above.
 Makefiles can be switched to old ones by script
 
   sh ./switch-omk2std
   make
 
 recent GNU make program version 3.81beta1 and above.
 Makefiles can be switched to old ones by script
 
   sh ./switch-omk2std
   make
 

-If you have problem to obtain recent GNU make program,

 
 

- ftp://alpha.gnu.org/gnu/make/make-3.81beta4.tar.bz2
+COMPILATION from OrtCAN project GIT repository tree
+===================================================

 
 

-you can use our local copy
+There are more options to build LinCAN driver.
+The first one is to use stand-alone driver module build.
+The other option is to build LinCAN driver as part of the
+whole OrtCAN tree.

 
 

-  http://cmp.felk.cvut.cz/~pisa/can/make-3.81beta1.tar.gz
+The latest version of stand-alone LinCAN sources can be
+obtained from GIT repository and build by next commands

 
 

+  git clone git://git.code.sf.net/p/ortcan/lincan
+  cd lincan
+  ./build-lincan.sh

 
 

-COMPILATION from CVS sources without full OCERA tree
-====================================================
-  
----------------------------------------------------------------------------
-Obtaining CVS sources of the CAN components only
----------------------------------------------------------------------------
-  cvs -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera login
-  cvs -z3 -d:pserver:anonymous@ocera.cvs.sourceforge.net:/cvsroot/ocera co
-         ocera/components/comm/can
+The other option is to build LinCAN driver as part of the whole
+OrtCAN tree

 
 

----------------------------------------------------------------------------
-Commands to build OCERA CVS CAN components outside OCERA tree
----------------------------------------------------------------------------
-  cd ocera/components/comm/can
-  ./switch2standalone
+  git clone git://git.code.sf.net/p/ortcan/ortcan-top
+  cd ortcan/
+  git submodule update --init
+  make default-config

   make
 
   make
 

-The selection of required features and options can be specified before make 
-command invocation. Lines containing required changes to config.omk-default 
-file should be stored in config.omk file. The config.omk is not altered by 
-OMK system and options defined there override values defined in 
-config.omk-default file. GNU make program version 3.81beta1 or newer is 
-required by OMK make-system. If this is problem, LinCAN driver can be 
-compiled with use of old style Makefiles as well.
-
----------------------------------------------------------------------------
-Old style Makefiles compilation of the LinCAN driver only
----------------------------------------------------------------------------
-  cd ocera/components/comm/can/lincan
-  ./switch-omk2std
-  make
+COMPILATION options
+===================
+
+The options are defined in "config.omk" file for OMK based builds.
+File is looked for at directory where are build top directory,
+files "Makefile.rules" and "config.omk-default"
+located. To select card which is not enabled by default
+add line of next format to the "config.omk" file
+
+  CONFIG_OC_LINCAN_CARD_tscan1=y
+
+The cross-compilation and build against non-default kernel
+can be selected in "config.omk" file as well
+
+  LINUX_DIR=/usr/src/linux-2.6-mpc5200-build
+  CC=powerpc-linux-gnu-gcc
+  CXX=powerpc-linux-gnu-g++
+  AR=powerpc-linux-gnu-ar
+  LD=powerpc-linux-gnu-ld

 
 
 INSTALLATION
 ============
 Type 'make install' for standard make system compilation.
 The driver should be copied into actual kernel version
 
 
 INSTALLATION
 ============
 Type 'make install' for standard make system compilation.
 The driver should be copied into actual kernel version

-modules directory "/lib/modules/x.y.z/kernel/drivers/char".
+modules directory "/lib/modules/x.y.z/extra".

 
 OMK system requires manual copy of files from "_compiled" tree
 
 OMK system requires manual copy of files from "_compiled" tree

-to its final destinations.
+to its final destinations. Just compiled driver can be
+tested directly from LinCAN build directory (i.e. example
+for PC/104 PCM3680 board)
+
+  insmod _compiled/modules/lincan.ko hw=pcm3680 io=0x200 irq=7,11

 
 

-Create file "lincan.rules" with contents listed below in or linked
-into "/etc/udev/rules.d" directory to enable automatic device nodes
-creation for UDEV based system
+Driver can be copied into system final location after testing
+
+  mkdir /lib/modules/$(uname -r)/extra
+  cp _compiled/modules/lincan.ko /lib/modules/$(uname -r)/extra
+  chown root:root /lib/modules/$(uname -r)/extra/lincan.ko
+  depmod -a
+
+Right to access the driver for non-root users can be granted by
+generation of "10-lincan.rules" in the UDEV configuration directory
+"/etc/udev/rules.d"

 
   # LinCAN driver
   SUBSYSTEM=="can",GROUP="users",MODE="0660"
 
 
   # LinCAN driver
   SUBSYSTEM=="can",GROUP="users",MODE="0660"
 

-The driver automatic loding can be requested by addition of "lincan"
-line into "/etc/modules" od Debian based systems.
+The driver automatic loading of the driver can be requested by addition
+of "lincan" line into "/etc/modules" for Debian based systems. The module
+parameters can be specified in the same file after "lincan" driver name
+or in separate file in "/etc/modprobe.d" directory (i.e.)
+
+  echo >/etc/modprobe.d/lincan.conf \
+     options lincan processlocal=2 hw=pcm3680 io=0x200 irq=7,11

 
 

-The target hardware/board specific options should be added into
-"/etc/modprobe.conf" file or file with similar functionality for your
-distribution. The options are discusses in the next paragraph.
+This files location can vary between distributions.
+The LinCAN driver options are discusses in more details in
+the next paragraph.

 
 LOADING
 =======
 
 LOADING
 =======


@@ -254,6 +266,7 @@ The hw argument can be one of:
 - gensja1000io for many sja1000 I/O mapped cards (PCAN-PC/104 for example).
 - gensja1000mm for ISA memory mapped sja1000 CAN cards
   (for pikronisa card used by PiKRON Ltd. the clockfreq=24000 has to be specified)
 - gensja1000io for many sja1000 I/O mapped cards (PCAN-PC/104 for example).
 - gensja1000mm for ISA memory mapped sja1000 CAN cards
   (for pikronisa card used by PiKRON Ltd. the clockfreq=24000 has to be specified)

+- pcisja1000mm for SJA1000 directly mapped into PCI mem region 0

 - pimx1 for MX1_DIS1 extension board for PiMX1 ARM based BCC
 - msmcan for MICROSPACE IO space indexed i82527
 - unican for Unicontrols PCAN card
 - pimx1 for MX1_DIS1 extension board for PiMX1 ARM based BCC
 - msmcan for MICROSPACE IO space indexed i82527
 - unican for Unicontrols PCAN card