Bug 93382 - Minor clarifications to §(Marshaling (Wire Format)) of the specification
Summary: Minor clarifications to §(Marshaling (Wire Format)) of the specification
Status: RESOLVED FIXED
Alias: None
Product: dbus
Classification: Unclassified
Component: core (show other bugs)
Version: git master
Hardware: Other All
: medium normal
Assignee: D-Bus Maintainers
QA Contact: D-Bus Maintainers
URL:
Whiteboard: review+
Keywords: patch
Depends on:
Blocks:
 
Reported: 2015-12-15 09:23 UTC by Philip Withnall
Modified: 2016-06-30 15:52 UTC (History)
1 user (show)

See Also:
i915 platform:
i915 features:


Attachments
spec: Clarify the marshaling format in a few minor ways (4.45 KB, patch)
2015-12-15 09:26 UTC, Philip Withnall
Details | Splinter Review
spec: Clarify the marshaling format in a few minor ways (6.25 KB, patch)
2015-12-20 16:04 UTC, Philip Withnall
Details | Splinter Review

Description Philip Withnall 2015-12-15 09:23:52 UTC
At the systemd conference this year, it was noted that the marshaling section in the D-Bus specification is unclear in a few places.

For example, there was some confusion in https://github.com/godbus/dbus/pull/18.

Patch coming with my blind attempt at clarifying it.
Comment 1 Philip Withnall 2015-12-15 09:26:56 UTC
Created attachment 120520 [details] [review]
spec: Clarify the marshaling format in a few minor ways

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).
Comment 2 Simon McVittie 2015-12-15 11:36:56 UTC
Comment on attachment 120520 [details] [review]
spec: Clarify the marshaling format in a few minor ways

Review of attachment 120520 [details] [review]:
-----------------------------------------------------------------

::: doc/dbus-specification.xml
@@ +1006,5 @@
>          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>. Any alignment padding is placed after the
> +        trailing nul byte, rather than between <varname>n</varname> and the
> +        string text.

Any alignment padding for the string itself would come immediately before the length /n/, as described in the next paragraph.

Any alignment padding that comes after the trailing nul would be the alignment padding of *the next thing in the message* (varying from no padding at all for a byte or signature, up to 0-7 bytes for a (u)int64, double or struct) so it isn't really anything to do with the string.

Both of these are a consequences of the general rule (which might not be explicitly stated in as many words, but perhaps should be) that immediately before any value of type T, you zero-pad to T's alignment.

So I think it would be more accurate to say something like this:

The alignment of the string-like type is the same as the alignment of /n/: any padding required for /n/ appears immediately before /n/ itself. There is never any alignment padding between /n/ and the string text, or between the string text and the trailing nul. The alignment padding for the next value in the message (if there is one) starts after the trailing nul.

For example, if the current position is a multiple of 8 bytes from the beginning of a little-endian message, strings "foo", "+" and "bar" would be serialized in sequence as follows:

                                         # no padding required, we are already at a multiple of 4
0x03 0x00 0x00 0x00                      # length of "foo" = 3
                    0x66 0x6f 0x6f       # "foo"
                                   0x00  # trailing nul

                                         # no padding required, we are already at a multiple of 4
0x01 0x00 0x00 0x00                      # length of "+" = 1
                    0x2b                 # "+"
                         0x00            # trailing nul

                               0x00 0x00 # 2 bytes of padding to reach next multiple of 4
0x03 0x00 0x00 0x00                      # length of "bar" = 1
                    0x62 0x61 0x72       # "bar"
                                    0x00 # trailing nul
Comment 3 Philip Withnall 2015-12-20 16:04:32 UTC
Created attachment 120606 [details] [review]
spec: Clarify the marshaling format in a few minor ways

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).

Including some wording and an example by Simon McVittie
<smcv@debian.org>.
Comment 4 Simon McVittie 2016-06-30 13:09:15 UTC
Looks good, will apply soon.

Please change "review-" to "review?" in the "status whiteboard" when you believe you have fixed all negative review points and would like a patch re-reviewed. I normally assume that bugs still marked "review-" are waiting for a response from the patch submitter.
Comment 5 Simon McVittie 2016-06-30 15:52:25 UTC
Fixed in git for 1.11.4 (spec 0.28), thanks.


Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.