Updated documentation.

In particular, a tentative protocol specification (bmcp.txt) has been added.

2 files changed, 230 insertions, 0 deletions

diff --git a/doc/bmcp.txt b/doc/bmcp.txt
new file mode 100644
index 0000000..a7b1f45
--- /dev/null
+++ b/doc/bmcp.txt
@@ -0,0 +1,230 @@
+BMC Protocol.
+=============
+
+Requests are sent from the client to the server. Each request is followed by a
+reply sent from the server to the client.
+
+Note: each message (except for the handshake messages) starts with a unique
+message type field. For simplicity, these are not indicated below.
+
+-------------------------------------------------------------------------------------------
+
+A new session begins with a handshake:
+
+* Handshake
+
+  Request fields:
+    Magic number
+  Reply fields:
+    Magic number
+
+  Note: New connections not starting with a handshake request will be rejected
+  (disconnected) immediately.
+
+
+-------------------------------------------------------------------------------------------
+
+After a successful handshake, the session proceeds by exchanging request/reply
+pairs in an arbitrary order. Any reply message may be replaced by an error
+message (to indicate bad syntax or something else that prevents the normal
+reply from being generated):
+
+* Error
+
+  Reply fields:
+    <size>
+    <description>
+
+
+* CompareHistory (Use case 1)
+
+  Request fields:
+    BMCONTEXT (<size> <test case> <size> <test function> <size> <data tag>
+               <size> <metric> <size> <platform> <size> <host>)
+    BRANCH (<size> <git repo> <size> <git branch>)
+    SNAPSHOT (<timestamp> <size> <sha1>)
+
+    Note: The sha1 will be used to identify the start of the history if
+    possible. Otherwise (sha1 size = 0) the timestamp will be used.
+
+  Reply fields:
+    <n>
+    <timestamp 1> <size> <sha 1> <value 1> <iterations 1>
+    <timestamp 2> <size> <sha 2> <value 2> <iterations 2>
+    ...
+    <timestamp n> <size> <sha n> <value n> <iterations n>
+
+
+* CompareBranches (Use case 2)
+
+  Request fields:
+    BMCONTEXT
+    BRANCH1
+    SNAPSHOT1
+    BRANCH2
+    SNAPSHOT2
+  
+  Reply fields:
+    <value 1> <iterations 1>
+    <value 2> <iterations 2>
+
+
+* CompareDirect (Use case 3)
+
+  Request fields:
+    BMCONTEXT
+    BRANCH
+    SNAPSHOT
+    <value> <iterations>
+
+  Reply fields:
+    <value 1> <iterations 1>
+    <value 2> <iterations 2>
+
+  Note: The second value/iterations pair in the reply is identical to the one
+  given in the request.
+
+
+* AddResults
+
+  Request fields:
+    <size> <platform>
+    <size> <host>
+    BRANCH
+    SNAPSHOT
+    <size> <testCase>
+    <size> <metric>
+    <nF>
+    <size> <testFunction 1>
+       <nT>
+       <size> <dataTag 1> <value 1> <iterations 1>
+       <size> <dataTag 2> <value 2> <iterations 2>
+       ...
+       <size> <dataTag nT> <value nT> <iterations nT>
+    <size> <testFunction 2>
+       <nT>
+       <size> <dataTag 1> <value 1> <iterations 1>
+       <size> <dataTag 2> <value 2> <iterations 2>
+       ...
+       <size> <dataTag nT> <value nT> <iterations nT>
+
+    ....
+
+    <size> <testFunction nF>
+       <nT>
+       <size> <dataTag 1> <value 1> <iterations 1>
+       <size> <dataTag 2> <value 2> <iterations 2>
+       ...
+       <size> <dataTag nT> <value nT> <iterations nT>
+
+  Reply fields:
+     -
+
+  Note: The reply message serves as a silent acknowledgement only.
+
+
+* ListAvailableBenchmarks
+
+  Request fields:
+    <size> <metric>
+    <size> <platform>
+    <size> <host>
+    BRANCH
+
+  Reply fields:
+    <n>
+    <size> <testCase 1> <size> <testFunction 1> <size> <dataTag 1>
+    <size> <testCase 2> <size> <testFunction 2> <size> <dataTag 2>
+    ...
+    <size> <testCase n> <size> <testFunction n> <size> <dataTag n>
+
+  Note: This request lists benchmarks that occur in combination with zero or
+  more other entities (i.e. at least one result exists for this combination of
+  entity values). An empty entity value (size = 0) is not part of the
+  combination restriction.
+
+
+* ListAvailableMetrics
+
+  Request fields:
+    BENCHMARK (<size> <testCase> <size> <testFunction> <size> <dataTag>)
+    <size> <platform>
+    <size> <host>
+    BRANCH
+
+  Reply fields:
+    <n>
+    <size> <metric 1>
+    <size> <metric 2>
+    ...
+    <size> <metric n>
+
+  Note: Same semantics as for ListAvailableBenchmarks (see this).
+
+
+* ListAvailablePlatforms
+
+  Request fields:
+    BENCHMARK (<size> <testCase> <size> <testFunction> <size> <dataTag>)
+    <size> <metric>
+    <size> <host>
+    BRANCH
+
+  Reply fields:
+    <n>
+    <size> <platform 1>
+    <size> <platform 2>
+    ...
+    <size> <platform n>
+
+  Note: Same semantics as for ListAvailableBenchmarks (see this).
+
+
+* ListAvailableHosts
+
+  Request fields:
+    BENCHMARK (<size> <testCase> <size> <testFunction> <size> <dataTag>)
+    <size> <metric>
+    <size> <platform>
+    BRANCH
+
+  Reply fields:
+    <n>
+    <size> <host 1>
+    <size> <host 2>
+    ...
+    <size> <host n>
+
+  Note: Same semantics as for ListAvailableBenchmarks (see this).
+
+
+* ListAvailableBranches
+
+  Request fields:
+    BENCHMARK (<size> <testCase> <size> <testFunction> <size> <dataTag>)
+    <size> <metric>
+    <size> <platform>
+    <size> <host>
+
+  Reply fields:
+    <n>
+    <size> <git repo 1> <size> <git branch 1>
+    <size> <git repo 2> <size> <git branch 2>
+    ...
+    <size> <git repo n> <size> <git branch n>
+
+  Note: Same semantics as for ListAvailableBenchmarks (see this).
+
+
+* ListAvailableSnapshots
+
+  Request fields:
+    BMCONTEXT
+    BRANCH
+
+  Reply fields:
+    <n>
+    <timestamp 1> <size> <sha1 1>
+    <timestamp 2> <size> <sha1 2>
+    ...
+    <timestamp n> <size> <sha1 n>
diff --git a/doc/er-diagram.dia b/doc/er-diagram.dia
index 615d623..8817a6c 100644
--- a/doc/er-diagram.dia
+++ b/doc/er-diagram.dia