[libc] Add endianness support

[gchatelet]

Summary

Add endianness detection support. This will be useful to implement memcmp.

[gchatelet]

Let me know if you want this header to live somewhere else, or if you had other plans in mind.

libc/src/__support/endian.h

31

Here I decided to always define the symbol and set it to 0 or 1 but maybe it's better to leave it undefined. I fear that someone writes #ifdef LLVM_LIBC_IS_LITTLE_ENDIAN. It would always be true.

[gchatelet]

• Added missing modification to CMakeLists.txt

[sivachandra]

In D100571#2691821, @gchatelet wrote:

Let me know if you want this header to live somewhere else, or if you had other plans in mind.

The endianess support will rarely ever be updated. So, putting it in common is OK. If it were something which gets updated frequently, I would have suggested a separate library to avoid recompiles of parts which don't use endianess support.

libc/src/__support/endian.h

13

Include stdint.h as cstdint is a C++ header.

31

To avoid macro confusion, may be this:

namespace __llvm_libc {
namespace internal {

template <bool IsLittleEndian>
class Endian;

template <>
class Endian<__BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__> {
 public:
  static uint8_t toBigEndian(uint8_t v) { return v; }
  static uint16_t toBigEndian(uint16_t v) { return __builtin_bswap16(v); }
  ...
};

template <>
class Endian<__BYTE_ORDER__ != __ORDER_LITTLE_ENDIAN__> {
 public:
  static uint8_t toBigEndian(uint8_t v) { return v; }
  static uint16_t toBigEndian(uint16_t v) { return v; }
  ...
};

} // namespace internal

using Endian = internal::Endian<true>;
} // namespace __llvm_libc

You can also add toLittleEndian methods for the sake of completeness. Also, we probably need tests for this? For, we need the return type, the arg type, and the builtin function name to match. So, tests might protect us from mismatches.

[gchatelet]

• Add tests and remove macros

[gchatelet]

• Simplify tests

[gchatelet]

Thx for the suggestion, I didn't go with explicit member function as it would allow for integer promotion.
In the case of endianness we want to make sure we only accept one of uint8_t, uint16_t, uint32_t, uint64_t and no other type.
I've added the symmetric functions as you suggested.

[sivachandra]

In D100571#2694526, @gchatelet wrote:

Thx for the suggestion, I didn't go with explicit member function as it would allow for integer promotion.
In the case of endianness we want to make sure we only accept one of uint8_t, uint16_t, uint32_t, uint64_t and no other type.
I've added the symmetric functions as you suggested.

I think we can try to be cute and make it a compile-time error to use a non-uint*_t type, but not sure if it is worth it.

libc/src/__support/CMakeLists.txt

 add_header_library(
   common
   HDRS
     common.h
+    endian.h
     sanitizer.h
 )
 
 add_header_library(
   integer_operations
   HDRS
     integer_operations.h
 )
 

libc/src/__support/endian.h

