[PATCH:libX11] specs/libX11: Update Portability Considerations for the 21st century

[Peter Hutterer]

On Sun, Jan 01, 2017 at 08:57:58PM -0800, Alan Coopersmith wrote:
> Signed-off-by: Alan Coopersmith <alan.coopersmith at oracle.com>

thanks

   28f4b98..663f470  master -> master

Cheers,
   Peter

> ---
>  specs/libX11/AppC.xml | 21 +++++++++++++++------
>  1 file changed, 15 insertions(+), 6 deletions(-)
> 
> The current version of this section can be seen at:
> https://www.x.org/releases/X11R7.7/doc/libX11/libX11/libX11.html#Portability_Considerations
> 
> diff --git a/specs/libX11/AppC.xml b/specs/libX11/AppC.xml
> index bac148c..8eb1e00 100644
> --- a/specs/libX11/AppC.xml
> +++ b/specs/libX11/AppC.xml
> @@ -3211,13 +3211,12 @@ You must pass back the same pointer and size that were returned by
>  </sect2>
>  <sect2 id="Portability_Considerations">
>  <title>Portability Considerations</title>
>  <para>
>  <!-- .LP -->
> -Many machine architectures, 
> -including many of the more recent <acronym>RISC</acronym> architectures,
> -do not correctly access data at unaligned locations; 
> +Many machine architectures
> +do not correctly or efficiently access data at unaligned locations;
>  their compilers pad out structures to preserve this characteristic.
>  Many other machines capable of unaligned references pad inside of structures
>  as well to preserve alignment, because accessing aligned data is
>  usually much faster.
>  Because the library and the server use structures to access data at
> @@ -3227,11 +3226,13 @@ that is, 16-bit data starts on 16-bit boundaries in the request
>  and 32-bit data on 32-bit boundaries.
>  All requests <emphasis remap='I'>must</emphasis> be a multiple of 32 bits in length to preserve
>  the natural alignment in the data stream.
>  You must pad structures out to 32-bit boundaries.
>  Pad information does not have to be zeroed unless you want to
> -preserve such fields for future use in your protocol requests.
> +preserve such fields for future use in your protocol requests,
> +but it is recommended to zero it to avoid inadvertant data leakage
> +and improve compressability.
>  Floating point varies radically between machines and should be
>  avoided completely if at all possible.
>  </para>
>  <para>
>  <!-- .LP -->
> @@ -3264,19 +3265,27 @@ take on values larger than the maximum 16-bit
>  <type>unsigned</type>
>  <type>int</type>.
>  </para>
>  <para>
>  <!-- .LP -->
> -The library currently assumes that a
> +The library has always assumed that a
>  <type>char</type>
>  is 8 bits, a
>  <type>short</type>
>  is 16 bits, an
>  <type>int</type>
>  is 16 or 32 bits, and a
>  <type>long</type>
> -is 32 bits.  
> +is 32 bits.
> +Unfortunately, this assumption remains on machines where a <type>long</type>
> +can hold 64-bits, and many functions and structures require unnecessarily
> +large fields to avoid breaking compatibility with existing code.  Special
> +care must be taken with arrays of values that are transmitted in the
> +protocol as CARD32 or INT32 but have to be converted to arrays of 64-bit
> +<type>long</type> when passed to or from client applications.
> +</para>
> +<para>
>  The 
>  <function>PackData</function>
>  macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
>  However, much more work is needed to make this work properly.
>  </para>
> -- 
> 2.7.4
> 
> _______________________________________________
> xorg-devel at lists.x.org: X.Org development
> Archives: http://lists.x.org/archives/xorg-devel
> Info: https://lists.x.org/mailman/listinfo/xorg-devel
>