[XLS][c_api] add the following c-apis

- xls_bits_to_bytes
- xls_bits_to_uint64
- xls_bits_to_int64

Signed-off-by: Hui Peng <[email protected]>

Author: benquike

xls/public/c_api.cc

@@ -16,6 +16,7 @@
 
 #include <string.h>  // NOLINT(modernize-deprecated-headers)
 
+#include <algorithm>
 #include <cstddef>
 #include <cstdint>
 #include <cstdlib>
@@ -454,6 +455,50 @@ bool xls_bits_get_bit(const struct xls_bits* bits, int64_t index) {
   return cpp_bits->Get(index);
 }
 
+bool xls_bits_to_bytes(const struct xls_bits* bits, char** error_out,
+                       uint8_t** bytes_out, size_t* byte_count_out) {
+  CHECK(bits != nullptr);
+  CHECK(bytes_out != nullptr);
+  CHECK(error_out != nullptr);
+  CHECK(byte_count_out != nullptr);
+  const auto* cpp_bits = reinterpret_cast<const xls::Bits*>(bits);
+  auto bytes = cpp_bits->ToBytes();
+  *byte_count_out = bytes.size();
+  *bytes_out = new uint8_t[bytes.size()];
+  std::copy(bytes.begin(), bytes.end(), *bytes_out);
+  return true;
+}
+
+bool xls_bits_to_uint64(const struct xls_bits* bits, char** error_out,
+                        uint64_t* value_out) {
+  CHECK(bits != nullptr);
+  CHECK(value_out != nullptr);
+  CHECK(error_out != nullptr);
+  const auto* cpp_bits = reinterpret_cast<const xls::Bits*>(bits);
+  auto result = cpp_bits->ToUint64();
+  if (!result.ok()) {
+    *error_out = xls::ToOwnedCString(result.status().ToString());
+    return false;
+  }
+  *value_out = result.value();
+  return true;
+}
+
+bool xls_bits_to_int64(const struct xls_bits* bits, char** error_out,
+                       int64_t* value_out) {
+  CHECK(bits != nullptr);
+  CHECK(value_out != nullptr);
+  CHECK(error_out != nullptr);
+  const auto* cpp_bits = reinterpret_cast<const xls::Bits*>(bits);
+  auto result = cpp_bits->ToInt64();
+  if (!result.ok()) {
+    *error_out = xls::ToOwnedCString(result.status().ToString());
+    return false;
+  }
+  *value_out = result.value();
+  return true;
+}
+
 struct xls_bits* xls_bits_width_slice(const struct xls_bits* bits,
                                       int64_t start, int64_t width) {
   CHECK(bits != nullptr);
@@ -704,6 +749,10 @@ void xls_c_strs_free(char** c_strs, size_t count) {
   delete[] c_strs;
 }
 
+void xls_bytes_free(uint8_t *bytes) {
+  delete[] bytes;
+}
+
 bool xls_value_to_string(const struct xls_value* v, char** string_out) {
   CHECK(v != nullptr);
   CHECK(string_out != nullptr);

xls/public/c_api.h

@@ -213,6 +213,23 @@ bool xls_bits_eq(const struct xls_bits* a, const struct xls_bits* b);
 // returns 1, `xls_bits_get_bit(bits, 1)` returns 0.
 bool xls_bits_get_bit(const struct xls_bits* bits, int64_t index);
 
+// Converts the given bits value to a byte array, whose length is saved in
+// byte_count_out. The caller must free the returned `bytes_out` pointer
+// via `xls_bytes_free` if xls_bits_to_bytes returns true.
+// If the conversion fails and it returns false, error_out is populated
+// with an error message and the caller must free the
+// `error_out` pointer with `xls_c_str_free`.
+bool xls_bits_to_bytes(const struct xls_bits* bits, char** error_out,
+                       uint8_t** bytes_out, size_t* byte_count_out);
+
+// Converts the given bits value to a signed or unsigned integer 64-bit integer
+// value. if the conversion is not possible, false is returned, `error_out`
+// contains the error message and the caller must free the `error_out` pointer
+// with `xls_c_str_free`.
+bool xls_bits_to_uint64(const struct xls_bits* bits, char** error_out,
+                        uint64_t* value_out);
+bool xls_bits_to_int64(const struct xls_bits* bits, char** error_out,
+                       int64_t* value_out);
 struct xls_bits* xls_bits_width_slice(const struct xls_bits* bits,
                                       int64_t start, int64_t width);
 
@@ -319,6 +336,11 @@ void xls_c_str_free(char* c_str);
 // Frees an array of C strings that were provided by this XLS public API.
 void xls_c_strs_free(char** c_strs, size_t count);
 
+
+// Frees the given `bytes` -- the bytes should have been allocated by the
+// XLS library where ownership was passed back to the caller.
+void xls_bytes_free(uint8_t* bytes);
+
 // Returns a string representation of the given IR package `p`.
 bool xls_package_to_string(const struct xls_package* p, char** string_out);
 

xls/public/c_api_symbols.txt

@@ -15,8 +15,11 @@ xls_bits_shift_right_arithmetic
 xls_bits_shift_right_logical
 xls_bits_smul
 xls_bits_sub
+xls_bits_to_bytes
 xls_bits_to_debug_string
+xls_bits_to_int64
 xls_bits_to_string
+xls_bits_to_uint64
 xls_bits_umul
 xls_bits_width_slice
 xls_bits_xor
@@ -56,6 +59,7 @@ xls_builder_base_add_xor
 xls_builder_base_add_xor_reduce
 xls_builder_base_add_zero_extend
 xls_bvalue_free
+xls_bytes_free
 xls_c_str_free
 xls_c_strs_free
 xls_convert_dslx_path_to_ir

xls/public/c_api_test.cc

@@ -16,6 +16,7 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <cstdlib>
 #include <filesystem>  // NOLINT
 #include <functional>
 #include <initializer_list>
@@ -435,6 +436,78 @@ TEST(XlsCApiTest, MakeBitsFromUint8DataWithMsbPadding) {
   EXPECT_EQ(xls_bits_get_bit(bits, 5), 1);
 }
 
+TEST(XlsCApiTest, BitsToBytes) {
+  char* error_out = nullptr;
+  xls_bits* bits = nullptr;
+  ASSERT_TRUE(xls_bits_make_ubits(32, 0x0A0B0C0D, &error_out, &bits));
+  uint8_t* bytes = nullptr;
+  size_t byte_count = 0;
+
+  absl::Cleanup free_memory([&error_out, &bits, &bytes] {
+    xls_c_str_free(error_out);
+    xls_bits_free(bits);
+    xls_bytes_free(bytes);
+  });
+
+  ASSERT_TRUE(xls_bits_to_bytes(bits, &error_out, &bytes, &byte_count));
+  EXPECT_EQ(byte_count, 4);
+  EXPECT_EQ(bytes[0], 0x0D);
+  EXPECT_EQ(bytes[1], 0x0C);
+  EXPECT_EQ(bytes[2], 0x0B);
+  EXPECT_EQ(bytes[3], 0x0A);
+}
+
+TEST(XlsCApiTest, BitsToBytesWithPadding) {
+  char* error_out = nullptr;
+  xls_bits* bits = nullptr;
+  ASSERT_TRUE(xls_bits_make_ubits(
+      34, 0b11'0000'0000'0000'0000'0000'0000'0000'0000, &error_out, &bits));
+  uint8_t* bytes = nullptr;
+  size_t byte_count = 0;
+
+  absl::Cleanup free_memory([&error_out, &bits, &bytes] {
+    xls_c_str_free(error_out);
+    xls_bits_free(bits);
+    xls_bytes_free(bytes);
+  });
+
+  ASSERT_TRUE(xls_bits_to_bytes(bits, &error_out, &bytes, &byte_count));
+  EXPECT_EQ(byte_count, 5);
+  EXPECT_EQ(bytes[0], 0x00);
+  EXPECT_EQ(bytes[1], 0x00);
+  EXPECT_EQ(bytes[2], 0x00);
+  EXPECT_EQ(bytes[3], 0x00);
+  EXPECT_EQ(bytes[4], 0b11);
+}
+
+TEST(XlsCApiTest, BitsToUint64Fit) {
+  char* error_out = nullptr;
+  xls_bits* bits = nullptr;
+  ASSERT_TRUE(xls_bits_make_ubits(64, 0x0A0B0C0D, &error_out, &bits));
+  absl::Cleanup free_memory([&error_out, &bits] {
+    xls_c_str_free(error_out);
+    xls_bits_free(bits);
+  });
+
+  uint64_t value = 0;
+  ASSERT_TRUE(xls_bits_to_uint64(bits, &error_out, &value));
+  EXPECT_EQ(value, 0x0A0B0C0D);
+}
+
+TEST(XlsCApiTest, BitsToInt64Fit) {
+  char* error_out = nullptr;
+  xls_bits* bits = nullptr;
+  ASSERT_TRUE(xls_bits_make_ubits(64, 0x0A0B0C0D, &error_out, &bits));
+  absl::Cleanup free_memory([&error_out, &bits] {
+    xls_c_str_free(error_out);
+    xls_bits_free(bits);
+  });
+
+  int64_t value = 0;
+  ASSERT_TRUE(xls_bits_to_int64(bits, &error_out, &value));
+  EXPECT_EQ(value, 0x0A0B0C0D);
+}
+
 TEST(XlsCApiTest, MakeSbitsDoesNotFit) {
   char* error_out = nullptr;
   xls_bits* bits = nullptr;