The software support contains of core install binaries and the developer's support files . We are providing a basic API (application programming interface) set for developers allowing building of applications which can access i/o ports and physical memory areas .

for ISA / PCMCIA / PCI cards mounted on our USB2 family of products or the SSI2 family of products .

The majority of the software running under Linux is open source , and many of it's user's are actual developers and professional programmers . We have geared our Linux product release specifically for developers and programmers , who can take the source code of a specific ISA, PCI, or PCMCIA card , and make it working with USB2 / SSI2 products .

2. Where is the source code?

We have developed an independent USB2 host and device support. Originally developed under Windows operating systems we have ported it to work under Linux operating system.

We do not share our source code with developers or users - it is our company proprietary and confidential code. We are providing instead an easy to use interface to our products, together with samples.

Most of the present day Linux kernels contain USB2 EHCI host support. Our USB2 host support can co-exist with the built in Linux USB2 host support.

If needed, you can add an USB2 host controller - as a PCI card to a desktop computer, or a PCMCIA card to a notebook computer, and use this controller specifically for the USB2ISA family of products and USB2PCMCIA product.

Our SSI2 products require using a host card - SSI2 Host PCI for a desktop computer, or SSI2 HOST CB/EC for a notebook computer with either CardBus or ExpressCard slots.

3. Core binaries use

The linux release files are packed in a single .zip file.

The file name includes our release number - for ex. linux-2-0-x.zip. Every time any of the files are updated, the release number is increased to reflect the change.

You can copy the .zip file to a disk, unpack/unzip, and copy the files to a folder on your linux system.

Number of driver related files are not normally visible after unzip.

While copying our files with file explorer - please select 'show hidden files' option in order to see all the files.

There are 2 main sub-folders containing files for 32bit and 64bit releases of the Linux operating system.

The driver needs to be build under !!! EVERY !!! computer system and operating system version.
You can use 'arstech.ko' binary only for identical desktop/notebook system, running identical Linux kernel and distribution.
More on building drivers for different 2.6.xx kernels is provided in ch.5 .

The binaries have been built and tested for x86 type processors - including the 32/64bit families of - Intel , AMD , VIA , Transmeta ... and compatible processors . The majority of the today's computer systems include one of the above processors .

We can build and provide releases for other types of processors as well - like IBM PowerPC , ARM ... processors .

3.1 loading our driver -

For loading under 2.6.xx kernels, a driver has to be built for every specific kernel version and environment. Please refer to chapter 5 for details on building of the driver.

In the same way, the Linux 2.6.xx kernel needs to be built in a way that it allows loading of kernel modules . If the kernel does not allow this there will be an error message message . You will need to change the kernel , or use another system , which kernel allows loading of modules .

To load please type -
insmod arstech.ko

The above methods allow loading of driver while logged as 'root' . When logged as user the driver will need to be loaded using the 'sudo' command -

sudo insmod arstech.ko

3.2. ARS Technologies enumerator

You can load the enumerator on command line as -
./arsenum
or
sudo ./arsenum

The program scans and reports the computer system's i/o and memory spaces .

When first run the program shows the number of USB2 EHCI hosts found , and if there are more than one , asks for a selection of which one will be used with our USB2ISA / USB2PCMCIA products . The selection is stored and the next time the program is run , there is no selection prompt .

To select another host - choose 'd' on the main command selection , re-run the program and make another selection .

When an USB2ISA / USB2PCMCIA product is connected / disconnected there are text messages . When inserted , the enumerator reports the type of the card - USB2ISA or USB2PCMCIA , the usb port where it was connected . A scanning of the hardware resources is performed and the found i/o ports , and physical memory areas are reported .

When running the enumerator program it shows the SSI2 hosts found - if found present.

When an SSI2 ISA / SSI2 PCI / SSI2 PCMCIA product is connected / disconnected there are text messages . When inserted , the enumerator reports the type of the card - SSI2 ISA / SSI2 PCI / SSI2 PCMCIA , the usb port where it was connected . A scanning of the hardware resources is performed and the found i/o ports , and physical memory areas are reported .

The scanning of the hardware resources is not ideal , and some hidden ports / memory areas may not be recognized or reported .

There may be a need to add manually resources which were not detected. Choose 'r' to add resources, select the resource type : 1-i/o ports, 2-memory area, 3-irq channel, or 4-dma channel, and type the addresses or the channel number.

The main command prompt of the enumerator contains a selection of commands for manual read/write of i/o & physical memory spaces . Please use for an initial check / test of the ISA / PCI / PCMCIA cards .

3.3. Debug mode of the enumerator

To load the enumerator in debug mode type on command line -
./arsenum d
or
sudo ./arsenum d

The enumerator will display one after another messages on the steps it takes.

In case of problems, please check / take a note of the last displayed message before the problem occurred, and notify us.

3.4. Building of the enumerator

Linux allows running binaries of applications build on one environment, defined as a combination of - kernel/gcc/libraries versions, on a variety of other environments.

We provide pre-built binary of the enumerator - 'arsenum' for both 32bit and 64bit environments.

Occasionally this does not work - the enumerator may crash, or can not start.

In order to assist the work in a specific or a customized environment, we provide a way to build the enumerator.

Under '/32bit' and '/64bit' folders, there is the '/app' folder containing build files. Run -
./mk.bat
to build a binary of the enumerator - 'arsenum' for the specific environment.

4. Developer's support

4.1 Basic API set

Here is the commands list :

