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
  53 The command strucure is as follows:
  54
  55 struct comedi_cmd_struct{
  56        unsigned int subdev;
  57        unsigned int flags;
  58
  59        unsigned int start_src;
  60        unsigned int start_arg;
  61
  62        unsigned int scan_begin_src;
  63        unsigned int scan_begin_arg;
  64
  65        unsigned int convert_src;
  66        unsigned int convert_arg;
  67
  68        unsigned int scan_end_src;
  69        unsigned int scan_end_arg;
  70
  71        unsigned int stop_src;
  72        unsigned int stop_arg;
  73
  74        unsigned int *chanlist;         /* channel/range list */
  75        unsigned int chanlist_len;
  76
  77        sampl_t *data;                  /* data list, size depends on subd flags */
  78        unsigned int data_len;
  79 };
  80
  81 subdev is the target subdevice.  flags are flags, similar to the
  82 old trigger structure.  chanlist, chanlist_len, data, and data_len
  83 are similar to the old trigger structure, although chanlist_len has
  84 been changed from n_chan.  data and data_len are used only by users
  85 who write kernel-space code, i.e., virtual comedi devices or RTLinux.
  86
  87
  88 Some examples for commands:
  89
  90 Suppose you want to measure channels 1,2,3,4 at a rate of 10 khz, with
  91 the inter-sample time at 10 us (100 khz), and that you want to measure
  92 10000 scans.  This is analogous to the old mode2 acquisition.
  93 Initialization of the command structure to do this would include:
  94
  95         start_src       = TRIG_NOW;
  96         start_arg       = 0;            // doesn't matter
  97         scan_begin_src  = TRIG_TIMER;
  98         scan_begin_arg  = 100000;       // == 100e3 nanoseconds
  99         convert_src     = TRIG_TIMER;
 100         convert_arg     = 10000;        // == 10e3 nanoseconds
 101         scan_end_src    = TRIG_COUNTER;
 102         scan_end_arg    = 4;            // == number of channels
 103         stop_src        = TRIG_COUNTER;
 104         stop_arg        = 10000;        // == 10000 scans
 105
 106 If, instead, you wish to start continuous acquisition, and stop it with
 107 a comedi_cancel(), you would change the stop event trigger to:
 108
 109         stop_src        = TRIG_NONE;
 110         stop_arg        = 0;
 111
 112 Suppose you want to use an external signal to trigger scan_begin events.
 113 Then you would change the scan_begin event trigger to:
 114
 115         scan_begin_src  = TRIG_EXT;
 116         scan_begin_arg  = 2;            // external trigger #2
 117
 118 The number of possible external trigger lines is board dependent.  Your
 119 board may only have one non-configurable digital external trigger, or
 120 it may support complicated selection of external triggering, including
 121 analog triggers at multiple levels, edge or level digital triggers,
 122 synchonization signals with other boards, etc.  Eventually, boards
 123 that support complicated triggering will have a triggering subdevice
 124 with which you can configure all the different features.
 125
 126 Here's some pseudo-code that describes how the device should interpret
 127 your command:
 128
 129 do_command()
 130 {
 131         while(!start_trigger)
 132                 do_nothing();
 133
 134         while(!stop_trigger){
 135                 if(!scan_begin_trigger)
 136                         continue;
 137
 138                 while(!scan_end_trigger){
 139                         while(!convert_trigger)
 140                                 do_nothing();
 141                         do_conversion();
 142                 }
 143         }
 144 }
 145
 146 The fencepost issues, i.e., what happens when you have conflicting
 147 triggers, is device-dependent.
 148