Driver API: Update documentation for 64-bit sizes

3 files changed, 294 insertions, 71 deletions

diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml
index 9f246c4a6c..ac5729880d 100644
--- a/erts/doc/src/driver.xml
+++ b/erts/doc/src/driver.xml
@@ -30,11 +30,11 @@
   </header>
 
   <note><p>This document was written a long time ago. A lot of it is still
-           valid, but some things have changed since it was first written.
-	   Updates of this document are planned for the future. The reader
-	   is encouraged to also read the
-	   <seealso marker="erl_driver">erl_driver</seealso>, and the
-	   <seealso marker="erl_driver">driver_entry</seealso> documentation.
+           interesting since it explains important concepts, but it was
+	   written for an older driver interface so the examples does not
+	   work anymore. The reader is encouraged to read
+	   <seealso marker="erl_driver">erl_driver</seealso> and the
+	   <seealso marker="driver_entry">driver_entry</seealso> documentation.
    </p></note>
 
   <section>
diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index 8bdd154cb9..a2efdf3ebc 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -34,18 +34,22 @@
   <lib>driver_entry</lib>
   <libsummary>The driver-entry structure used by erlang drivers.</libsummary>
   <description>
-    <p>As of erts version 5.5.3 the driver interface has been extended
-      (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>).
-      The extended interface introduces
-      <seealso marker="erl_driver#version_management">version management</seealso>,
-      the possibility to pass capability flags
-      (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>)
-      to the runtime system at driver initialization, and some new
-      driver API functions.      </p>
+    <p>
+      As of erts version 5.9 (OTP release R15B) the driver interface
+      has been changed with larger types for the callbacks
+      <seealso marker="#output">output</seealso>,
+      <seealso marker="#control">control</seealso> and
+      <seealso marker="#call">call</seealso>.
+      See driver <seealso marker="erl_driver#version_management">
+      version management</seealso> in
+      <seealso marker="erl_driver">erl_driver</seealso>.
+    </p>
     <note>
       <p>Old drivers (compiled with an <c>erl_driver.h</c> from an
-        earlier erts version than 5.5.3) have to be recompiled
-        (but do not have to use the extended interface).</p>
+      earlier erts version than 5.9) have to be updated and have
+      to use the extended interface (with
+      <seealso marker="erl_driver#version_management">version management
+      </seealso>).</p>
     </note>
     <p>The <c>driver_entry</c> structure is a C struct that all erlang
       drivers define. It contains entry points for the erlang driver
@@ -53,7 +57,7 @@
       the driver.</p>
     <p>      
       <marker id="emulator"></marker>
-      The <seealso marker="driver_entry">erl_driver</seealso> driver
+      The <seealso marker="erl_driver">erl_driver</seealso> driver
       API functions need a port handle
       that identifies the driver instance (and the port in the
       emulator). This is only passed to the <c>start</c> function, but
@@ -84,7 +88,7 @@
       the emulator, the driver is <em>not</em> allowed to modify the
       <c>driver_entry</c>.</p>
     <note>
-      <p>Do <em>not</em> declare the <c>driver_entry</c><c>const</c>. This since the emulator needs to
+      <p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>. This since the emulator needs to
         modify the <c>handle</c>, and the <c>handle2</c>
         fields. A statically allocated, and <c>const</c>
         declared <c>driver_entry</c> may be located in
@@ -116,7 +120,7 @@ typedef struct erl_drv_entry {
     void (*stop)(ErlDrvData drv_data);
                                 /* called when port is closed, and when the
                                    emulator is halted. */
-    void (*output)(ErlDrvData drv_data, char *buf, int len);
+    void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len);
                                 /* called when we have output from erlang to 
                                    the port */
     void (*ready_input)(ErlDrvData drv_data, ErlDrvEvent event); 
@@ -130,8 +134,9 @@ typedef struct erl_drv_entry {
     void (*finish)(void);       /* called before unloading the driver -
                                    DYNAMIC DRIVERS ONLY */
     void *handle;               /* Reserved -- Used by emulator internally */
-    int (*control)(ErlDrvData drv_data, unsigned int command, char *buf, 
-                   int len, char **rbuf, int rlen); 
+    ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command,
+                            char *buf, ErlDrvSizeT len,
+			    char **rbuf, ErlDrvSizeT rlen);
                                 /* "ioctl" for drivers - invoked by 
                                    port_control/3 */
     void (*timeout)(ErlDrvData drv_data);        /* Handling of timeout in driver */
