documentation additions and updates

diff --git a/demo/insn.c b/demo/insn.c
index bce46f32d204cddf3853ca2cc2501675bcd5811d..9b3053079e76a01d72cb17673451f0256b2a5482 100644 (file)
--- a/demo/insn.c
+++ b/demo/insn.c
@@ -1,5 +1,12 @@
 /*
-   A little input demo
+   This example shows how to use instructions, i.e., comedi_insns.  
+
+   Using instructions directly, as in this example, is not recommended
+   for the beginner.  Use the higher-level functions such as
+   comedi_data_read(), comedi_data_write(), etc.  Then, if you
+   need the additional flexibility that using instructions directly
+   provides, study this example and the implementations of
+   comedi_data_read(), etc.
  */
 
 #include <stdio.h>
@@ -8,8 +15,8 @@
 #include <unistd.h>
 #include <sys/ioctl.h>
 #include <errno.h>
-#include <getopt.h>
-#include <ctype.h>
+#include <sys/time.h>
+#include <unistd.h>
 
 extern int verbose_flag;
 extern int subdevice;
@@ -21,12 +28,22 @@ extern char *filename;
 comedi_t *device;
 
 
+/*
+ * This example does 3 instructions in one system call.  It does
+ * a gettimeofday() call, then reads N_SAMPLES samples from an
+ * analog input, and the another gettimeofday() call.
+ *
+ */
+
+#define N_SAMPLES 10
+
 int main(int argc, char *argv[])
 {
-       int ret;
-       comedi_insn insn;
+       int ret,i;
+       comedi_insn insn[3];
        comedi_insnlist il;
-       lsampl_t data;
+       struct timeval t1,t2;
+       lsampl_t data[N_SAMPLES];
 
        parse_options(argc,argv);
 
@@ -41,23 +58,40 @@ int main(int argc, char *argv[])
                        filename,subdevice,channel,range,aref);
        }
 
-       il.n_insns=1;
-       il.insns=&insn;
+       /* Set up a the "instruction list", which is just a pointer
+        * to the array of instructions and the number of instructions.
+        */
+       il.n_insns=3;
+       il.insns=insn;
+
+       /* Instruction 0: perform a gettimeofday() */
+       insn[0].insn=INSN_GTOD;
+       insn[0].n=2;
+       insn[0].data=(void *)&t1;
 
-       insn.insn=INSN_READ;
-       insn.n=1;
-       insn.data=&data;
-       insn.subdev=subdevice;
-       insn.chanspec=CR_PACK(channel,range,aref);
+       /* Instruction 1: do 10 analog input reads */
+       insn[1].insn=INSN_READ;
+       insn[1].n=N_SAMPLES;
+       insn[1].data=data;
+       insn[1].subdev=subdevice;
+       insn[1].chanspec=CR_PACK(channel,range,aref);
 
-       ret=ioctl(comedi_fileno(device),COMEDI_INSNLIST,&il);
-       //ret=comedi_data_read(device,subdevice,channel,range,aref,&data);
+       /* Instruction 2: perform a gettimeofday() */
+       insn[2].insn=INSN_GTOD;
+       insn[2].n=2;
+       insn[2].data=(void *)&t2;
+
+       ret=comedi_do_insnlist(device,&il);
        if(ret<0){
                comedi_perror(filename);
                exit(0);
        }
 
-       printf("%d\n",data);
+       printf("initial time: %ld.%06ld\n",t1.tv_sec,t1.tv_usec);
+       for(i=0;i<N_SAMPLES;i++){
+               printf("%d\n",data[i]);
+       }
+       printf("final time: %ld.%06ld\n",t2.tv_sec,t2.tv_usec);
 
        return 0;
 }