AXL: write documenation on settable options

doc/README.md

@@ -19,6 +19,48 @@ If no state files is needed, one may pass NULL in place of the path name.
 
 One must call AXL\_Finalize to shut down the library.
 
+# Setting options
+AXL contains several tunable options that control how files are transferred.
+These are settable using the AXL\_Config function which takes as its single
+argument a pointer to a kvtree of option-value pairs. On success a non-NULL
+pointer is returned, on failure NULL is returned. Calling AXL\_Config with a
+NULL pointer instead returns a kvtree with the current values of all settable
+configuration options. It must be freed used kvtree\_delete after use.  A
+subset of options can also be set for individual AXL transfers by passing them
+in a subtree "id" of the kvtree indexed by their integer transfer id. These
+options are included in the result of AXL\_Config as an "id" subtree. By
+default a transfer will use the values of the global configuration options
+present at the time the transfer is created.
+
+An example kvtree may look like this:
+
+    +- FILE_BUF_SIZE
+    |  +- 1000000
+    +- DEBUG
+    |  +- 0
+    +- id
+       +- 42
+       |  +- FILE_BUF_SIZE
+       |  |  +- 1048576
+       |  +- COPY_METADATA 
+       |     +- 1
+       +- 1
+          +- FILE_BUF_SIZE
+             +- 65536
+
+axl.h defines symbolic names for all parameter which should be used instead of
+the immediate strings whenever possible to avoid typos and runtime errors.
+
+The current set of configuariont options including their default value is
+(prefix Name by AXL\_KEY\_CONFIG\_ for symbolic name):
+
+Name | Type  | Default | Per transfer | Description
+-----|------:|-----:|:-:|--------------------------------------------------------
+FILE\_BUF\_SIZE | Byte count | 1048576 | Yes | Specify the number of bytes to use for internal buffers when copying files between the parallel file system and the cache.
+DEBUG           |    Boolean |       0 |  No | Set to 1 to have AXL print debug messages to stdout, set to 0 for no output.
+MKDIR           |    Boolean |       1 | Yes | Specifies whether the device supports the creation of directories (1) or not (0).
+COPY\_METADATA  |    Boolean |       0 | Yes | Whether file metadata like timestamp and permission bits should also be copied.
+
 # Transferring files
 Regardless of the transfer type, the basic control flow of a transfer is always:
 1. AXL\_Create - allocate a new transfer object, providing its type and a name