@@ -144,8 +149,9 @@ typedef struct erl_drv_entry {
                                    closed, and there is data in the 
                                    driver queue that needs to be flushed
                                    before 'stop' can be called */
-    int (*call)(ErlDrvData drv_data, unsigned int command, char *buf, 
-                   int len, char **rbuf, int rlen, unsigned int *flags); 
+    ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command,
+                         char *buf, ErlDrvSizeT len,
+			 char **rbuf, ErlDrvSizeT rlen, unsigned int *flags);
                                 /* Works mostly like 'control', a synchronous
                                    call into the driver. */
     void (*event)(ErlDrvData drv_data, ErlDrvEvent event,
@@ -192,7 +198,7 @@ typedef struct erl_drv_entry {
 	  <c>start</c>, then <c>stop</c> is the place to deallocate that
 	  memory.</p>
       </item>
-      <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, int len)</tag>
+      <tag><marker id="output"/>void (*output)(ErlDrvData drv_data, char *buf, ErlDrvSizeT len)</tag>
       <item>
         <p>This is called when an erlang process has sent data to the
           port. The data is pointed to by <c>buf</c>, and is
@@ -243,7 +249,7 @@ typedef struct erl_drv_entry {
           emulator will modify this field; therefore, it is important
           that the <c>driver_entry</c> isn't declared <c>const</c>.</p> 
       </item>
-      <tag><marker id="control"></marker>int (*control)(ErlDrvData drv_data, unsigned int command, char *buf,  int len, char **rbuf, int rlen)</tag>
+      <tag><marker id="control"></marker>ErlDrvSSizeT (*control)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen)</tag>
       <item>
         <p>This is a special routine invoked with the erlang function
           <c>port_control/3</c>. It works a little like an "ioctl" for
@@ -316,7 +322,7 @@ typedef struct erl_drv_entry {
           opposed to the asynchronous function, which is called in
           some thread (if multithreading is enabled).</p>
       </item>
-      <tag><marker id="call"/>int (*call)(ErlDrvData drv_data, unsigned int command, char *buf, int len, char **rbuf, int rlen, unsigned int *flags)</tag>
+      <tag><marker id="call"/>ErlDrvSSizeT (*call)(ErlDrvData drv_data, unsigned int command, char *buf, ErlDrvSizeT len, char **rbuf, ErlDrvSizeT rlen, unsigned int *flags)</tag>
       <item>
         <p>This function is called from <c>erlang:port_call/3</c>. It
           works a lot like the <c>control</c> call-back, but uses the
@@ -452,7 +458,7 @@ typedef struct erl_drv_entry {
     <title>SEE ALSO</title>
     <p><seealso marker="erl_driver">erl_driver(3)</seealso>, 
       <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>,
-      <seealso marker="erts:erlang">erlang(3)</seealso>,
+      <seealso marker="erlang">erlang(3)</seealso>,
       kernel(3)</p>
   </section>
 </cref>
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index 8e18dd6657..b5df4ca0c8 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -37,15 +37,18 @@
     <p>As of erts version 5.5.3 the driver interface has been extended
       (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>).
       The extended interface introduce
-      <seealso marker="erl_driver#version_management">version management</seealso>,
+      <seealso marker="#version_management">version management</seealso>,
       the possibility to pass capability flags
       (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>)
       to the runtime system at driver initialization, and some new
       driver API functions.      </p>
     <note>
-      <p>Old drivers (compiled with an <c>erl_driver.h</c> from an
-        earlier erts version than 5.5.3) have to be recompiled
-        (but does not have to use the extended interface).</p>
+      <p>As of erts version 5.9 old drivers has to be recompiled
+      and has to use the extended interface. They also has to be
+      adjusted to the
+      <seealso marker="#rewrites_for_64_bits">64-bit capable driver interface.
+      </seealso>
+      </p>
     </note>
     <p>The driver calls back to the emulator, using the API
       functions declared in <c>erl_driver.h</c>. They are used for
@@ -242,9 +245,9 @@
       </p>
       </item>
       <tag>Adding / removing drivers</tag>
-      <item>A driver can add and later remove drivers.</item>
+      <item><p>A driver can add and later remove drivers.</p></item>
       <tag>Monitoring processes</tag>
-      <item>A driver can monitor a process that does not own a port.</item>
+      <item><p>A driver can monitor a process that does not own a port.</p></item>
       <tag><marker id="version_management">Version management</marker></tag>
       <item>
         <p>Version management is enabled for drivers that have set the
@@ -268,15 +271,203 @@
           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>
-        <p>The emulator tries to check that a driver that doesn't use the
-          extended driver interface isn't incompatible when loading it.
-          It can, however, not make sure that it isn't incompatible. Therefore,
-          when loading a driver that doesn't use the extended driver
-          interface, there is a risk that it will be loaded also when
-          the driver is incompatible. When the driver uses the extended driver
-          interface, the emulator can verify that it isn't of an incompatible
-          driver version. You are therefore advised to use the extended driver
-          interface.</p>
+	<p>The emulator will refuse to load a driver that does not use
+	  the extended driver interface since,
+	  to allow for 64-bit capable drivers,
+	  incompatible type changes for the callbacks
+	  <seealso marker="driver_entry#output">output</seealso>,
+	  <seealso marker="driver_entry#control">control</seealso> and
+	  <seealso marker="driver_entry#call">call</seealso>
+	  were introduced in release R15B. A driver written
+	  with the old types would compile with warnings and when
+	  called return garbage sizes to the emulator causing it
+	  to read random memory and create huge incorrect result blobs.</p>
+	<p>Therefore it is not enough to just recompile drivers written with
+	  version management for pre-R15B types; the types has to be changed
+	  in the driver suggesting other rewrites especially regarding
+	  size variables. Investigate all warnings when recompiling!</p>
+	<p>Also, the API driver functions <c>driver_output*</c>,
+	  <c>driver_vec_to_buf</c>, <c>driver_alloc/realloc*</c>
+	  and the <c>driver_*</c> queue functions were changed to have
+	  larger length arguments and return values. This is a
+	  lesser problem since code that passes smaller types
+	  will get them auto converted in the calls and as long as
+	  the driver does not handle sizes that overflow an <c>int</c>
+	  all will work as before.</p>
+      </item>
+    </taglist>
+  </section>
+
+  <section>
+    <marker id="rewrites_for_64_bits"/>
+    <title>
+      REWRITES FOR 64-BIT DRIVER INTERFACE
+    </title>
+    <p>
+      For erts-5.9 two new integer types
+      <seealso marker="#ErlDrvSizeT">ErlDrvSizeT</seealso> and
+      <seealso marker="#ErlDrvSSizeT">ErlDrvSSizeT</seealso>
+      were introduced that can hold 64-bit sizes if necessary.
+    </p>
+    <p>
+      To not update a driver and just recompile it probably works
+      when building for a 32-bit machine creating a false sense of security.
+      Hopefully that will generate many important warnings.
+      But when recompiling the same driver later on for a 64-bit machine
+      there <em>will</em> be warnings and almost certainly crashes.
+      So it is a BAD idea to postpone updating the driver and
+      not fixing the warnings!
+    </p>
+    <p>
+      When recompiling with <c>gcc</c> use the <c>-Wstrict-prototypes</c>
+      flag to get better warnings. Try to find a similar flag if you
+      are using some other compiler.
+    </p>
+    <p>
+      Here follows a checklist for rewriting a pre erts-5.9 driver,
+      most important first.
+    </p>
+    <taglist>
+      <tag>Return types for driver callbacks</tag>
+      <item>
+	<p>
+	  Rewrite driver callback
+	  <c><seealso marker="driver_entry#control">control</seealso></c>
+	  to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.
+	</p>
+	<p>
+	  Rewrite driver callback
+	  <c><seealso marker="driver_entry#call">call</seealso></c>
+	  to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.
+	</p>
+	<note>
+	  <p>
+	    These changes are essential to not crash the emulator
+	    or worse cause malfunction.
+	    Without them a driver may return garbage in the high 32 bits
+	    to the emulator causing it to build a huge result from random
+	    bytes either crashing on memory allocation or succeeding with
+	    a random result from the driver call.
+	  </p>
+	</note>
+      </item>
+      <tag>Arguments to driver callbacks</tag>
+      <item>
+	<p>
+	  Driver callback
+	  <c><seealso marker="driver_entry#output">output</seealso></c>
+	  now gets <c>ErlDrvSizeT</c> as 3:rd argument instead
+	  of previously <c>int</c>.
+	</p>
+	<p>
+	  Driver callback
+	  <c><seealso marker="driver_entry#control">control</seealso></c>
+	  now gets <c>ErlDrvSizeT</c> as 4:th and 6:th arguments instead
+	  of previously <c>int</c>.
+	</p>
+	<p>
+	  Driver callback
+	  <c><seealso marker="driver_entry#call">call</seealso></c>
+	  now gets <c>ErlDrvSizeT</c> as 4:th and 6:th arguments instead
+	  of previously <c>int</c>.
+	</p>
+	<p>
+	  Sane compiler's calling conventions probably make these changes
+	  necessary only for a driver to handle data chunks that require
+	  64-bit size fields (mostly larger than 2 GB since that is what
+	  an <c>int</c> of 32 bits can hold). But it is possible to think
+	  of non-sane calling conventions that would make the driver
+	  callbacks mix up the arguments causing malfunction.
+	</p>
+	<note>
+	  <p>
+	    The argument type change is from signed to unsigned which
+	    may cause problems for e.g. loop termination conditions or
+	    error conditions if you just change the types all over the place.
+	  </p>
+	</note>
+      </item>
+      <tag>Larger <c>size</c> field in <c>ErlIOVec</c></tag>
+      <item>
+	<p>
+	  The <c>size</c> field in
+	  <seealso marker="#ErlIOVec"><c>ErlIOVec</c></seealso>
+	  has been changed to <c>ErlDrvSizeT</c> from <c>int</c>.
+	  Check all code that use that field.
+	</p>
+	<p>
+	  Automatic type casting probably makes these changes necessary only
+	  for a driver that encounters sizes larger than 32 bits.
+	</p>
+	<note>
+	  <p>
+	    The <c>size</c> field changed from signed to unsigned which
+	    may cause problems for e.g. loop termination conditions or
+	    error conditions if you just change the types all over the place.
+	  </p>
+	</note>
+      </item>
+      <tag>Arguments and return values in the driver API</tag>
+      <item>
+	<p>
+	  Many driver API functions has changed argument type
+	  and/or return value to <c>ErlDrvSizeT</c> from mostly <c>int</c>.
+	  Automatic type casting probably makes these changes necessary only
+	  for a driver that encounters sizes larger than 32 bits.
+	</p>
+	<taglist>
+	  <tag><seealso marker="#driver_output">driver_output</seealso></tag>
+	  <item>3:rd argument</item>
+	  <tag><seealso marker="#driver_output2">driver_output2</seealso></tag>
+	  <item>3:rd and 5:th arguments</item>
+	  <tag>
+	  <seealso marker="#driver_output_binary">driver_output_binary</seealso>
+	  </tag>
+	  <item>3:rd 5:th and 6:th arguments</item>
+	  <tag><seealso marker="#driver_outputv">driver_outputv</seealso></tag>
+	  <item>3:rd and 5:th arguments</item>
+	  <tag>
+	  <seealso marker="#driver_vec_to_buf">driver_vec_to_buf</seealso>
+	  </tag>
+	  <item>3:rd argument and return value</item>
+	  <tag><seealso marker="#driver_alloc">driver_alloc</seealso></tag>
+	  <item>1:st argument</item>
+	  <tag><seealso marker="#driver_realloc">driver_realloc</seealso></tag>
+	  <item>2:nd argument</item>
+	  <tag>
+	  <seealso marker="#driver_alloc_binary">driver_alloc_binary</seealso>
+	  </tag>
+	  <item>1:st argument</item>
+	  <tag>
+	  <seealso marker="#driver_realloc_binary">driver_realloc_binary</seealso>
+	  </tag>
+	  <item>2:nd argument</item>
+	  <tag><seealso marker="#driver_enq">driver_enq</seealso></tag>
+	  <item>3:rd argument</item>
+	  <tag><seealso marker="#driver_pushq">driver_pushq</seealso></tag>
+	  <item>3:rd argument</item>
+	  <tag><seealso marker="#driver_deq">driver_deq</seealso></tag>
+	  <item>2:nd argument and return value</item>
+	  <tag><seealso marker="#driver_sizeq">driver_sizeq</seealso></tag>
+	  <item>return value</item>
+	  <tag><seealso marker="#driver_enq_bin">driver_enq_bin</seealso></tag>
+	  <item>3:rd and 4:th argument</item>
+	  <tag><seealso marker="#driver_pushq_bin">driver_pushq_bin</seealso></tag>
+	  <item>3:rd and 4:th argument</item>
+	  <tag><seealso marker="#driver_enqv">driver_enqv</seealso></tag>
+	  <item>3:rd argument</item>
+	  <tag><seealso marker="#driver_pushqv">driver_pushqv</seealso></tag>
+	  <item>3:rd argument</item>
+	  <tag><seealso marker="#driver_peekqv">driver_peekqv</seealso></tag>
+	  <item>return value</item>
+	</taglist>
+	<note>
+	  <p>
+	    This is a change from signed to unsigned which
+	    may cause problems for e.g. loop termination conditions and
+	    error conditions if you just change the types all over the place.
+	  </p>
+	</note>
       </item>
     </taglist>
   </section>
@@ -285,7 +476,11 @@
     <title>DATA TYPES</title>
 
     <taglist>
-     <tag><marker id="ErlDrvSysInfo"/>ErlDrvSysInfo</tag>
+      <tag><marker id="ErlDrvSizeT"/>ErlDrvSizeT</tag>
+      <item><p>An unsigned integer type to be used as <c>size_t</c></p></item>
+      <tag><marker id="ErlDrvSSizeT"/>ErlDrvSSizeT</tag>
+      <item><p>A signed integer type the size of <c>ErlDrvSizeT</c></p></item>
+      <tag><marker id="ErlDrvSysInfo"/>ErlDrvSysInfo</tag>
       <item>
       <p/>
       <code type="none">
@@ -332,12 +527,12 @@ typedef struct ErlDrvSysInfo {
         <tag><c>erts_version</c></tag>
         <item>A string containing the version number of the runtime system
            (the same as returned by
-          <seealso marker="erts:erlang#system_info_version">erlang:system_info(version)</seealso>).
+          <seealso marker="erlang#system_info_version">erlang:system_info(version)</seealso>).
         </item>
         <tag><c>otp_release</c></tag>
         <item>A string containing the OTP release number
            (the same as returned by
-          <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).
+          <seealso marker="erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).
         </item>
         <tag><c>thread_support</c></tag>
         <item>A value <c>!= 0</c> if the runtime system has thread support;
@@ -351,12 +546,12 @@ typedef struct ErlDrvSysInfo {
         <item>The number of async threads in the async thread pool used
            by <seealso marker="#driver_async">driver_async()</seealso>
            (the same as returned by
-          <seealso marker="erts:erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).
+          <seealso marker="erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).
         </item>
         <tag><c>scheduler_threads</c></tag>
         <item>The number of scheduler threads used by the runtime system
            (the same as returned by
-          <seealso marker="erts:erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).
+          <seealso marker="erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).
         </item>
         <tag><c>nif_major_version</c></tag>
         <item>The value of <c>ERL_NIF_MAJOR_VERSION</c> when the runtime system was compiled.
@@ -371,7 +566,7 @@ typedef struct ErlDrvSysInfo {
       <p/>
       <code type="none">
 typedef struct ErlDrvBinary {
-   int orig_size;
+   ErlDrvSint orig_size;
    char orig_bytes[];
 } ErlDrvBinary;
 </code>
@@ -423,7 +618,7 @@ typedef struct ErlDrvBinary {
       <item>
         <p>The <c>ErlDrvData</c> is a handle to driver-specific data,
           passed to the driver call-backs. It is a pointer, and is
-          most often casted to a specific pointer in the driver.</p>
+          most often type casted to a specific pointer in the driver.</p>
       </item>
       <tag>SysIOVec</tag>
       <item>
@@ -437,7 +632,7 @@ typedef struct ErlDrvBinary {
       <code type="none">
 typedef struct ErlIOVec {
   int vsize;
-  int size;
+  ErlDrvSizeT size;
   SysIOVec* iov;
   ErlDrvBinary** binv;
 } ErlIOVec;
@@ -630,7 +825,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)</nametext></name>
       <fsummary>Send data from driver to port owner</fsummary>
       <desc>
         <marker id="driver_output"></marker>
@@ -650,7 +845,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, int hlen, char *buf, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</nametext></name>
       <fsummary>Send data and binary data to port owner</fsummary>
       <desc>
         <marker id="driver_output2"></marker>
@@ -665,7 +860,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, int hlen, ErlDrvBinary* bin, int offset, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
       <fsummary>Send data from a driver binary to port owner</fsummary>
       <desc>
         <marker id="driver_output_binary"></marker>
@@ -688,7 +883,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, int hlen,  ErlIOVec *ev, int skip)</nametext></name>
+      <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen,  ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
       <fsummary>Send vectorized data to port owner</fsummary>
       <desc>
         <marker id="driver_outputv"></marker>
@@ -711,7 +906,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, int len)</nametext></name>
+      <name><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)</nametext></name>
       <fsummary>Collect data segments into a buffer</fsummary>
       <desc>
         <marker id="driver_vec_to_buf"></marker>
@@ -738,7 +933,7 @@ typedef struct ErlIOVec {
           <c>time</c> parameter is the time in milliseconds before the
           timer expires.</p>
         <p>When the timer reaches 0 and expires, the driver entry
-          function <seealso marker="driver_entry#emulator">timeout</seealso> is called.</p>
+          function <seealso marker="driver_entry#timeout">timeout</seealso> is called.</p>
         <p>Note that there is only one timer on each driver instance;
           setting a new timer will replace an older one.</p>
         <p>Return value is 0 (-1 only when the <c>timeout</c> driver
@@ -832,7 +1027,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>void *</ret><nametext>driver_alloc(size_t size)</nametext></name>
+      <name><ret>void *</ret><nametext>driver_alloc(ErlDrvSizeT size)</nametext></name>
       <fsummary>Allocate memory</fsummary>
       <desc>
         <marker id="driver_alloc"></marker>
@@ -846,7 +1041,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>void *</ret><nametext>driver_realloc(void *ptr, size_t size)</nametext></name>
+      <name><ret>void *</ret><nametext>driver_realloc(void *ptr, ErlDrvSizeT size)</nametext></name>
       <fsummary>Resize an allocated memory block</fsummary>
       <desc>
         <marker id="driver_realloc"></marker>
@@ -872,7 +1067,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>ErlDrvBinary*</ret><nametext>driver_alloc_binary(int size)</nametext></name>
+      <name><ret>ErlDrvBinary*</ret><nametext>driver_alloc_binary(ErlDrvSizeT size)</nametext></name>
       <fsummary>Allocate a driver binary</fsummary>
       <desc>
         <marker id="driver_alloc_binary"></marker>
@@ -892,7 +1087,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>ErlDrvBinary*</ret><nametext>driver_realloc_binary(ErlDrvBinary *bin, int size)</nametext></name>
+      <name><ret>ErlDrvBinary*</ret><nametext>driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size)</nametext></name>
       <fsummary>Resize a driver binary</fsummary>
       <desc>
         <marker id="driver_realloc_binary"></marker>
@@ -958,7 +1153,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name>
       <fsummary>Enqueue data in the driver queue</fsummary>
       <desc>
         <marker id="driver_enq"></marker>
@@ -982,7 +1177,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name>
       <fsummary>Push data at the head of the driver queue</fsummary>
       <desc>
         <marker id="driver_pushq"></marker>
@@ -997,7 +1192,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_deq(ErlDrvPort port, int size)</nametext></name>
+      <name><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, ErlDrvSizeT size)</nametext></name>
       <fsummary>Dequeue data from the head of the driver queue</fsummary>
       <desc>
         <marker id="driver_deq"></marker>
@@ -1013,7 +1208,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_sizeq(ErlDrvPort port)</nametext></name>
+      <name><ret>ErlDrvSizeT</ret><nametext>driver_sizeq(ErlDrvPort port)</nametext></name>
       <fsummary>Return the size of the driver queue</fsummary>
       <desc>
         <marker id="driver_sizeq"></marker>
@@ -1026,7 +1221,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,  int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
       <fsummary>Enqueue binary in the driver queue</fsummary>
       <desc>
         <marker id="driver_enq_bin"></marker>
@@ -1043,7 +1238,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len)</nametext></name>
+      <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
       <fsummary>Push binary at the head of the driver queue</fsummary>
       <desc>
         <marker id="driver_pushq_bin"></marker>
@@ -1060,13 +1255,35 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
+      <name><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, ErlIOVec *ev)</nametext></name>
+      <fsummary>Get the driver queue as an IO vector</fsummary>
+      <desc>
+        <marker id="driver_peekqv"></marker>
+        <p>
+	  This function retrieves the driver queue into a supplied
+	  <c>ErlIOVec</c> <c>ev</c>. It also returns the queue size.
+	  This is one of two ways to get data out of the queue.
+	</p>
+	<p>
+	  If <c>ev</c> is <c>NULL</c> all ones i.e. <c>-1</c> type cast to
+	  <c>ErlDrvSizeT</c> is returned.
+	</p>
+        <p>Nothing is removed from the queue by this function, that must be done
+          with <c>driver_deq</c>.</p>
+        <p>This function can be called from an arbitrary thread if a
+          <seealso marker="#ErlDrvPDL">port data lock</seealso>
+          associated with the <c>port</c> is locked by the calling
+          thread during the call.</p>
+      </desc>
+    </func>
+    <func>
       <name><ret>SysIOVec*</ret><nametext>driver_peekq(ErlDrvPort port, int *vlen)</nametext></name>
       <fsummary>Get the driver queue as a vector</fsummary>
       <desc>
         <marker id="driver_peekq"></marker>
         <p>This function retrieves the driver queue as a pointer to an
           array of <c>SysIOVec</c>s. It also returns the number of
-          elements in <c>vlen</c>. This is the only way to get data
+          elements in <c>vlen</c>. This is one of two ways to get data
           out of the queue.</p>
         <p>Nothing is removed from the queue by this function, that must be done
           with <c>driver_deq</c>.</p>
@@ -1079,7 +1296,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip)</nametext></name>
+      <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
       <fsummary>Enqueue vector in the driver queue</fsummary>
       <desc>
         <marker id="driver_enqv"></marker>
@@ -1095,7 +1312,7 @@ typedef struct ErlIOVec {
       </desc>
     </func>
     <func>
-      <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip)</nametext></name>
+      <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
       <fsummary>Push vector at the head of the driver queue</fsummary>
       <desc>
         <marker id="driver_pushqv"></marker>
@@ -1494,7 +1711,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	term encoded with the
 	<seealso marker="erl_ext_dist">external format</seealso>,
 	i.e., a term that has been encoded by
-	<seealso marker="erts:erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
+	<seealso marker="erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
 	<seealso marker="erl_interface:ei">erl_interface</seealso>, etc.
 	For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c>
 	that contains the term <c>{17, 4711}</c> encoded with the
@@ -1694,7 +1911,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
            The driver defined handle is normally created in the
           <seealso marker="driver_entry#start">driver start call-back</seealso>
            when a port is created via
-          <seealso marker="erts:erlang#open_port/2">erlang:open_port/2</seealso>. </item>
+          <seealso marker="erlang#open_port/2">erlang:open_port/2</seealso>. </item>
         </taglist>
         <p>The caller of <c>driver_create_port()</c> is allowed to
           manipulate the newly created port when <c>driver_create_port()</c>
@@ -2462,7 +2679,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
     <title>SEE ALSO</title>
     <p><seealso marker="driver_entry">driver_entry(3)</seealso>,
       <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>,
-      <seealso marker="erts:erlang">erlang(3)</seealso></p>
+      <seealso marker="erlang">erlang(3)</seealso></p>
     <p>An Alternative Distribution Driver (ERTS User's
       Guide Ch. 3)</p>
   </section>