typing

diff --git a/doc/glossary.sgml b/doc/glossary.sgml
index aaa74d6f0777b30c51966941a27cb25d5402b84d..23fd8ba549e0cc94ec869bcd4c0823508079f39d 100644 (file)
--- a/doc/glossary.sgml
+++ b/doc/glossary.sgml
@@ -1,36 +1,171 @@
-
-
-Buffer:
-
-
-Buffer Overflow:
-
-
-Buffer Overrun:
-
-
-Command:
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<glossary>
+  <title>
+    Glossary
+  </title>
+  <glossentry>
+    <glossterm>
+buffer
+    </glossterm>
+    <glossdef>
+      <para>
+Comedi uses permanently allocated kernel memory for streaming input
+and output to store data that has been measured by a device, but has
+not been read by an application.  These buffers can be resized by the
+Comedilib function comedi_buffer_XXX() or the coemdi_config
+utility.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+buffer overflow
+    </glossterm>
+    <glossdef>
+      <para>
+This is an error message that indicates that the driver ran out of
+space in a Comedi buffer to put samples.  It means that the application
+is not copying data out of the buffer quickly enough.  Often, this
+problem can be fixed by making the Comedi buffer larger.  See 
+comedi_buffer_XXX for more information.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+overrun
+    </glossterm>
+    <glossdef>
+      <para>
+This is an error message that indicates that there was device-level
+problem, typically with trigger pulses occurring faster than the
+board can handle.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+command
+    </glossterm>
+    <glossdef>
+      <para>
+Comedi commands are the mechanism that applications configure
+subdevices for streaming input and output.
   (also: cmd, comedi_command)
-
-
-DMA:
-
-
-FIFO:
-
-
-Instruction:
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+DMA
+    </glossterm>
+    <glossdef>
+      <para>
+Direct memory access.  DMA is a method of transferring data between
+a device and the main memory of a computer.  DMA operates differently
+on ISA and PCI cards.  ISA DMA is handled by a controller on the
+motherboard and is limited to transfers to/from the lowest 16 MB of
+physical RAM and can only handle a single segment of memory at a time.
+These limitations make it almost useless.  PCI ("bus mastering") DMA
+is handled by a controller on the device, and can typically address
+4 GB of RAM and handle many segments of memory simultaneously.  DMA
+is usually not the only means to data transfer, and may or may not
+be the optimal transfer mechanism for a particular situation.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+FIFO
+    </glossterm>
+    <glossdef>
+      <para>
+Most devices have a limited amount of on-board space to store samples
+before they are transferred to the Comedi buffer.  This allows the CPU or
+DMA controller to do other things, and then efficiently process a
+large number of samples simultaneously.  It also increases the
+maximum interrupt latency that the system can handle without
+interruptions in data.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+instruction
+    </glossterm>
+    <glossdef>
+      <para>
+Comedi instructions are the mechanism used by applications to do
+immediate input from channels, output to channels, and configuration
+of subdevices and channels.
   (also: insn)
-
-
-Instruction List:
-
-
-Configuration Options:
-  (also: Options, Option List)
-
-
-Poll:
-
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+instruction list
+    </glossterm>
+    <glossdef>
+      <para>
+Instruction lists allow the application to perform multiple Comedi
+instructions in the same system call.
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+option list
+    </glossterm>
+    <glossdef>
+      <para>
+Option lists are used with comedi_config to perform driver
+configuration.
+  (also: configuration options, options)
+      </para>
+    </glossdef>
+  </glossentry>
+
+  <glossentry>
+    <glossterm>
+poll
+    </glossterm>
+    <glossdef>
+      <para>
+The term poll (and polling) is used for several different related
+concepts in Comedi.  Comedi implements the poll() system call for
+Comedi devices, which is similar to select(), and returns information
+about file descriptors that can be read or written.  Comedilib also
+has a function called comedi_poll(), which causes the driver to
+copy all available data from the device to the Comedi buffer.  In
+addition, some drivers may use a polling technique in place of
+interrupts.
+      </para>
+    </glossdef>
+  </glossentry>
+
+<!--
+  <glossentry>
+    <glossterm>
+
+    </glossterm>
+    <glossdef>
+      <para>
+
+      </para>
+    </glossdef>
+  </glossentry>
+-->
+
+</glossary>