
	ADDI-DATA Linux driver (copyright 2009-2021 - ADDI-DATA GmbH)
	=============================================================


	1 - INTRODUCTION
	
	2 - INSTALLATION
		2.1 - Installation for building in kernel sources
		2.2 - Installation for building out of kernel sources
	
	3 - CONFIGURATION AND COMPILATION	
		3.1 - Building in kernel sources
		3.2 - Building out of kernel sources
	
	4 - LOADING / UNLOADING THE DRIVER MANUALY
		4.1 - IS THE DRIVER LOADED?
	
	5 - LOADING THE DRIVER AUTOMATICALLY AT BOOT TIME
		5.1 - IS THE DRIVER INSTALLED?
		5.2 - Tell the OS to load the driver at boot time
	
	6 - SAMPLES
	
	7 - TROUBLESHOOTING
		7.1 - CONFLICT WITH COMEDI

	8 - GENERAL INFORMATION


 1 - INTRODUCTION
 ================
 
 The driver is designed as a kernel module compliant with 
 kernel from version 2.4 to 5.x.
 It contains ioctl functions that can be called from a user level
 application, and exported kernel functions that can be called in a other  
 kernel module.
 
 ioctl commands are described in the file apcie2200.h
 kernel API is described in the file apcie2200-kapi.h
 
 The driver can be adapted to be used with realtime patches like RTAI.
 
 The directory "samples" contains a software that shows how to use the IOCTL interface.
 The directory "ksamples" contains the sources of kernel modules that show how to use 
 the kernel API.


 2 - INSTALLATION
 ================
 
 To be compiled, the driver uses the kernel compilation process.
 Driver sources have generally to be installed and built in the kernel sources directory.
 But, they can be installed and built out of kernel sources.
 
	2.1 - Installation for building in kernel sources
 	=================================================
 	
 	Copy the driver package into e.g. you /tmp directory:
 	/tmp/apcie2200_rXXX.tar.bz2
 	
 	Untar the package archive:
  	$ tar -jvxf /tmp/apcie2200_rXXX.tar.bz2
 	
	This will create the directory /tmp/apcie2200_rXXX/ that contains the driver sources.
	
	Move headers into the kernel sources:
	mv -Rfp /tmp/apcie2200_rXXX/include/linux/addidata /usr/src/linux/include/linux
	
	Move the driver code into the kernel sources:
	mkdir /usr/src/linux/drivers/addidata
	mv -Rfp /tmp/apcie2200_rXXX/drivers/addidata/apcie2200 /usr/src/linux/drivers/addidata
	
	2.2 Installation for building out of kernel sources
 	===================================================	
 	
 	Extract the package where you want e.g.: /tmp
 	
 	Copy the driver package into e.g. you tmp directory:
 	/tmp/apcie2200_rXXX.tar.bz2
 	
 	Untar the package archive:
 	tar -jvxf /tmp/apcie2200_rXXX.tar.bz2
 	
	This will create the directory /tmp/apcie2200_rXXX/ that contains the driver sources.
	
	
 3 - CONFIGURATION AND COMPILATION	
 =================================
 
 	3.1 - Building in kernel sources
 	================================ 
 	
 	If you have a link called linux, pointing on /usr/src/linux, 
 	and that you correctly installed sources, you don't have to configure anything.
 	Else please read the following section.
 	
 	3.2 - Building out of kernel sources
 	==================================== 
 	
 	In apcie2200_rXXX/drivers/addidata/apcie2200/, edit the "_makefile" file, you will see both fields:
 	
	####################################################################
	# relative path of the source of the kernel to build against
	# IF YOU ARE BUILDING THIS DRIVER OUTSIDE THE KERNEL SOURCE
	# PLEASE ADAPT THIS VARIABLE TO YOUR LOCAL INSTALLATION 
	ifeq ($(KERNELSRCDIR),)
	KERNELSRCDIR:=/lib/modules/$(shell uname -r)/build
	endif
	####################################################################


	####################################################################
	# relative path of the addidata include directory
	# IF YOU ARE BUILDING THIS DRIVER OUTSIDE THE KERNEL SOURCE
	# PLEASE ADAPT THIS VARIABLE TO YOUR LOCAL INSTALLATION 
	ifeq ($(ADDIDATAINC),)
	ADDIDATAINC:=$(shell pwd)/../../../include/linux/addidata
	endif
	#################################################################### 		
	
	KERNELSRCDIR is the path of kernel sources (by default, it will point to current loaded kernel).
	ADDIDATAINC is the path of ADDI-DATA driver header.
	Edit these values if they are not correct.
	
	To compile the driver, go into the driver sources directory 
	e.g. apcie2200_ioctl and type:
	
		- For kernel 2.4
			make -f _makefile 2.4
	
		- For kernel 2.6 and upper
			make -f _makefile 2.6
			

 4 - LOADING / UNLOADING THE DRIVER MANUALY
 ==========================================
 
	REMARK: Those operations will probably require root privileges.
 	
 	Kernel 2.4:
 		The driver is named apcie2200.o, to load it use:
 		insmod apcie2200.o 	
 		
 		To unload the driver:
 		rmmod apcie2200
 	
 	Kernel 2.6 and upper:

 		The driver is named apcie2200.ko, to load it use:
 		insmod apcie2200.ko 	
 		
 		To unload the driver:
 		rmmod apcie2200


	4.1 - IS THE DRIVER LOADED?
	===========================

 	You can check if the driver has been successfully loaded with the command lsmod.
	The names of the loaded drivers appear.

	REMARK: for more information about lsmod, type 
	man lsmod


