[ovs-dev] [PATCH] Introduce OVSDB readme markdown

[Ryan Moats]

From: RYAN D. MOATS <rmoats at us.ibm.com>

Provide a point to start collecting documentation on OVSDB
and seed it with experiences from making use of change
tracking.

Signed-off-by: RYAN D. MOATS <rmoats at us.ibm.com>
---
 ovsdb/README.md |   38 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 38 insertions(+), 0 deletions(-)
 create mode 100644 ovsdb/README.md

diff --git a/ovsdb/README.md b/ovsdb/README.md
new file mode 100644
index 0000000..03e4abf
--- /dev/null
+++ b/ovsdb/README.md
@@ -0,0 +1,38 @@
+OVSDB developer documentation
+=============================
+
+The OVSDB (Open vSwitch database) stores network state used by
+Open vSwitch implementations. 
+
+Design & Architecture
+---------------------
+
+While OVSDB supports only a single central server, it maintains
+a local in-memory replica at each client.  Clients perform reads
+and propose writes to the local in-memory replica. Proposed 
+writes are delivered to the central server via "transactions"
+and if accepted, will trigger notifications to other clients.
+
+The server process also maintains the database in memory, using
+a disk file to provide both backing and a transaction log. This
+file stores the database and transactions using a JSON format,
+which is also used by the OVSDB management protocol (see [1]).
+
+[1]: http://tools.ietf.org/html/rfc7047
+
+Differences from other databases
+--------------------------------
+
+This section is intended to point out some of the differences
+between how OVSDB works and more "classic" databases.
+
+In OVSDB, change tracking is applied at each client in the 
+IDL layer. This means that when a client makes a request to
+track changes on a particular table, they are essentially
+requesting information about the incremental changes from that
+point in time.  Once the client clears tracked changes, that
+information will no longer be available. The implication of
+this is that it is not a simple matter for code to "replay"
+changes from the past. Rather, code should be structured with
+a path for processing the full table as well as a path that
+processes incremental changes.
-- 
1.7.1