boostorg/endian
1
0
Fork 1
mirror of https://github.com/boostorg/endian.git synced 2026-07-09 10:00:52 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
ptal-master
endian/doc/do_list.html
T

280 lines
13 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Endian Library Do List</title>
</head>
<body>
<h1>Endian Library Do List</h1>
<h2>To Do</h2>
<ul>
<li>Re-read all messages, and extract Acknowledgements and revise TODO list.</li>
<li>Develop the use-cases example programs, using plain integers and UDT's.
</li>
<li>Apply revised conversion functions to the example programs. Iterate until
happy.</li>
<li>Apply the integers to the example programs, and also see if using<br>
the revised conversion functions to implement some or all of the<br>
integers.</li>
<li>Apply mockups of the buffers to the example programs, to get a<br>
firmer idea if the buffer idea actually seems to do be worthwhile in<br>
practice.</li>
<li>Post work-in-progress for feedback.</li>
<li>boost-root/boost/detail/endian.hpp: Boost.Endian should provide identical
functionality in a Boost license only header. That implies rewriting the
portions covered by the original SGI copyright. The boost-root/boost/detail/endian.hpp
header should be changed to forward to the Boost.Endian header to preserve
existing code, and the SGI copyright thus eliminated.</li>
<li>Finalize and hold mini-review.</li>
</ul>
<h2>Format Review Comments</h2>
<h3 dir="ltr">Votes</h3>
<ul>
<li dir="ltr">
<p dir="ltr">John Filo - &quot;Absolutely. I'd like to see support for float and
double, but<br>
even without those additions, I still vote yes.&quot; &quot;For those who deal with
non-native endian data, this library is<br>
extremely useful. It automatically eliminates a whole class of common<br>
programming errors when dealing with such data.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Hartmut Kaiser - &quot;Even if this is not a full review, I would like
to vote YES to include this <br>
library into Boost.
<p>Boost.Spirit is using (and shipping) with an older version of this library
<br>
for several years now and we never had any problems with its usage in <br>
Spirit. It is used as the underlying framework for the binary parsers and <br>
generators and it is functioning as advertised.</p>
<p>As a quick test I replaced the internal (older) version of Boost.Endian in
<br>
Spirit with the reviewed version. All of Spirits regression tests still <br>
pass. &quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Robert Stewart - &quot;There are issues that keep me from saying yes
at this time. &nbsp;There are too many suggested variations and ideas under
consideration to accept the library in its present state. &nbsp;However, a
mini-review should be sufficient to evaluate the final form, once Beman
determines a course of action, and determine whether to accept it or not.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Tim Blechmann - &quot;the library should be accepted, if<br>
<br>
(a) the interface of the conversion functions is changed<br>
(b) the performance can be improved<br>
(c) the documentation integrates better with the rest of the boost<br>
&nbsp; &nbsp;documentation.&quot;<br>
&nbsp;</li>
<li dir="ltr">
<p dir="ltr">Vicente J. Botet Escriba - &quot;No in its current state.<br>
Once the library takes in account the requested modification (that Beman has
already accepted) a mini-review will be necessary to improve the library
before release.&quot;</li>
</ul>
<h3>Executive summary</h3>
<ul>
<li>Common use case scenarios should be developed.</li>
<li>Example programs should be developed for the common use case scenarios.</li>
<li>Documentation should illuminate the differences between endian
integer/float type and endian conversion approaches to the common use case
scenarios, and provide guidelines for choosing the most appropriate approach
for user's applications.</li>
<li>Conversion functions supplying results via <code>return</code> should be
provided.</li>
<li>Platform specific performance enhancements such as use of compiler
intrinsics or relaxed alignment requirements should be supported.</li>
<li>Endian integer (and floating) types should be implemented via the
conversion functions. If that can't be done efficiently, consideration should
be given to expanding the conversion function signatures to resolve the
inefficiencies.</li>
<li>Benchmarks that measure performance should be provided. It should be
possible to compare platform specific performance enhancements against
portable base implementations, and to compare endian integer approaches
against endian conversion approaches for the common use case scenarios.</li>
<li>Float (32-bits) and double (64-bits) should be supported. IEEE 754 is the
primary use case.</li>
<li>Support for user defined types (UDTs) is desirable, and should be
supported where there would be no conflict with the other concerns.</li>
<li>There is some concern that endian integer/float arithmetic operations
might used
inadvertently or inappropriately. The impact of adding an endian_buffer class without arithmetic
operations should be investigated.</li>
<li>Stream insertion and extraction of the endian integer/float types should
be documented and included in the test coverage.</li>
<li>Binary I/O support that was investigated during development of the Endian
library should be put up for min-review for inclusion in the Boost I/O
library.</li>
</ul>
<h3>Docs</h3>
<ul>
<li>Document use of endian integers with stream inserters and extractors.</li>
<li>Either add tutorial or remove from menu bar.</li>
<li>Conversion in note mention similarity to htonl() , etc.</li>
<li>Conversion: add discussion of alignment, packing, etc. Bottom line; use at
your own risk. Use Phil's example:<br>
struct S {<br>
&nbsp;uint16_t a;<br>
&nbsp;uint32_t b;<br>
} __attribute__ ((packed));</li>
<li>Requirements for template parameters. </li>
<li>UDTs<ul>
<li>Integers</li>
<li>Conversion</li>
</ul>
</li>
<li>Distinguish use cases and recommendations for which approach (integers vs
conversion) is appropriate.<ul>
<li><a href="http://lists.boost.org/Archives/boost/2011/09/185698.php">
http://lists.boost.org/Archives/boost/2011/09/185698.php</a></li>
</ul>
</li>
<li>&gt; section `experience': this section gives no insights for people who use
or<br>
&gt; read the code. it mainly tells: &quot;we are not the first and the domain of the<br>
&gt; library is important.&quot;. imo this section can be removed (maybe the part that<br>
&gt; it is not related to any c library can go to the `design considerations'<br>
&gt;<br>
&gt; section &quot;motivating use cases&quot;: this is more a marketing blurb/testimonial.<br>
&gt; maybe this could be changed to a section about possible use cases, listing<br>
&gt; `communicating between different devices' and `reading/writing of binary
file<br>
&gt; formats'.</li>
<li>one other point ... the help file seems to directly link to the c++
headers.<br>
this should be changed:<br>
<br>
* some browsers (at least chromium) will not display the header when clicking<br>
&nbsp;the link, but will save them on disk.<br>
<br>
* providing a direct link to the source code from the docs implies that the<br>
&nbsp;user will get some information that are necessary to use the library by<br>
&nbsp;reading the sources. imo, this is not the case for using boost.endian.<br>
<br>
* if a user opens integer.hpp, the first 60 lines just contain copyright, some<br>
&nbsp;historical notes, compiler-specific stuff, includes and ifdefs. imo, this is<br>
&nbsp;the implementation part, which should not be exposed to a user.<br>
<br>
so i'd suggest to completely remove the links to the c++ headers.<br>
&nbsp;</li>
<li>
<div class="im">
&gt; explaining the other builting types are not considered. Why only
big/little<br>
&gt; endianness has been taken in account?</div>
<p>I'll add FAQ and/or add more entries to the final docs.<br>
<br>
Only big/little endianness is taken into account because these are the<br>
only endian schemes that have any practical value. All the others are<br>
just historical curiosities.</li>
</ul>
<h3>Code</h3>
<p>Also change docs if applicable.</p>
<ul>
<li><span style="background-color: #FFCCFF">Beman: TODO</span><span style="background-color: #FFCCFF">:
</span><span style="background-color: #FFCCFF">Google</span><span style="background-color: #FFCCFF">
&quot;unaligned integer&quot;, look at various entries. For example, http://</span><span style="background-color: #FFCCFF">infocenter.arm.com</span><span style="background-color: #FFCCFF">/help/</span><span style="background-color: #FFCCFF">index.jsp?topic</span><span style="background-color: #FFCCFF">=/</span><span style="background-color: #FFCCFF">com.arm.doc.faqs</span><span style="background-color: #FFCCFF">/ka3544.html</span></li>
<li>Merge conversion2 into conversion.hpp</li>
<li>Use builtins where applicable (GCC, possibly others)</li>
<li>Endian integer types should use the conversion functions where applicable.</li>
<li>Beman: Some platforms (compiler/processor taken together) don't require
alignment for the conversion functions if code is inlined, although speed may
suffer. (test to verify this assertion). On those platforms, conversion
functions (perhaps in-place) can be used to implement unaligned integers.<ul>
<li>Microsoft <a href="http://msdn.microsoft.com/en-us/library/ms253978.aspx">
UNALIGNED / __unaligned</a> keywords for pointers. Also
<a href="http://msdn.microsoft.com/en-us/library/ms253935.aspx">Packing
Structures</a>.</li>
<li>GCC
<a href="http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html">
http://www.mailinglistarchive.com/gcc@gcc.gnu.org/msg21079.html</a></li>
<li>Intel performs well on simple unaligned test. See
<a href="../test/unaligned_test.cpp">../test/unaligned_test.cpp</a></li>
</ul>
</li>
<li>Beman: Does the use of the unrolling templates get in the way of processor
specific optimization code?</li>
<li>Test use of endian integers with stream inserters and extractors.</li>
<li>Continue work on benchmarks and timings. Consider using use-case example
programs as benchmarks.</li>
<li>
<div class="im">
&gt; The reorder fuction should provide both reorder in place and returned.</div>
<p>Interesting, but providing two ways of doing something is often<br>
considered the not best design practice. And the tests I've run so far<br>
don't indicate any efficiency concern. Once all other aspects of the<br>
interface and implementation are settled, let's revisit that question.<br>
&nbsp;</li>
<li>&gt; The endianness scoped enum native should be replaced so it is defined<br>
&gt; depending on the endianess of the platform.<br>
&gt;<br>
&gt; &nbsp;BOOST_SCOPED_ENUM_START(<wbr />endianness) { big, little, native=(big or
little)<br>
&gt; }; BOOST_SCOPED_ENUM_END<br>
&gt;<br>
&gt; This will have the advantage to reduce of 1/3 the number of specializations.<br>
<br>
Does this work?<br>
&nbsp;</li>
<li dir="ltr">
<div class="im">
&gt; The library should provide in addition endian conversion functions that
have<br>
&gt; the endiannes as template parameters to make possible generic functions.</div>
<p dir="ltr">Compile time dispatch on an endianness enum was also requested in<br>
another review. That's fine with me, but I haven't had a chance to<br>
figure out the interface details.</li>
</ul>
<h3>Infrastructure</h3>
<ul>
<li>Remove scoped_enum_emulation_test stuff.</li>
<li>Remove timer stuff.</li>
<li>Use Boost.Timer.</li>
<li>
<div class="im">
&gt; endian_operations_test.cpp and endian_in_union_test.cpp ... maybe rename
from<br>
&gt; _test.cpp to _compile_test.cpp? they don't seem to do any run-time tests.
they<br>
&gt; also should not include &lt;cassert&gt; since no assertion statement is needed,
this<br>
&gt; might speed up the compilation time of the testsuite by something like
50ms ;)</div>
<p>Will do.</li>
<li>Make the bin() functionality available</li>
</ul>
<h3>Performance</h3>
<p>&nbsp;</p>
<h3>Acknowledge</h3>
<p>Gordon Woodhull, Hartmut Kaiser, Phil Endecott, tymofey, Giovanni Piero Deretta, Pyry Jahkola,
John Filo, Vitaly Budovski, Tomas Puverle, Vicente J. Botet Escriba, Tim
Blechmann, Daniel James, Mathias Gaunard, Adder, Tim Moore</p>
<p>Paul Bristow docs help </p>
<h2>Floating Point Support</h2>
<p>* Because FP formats vary, just dealing with endianness doesn't ensure<br>
portability.<br>
* The endianness of FP and integer values differs on some platforms,<br>
so we will have to build up a config file with separate entries for<br>
each platform, and that will take time to mature.<br>
* Ditto FP sizes.<br>
* I'm only willing to provide conversion.hpp FP support. Providing<br>
types that mimic FP types is far beyond my knowledge of how to deal<br>
with floating point's notorious arithmetic issues.</p>
<p>Support IEEE754 format (32 bit, 64 bit) only.</p>
<div class="im">
<br>
&nbsp;</div>
<p>&nbsp;</p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink