From d62f7ce538aa6c9b771fe07010dbd27f9f75c4a8 Mon Sep 17 00:00:00 2001
From: Philip Withnall <philip.withnall@collabora.co.uk>
Date: Tue, 15 Dec 2015 09:25:36 +0000
Subject: [PATCH] spec: Clarify the marshaling format in a few minor ways
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is an attempt to make that section a little clearer. I don’t think
any factual inaccuracies have been fixed (because I couldn’t find any).

https://bugs.freedesktop.org/show_bug.cgi?id=93382
---
 doc/dbus-specification.xml | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 0500220..3b55915 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -968,8 +968,10 @@
       <para>
         Each value in a block of bytes is aligned "naturally," for example
         4-byte values are aligned to a 4-byte boundary, and 8-byte values to an
-        8-byte boundary. To properly align a value, <firstterm>alignment
-        padding</firstterm> may be necessary. The alignment padding must always
+        8-byte boundary. Boundaries are calculated globally, with respect to
+        the first byte in the message. To properly align a value,
+        <firstterm>alignment padding</firstterm> may be necessary before the
+        value. The alignment padding must always
         be the minimum required padding to properly align the following value;
         and it must always be made up of nul bytes. The alignment padding must
         not be left uninitialized (it can't contain garbage), and more padding
@@ -996,21 +998,24 @@
       </para>
 
       <para>
-        The string-like types are all marshalled as a
+        The string-like types (STRING, OBJECT_PATH and SIGNATURE) are all
+        marshalled as a
         fixed-length unsigned integer <varname>n</varname> giving the
         length of the variable part, followed by <varname>n</varname>
         nonzero bytes of UTF-8 text, followed by a single zero (nul) byte
         which is not considered to be part of the text. The alignment
         of the string-like type is the same as the alignment of
-        <varname>n</varname>.
+        <varname>n</varname>. Any alignment padding is placed after the
+        trailing nul byte, rather than between <varname>n</varname> and the
+        string text.
       </para>
 
       <para>
         For the STRING and OBJECT_PATH types, <varname>n</varname> is
-        encoded in 4 bytes, leading to 4-byte alignment.
-        For the SIGNATURE type, <varname>n</varname> is encoded as a single
-        byte. As a result, alignment padding is never required before a
-        SIGNATURE.
+        encoded in 4 bytes (a <literal>UINT32</literal>), leading to 4-byte
+        alignment. For the SIGNATURE type, <varname>n</varname> is encoded as a
+        single byte (a <literal>UINT8</literal>). As a result, alignment
+        padding is never required before a SIGNATURE.
       </para>
     </sect2>
 
@@ -1024,7 +1029,8 @@
         element type, followed by the <varname>n</varname> bytes of the
         array elements marshalled in sequence. <varname>n</varname> does not
         include the padding after the length, or any padding after the
-        last element.
+        last element. i.e. <varname>n</varname> should be divisible by the
+        number of elements in the array.
       </para>
 
       <para>
@@ -1033,7 +1039,7 @@
         the 64-bit integer 5 would be marshalled as:
 
         <screen>
-00 00 00 08               <lineannotation>8 bytes of data</lineannotation>
+00 00 00 08               <lineannotation><varname>n</varname> = 8 bytes of data</lineannotation>
 00 00 00 00               <lineannotation>padding to 8-byte boundary</lineannotation>
 00 00 00 00  00 00 00 05  <lineannotation>first element = 5</lineannotation>
         </screen>
@@ -1057,8 +1063,10 @@
         marshalled value with the type given by that signature. The
         variant has the same 1-byte alignment as the signature, which means
         that alignment padding before a variant is never needed.
-        Use of variants may not cause a total message depth to be larger
+        Use of variants must not cause a total message depth to be larger
         than 64, including other container types such as structures.
+        (See <link linkend="message-protocol-marshaling-signature">Valid
+        Signatures</link>.)
       </para>
     </sect2>
 
-- 
2.5.0