File	Date	Author	Commit
doc	2009-10-31	Michael Davidsaver	[a14ebc] update doc
user	2009-06-22	mdavidsaver	[04687b] user: fix capture out formatting
.gitignore	2012-02-19	Michael Davidsaver	[8c4325] update ignore
99-maxp.rules	2009-06-24	Michael Davidsaver	[9f02d1] add example udev rule
COPYING	2009-09-16	Michael Davidsaver	[785399] add license
Changelog	2012-02-19	Michael Davidsaver	[ce41a1] update changelog
Makefile	2009-05-14	Michael Davidsaver	[f969d5] add module_install target
README	2009-10-31	Michael Davidsaver	[a14ebc] update doc
circ_buf_ext.c	2012-02-19	Michael Davidsaver	[dea202] missing header for kmalloc
circ_buf_ext.h	2009-05-13	Michael Davidsaver	[477f17] use circ_count for read test.
maxp-cap.c	2012-02-19	Michael Davidsaver	[b094ff] switch to "new" ioctl call
maxp-cap.h	2009-05-13	Michael Davidsaver	[a79903] use device_create to cause uevents
maxp-cmd.c	2012-02-19	Michael Davidsaver	[dea202] missing header for kmalloc
maxp-cmd.h	2009-05-13	Michael Davidsaver	[a79903] use device_create to cause uevents
maxp-ioctl.h	2009-10-31	Michael Davidsaver	[809f4f] revise ioctl to use unsigned for flags
maxp-main.c	2012-02-19	Michael Davidsaver	[5c95c4] missing include for TASK_INTERRUPTABLE
maxp.h	2009-07-07	Michael Davidsaver	[fbc9e6] doc update

Read Me

MAXp Driver

Michael Davidsaver <mdavidsaver@bnl.gov>

= Building =

Requires the usual (gcc,make,kernel headers)

$ make

$ sudo make modules_install
or
$ make modules_install INSTALL_MOD_PATH=/some/dir

Examples apps

$ make -C user

= Using =

== udev ==

The file 99-maxp.rules contains an example rule to allow
udev to create the maxp device files with the group ownership
instead of the default.

== Loading ==

# modprobe maxp [options]

Several options are available if required.
The defaults will be sufficient for most users.

startdev=0

  first minor number.

maxdev=16

  Highest number for a MAXp device.  Controls
  minor number allocation.  This should always
  be >=16 to allow for all possible dip switch
  settings.

bufsize=RESP_BUFFER_SIZE*4 (4096)

  Do not change this number unless you know what
  you are doing.  Size of per-device circular
  buffer used for responces.  When this buffer
  is full additional responces are lost.

= User-space interface =

Each MAXp card has two special device files which
by default are named '/dev/maxpcmd%d' and
'/dev/maxpcap%d' where '%d' is an integer
determined by the card id dip switch setting.
It is repeatable through system reboots.

Each device file can be manipulated in the
usual fashion.

== Command Device ==

/dev/maxpcmd%d

Used to send command strings to a MAXp and to receive
responces.  The read(2) call does not impliment seek,
or an option like 'MSG_PEEK'.  It is strongly suggested
that only one process read or write maxpcmd at a time.  The
driver does not enforce this because there does not to be
a good way to do this.


open()

  Use O_TRUNC to clear the responce buffer when opened.

write()

  Send a raw command string.

  eg. write(fd,'WY;',3)

read()

  Read a responce from the device.  If to responce is
  unavailable, read() will block unless O_NONBLOCK is set.

lseek() - not supported

select()

  Test to see if a responce is available.

ioctl() - nothing special

== Capture Device ==

/dev/maxpcap%d

Handles the asynchronous features of the MAXp.  These
are interrupt driven status and position/encoder updates.

open()

  Use O_DIRECT to read RT encoder/positions instead of
  capture (not recommended).

write() - not supported

read()

  Read a 'packet' of information including status flags,
  encoder, and position data.  When O_NONBLOCK is not set
  read() will wait until the next update condition occurs.
  Two possible conditions exist: status (limit switch),
  and data (encoder/position).  Each open file descripter
  can be independently set using the MAXP_BLOCK_COND ioctl().

lseek()

  Allows parts of the 'packet' to be ignored.

select()

  Wait for the next update condition (same as read()).

ioctl()

  MAXP_CARD_ID - Return an identifer for the hardware.
    This exists to allow for firmware version specific
    quirks which can't be handled in the driver (ie
    command string syntax).

  MAXP_CARD_AXES - Return number of axes supported.

  MAXP_FLAG_GET, MAXP_FLAG_CLEAR - Allow access to all
    status information.

  MAXP_BLOCK_COND - Set update condition to block on:
    MAXP_BLOCK_CAP or MAXP_BLOCK_STS

  MAXP_REQUEST_CAP - Request an asynchronus capture
    update (encoder/position).

== Example ==

Commands and replies

$ echo -n "WY;" > /dev/maxpcmd0
$ cat /dev/maxpcmd0
MAXP-.............
^C
$

Basic test

$ ./user/maxp-info /dev/maxpcap0 /dev/maxpcmd0
...

Manually request capture asynchronous data update

$ ./user/maxp-cap /dev/maxpcap0
...
...

In another console
$ ./user/maxp-req /dev/maxpcap0