KernelLibrary.md

@@ -5,7 +5,32 @@ in the include/kernels directory.
 
 ## I/O Kernels:  Sources and Sinks
 
-## Transposition
+Source kernels are kernels that provide the input data streams for processing
+by other kernels.   There are source kernels for obtaining input streams from
+the operating systems (files or devices) as well as from memory buffers.
+
+```ReadSourceKernel``` produces a data stream by using the operating system ```read``` call to populate the input stream.   Normally, the stream set produceed is a ```1xi8`` stream set, i.e., a stream set consisting of a single stream of 8-bit values (bytes).
+Typical usage:
+```
+StreamSet * const ByteStream = P->CreateStreamSet(1, 8);
+P->CreateKernelCall<ReadSourceKernel>(fileDescriptor, ByteStream);
+```
+Here ```P``` is a program or pipeline builder, and ```fileDescriptor``` is
+scalar integer for an open file or device.  In addition to byte streams, read source kernels may produce streams of 16-, 32, or 64-bit values.
+
+```MMapSourceKernel``` is a substitution for ```ReadSourceKernel``` that may be used to
+populate an input stream using the operating system ```mmap``` facility on Posix-based systems.  Its usage is restricted to input from open file descriptors that correspond to plain files, it may not be used with devices or with standard input.
+
+```FDSourceKernel``` is a somewhat more flexible input kernel that allows the choice of using ```read``` or ```mmap``` at run-time.  It takes one additional input parameter,
+a boolean scalar value identifying whether to use ```mmap``` if possible.   If this scalar is given the value 1 (true), then ```mmap``` will be used for ordinary files, while ```read``` will be used for devices or standard input.
+
+```MemorySourceKernel``` is a kernel that produces a stream set from a memory buffer.   Its parameters are a scalar pointer to the buffer, and a scalar length of the buffer.
+ 
 
-## Stream Utilities
 
+
+
+
+## Transposition
+
+## Stream Utilities
\ No newline at end of file