From bf3222f10edbd1f6a5186c8fb35c29900ad0665f Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
Date: Thu, 20 Mar 2014 19:01:11 +0100
Subject: Introduce minimum allowed major driver and nif versions on load

---
 erts/doc/src/erl_driver.xml |  7 +++++--
 erts/doc/src/erl_nif.xml    | 26 ++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 2 deletions(-)

(limited to 'erts/doc/src')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 8da1836da7..ad37813ac0 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -315,10 +315,13 @@
           <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when
           new features are added. The runtime system uses the minor version
           of the driver to determine what features to use.
-          The runtime system will refuse to load a driver if the major
+          The runtime system will normally refuse to load a driver if the major
           versions differ, or if the major versions are equal and the
           minor version used by the driver is greater than the one used
-          by the runtime system.</p>
+          by the runtime system. Old drivers with lower major versions
+	  will however be allowed after a bump of the major version during
+	  a transition period of two major releases. Such old drivers might
+	  however fail if deprecated features are used.</p>
 	<p>The emulator will refuse to load a driver that does not use
 	  the extended driver interface,
 	  to allow for 64-bit capable drivers,
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 8b19725c02..6b1f4cccf8 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -316,6 +316,32 @@ ok
       <p>The library initialization callbacks <c>load</c>, <c>reload</c> and
       <c>upgrade</c> are all thread-safe even for shared state data.</p>
       </item>
+
+      <tag><marker id="version_management"/>Version Management</tag>
+      <item><p>
+      When a NIF library is built, information about NIF API version
+      is compiled into the library. When a NIF library is loaded the
+      runtime system verifies that the library is of a compatible version.
+      <c>erl_nif.h</c> defines <c>ERL_NIF_MAJOR_VERSION</c>, and
+      <c>ERL_NIF_MINOR_VERSION</c>. <c>ERL_NIF_MAJOR_VERSION</c> will be
+      incremented when NIF library incompatible changes are made to the
+      Erlang runtime system. Normally it will suffice to recompile the NIF
+      library when the <c>ERL_NIF_MAJOR_VERSION</c> has changed, but it
+      could, under rare circumstances, mean that NIF libraries have to
+      be slightly modified. If so, this will of course be documented.
+      <c>ERL_NIF_MINOR_VERSION</c> will be incremented when
+      new features are added. The runtime system uses the minor version
+      to determine what features to use.
+      </p><p>
+      The runtime system will normally refuse to load a NIF library if
+      the major versions differ, or if the major versions are equal and
+      the minor version used by the NIF library is greater than the one
+      used by the runtime system. Old NIF libraries with lower major
+      versions will however be allowed after a bump of the major version
+      during a transition period of two major releases. Such old NIF
+      libraries might however fail if deprecated features are used.
+      </p></item>
+
       <tag>Dirty NIFs</tag>
       <item><p><marker id="dirty_nifs"/><em>Note that the dirty NIF functionality
       is experimental</em> and that you have to enable support for dirty
-- 
cgit v1.2.3