Slap together some notes about insn_config

diff --git a/Documentation/comedi/insn_config b/Documentation/comedi/insn_config
new file mode 100644 (file)
index 0000000..8977f90
--- /dev/null
+++ b/Documentation/comedi/insn_config
@@ -0,0 +1,255 @@
+
+
+INSN_CONFIG:
+
+The first data element (data[0]) is an ID.
+
+Generic return values:
+
+  Bad ID: EINVAL  (should be EIO?)
+  Length is wrong: EINVAL
+
+  EAGAIN: changed arguments, retry (like command_test)
+
+
+Notes:
+  - Should we use the length as an ID? (no, cuz its dumb)
+  - Should there be a generic flags parameter? (no)
+  - Should trigger source configs return a token? (no)
+  - Would it be better to have a special subdevice for trigger
+    configuration? (no, because it goes against the "subdevices
+    are independent" design.)
+  - Should this configure generic triggers and return a token
+    to be put into a command, or configure specific triggers
+    that are tied to start_src, convert_src, etc.?
+
+
+ID=0: COMEDI_INPUT
+ID=1: COMEDI_OUTPUT
+ID=2: open drain input (?)
+ID=3: open drain output
+
+  length=1
+  chanspec is used to specify channel
+  type: SUBD_DIO
+
+  These are used to configure the direction of digital I/O lines.
+
+  Modifications: none
+
+  Errors: none
+
+  Notes:
+    - does open drain input make sense?
+
+
+ID=xxx:  analog output waveform generation
+
+  Specify the number of samples in buffer.
+
+ID=xxx:  analog triggering
+
+  length=N
+  chanspec is ignored
+  type: any with cmd
+
+  [0] - ID
+  [1] - analog trigger channel
+  [2] - flags
+          trigger
+          slope/level
+         hysteresis
+  [3] - high
+
+  Modifications: ?
+  Errors:
+    - bad channel
+    - bad flags
+    - 
+  Notes:
+    - are there devices that can specify debouncing?
+    - are there devices that can specify a time value after
+      which the analog trigger resets?
+
+
+ID=xxx: simple digital triggering
+
+  length =
+  chanspec is ignored
+  type: any with cmd
+
+  [0] - ID
+  [1] - flags
+          trigger 
+         edge/level
+         rising/falling
+  [2] - divider (?)
+
+  Notes:
+    - should this configure pins, or configure triggers?
+      (ds: triggers, see independent subdevice design rule)
+      (ds: pins, because it makes other things easier)
+    - divider?  (ds: too complicated.  This is supposed to
+      be simple.)
+    - should this be encoded into the TRIG_EXT argument?
+      
+
+ID=xxx: extended digital triggering
+
+  length =
+  chanspec: ignored
+  type: any with cmd
+
+  [0] - ID
+  [1] - flags
+          trigger
+
+  Notes:
+    - should this be the same as triggering for counter/timers?
+
+
+ID=xxx: counter configuration
+
+  The subdevice has an accumulator which changes based on
+  triggers.
+
+  [0] - ID
+  [ ] - flags
+          generate command trigger when?
+  [1] - mode
+  [2] - source1_src
+  [3] - source1_arg
+  [4] - source2_src
+  [5] - source2_arg
+  [6] - gate_src
+  [7] - gate_arg
+
+  Modes:
+    UP_COUNTER:
+      acc++ on source1
+
+    DOWN_COUNTER:
+      acc-- on source1
+    
+    QUADRATURE:
+      acc+=atan(source1,source2)
+
+  Notes:
+    - configuring pins vs. configuring triggers would make this
+      easier
+
+
+ID=xxx: counter configuration, up counter
+
+  chanspec: used to determine particular counter channel
+
+  [0] - ID
+  [1] - flags
+          up/down
+  [2] - src (like command trigger)
+  [3] - arg
+
+  Notes:
+    - too simple?  no gating
+
+ID=xxx: counter configuration, up counter with gating
+ID=xxx: counter configuration, quadrature
+
+
+ID=xxx: command trigger, pattern matching
+
+  [0] - ID
+  [1] - bit mask (1 - watch, 0 - don't watch)
+  [2] - bit pattern
+
+
+ID=xxx: set software gate
+  [0] - ID
+  [1] - set/clear gate
+
+
+
+
+Applications:
+
+ - Pulse counting:
+   (STC: simple event counting)
+
+    mode - up counter
+    primary source - external line (+/-)
+
+ - Pulse counting with gate:
+   (STC: simple gated event counting)
+    
+    mode - up counter
+    primary source - external line
+    gate source - external line
+
+ - Pulse length measurement:
+    (STC: single pulse-width measurement)
+
+    mode - up counter with gate
+    primary source - timer
+    gate source - external line (+/-)
+
+    latch and reset on gate (-) transition
+
+ - Timestamping
+    (STC: buffered [non-]cumulative event counting,
+          single period measurement)
+
+    mode - up counter
+    primary source - timer
+    secondary source - external line
+
+    latch on secondary source (+) transition
+
+ - Up/Down counter:
+    (STC: relative position sensing)
+
+    mode - up/down counter
+    primary source - external line
+    secondary source - external line
+
+    when(P)acc+=S?+1:-1
+
+ - Quadrature counting:
+    
+    mode - quadrature
+    primary source - external line 1
+    secondary source - external line 2
+
+ - Frequency generation:
+
+    mode - up counter
+    primary source - timer
+    
+    invert output on primary source trigger
+
+ - Pulse generation
+    
+    (XXX needs work)
+    mode - dual up counter
+    primary source - timer
+    secondary source - timer
+
+    set output on primary source trigger
+    clear output on secondary source trigger
+
+  - Pulse Width Modulation
+
+    same as above
+    secondary source - timer (latch arg)
+
+  - Frequency Shift Keying:
+
+    mode - double up counter
+    primary source - timer
+    secondary source - timer
+    gate - soft, or external line
+
+    invert output on gate?primary:secondary source trigger
+
+  - 
+
+