1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 /* Functions for reading and writing integers in various endiannesses. */
9 * The classes LittleEndian and BigEndian expose static methods for
10 * reading and writing 16-, 32-, and 64-bit signed and unsigned integers
11 * in their respective endianness. The naming scheme is:
13 * {Little,Big}Endian::{read,write}{Uint,Int}<bitsize>
15 * For instance, LittleEndian::readInt32 will read a 32-bit signed
16 * integer from memory in little endian format. Similarly,
17 * BigEndian::writeUint16 will write a 16-bit unsigned integer to memory
18 * in big-endian format.
20 * The class NativeEndian exposes methods for conversion of existing
21 * data to and from the native endianness. These methods are intended
22 * for cases where data needs to be transferred, serialized, etc.
23 * swap{To,From}{Little,Big}Endian byteswap a single value if necessary.
24 * Bulk conversion functions are also provided which optimize the
25 * no-conversion-needed case:
27 * - copyAndSwap{To,From}{Little,Big}Endian;
28 * - swap{To,From}{Little,Big}EndianInPlace.
30 * The *From* variants are intended to be used for reading data and the
31 * *To* variants for writing data.
33 * Methods on NativeEndian work with integer data of any type.
34 * Floating-point data is not supported.
36 * For clarity in networking code, "Network" may be used as a synonym
37 * for "Big" in any of the above methods or class names.
39 * As an example, reading a file format header whose fields are stored
40 * in big-endian format might look like:
47 * uint32_t totalRecords;
51 * ExampleHeader(const void* data) {
52 * const uint8_t* ptr = static_cast<const uint8_t*>(data);
53 * magic = BigEndian::readUint32(ptr); ptr += sizeof(uint32_t);
54 * length = BigEndian::readUint32(ptr); ptr += sizeof(uint32_t);
55 * totalRecords = BigEndian::readUint32(ptr); ptr += sizeof(uint32_t);
56 * checksum = BigEndian::readUint64(ptr);
62 #ifndef mozilla_Endian_h_
63 #define mozilla_Endian_h_
65 #include "mozilla/Assertions.h"
66 #include "mozilla/Attributes.h"
67 #include "mozilla/Compiler.h"
68 #include "mozilla/DebugOnly.h"
69 #include "mozilla/StandardInteger.h"
70 #include "mozilla/TypeTraits.h"
74 #if defined(_MSC_VER) && _MSC_VER >= 1300
76 # pragma intrinsic(_byteswap_ushort)
77 # pragma intrinsic(_byteswap_ulong)
78 # pragma intrinsic(_byteswap_uint64)
82 # if defined(_M_X64) || defined(_M_AMD64) || defined(_AMD64_)
83 # define MOZ_LITTLE_ENDIAN 1
85 # error "CPU type is unknown"
89 # define MOZ_LITTLE_ENDIAN 1
91 # error "CPU type is unknown"
93 #elif defined(__APPLE__)
94 # if __LITTLE_ENDIAN__
95 # define MOZ_LITTLE_ENDIAN 1
97 # define MOZ_BIG_ENDIAN 1
99 #elif defined(__GNUC__) && \
100 defined(__BYTE_ORDER__) && \
101 defined(__ORDER_LITTLE_ENDIAN__) && \
102 defined(__ORDER_BIG_ENDIAN__)
104 * Some versions of GCC provide architecture-independent macros for
105 * this. Yes, there are more than two values for __BYTE_ORDER__.
107 # if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
108 # define MOZ_LITTLE_ENDIAN 1
109 # elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
110 # define MOZ_BIG_ENDIAN 1
112 # error "Can't handle mixed-endian architectures"
115 * We can't include useful headers like <endian.h> or <sys/isa_defs.h>
116 * here because they're not present on all platforms. Instead we have
117 * this big conditional that ideally will catch all the interesting
120 #elif defined(__sparc) || defined(__sparc__) || \
121 defined(_POWER) || defined(__powerpc__) || \
122 defined(__ppc__) || defined(__hppa) || \
123 defined(_MIPSEB) || defined(__ARMEB__) || \
124 defined(__s390__) || \
125 (defined(__sh__) && defined(__LITTLE_ENDIAN__)) || \
126 (defined(__ia64) && defined(__BIG_ENDIAN__))
127 # define MOZ_BIG_ENDIAN 1
128 #elif defined(__i386) || defined(__i386__) || \
129 defined(__x86_64) || defined(__x86_64__) || \
130 defined(_MIPSEL) || defined(__ARMEL__) || \
131 defined(__alpha__) || \
132 (defined(__sh__) && defined(__BIG_ENDIAN__)) || \
133 (defined(__ia64) && !defined(__BIG_ENDIAN__))
134 # define MOZ_LITTLE_ENDIAN 1
138 # define MOZ_LITTLE_ENDIAN 0
139 #elif MOZ_LITTLE_ENDIAN
140 # define MOZ_BIG_ENDIAN 0
142 # error "Cannot determine endianness"
145 #if defined(__clang__)
146 # if __has_builtin(__builtin_bswap16)
147 # define MOZ_HAVE_BUILTIN_BYTESWAP16 __builtin_bswap16
149 #elif defined(__GNUC__)
150 # if MOZ_GCC_VERSION_AT_LEAST(4, 8, 0)
151 # define MOZ_HAVE_BUILTIN_BYTESWAP16 __builtin_bswap16
153 #elif defined(_MSC_VER)
154 # define MOZ_HAVE_BUILTIN_BYTESWAP16 _byteswap_ushort
162 * We need wrappers here because free functions with default template
163 * arguments and/or partial specialization of function templates are not
164 * supported by all the compilers we use.
166 template<typename T
, size_t Size
= sizeof(T
)>
172 static T
swap(T value
)
174 #if defined(MOZ_HAVE_BUILTIN_BYTESWAP16)
175 return MOZ_HAVE_BUILTIN_BYTESWAP16(value
);
177 return T(((value
& 0x00ff) << 8) | ((value
& 0xff00) >> 8));
185 static T
swap(T value
)
187 #if defined(__clang__) || defined(__GNUC__)
188 return T(__builtin_bswap32(value
));
189 #elif defined(_MSC_VER)
190 return T(_byteswap_ulong(value
));
192 return T(((value
& 0x000000ffU
) << 24) |
193 ((value
& 0x0000ff00U
) << 8) |
194 ((value
& 0x00ff0000U
) >> 8) |
195 ((value
& 0xff000000U
) >> 24));
203 static inline T
swap(T value
)
205 #if defined(__clang__) || defined(__GNUC__)
206 return T(__builtin_bswap64(value
));
207 #elif defined(_MSC_VER)
208 return T(_byteswap_uint64(value
));
210 return T(((value
& 0x00000000000000ffULL
) << 56) |
211 ((value
& 0x000000000000ff00ULL
) << 40) |
212 ((value
& 0x0000000000ff0000ULL
) << 24) |
213 ((value
& 0x00000000ff000000ULL
) << 8) |
214 ((value
& 0x000000ff00000000ULL
) >> 8) |
215 ((value
& 0x0000ff0000000000ULL
) >> 24) |
216 ((value
& 0x00ff000000000000ULL
) >> 40) |
217 ((value
& 0xff00000000000000ULL
) >> 56));
222 enum Endianness
{ Little
, Big
};
225 # define MOZ_NATIVE_ENDIANNESS detail::Big
227 # define MOZ_NATIVE_ENDIANNESS detail::Little
233 * Assert that the memory regions [dest, dest+count) and [src, src+count]
234 * do not overlap. count is given in bytes.
236 static void assertNoOverlap(const void* dest
, const void* src
, size_t count
)
238 DebugOnly
<const uint8_t*> byteDestPtr
= static_cast<const uint8_t*>(dest
);
239 DebugOnly
<const uint8_t*> byteSrcPtr
= static_cast<const uint8_t*>(src
);
240 MOZ_ASSERT((byteDestPtr
< byteSrcPtr
&&
241 byteDestPtr
+ count
<= byteSrcPtr
) ||
242 (byteSrcPtr
< byteDestPtr
&&
243 byteSrcPtr
+ count
<= byteDestPtr
));
247 static void assertAligned(T
* ptr
)
249 MOZ_ASSERT((uintptr_t(ptr
) % sizeof(T
)) == 0, "Unaligned pointer!");
254 * Return |value| converted from SourceEndian encoding to DestEndian
257 template<Endianness SourceEndian
, Endianness DestEndian
, typename T
>
258 static inline T
maybeSwap(T value
)
260 if (SourceEndian
== DestEndian
)
263 return Swapper
<T
>::swap(value
);
267 * Convert |count| elements at |ptr| from SourceEndian encoding to
268 * DestEndian encoding.
270 template<Endianness SourceEndian
, Endianness DestEndian
, typename T
>
271 static inline void maybeSwapInPlace(T
* ptr
, size_t count
)
275 if (SourceEndian
== DestEndian
)
278 for (size_t i
= 0; i
< count
; i
++)
279 ptr
[i
] = Swapper
<T
>::swap(ptr
[i
]);
283 * Write |count| elements to the unaligned address |dest| in DestEndian
284 * format, using elements found at |src| in SourceEndian format.
286 template<Endianness SourceEndian
, Endianness DestEndian
, typename T
>
287 static void copyAndSwapTo(void* dest
, const T
* src
, size_t count
)
289 assertNoOverlap(dest
, src
, count
* sizeof(T
));
292 if (SourceEndian
== DestEndian
) {
293 memcpy(dest
, src
, count
* sizeof(T
));
297 uint8_t* byteDestPtr
= static_cast<uint8_t*>(dest
);
298 for (size_t i
= 0; i
< count
; ++i
) {
301 uint8_t buffer
[sizeof(T
)];
303 u
.val
= maybeSwap
<SourceEndian
, DestEndian
>(src
[i
]);
304 memcpy(byteDestPtr
, u
.buffer
, sizeof(T
));
305 byteDestPtr
+= sizeof(T
);
310 * Write |count| elements to |dest| in DestEndian format, using elements
311 * found at the unaligned address |src| in SourceEndian format.
313 template<Endianness SourceEndian
, Endianness DestEndian
, typename T
>
314 static void copyAndSwapFrom(T
* dest
, const void* src
, size_t count
)
316 assertNoOverlap(dest
, src
, count
* sizeof(T
));
319 if (SourceEndian
== DestEndian
) {
320 memcpy(dest
, src
, count
* sizeof(T
));
324 const uint8_t* byteSrcPtr
= static_cast<const uint8_t*>(src
);
325 for (size_t i
= 0; i
< count
; ++i
) {
328 uint8_t buffer
[sizeof(T
)];
330 memcpy(u
.buffer
, byteSrcPtr
, sizeof(T
));
331 dest
[i
] = maybeSwap
<SourceEndian
, DestEndian
>(u
.val
);
332 byteSrcPtr
+= sizeof(T
);
337 template<Endianness ThisEndian
>
338 class Endian
: private EndianUtils
341 /** Read a uint16_t in ThisEndian endianness from |p| and return it. */
342 static MOZ_WARN_UNUSED_RESULT
uint16_t readUint16(const void* p
) {
343 return read
<uint16_t>(p
);
346 /** Read a uint32_t in ThisEndian endianness from |p| and return it. */
347 static MOZ_WARN_UNUSED_RESULT
uint32_t readUint32(const void* p
) {
348 return read
<uint32_t>(p
);
351 /** Read a uint64_t in ThisEndian endianness from |p| and return it. */
352 static MOZ_WARN_UNUSED_RESULT
uint64_t readUint64(const void* p
) {
353 return read
<uint64_t>(p
);
356 /** Read an int16_t in ThisEndian endianness from |p| and return it. */
357 static MOZ_WARN_UNUSED_RESULT
int16_t readInt16(const void* p
) {
358 return read
<int16_t>(p
);
361 /** Read an int32_t in ThisEndian endianness from |p| and return it. */
362 static MOZ_WARN_UNUSED_RESULT
int32_t readInt32(const void* p
) {
363 return read
<uint32_t>(p
);
366 /** Read an int64_t in ThisEndian endianness from |p| and return it. */
367 static MOZ_WARN_UNUSED_RESULT
int64_t readInt64(const void* p
) {
368 return read
<int64_t>(p
);
371 /** Write |val| to |p| using ThisEndian endianness. */
372 static void writeUint16(void* p
, uint16_t val
) {
375 /** Write |val| to |p| using ThisEndian endianness. */
376 static void writeUint32(void* p
, uint32_t val
) {
379 /** Write |val| to |p| using ThisEndian endianness. */
380 static void writeUint64(void* p
, uint64_t val
) {
384 /** Write |val| to |p| using ThisEndian endianness. */
385 static void writeInt16(void* p
, int16_t val
) {
388 /** Write |val| to |p| using ThisEndian endianness. */
389 static void writeInt32(void* p
, int32_t val
) {
392 /** Write |val| to |p| using ThisEndian endianness. */
393 static void writeInt64(void* p
, int64_t val
) {
398 * Converts a value of type T to little-endian format.
400 * This function is intended for cases where you have data in your
401 * native-endian format and you need it to appear in little-endian
402 * format for transmission.
405 MOZ_WARN_UNUSED_RESULT
static T
swapToLittleEndian(T value
) {
406 return maybeSwap
<ThisEndian
, Little
>(value
);
409 * Copies count values of type T starting at src to dest, converting
410 * them to little-endian format if ThisEndian is Big.
411 * As with memcpy, dest and src must not overlap.
414 static void copyAndSwapToLittleEndian(void* dest
, const T
* src
,
416 copyAndSwapTo
<ThisEndian
, Little
>(dest
, src
, count
);
419 * Likewise, but converts values in place.
422 static void swapToLittleEndianInPlace(T
* p
, size_t count
) {
423 maybeSwapInPlace
<ThisEndian
, Little
>(p
, count
);
427 * Converts a value of type T to big-endian format.
430 MOZ_WARN_UNUSED_RESULT
static T
swapToBigEndian(T value
) {
431 return maybeSwap
<ThisEndian
, Big
>(value
);
434 * Copies count values of type T starting at src to dest, converting
435 * them to big-endian format if ThisEndian is Little.
436 * As with memcpy, dest and src must not overlap.
439 static void copyAndSwapToBigEndian(void* dest
, const T
* src
, size_t count
) {
440 copyAndSwapTo
<ThisEndian
, Big
>(dest
, src
, count
);
443 * Likewise, but converts values in place.
446 static void swapToBigEndianInPlace(T
* p
, size_t count
) {
447 maybeSwapInPlace
<ThisEndian
, Big
>(p
, count
);
451 * Synonyms for the big-endian functions, for better readability
455 MOZ_WARN_UNUSED_RESULT
static T
swapToNetworkOrder(T value
) {
456 return swapToBigEndian(value
);
460 copyAndSwapToNetworkOrder(void* dest
, const T
* src
, size_t count
) {
461 copyAndSwapToBigEndian(dest
, src
, count
);
465 swapToNetworkOrderInPlace(T
* p
, size_t count
) {
466 swapToBigEndianInPlace(p
, count
);
470 * Converts a value of type T from little-endian format.
473 MOZ_WARN_UNUSED_RESULT
static T
swapFromLittleEndian(T value
) {
474 return maybeSwap
<Little
, ThisEndian
>(value
);
477 * Copies count values of type T starting at src to dest, converting
478 * them to little-endian format if ThisEndian is Big.
479 * As with memcpy, dest and src must not overlap.
482 static void copyAndSwapFromLittleEndian(T
* dest
, const void* src
,
484 copyAndSwapFrom
<Little
, ThisEndian
>(dest
, src
, count
);
487 * Likewise, but converts values in place.
490 static void swapFromLittleEndianInPlace(T
* p
, size_t count
) {
491 maybeSwapInPlace
<Little
, ThisEndian
>(p
, count
);
495 * Converts a value of type T from big-endian format.
498 MOZ_WARN_UNUSED_RESULT
static T
swapFromBigEndian(T value
) {
499 return maybeSwap
<Big
, ThisEndian
>(value
);
502 * Copies count values of type T starting at src to dest, converting
503 * them to big-endian format if ThisEndian is Little.
504 * As with memcpy, dest and src must not overlap.
507 static void copyAndSwapFromBigEndian(T
* dest
, const void* src
,
509 copyAndSwapFrom
<Big
, ThisEndian
>(dest
, src
, count
);
512 * Likewise, but converts values in place.
515 static void swapFromBigEndianInPlace(T
* p
, size_t count
) {
516 maybeSwapInPlace
<Big
, ThisEndian
>(p
, count
);
520 * Synonyms for the big-endian functions, for better readability
524 MOZ_WARN_UNUSED_RESULT
static T
swapFromNetworkOrder(T value
) {
525 return swapFromBigEndian(value
);
528 static void copyAndSwapFromNetworkOrder(T
* dest
, const void* src
,
530 copyAndSwapFromBigEndian(dest
, src
, count
);
533 static void swapFromNetworkOrderInPlace(T
* p
, size_t count
) {
534 swapFromBigEndianInPlace(p
, count
);
539 * Read a value of type T, encoded in endianness ThisEndian from |p|.
540 * Return that value encoded in native endianness.
543 static T
read(const void* p
) {
546 uint8_t buffer
[sizeof(T
)];
548 memcpy(u
.buffer
, p
, sizeof(T
));
549 return maybeSwap
<ThisEndian
, MOZ_NATIVE_ENDIANNESS
>(u
.val
);
553 * Write a value of type T, in native endianness, to |p|, in ThisEndian
557 static void write(void* p
, T value
) {
558 T tmp
= maybeSwap
<MOZ_NATIVE_ENDIANNESS
, ThisEndian
>(value
);
559 memcpy(p
, &tmp
, sizeof(T
));
563 Endian(const Endian
& other
) MOZ_DELETE
;
564 void operator=(const Endian
& other
) MOZ_DELETE
;
567 template<Endianness ThisEndian
>
568 class EndianReadWrite
: public Endian
<ThisEndian
>
571 typedef Endian
<ThisEndian
> super
;
574 using super::readUint16
;
575 using super::readUint32
;
576 using super::readUint64
;
577 using super::readInt16
;
578 using super::readInt32
;
579 using super::readInt64
;
580 using super::writeUint16
;
581 using super::writeUint32
;
582 using super::writeUint64
;
583 using super::writeInt16
;
584 using super::writeInt32
;
585 using super::writeInt64
;
588 } /* namespace detail */
590 class LittleEndian MOZ_FINAL
: public detail::EndianReadWrite
<detail::Little
>
593 class BigEndian MOZ_FINAL
: public detail::EndianReadWrite
<detail::Big
>
596 typedef BigEndian NetworkEndian
;
598 class NativeEndian MOZ_FINAL
: public detail::Endian
<MOZ_NATIVE_ENDIANNESS
>
601 typedef detail::Endian
<MOZ_NATIVE_ENDIANNESS
> super
;
605 * These functions are intended for cases where you have data in your
606 * native-endian format and you need the data to appear in the appropriate
607 * endianness for transmission, serialization, etc.
609 using super::swapToLittleEndian
;
610 using super::copyAndSwapToLittleEndian
;
611 using super::swapToLittleEndianInPlace
;
612 using super::swapToBigEndian
;
613 using super::copyAndSwapToBigEndian
;
614 using super::swapToBigEndianInPlace
;
615 using super::swapToNetworkOrder
;
616 using super::copyAndSwapToNetworkOrder
;
617 using super::swapToNetworkOrderInPlace
;
620 * These functions are intended for cases where you have data in the
621 * given endianness (e.g. reading from disk or a file-format) and you
622 * need the data to appear in native-endian format for processing.
624 using super::swapFromLittleEndian
;
625 using super::copyAndSwapFromLittleEndian
;
626 using super::swapFromLittleEndianInPlace
;
627 using super::swapFromBigEndian
;
628 using super::copyAndSwapFromBigEndian
;
629 using super::swapFromBigEndianInPlace
;
630 using super::swapFromNetworkOrder
;
631 using super::copyAndSwapFromNetworkOrder
;
632 using super::swapFromNetworkOrderInPlace
;
635 #undef MOZ_NATIVE_ENDIANNESS
637 } /* namespace mozilla */
639 #endif /* mozilla_Endian_h_ */