+//===-- Endianness support ------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_LIBC_SRC_SUPPORT_ENDIAN_H
+#define LLVM_LIBC_SRC_SUPPORT_ENDIAN_H
+
+#include <stdint.h>
+
+namespace __llvm_libc {
+
+// We rely on compiler preprocessor defines to allow for cross compilation.
+#if !defined(__BYTE_ORDER__) || !defined(__ORDER_LITTLE_ENDIAN__) ||           \
+    !defined(__ORDER_BIG_ENDIAN__)
+#error "Missing preprocessor definitions for endianness detection."
+#endif
+
+namespace internal {
+
+// Converts uint8_t, uint16_t, uint32_t, uint64_t to its big or little endian
+// counterpart.
+// We use explicit template specialization:
+// - to prevent accidental integer promotion.
+// - to prevent fallback in (unlikely) case of middle-endianness.
+
+template <unsigned ORDER> struct Endian {
+  static constexpr const bool isLittle = ORDER == __ORDER_LITTLE_ENDIAN__;
+  static constexpr const bool isBig = ORDER == __ORDER_BIG_ENDIAN__;
+  template <typename T> static T ToBigEndian(T value);
+  template <typename T> static T ToLittleEndian(T value);
+};
+
+// Little Endian specializations
+template <>
+template <>
+inline uint8_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToBigEndian<uint8_t>(uint8_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint8_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToLittleEndian<uint8_t>(uint8_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint16_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToBigEndian<uint16_t>(uint16_t v) {
+  return __builtin_bswap16(v);
+}
+template <>
+template <>
+inline uint16_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToLittleEndian<uint16_t>(uint16_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint32_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToBigEndian<uint32_t>(uint32_t v) {
+  return __builtin_bswap32(v);
+}
+template <>
+template <>
+inline uint32_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToLittleEndian<uint32_t>(uint32_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint64_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToBigEndian<uint64_t>(uint64_t v) {
+  return __builtin_bswap64(v);
+}
+template <>
+template <>
+inline uint64_t
+Endian<__ORDER_LITTLE_ENDIAN__>::ToLittleEndian<uint64_t>(uint64_t v) {
+  return v;
+}
+
+// Big Endian specializations
+template <>
+template <>
+inline uint8_t Endian<__ORDER_BIG_ENDIAN__>::ToBigEndian<uint8_t>(uint8_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint8_t
+Endian<__ORDER_BIG_ENDIAN__>::ToLittleEndian<uint8_t>(uint8_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint16_t
+Endian<__ORDER_BIG_ENDIAN__>::ToBigEndian<uint16_t>(uint16_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint16_t
+Endian<__ORDER_BIG_ENDIAN__>::ToLittleEndian<uint16_t>(uint16_t v) {
+  return __builtin_bswap16(v);
+}
+template <>
+template <>
+inline uint32_t
+Endian<__ORDER_BIG_ENDIAN__>::ToBigEndian<uint32_t>(uint32_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint32_t
+Endian<__ORDER_BIG_ENDIAN__>::ToLittleEndian<uint32_t>(uint32_t v) {
+  return __builtin_bswap32(v);
+}
+template <>
+template <>
+inline uint64_t
+Endian<__ORDER_BIG_ENDIAN__>::ToBigEndian<uint64_t>(uint64_t v) {
+  return v;
+}
+template <>
+template <>
+inline uint64_t
+Endian<__ORDER_BIG_ENDIAN__>::ToLittleEndian<uint64_t>(uint64_t v) {
+  return __builtin_bswap64(v);
+}
+
+} // namespace internal
+
+using Endian = internal::Endian<__BYTE_ORDER__>;
+
+} // namespace __llvm_libc
+
+#endif // LLVM_LIBC_SRC_SUPPORT_ENDIAN_H

libc/test/src/CMakeLists.txt

+add_subdirectory(__support)
 add_subdirectory(ctype)
 add_subdirectory(errno)
 add_subdirectory(fenv)
 add_subdirectory(math)
 add_subdirectory(string)
 
 if(NOT LLVM_LIBC_FULL_BUILD)
   return()

libc/test/src/__support/CMakeLists.txt

+add_libc_testsuite(libc_support_unittests)
+
+add_libc_unittest(
+  endian_test
+  SUITE
+    libc_support_unittests
+  SRCS
+    endian_test.cpp
+  DEPENDS
+    libc.src.__support.common
+)

libc/test/src/__support/endian_test.cpp

+//===-- Unittests for endian ----------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include "src/__support/endian.h"
+#include "utils/UnitTest/Test.h"
+
+namespace __llvm_libc {
+
+struct LlvmLibcEndian : testing::Test {
+  template <typename T> void check(const T original, const T swapped) {
+#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+    EXPECT_EQ(Endian::ToLittleEndian(original), original);
+    EXPECT_EQ(Endian::ToBigEndian(original), swapped);
+#endif
+#if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+    EXPECT_EQ(Endian::ToBigEndian(original), original);
+    EXPECT_EQ(Endian::ToLittleEndian(original), swapped);
+#endif
+  }
+};
+
+TEST_F(LlvmLibcEndian, Field) {
+  EXPECT_EQ(Endian::isLittle, __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__);
+  EXPECT_EQ(Endian::isBig, __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__);
+}
+
+TEST_F(LlvmLibcEndian, uint8_t) {
+  const auto original = uint8_t(0x12);
+  check(original, original);
+}
+
+TEST_F(LlvmLibcEndian, uint16_t) {
+  const auto original = uint16_t(0x1234);
+  const auto swapped = __builtin_bswap16(original);
+  check(original, swapped);
+}
+
+TEST_F(LlvmLibcEndian, uint32_t) {
+  const auto original = uint32_t(0x12345678);
+  const auto swapped = __builtin_bswap32(original);
+  check(original, swapped);
+}
+
+TEST_F(LlvmLibcEndian, uint64_t) {
+  const auto original = uint64_t(0x123456789ABCDEF0);
+  const auto swapped = __builtin_bswap64(original);
+  check(original, swapped);
+}
+
+} // namespace __llvm_libc