5 - LOADING THE DRIVER AUTOMATICALLY AT BOOT TIME
=================================================

	REMARKS: 
	- This description is for kernel that are supporting UDev.
	  If your kernel doesn't support UDev, see "4 - LOADING / UNLOADING THE DRIVER MANUALY".
	  
	- Those operations will probably require root privileges.

	Maybe you want to load the driver at each boot automatically.

	Go into your driver sources directory, e.g.: /tmp/apcie2200/
	Then, launch these simple commands:
		make -f _makefile install_26
		depmod -ae


	What is the script doing?
	=========================

	This will copy the module in the subdirectory
	/lib/modules/<kernel_version_of_the_kernel_you_are_building>/extra/ with a debian system.

	And create the udev rules under /etc/udev/addidata.rules and a link under /etc/udev/rules.d/addidata.rules


	5.1 - IS THE DRIVER INSTALLED?
	==============================
	
	You can check if the driver file takes place in one of the subdirectories of 
	/lib/modules/<kernel_version_of_the_kernel_you_are_building>
	e.g.: /lib/modules/2.6.15

	To do so, launch the following command:
		find /lib/modules/<kernel_version_of_the_kernel_you_are_building> -name <name_of_the_module>

	e.g. for a 2.4 kernel:
		find /lib/modules/2.4.27 -name apcie2200.o
		(the module extension is .o)

	e.g. for a 2.6 and upper kernel:
		find /lib/modules/2.6.15 -name apcie2200.ko 
		(the module extension is .ko)

	If there is no result, it means that something failed.


	5.2 - Tell the OS to load the driver at boot time
 	=================================================

	Kernel 2.4, 2.6, 3.x, 4.x and 5.x
		Edit the file /etc/modules, and add the name of the module, e.g. apcie2200, 
		or simply use the command:
		echo "apcixxx">>/etc/modules

	You probably have to be root.
	If you do not find the /etc/modules file, please refer to your distribution 
	documentation (man modules).



6 - SAMPLES
===========
 
 	One or more samples are available. They are located in the samples directory.
 	To build them, go into the driver sources directory:
 	make -f _makefile samples
 	
 	REMARK: Before to run them, the driver has to be loaded.
 	

7 - TROUBLESHOOTING
===================
 
	7.1 - CONFLICT WITH COMEDI
 
	The Comedi project (https://comedi.org/) develops open-source drivers, tools, and libraries for data acquisition.
	Since kernel 2.6.30, Comedi drivers are included in kernel tree.
	Depending on the kernel and/or Linux distribution you are using, the Comedi drivers can be loaded automatically and detects Addi
-Data boards.
	If Comedi driver is loaded, it prevents the current driver to detect any installed board and to work with.
	This case can be verified by using the command 'lspci -k'.
	There is a workaround which consists of blacklist the Comedi driver.
	Create or Edit the /etc/modprobe.d/blacklist.conf file. Add the following lines and reboot the computer.

		blacklist comedi
		blacklist comedi_pci
		blacklist addi_apcie_2200
		
		
8 - GENERAL INFORMATION
=======================

 In the ADDI-DATA header directory (default: /usr/src/linux/include/linux/addidata/)
 See apcie2200.h for description of the IOCTL commands provided.
 See apcie2200-kapi.h for description of the kernel functions provided.
 See apcie2200-events.h for description of the event structure.
  
 These two commands are deprecated since there is possibility 
 to retrieve the same information from OS facilities :
 * CMD_apcie2200_CheckAndGetPCISlotNumber   
 * CMD_apcie2200_GetHardwareInformation     

 For each board detected the driver dynamically creates a 
 special character device file in /proc/sys/apcie2200 (kernel 2.4).

 * The major device number is provided by the operating system. 
 * The minor device number is actually the ordinal in the PCI device list (order of detection)
 * the name of the file is the PCI slot identification : BUS/SLOT/FUNCTION in hexadecimal

 On kernel >= 2.6, special character device file in /proc/sys/ are no more allowed, a node is created under /dev/apcie2200.

 WARNING: This driver has not been tested with a true PCI hotplug system.

 For any request or remark please contact us:
 info@addi-data.com
