Elomax Driver project

elomax

This is the documentation of the "Elomax Driver" project.

Elomax Driver Requirements

Elomax (http://www.elomax.nl) units are units that control io and can be addressed via usb. Elomax produces several types:

• iosolution, 12 single bit digital io,
• aninsolution, 4 differential 12 bit analog in plus 8 digital io,
• fansolution, 4 8 bits pwm outputs plus 8 digital io

All these 'solutions' have in common that they communicate via 8 byte blocks, though the content of these 8 bytes differs per 'solution'.

That is where this package comes in. This package has to implement the bare usb communication, delivering the 8 byte blocks both ways, without interpreting their content.

This package has to fullfill the requirements:

• it has to be implemented as a linux 2.6 driver
• it must be capable to deliver the last received information from the 'solution' to the requesting application
• it must be capable to deliver the data from the application to the 'solution'
• it must support at least the 'solution' types: iosolution, aninsolution and fansolution
• it must be capable to tell an user application the type of 'solution' 'behind' the device file
• it must be capable to tell the application a unique and reproducable identification, representing the physical connection of the 'solution' (to which usb-bus, via which hub, at which port the 'solution' is connected).
• it must support simultaneous access by multiple applications

Elomax Driver User View

To install the driver in the system:

• build the elomax.ko file from the sources in this package
• place the elomax.ko file somewhere in the /lib/modules/`uname -r`/ directory
• run the command 'depmod -a'
• place the 20-elomax.rules file in the /etc/udev/rules.d/ directory

When an elomax unit is connected to the system's usb-bus, the kernel will tell udev about it. This result udev in telling the kernel to load the elomax.ko module, after which the usb-core of the kernel will 'probe' the unit through this package. The driver will accept control over the unit, which it tells to the usb-core, who will tell udev to create a device file for the unit.

Via this device file can an user application access the driver and so the unit. The allowed operations on the device file are described in elomax.h.

Elomax Driver Implementation

Where the picture above gives an hierarchical overview, the picture below gives the relationship between functions and data inside this package, roughly ordered in time.

The solid lines represent the usage/update of data by a function. The dashed lines represent one function calling another. The dotted lines represent the possibility to find related data (usually a 'pointer to' the destination data is included in the source data).

First there is the stage of module loading. The modprobe/rmmod commands respectively trigger the execution of the kernelmodule_init() and kernelmodule_exit() functions. This functionality is described in more detail in kernelmodule.h.

The (un)loading of this package triggers the construction/destruction of the elomax_driver layer. The functions elomax_driver_construct() and elomax_driver_destruct() announce this package to the usb-core. It gives the {vendorid, productid} pairs for which this driver wants to be informed. When such a unit is connected/disconnected, the functions according the driver-table are called (elomax_driver_probe() and elomax_driver_disconnect()). This functionality is described in more detail in elomaxdriver.h.

The third stage is triggered when an elomax-unit is connected to the usb-bus. This results in the construction of an elomax_instance which is announced to the usb-core by telling the class-driver-table. The usb-core now (lets) create(s) the corresponding device-file with its minor-node. This is describe in more detail in elomaxinstance.h.

The fourth and last stage is user-access to the device-file. The class-driver told the usb-core which function to call, which when the user access the device-file results in elomax_instance_open(), elomax_instance_read(), elomax_instance_write() and/or elomax_instance_close() to be called. These functions are described in more detail in elomaxinstance-priv.h.

This interaction can also be depicted as shown in the figure below.