standard commands used by application for direct access to i/o ports -

!!! Note1 : In order to read/write meaningful values , the ARSTech enumerator should be running , the USB2ISA / USB2PCMCIA , or SSI2 ISA / SSI2 PCI / SSI2 PCMCIA card needs to be connected and recognized by the enumerator , and the mounted ISA / PCI / PCMCIA card need to actually have the i/o port or the physical memory area being accessed .

!!! Note2: The calling convention of the api set is different that the Linux - outb/outw , writeb/writew commands. The first parameter in our api set is the address of the port or physical memory , compared to Linux where the address is the second parameter. Please replace as for ex. -
#define outb(a, b) out8(b, a)

!!! Note3 : An additional API set is available in our SDKBUS kit allowing the additional possibilities of -
- building of kernel drivers which use the kernel level api set
- dealing with IRQ and DMA channels and events based on them
- managing the hardware - issuing hardware reset , adjusting read/write cycle ...
for ISA / PCI / PCMCIA cards mounted on our USB2 family of products , or SSI2 family of products .

4.2 Samples for using our API set

There are 2 samples located in 'sample-st' and 'sample-dyn' directories , showing reading of sector 1 - partition table of a hard disk , connected to an ISA I/O card mounted on USB2ISA / SSI2 ISA - the type that has one floppy , one ide controllers , 2 serial and one parallel ports . The disk need to be connected and powered on .

In addition the ARSTech enumerator should be running , the USB2ISA / USB2PCMCIA / SSI2 ISA / SSI2 PCI / SSI2 PCMCIA card needs to be connected and recognized by the enumerator , and the mounted ISA / PCI / PCMCIA card need to actually have the i/o port or the physical memory area being accessed .

To build the samples you can run the script file -
./mk.bat

The api set in 'sample-st' is obtained from our archive (or static library) file - libars1.a . You will need to link with this archive for every new project you are building .

The api set in 'sample-dyn' is obtained from the dynamic library file - arsusb1.so . You will need to place this file in the same folder where your binary is .

5. Support for 2.6.xx kernels

The 2.6 line of Linux kernels was introduced in the beginning of 2004, and as of the present time they are in use in wide variety of systems.

For one of another reason the 2.6 kernels are very strict with the loadable modules - they require every module to be built under the same conditions as the rest of the standard or custom, built-in or loadable modules. Any difference in the - kernel version or revision, processor, compiler ... etc. will prevent the module from being loaded.

5.1 prepare for building of the driver

The process of building of a 2.6 module / driver is quite complex - and it applies to any type of 2.6 linux driver. One important detail is - the kernel you want to work on has to have the kernel symbols . They are normally available after building of a new kernel, or after installing a development platform - for ex. Ubuntu. Every module then is using these kernel symbols for info (address) on where the kernel functions it uses are coming from .

You need a development platform - we are using Ubuntu 9.04/8.10/8.04, 2.6.28/27/24 kernels + gcc4

Create directory 'arstech' on your root (/) ot home (/home) folder.

Unzip and copy all the files from the linux release on your '/arstech' folder.

5.2 selecting the location of the driver build files

We are providing number of driver files - built with gcc4, and tested under Ubuntu 8.04/8.10/9.04 versions, 32bit and 64bit releases, which have kernels - 2.6.24/2.6.27/2.6.28.

You need to build a driver for the particular environment, as a combination of computer hardware, kernel, Linux distribution .

The important parameters of the environment are -
- is it 32bit or 64bit
- kernel release number

If not knowing these parameters, please run once the 'enumerator' as -
./arsenum
or
sudo ./arsenum

A 32bit enumerator is not going to run on 64bit environment, and 64bit enumerator is not going to run on 32bit environment.

After the top lines of the 'arsenum' it shows - processor, and kernel, for ex.
kernel=2.6.30
processor=x86_64

Based on this information, select the 'closest' , and 'lower' kernel driver files location, for ex. in -
arstech/rel/64bit/drv/2-6-28-ubuntu-9-04

5.3 building and loading of a module under the same / default (booted) kernel

Please note that the 'arsbuild.bat' is a text file which need CR+LF in the end of each line. Some text editors only have CR in the end of the line and the script can not run.
In this case the file has to modified to CR+LF in the end of each line.

5.4 building of a module under a different kernel than the default (booted) kernel

In general you will need to go through similar as above number of steps -
- you need a development platform - we use Ubuntu , 2.6.24/26/28 kernel + gcc4
- then you need to download the kernel source of the kernel you want to work on - for ex. 2.6.26 ; you will need to go through the steps of building of the kernel with the options you like

You can load a kernel sources from - www.kernel.org, for ex. linux-2.6.26.tar.gz. Unpack the file and copy the 'linux-2.6.26' directory to for ex. - '/arstech/kernel' . You may need to build the kernel.

You can build a driver for other kernels by modifying the 'Makefile'. Please load 'Makefile' in a text editor and, look at the content. Then you can change Makefile to for ex. -
26:
make -C /arstech/kernel/linux-2.6.26 M=$(PWD) modules
After saving 'Makefile', opening and running from shell -
> make -i 26
, you will have 2.6.26 driver.

Or, you can modify the - drv-build.bat script file to include make of other kernels as well.

If you build drivers for number of kernels - please save them with different names, or in different folders. When testing, please copy the matching newly created 2.6.15 arstech.ko driver for ex. to where the 'arsenum' is, reboot under 2.6.26 kernel and test.