	ADDI-DATA IOCTL Linux driver copyright 2009 - ADDI-DATA
	=======================================================

	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 - GENERAL INFORMATION


 INTRODUCTION
 ============
 
 The driver is designed as a kernel module compliant with 
 kernel 2.4 and 2.6.
 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 apcie1516.h
 kernel API is described in the file apcie1516-kapi.h
 
 The driver can be adapted to be used with realtime patches like RTAI.
 
 The directory "samples" contains a software that examplifies the use of the IOCTL interface.
 The directory "ksamples" contains the sources of kernel modules that show how to use 
 the kernel API.

 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/apcie1516_rXXX.tar.bz2
 	
 	Untar the package archive:
  	$ tar -jvxf /tmp/apcie1516_rXXX.tar.bz2
 	
	This will create the directory /tmp/apcie1516_rXXX/ that contains the driver sources.
	
	Move headers into the kernel sources:
	mv -Rfp /tmp/apcie1516_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/apcie1516_rXXX/drivers/addidata/apcie1516 /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/apcie1516_rXXX.tar.bz2
 	
 	Untar the package archive:
 	tar -jvxf /tmp/apcie1516_rXXX.tar.bz2
 	
	This will create the directory /tmp/apcie1516_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 apcie1516_rXXX/drivers/addidata/apcie1516/, 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 
	KERNELSRCDIR:=/usr/src/linux/
	####################################################################


	####################################################################
	# 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 
	ADDIDATAINC:=$(shell pwd)/../../../include/linux/addidata/
	#################################################################### 		
	
	KERNELSRCDIR is the path of kernel sources.
	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. apcie1516_ioctl and type:
	
		- For kernel 2.4
			make -f _makefile 2.4
	
		- For kernel 2.6
			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 apcie1516.o, to load it use:
 		insmod apcie1516.o 	
 		
 		To unload the driver:
 		rmmod apcie1516
 	
 	Kernel 2.6:
 		The driver is named apcie1516.ko, to load it, use the mkdevs.sh script:
 		./mkdevs.sh 	
 	
 		To unload the driver:
 		rmmod apcie1516


	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/apcie1516/
	Then, launch these simple commands:
		make -f _makefile install_26

	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

	To configure udev manually, add in your configuration file:
	SUBSYSTEMS=="apcie1516", SYMLINK+="apcie1516/%m"
	and call
	$ udevcontrol reload_rules 
	or 
	$ udevadm control --reload_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 apcie1516.o
		(the module extension is .o)

	e.g. for a 2.6 kernel:
		find /lib/modules/2.6.15 -name apcie1516.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 and 2.6 without UDev:
		Edit the file /etc/modules, and add the name of the module, e.g. apcie1516, 
		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 - GENERAL INFORMATION
=======================

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

 For each board detected the driver dynamically creates a 
 special character device file in /proc/sys/apcie1516 (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/apcie1516.

 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
