Add documentation to README

1 files changed, 82 insertions, 2 deletions

diff --git a/p11p-daemon/README.md b/p11p-daemon/README.md
index 5abb132..43a4170 100644
--- a/p11p-daemon/README.md
+++ b/p11p-daemon/README.md
@@ -52,8 +52,56 @@ Compile:
 
 ## Configuring p11p-daemon
 
-For now, see config/sys.config for how to configure virtual tokens,
-each with one or more PKCS #11 module, i.e. shared library.
+Edit config/sys.config to define virtual tokens.
+
+A PKCS #11 application ("client"), connecting to p11p-daemon performs
+PKCS #11 operations on a virtual token. Each virtual token represents
+one or more physical cryptographic devices with a PKCS #11 interface
+("tokens").
+
+Each virtual token has a name, a mode and a list of PKCS #11 modules,
+i.e. shared libraries.
+
+### vtoken name
+
+A string identifying a virtual token. This name is reflected in the
+name of the socket used by the client to connect to p11p-daemon.
+
+### vtoken modules
+
+A list of PKCS #11 modules backing the virtual token.
+
+Each entry in this list has a name, a path to the shared library to
+load and, optionally, an environment to run it in. The environment can
+be used to pass configuration to the module.
+
+### vtoken mode
+
+The mode of a virtual token determines some of its behaviour with
+reagard to choosing which token to satisfy a client request.
+
+#### failover
+
+In failover mode, the virtual token will use the first token in the
+list of tokens until that token fails and then switch to the next in
+the list.
+
+Failover mode has one parameter specifying the number of seconds (?)
+to wait for a token to respond before giving up and decide that the
+token has failed.
+
+#### balance
+
+In balance mode, the virtual token will balance client requests over
+all configured tokens in accordance with its configuration parameter.
+
+Balance mode has one parameter, a list of invocation counts.  An
+invocation count is an integer specifying how many times a token
+should be invoked before moving to the next in the list. The first
+integer in the list corresponds to the first token, the second integer
+to the second token, and so on.
+
+The default invocation count is one.
 
 ## Running p11p-daemon
 
@@ -96,6 +144,38 @@ Quit by entering "q()." in the Erlang shell.
   TODO: Make this work, or prohibit it by rejecting a second user of
   the same vtoken.
 
+## Hacking
+
+### Layout in src
+
+There are clients, servers, remotes and tokens:
+- Clients are p11 applications connecting to a unix socket set up by a
+  p11p_server.
+- Servers proxy p11 requests between clients and remotes.
+- Remotes are unix processes loading vendor.so at startup and talking
+  to a token. NOTE: This term, remote, was inherited from p11-kit and
+  will change at some point.
+- Tokens are p11 devices, associated with one or more remotes.
+
+The modules are:
+- p11p_app.erl -- The application starts the main supervisor,
+  p11p_sup.
+
+- p11p_sup.erl -- The main supervisor starts the the server
+  supervisor, the config server, and the manager of "remotes".
+
+- p11p_server_sup.erl -- The server supervisor starts one server per
+  configured token.
+
+- p11p_server.erl -- A server, binding to a unix socket and proxying
+  p11 requests and rsponses between clients and a remote.
+
+- p11p_config.erl -- The config server reads the configuration file(s)
+  and is used by any module needing configuration.
+
+- p11p_remote_manager.erl -- The manager of remotes
+
+
 ## Contact
 
   linus+p11p@sunet.se