From 01aa8b82dd0f8229355ffd2bb2bc8e8f496d2df6 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Fri, 26 Apr 2019 19:43:53 +0200
Subject: erl_interface: Tweak bit string encode/decode API

to support zero copy decoding
and bit offset arguments for future unaligned bit strings.
---
 lib/erl_interface/doc/src/ei.xml | 60 ++++++++++++++++++++++++++--------------
 1 file changed, 39 insertions(+), 21 deletions(-)

(limited to 'lib/erl_interface/doc')

diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml
index 254ae27cc8..7808bfd94f 100644
--- a/lib/erl_interface/doc/src/ei.xml
+++ b/lib/erl_interface/doc/src/ei.xml
@@ -183,28 +183,36 @@ typedef enum {
       </func>
 
       <func>
-          <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_decode_bitstring(const char *buf, int *index, void *p, size_t plen, size_t *bitsp)</nametext></name>
+          <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_decode_bitstring(const char *buf, int *index, const char **pp, unsigned int *bitoffsp, size_t *nbitsp)</nametext></name>
           <fsummary>Decode a bitstring.</fsummary>
           <desc>
-            <p>Decodes a bitstring from the binary format.</p>
+            <p>Decodes a bit string from the binary format.</p>
 	    <taglist>
-	      <tag><c>p</c></tag>
-	      <item><p>Either <c>NULL</c> or points to a buffer where the bytes of the
-	        bitstring will be written.</p>
+	      <tag><c>pp</c></tag>
+	      <item><p>Either <c>NULL</c> or <c>*pp</c> returns a pointer to
+	       the first byte of the bit string. The returned bit string is
+	       readable as long as the buffer pointed to by <c>buf</c> is
+	       readable and not written to.</p>
 	      </item>
-	      <tag><c>plen</c></tag>
-	      <item><p>The max size of the bitstring in <em>bytes</em>, that is the
-	        size of the buffer if <c>p != NULL</c>.</p>
+	      <tag><c>bitoffsp</c></tag>
+	      <item><p>Either <c>NULL</c> or <c>*bitoffsp</c> returns the
+	       number of unused bits in the first byte pointed to by
+	       <c>*pp</c>. The value of <c>*bitoffsp</c> is between 0 and 7.
+	       Unused bits in the first byte are the most significant bits.</p>
 	      </item>
-	      <tag><c>*bitsp</c></tag>
-	      <item><p>If <c>bitsp</c> is not <c>NULL</c>, set to the actual
-	        number of <em>bits</em> of the bitstring.</p>
+	      <tag><c>nbitsp</c></tag>
+	      <item><p>Either <c>NULL</c> or <c>*nbitsp</c> returns the length
+	       of the bit string in <em>bits</em>.</p>
 	      </item>
 	    </taglist>
-	    <p>Returns <c>0</c> if it was a bitstring no longer than <c>plen</c>
-	      bytes. The actual length of the bitstring will be
-	      <c>(*bitsp+7)/8</c> bytes. If <c>(*bitsp % 8) > 0</c> only the high
-	      <c>(*bitsp % 8)</c> bits of the last byte are significant.</p>
+	    <p>Returns <c>0</c> if it was a bit string term.</p>
+	    <p>The number of <em>bytes</em> pointed to by <c>*pp</c>, which are
+	      part of the bit string, is <c>(*bitoffsp + *nbitsp + 7)/8</c>. If
+	      <c>(*bitoffsp + *bitsp)%8 > 0</c> then only <c>(*bitoffsp +
+	      *bitsp)%8</c> bits of the last byte are used. Unused bits in
+	      the last byte are the least significant bits.</p>
+	    <p>The values of unused bits in the first and last byte are undefined
+	      and cannot be relied on.</p>
 	    <p>Number of bits may be divisible by 8, which means a binary
 	      decodable by <c>ei_decode_binary</c> is also decodable by
 	      <c>ei_decode_bitstring</c>.</p>
@@ -490,14 +498,24 @@ typedef enum {
     </func>
 
     <func>
-      <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_encode_bitstring(char *buf, int *index, const void *p, size_t bits)</nametext></name>
-      <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_x_encode_bitstring(ei_x_buff* x, const void *p, size_t bits)</nametext></name>
+      <name since="OTP @OTP-15712@"><ret>int</ret>
+      <nametext>ei_encode_bitstring(char *buf, int *index, const char *p, size_t bitoffs, size_t nbits)</nametext></name>
+      <name since="OTP @OTP-15712@"><ret>int</ret>
+      <nametext>ei_x_encode_bitstring(ei_x_buff* x, const char *p, size_t bitoffs, size_t nbits)</nametext></name>
       <fsummary>Encode a bitstring.</fsummary>
       <desc>
-        <p>Encodes a bitstring in the binary format. The data is at
-          <c>p</c>. The size of the data is <c>bits</c> bits or
-	  <c>(bits+7)/8</c> bytes. If <c>(bits%8) > 0</c> only the high
-	  <c>(bits%8)</c> bits of the last byte are significant.</p>
+        <p>Encodes a bit string in the binary format.</p>
+	<p>The data is at <c>p</c>. The length of the bit string is <c>nbits</c>
+	  bits. The first <c>bitoffs</c> bits of the data at <c>p</c> are unused.
+	  The first byte which is part of the bit string is
+	  <c>p[bitoffs/8]</c>. The <c>bitoffs%8</c> most significant bits of
+	  the first byte <c>p[bitoffs/8]</c> are unused.</p>
+	<p>The number of bytes which is part of the bit string is <c>(bitoffs +
+	  nbits + 7)/8</c>. If <c>(bitoffs + nbits)%8 > 0</c> then only <c>(bitoffs +
+	  nbits)%8</c> bits of the last byte are used. Unused bits in
+	  the last byte are the least significant bits.</p>
+	<p>The values of unused bits are disregarded and does not need to be
+	  cleared.</p>
       </desc>
     </func>
 
-- 
cgit v1.2.3