documentation additions and updates

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;
 
-	insn.insn=INSN_READ;
-	insn.n=1;
-	insn.data=&data;
-	insn.subdev=subdevice;
-	insn.chanspec=CR_PACK(channel,range,aref);
+	/* Instruction 0: perform a gettimeofday() */
+	insn[0].insn=INSN_GTOD;
+	insn[0].n=2;
+	insn[0].data=(void *)&t1;
 
-	ret=ioctl(comedi_fileno(device),COMEDI_INSNLIST,&il);
-	//ret=comedi_data_read(device,subdevice,channel,range,aref,&data);
+	/* 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);
+
+	/* 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;
 }