Documentation/comedi/command

   1
   2 Version 0.8.x will feature a replacement for the comedi_trig
   3 structure that allows much more flexible acquisition with
   4 applicable hardware.  Gone will be the days of "mode2" and
   5 friends.
   6
   7 The replacement for mode0, i.e., immediate acquisition, is a
   8 new ioctl that is very similar to the old trigger ioctl, but
   9 just implements mode0 features.
  10
  11 The other modes are replaced by the comedi "command" ioctl.
  12 The command structure allows you to specify what causes each
  13 action that is taken during acquisition.  The actions currently
  14 understood by comedi are:
  15
  16         - Start acquisition
  17         - Stop acquisition
  18         - Begin a scan
  19         - End a scan
  20         - Convert a sample
  21
  22 A "scan" is a repeated measurement of N different channels.
  23
  24 The different types of "triggers" or "trigger signals" that can
  25 cause events to occur are:
  26
  27         - TRIG_NONE - don't ever trigger
  28         - TRIG_NOW - cause trigger to occur right now (or really soon)
  29         - TRIG_FOLLOW - (see below)
  30         - TRIG_TIME - trigger at specific time
  31         - TRIG_TIMER - trigger at specific rate
  32         - TRIG_COUNT - trigger when count reaches specific value
  33         - TRIG_EXT - trigger on external signal
  34         - TRIG_INT - trigger on an internal comedi signal
  35
  36 Not all triggers are applicable to all events.  Supported triggers
  37 for specific events depends significantly on your particular
  38 device.  In addition, for every trigger type, there is a cooresponding
  39 argument that specifies the rate, the count, which external signal,
  40 etc.
  41
  42 In particular, scan_end events will almost always be triggered on
  43 TRIG_COUNT, with the argument being the number of channels in the
  44 scan.  (Actually, samples in the scan, since on most boards you can
  45 measure a single channel multiple times in a scan.)  Also, until
  46 otherwise supported, start events can only be TRIG_NOW.
  47
  48 TRIG_FOLLOW is a special type of trigger for scan_begin events that
  49 triggers on the next lower level trigger, in this case, the trigger
  50 for convert events.  It may or may not be supported.  Later, it may
  51 also be used for start events if you want to chain multiple commands.
  52 I might also consider using it for convert events, to indicate the
  53 board maximum rate.
  54
  55 The command strucure is as follows:
  56
  57 struct comedi_cmd_struct{
  58        unsigned int subdev;
  59        unsigned int flags;
  60
  61        unsigned int start_src;
  62        unsigned int start_arg;
  63
  64        unsigned int scan_begin_src;
  65        unsigned int scan_begin_arg;
  66
  67        unsigned int convert_src;
  68        unsigned int convert_arg;
  69
  70        unsigned int scan_end_src;
  71        unsigned int scan_end_arg;
  72
  73        unsigned int stop_src;
  74        unsigned int stop_arg;
  75
  76        unsigned int *chanlist;         /* channel/range list */
  77        unsigned int chanlist_len;
  78
  79        sampl_t *data;                  /* data list, size depends on subd flags */
  80        unsigned int data_len;
  81 };
  82
  83 subdev is the target subdevice.  flags are flags, similar to the
  84 old trigger structure.  chanlist, chanlist_len, data, and data_len
  85 are similar to the old trigger structure, although chanlist_len has
  86 been changed from n_chan.  data and data_len are used only by users
  87 who write kernel-space code, i.e., virtual comedi devices or RTLinux.
  88
  89
  90 Some examples for commands:
  91
  92 Suppose you want to measure channels 1,2,3,4 at a rate of 10 khz, with
  93 the inter-sample time at 10 us (100 khz), and that you want to measure
  94 10000 scans.  This is analogous to the old mode2 acquisition.
  95 Initialization of the command structure to do this would include:
  96
  97         start_src       = TRIG_NOW;
  98         start_arg       = 0;            // doesn't matter
  99         scan_begin_src  = TRIG_TIMER;
 100         scan_begin_arg  = 100000;       // == 100e3 nanoseconds
 101         convert_src     = TRIG_TIMER;
 102         convert_arg     = 10000;        // == 10e3 nanoseconds
 103         scan_end_src    = TRIG_COUNTER;
 104         scan_end_arg    = 4;            // == number of channels
 105         stop_src        = TRIG_COUNTER;
 106         stop_arg        = 10000;        // == 10000 scans
 107
 108 If, instead, you wish to start continuous acquisition, and stop it with
 109 a comedi_cancel(), you would change the stop event trigger to:
 110
 111         stop_src        = TRIG_NONE;
 112         stop_arg        = 0;
 113
 114 Suppose you want to use an external signal to trigger scan_begin events.
 115 Then you would change the scan_begin event trigger to:
 116
 117         scan_begin_src  = TRIG_EXT;
 118         scan_begin_arg  = 2;            // external trigger #2
 119
 120 The number of possible external trigger lines is board dependent.  Your
 121 board may only have one non-configurable digital external trigger, or
 122 it may support complicated selection of external triggering, including
 123 analog triggers at multiple levels, edge or level digital triggers,
 124 synchonization signals with other boards, etc.  Eventually, boards
 125 that support complicated triggering will have a triggering subdevice
 126 with which you can configure all the different features.
 127
 128 Here's some pseudo-code that describes how the device should interpret
 129 your command:
 130
 131 do_command()
 132 {
 133         while(!start_trigger)
 134                 do_nothing();
 135
 136         while(!stop_trigger){
 137                 if(!scan_begin_trigger)
 138                         continue;
 139
 140                 while(!scan_end_trigger){
 141                         while(!convert_trigger)
 142                                 do_nothing();
 143                         do_conversion();
 144                 }
 145         }
 146 }
 147
 148 The fencepost issues, i.e., what happens when you have conflicting
 149 triggers, is device-dependent.
 150