federicovaga / zio Goto Github PK

Zio is "the ultimate I/O framework".  It is being developed on the open
hardware repository at http://www.ohwr.org/projects/zio .

This version is known to compile and run with kernels 3.3 onwards
(it used to work from 2.6.34 onwards, and we may fix the dev.id issue
to restore such backward compatibility.

This README in not updated very often, so please take this information
with a grain of salt.  The architecture of ZIO and the basic concepts
are explained on www.ohwr.org/projects/zio/ (in particular the "files"
and "documents" tabs).

To test zio you need to load the core module:

   	insmod zio.ko

By detault ZIO uses "kmalloc" as a buffer, it is a simple buffer that
hosts a list of data blocks, for either input or output.

The default trigger is called "user", and it fires data transfers when
the user reads or writes. We also have the "timer" trigger: it is a
kernel-timer based trigger, that fires a block transfer on a timely
basis. You can use the "ms" parameter to set the inter-block time, in
milliseconds (the default is two seconds). You can also pass the
"nsamples" parameter to say how many samples are acquired at each
trigger instance.

With the core in place, you can load a driver (we have several, this only
shows the basics of zio-zero for input):

	insmod drivers/zio-zero.ko

zio-zero has three channel sets. cset 0 has three channels.
They simulate three analog inputs, 8-bits per sample.

     channel 0: returns zero forever
     channel 1: returns random numbers
     channel 2: returns a sawtooth signal (0 to 255 and back)

The char devices are called using device-cset-channel:

    /dev/zio/zzero-0-0-ctrl
    /dev/zio/zzero-0-0-data
    /dev/zio/zzero-0-1-ctrl
    /dev/zio/zzero-0-1-data
    /dev/zio/zzero-0-2-ctrl
    /dev/zio/zzero-0-2-data

To read data you can just cat, or "od -t x1" the data device.
To get control information meta-information) together with data, you
can use the "zio-dump" user-space utility, in this directory.

For example:

    ./zio-dump /dev/zio/zzero-0-2-*

This is the result with a trigger that uses 2000 as msec and 32
as nsample:

    ./zio-dump /dev/zio/zzero-0-2-*

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 2
    Ctrl: seq 1, n 32, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 1320403540.084798370 (0)
    Data: 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
    Data: 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 2
    Ctrl: seq 2, n 32, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 1320403542.091093781 (0)
    Data: 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
    Data: 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 2
    Ctrl: seq 3, n 32, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 1320403544.084790274 (0)
    Data: 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
    Data: 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f

zio-dump is able to access several pairs of devices (control and data),
and you can change the trigger and buffer attributes for the cset.

Example:

    echo 500 > /sys/zio/devices/zzero/cset0/trigger/ms-period
    echo 4 > /sys/zio/devices/zzero/cset0/trigger/nsamples
    echo 3 > /sys/zio/devices/zzero/cset0/chan0/buffer/max-buffer-len
    ./zio-dump /dev/zzero-0-*

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 0
    Ctrl: seq 102, n 4, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 4066.519285605 (0)
    Data: 00 00 00 00

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 1
    Ctrl: seq 102, n 4, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 4066.519285605 (0)
    Data: 71 29 a6 53

    Ctrl: version 0.2, trigger timer, dev zzero, cset 0, chan 2
    Ctrl: seq 102, n 4, size 1, bits 8, flags 01000001 (little-endian)
    Ctrl: stamp 4066.519285605 (0)
    Data: 60 61 62 63