Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- llvm/Bitcode/BitcodeConvenience.h - Convenience Wrappers -*- C++ -*-===//

//

// 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

//

//===----------------------------------------------------------------------===//

///

/// \file Convenience wrappers for the LLVM bitcode format and bitstream APIs.

///

/// This allows you to use a sort of DSL to declare and use bitcode

/// abbreviations and records. Example:

///

/// \code

///     using Metadata = BCRecordLayout<

///       METADATA_ID,  // ID

///       BCFixed<16>,  // Module format major version

///       BCFixed<16>,  // Module format minor version

///       BCBlob        // misc. version information

///     >;

///     Metadata metadata(Out);

///     metadata.emit(ScratchRecord, VERSION_MAJOR, VERSION_MINOR, Data);

/// \endcode

///

/// For details on the bitcode format, see

///   http://llvm.org/docs/BitCodeFormat.html

///

//===----------------------------------------------------------------------===//

#ifndef LLVM_BITCODE_BITCODECONVENIENCE_H

#define LLVM_BITCODE_BITCODECONVENIENCE_H

#include "llvm/Bitstream/BitCodes.h"

#include "llvm/Bitstream/BitstreamWriter.h"

#include <cstdint>

#include <optional>

namespace llvm {

namespace detail {

/// Convenience base for all kinds of bitcode abbreviation fields.

///

/// This just defines common properties queried by the metaprogramming.

template <bool Compound = false> class BCField {

public:

  static const bool IsCompound = Compound;

  /// Asserts that the given data is a valid value for this field.

  template <typename T> static void assertValid(const T &data) {}

  /// Converts a raw numeric representation of this value to its preferred

  /// type.

  template <typename T> static T convert(T rawValue) { return rawValue; }

};

} // namespace detail

/// Represents a literal operand in a bitcode record.

///

/// The value of a literal operand is the same for all instances of the record,

/// so it is only emitted in the abbreviation definition.

///

/// Note that because this uses a compile-time template, you cannot have a

/// literal operand that is fixed at run-time without dropping down to the

/// raw LLVM APIs.

template <uint64_t Value> class BCLiteral : public detail::BCField<> {

public:

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(Value));

  }

  template <typename T> static void assertValid(const T &data) {

    assert(data == Value && "data value does not match declared literal value");

  }

};

/// Represents a fixed-width value in a bitcode record.

///

/// Note that the LLVM bitcode format only supports unsigned values.

template <unsigned Width> class BCFixed : public detail::BCField<> {

public:

  static_assert(Width <= 64, "fixed-width field is too large");

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Fixed, Width));

  }

  static void assertValid(const bool &data) {

    assert(llvm::isUInt<Width>(data) &&

           "data value does not fit in the given bit width");

  }

  template <typename T> static void assertValid(const T &data) {

    assert(data >= 0 && "cannot encode signed integers");

    assert(llvm::isUInt<Width>(data) &&

           "data value does not fit in the given bit width");

  }

};

/// Represents a variable-width value in a bitcode record.

///

/// The \p Width parameter should include the continuation bit.

///

/// Note that the LLVM bitcode format only supports unsigned values.

template <unsigned Width> class BCVBR : public detail::BCField<> {

  static_assert(Width >= 2, "width does not have room for continuation bit");

public:

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::VBR, Width));

  }

  template <typename T> static void assertValid(const T &data) {

    assert(data >= 0 && "cannot encode signed integers");

  }

};

/// Represents a character encoded in LLVM's Char6 encoding.

///

/// This format is suitable for encoding decimal numbers (without signs or

/// exponents) and C identifiers (without dollar signs), but not much else.

///

/// \sa http://llvm.org/docs/BitCodeFormat.html#char6-encoded-value

class BCChar6 : public detail::BCField<> {

public:

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Char6));

  }

  template <typename T> static void assertValid(const T &data) {

    assert(llvm::BitCodeAbbrevOp::isChar6(data) && "invalid Char6 data");

  }

  template <typename T> char convert(T rawValue) {

    return static_cast<char>(rawValue);

  }

};

/// Represents an untyped blob of bytes.

///

/// If present, this must be the last field in a record.

class BCBlob : public detail::BCField<true> {

public:

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Blob));

  }

};

/// Represents an array of some other type.

///

/// If present, this must be the last field in a record.

template <typename ElementTy> class BCArray : public detail::BCField<true> {

  static_assert(!ElementTy::IsCompound, "arrays can only contain scalar types");

public:

  static void emitOp(llvm::BitCodeAbbrev &abbrev) {

    abbrev.Add(llvm::BitCodeAbbrevOp(llvm::BitCodeAbbrevOp::Array));

    ElementTy::emitOp(abbrev);

  }

};

namespace detail {

/// Attaches the last field to an abbreviation.

///

/// This is the base case for \c emitOps.

///

/// \sa BCRecordLayout::emitAbbrev

template <typename FieldTy> static void emitOps(llvm::BitCodeAbbrev &abbrev) {

  FieldTy::emitOp(abbrev);

}

/// Attaches fields to an abbreviation.

///

/// This is the recursive case for \c emitOps.

///

/// \sa BCRecordLayout::emitAbbrev

template <typename FieldTy, typename Next, typename... Rest>

static void emitOps(llvm::BitCodeAbbrev &abbrev) {

  static_assert(!FieldTy::IsCompound,

                "arrays and blobs may not appear in the middle of a record");

  FieldTy::emitOp(abbrev);

  emitOps<Next, Rest...>(abbrev);

}

/// Helper class for dealing with a scalar element in the middle of a record.

///

/// \sa BCRecordLayout

template <typename ElementTy, typename... Fields> class BCRecordCoding {

public:

  template <typename BufferTy, typename ElementDataTy, typename... DataTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, ElementDataTy element, DataTy &&...data) {

    static_assert(!ElementTy::IsCompound,

                  "arrays and blobs may not appear in the middle of a record");

    ElementTy::assertValid(element);

    buffer.push_back(element);

    BCRecordCoding<Fields...>::emit(Stream, buffer, code,

                                    std::forward<DataTy>(data)...);

  }

  template <typename T, typename ElementDataTy, typename... DataTy>

  static void read(ArrayRef<T> buffer, ElementDataTy &element,

                   DataTy &&...data) {

    assert(!buffer.empty() && "too few elements in buffer");

    element = ElementTy::convert(buffer.front());

    BCRecordCoding<Fields...>::read(buffer.slice(1),

                                    std::forward<DataTy>(data)...);

  }

  template <typename T, typename... DataTy>

  static void read(ArrayRef<T> buffer, std::nullopt_t, DataTy &&...data) {

    assert(!buffer.empty() && "too few elements in buffer");

    BCRecordCoding<Fields...>::read(buffer.slice(1),

                                    std::forward<DataTy>(data)...);

  }

};

/// Helper class for dealing with a scalar element at the end of a record.

///

/// This has a separate implementation because up until now we've only been

/// \em building the record (into a data buffer), and now we need to hand it

/// off to the BitstreamWriter to be emitted.

///

/// \sa BCRecordLayout

template <typename ElementTy> class BCRecordCoding<ElementTy> {

public:

  template <typename BufferTy, typename DataTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, const DataTy &data) {

    static_assert(!ElementTy::IsCompound,

                  "arrays and blobs need special handling");

    ElementTy::assertValid(data);

    buffer.push_back(data);

    Stream.EmitRecordWithAbbrev(code, buffer);

  }

  template <typename T, typename DataTy>

  static void read(ArrayRef<T> buffer, DataTy &data) {

    assert(buffer.size() == 1 && "record data does not match layout");

    data = ElementTy::convert(buffer.front());

  }

  template <typename T> static void read(ArrayRef<T> buffer, std::nullopt_t) {

    assert(buffer.size() == 1 && "record data does not match layout");

    (void)buffer;

  }

  template <typename T> static void read(ArrayRef<T> buffer) = delete;

};

/// Helper class for dealing with an array at the end of a record.

///

/// \sa BCRecordLayout::emitRecord

template <typename ElementTy> class BCRecordCoding<BCArray<ElementTy>> {

public:

  template <typename BufferTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, StringRef data) {

    // TODO: validate array data.

    Stream.EmitRecordWithArray(code, buffer, data);

  }

  template <typename BufferTy, typename ArrayTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, const ArrayTy &array) {

#ifndef NDEBUG

    for (auto &element : array)

      ElementTy::assertValid(element);

#endif

    buffer.reserve(buffer.size() + std::distance(array.begin(), array.end()));

    std::copy(array.begin(), array.end(), std::back_inserter(buffer));

    Stream.EmitRecordWithAbbrev(code, buffer);

  }

  template <typename BufferTy, typename ElementDataTy, typename... DataTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, ElementDataTy element, DataTy... data) {

    std::array<ElementDataTy, 1 + sizeof...(data)> array{{element, data...}};

    emit(Stream, buffer, code, array);

  }

  template <typename BufferTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &Buffer,

                   unsigned code, std::nullopt_t) {

    Stream.EmitRecordWithAbbrev(code, Buffer);

  }

  template <typename T>

  static void read(ArrayRef<T> Buffer, ArrayRef<T> &rawData) {

    rawData = Buffer;

  }

  template <typename T, typename ArrayTy>

  static void read(ArrayRef<T> buffer, ArrayTy &array) {

    array.append(llvm::map_iterator(buffer.begin(), T::convert),

                 llvm::map_iterator(buffer.end(), T::convert));

  }

  template <typename T> static void read(ArrayRef<T> buffer, std::nullopt_t) {

    (void)buffer;

  }

  template <typename T> static void read(ArrayRef<T> buffer) = delete;

};

/// Helper class for dealing with a blob at the end of a record.

///

/// \sa BCRecordLayout

template <> class BCRecordCoding<BCBlob> {

public:

  template <typename BufferTy>

  static void emit(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                   unsigned code, StringRef data) {

    Stream.EmitRecordWithBlob(code, buffer, data);

  }

  template <typename T> static void read(ArrayRef<T> buffer) { (void)buffer; }

  /// Blob data is not stored in the buffer if you are using the correct

  /// accessor; this method should not be used.

  template <typename T, typename DataTy>

  static void read(ArrayRef<T> buffer, DataTy &data) = delete;

};

/// A type trait whose \c type field is the last of its template parameters.

template <typename Head, typename... Tail> struct last_type {

  using type = typename last_type<Tail...>::type;

};

template <typename Head> struct last_type<Head> { using type = Head; };

/// A type trait whose \c value field is \c true if the last type is BCBlob.

template <typename... Types>

using has_blob = std::is_same<BCBlob, typename last_type<int, Types...>::type>;

/// A type trait whose \c value field is \c true if the given type is a

/// BCArray (of any element kind).

template <typename T> struct is_array {

private:

  template <typename E> static bool check(BCArray<E> *);

  static int check(...);

public:

  typedef bool value_type;

  static constexpr bool value = !std::is_same<decltype(check((T *)nullptr)),

                                              decltype(check(false))>::value;

};

/// A type trait whose \c value field is \c true if the last type is a

/// BCArray (of any element kind).

template <typename... Types>

using has_array = is_array<typename last_type<int, Types...>::type>;

} // namespace detail

/// Represents a single bitcode record type.

///

/// This class template is meant to be instantiated and then given a name,

/// so that from then on that name can be used.

template <typename IDField, typename... Fields> class BCGenericRecordLayout {

  llvm::BitstreamWriter &Stream;

public:

  /// The abbreviation code used for this record in the current block.

  ///

  /// Note that this is not the same as the semantic record code, which is the

  /// first field of the record.

  const unsigned AbbrevCode;

  /// Create a layout and register it with the given bitstream writer.

  explicit BCGenericRecordLayout(llvm::BitstreamWriter &Stream)

      : Stream(Stream), AbbrevCode(emitAbbrev(Stream)) {}

  /// Emit a record to the bitstream writer, using the given buffer for scratch

  /// space.

  ///

  /// Note that even fixed arguments must be specified here.

  template <typename BufferTy, typename... Data>

  void emit(BufferTy &buffer, unsigned id, Data &&...data) const {

    emitRecord(Stream, buffer, AbbrevCode, id, std::forward<Data>(data)...);

  }

  /// Registers this record's layout with the bitstream reader.

  ///

  /// eturns The abbreviation code for the newly-registered record type.

  static unsigned emitAbbrev(llvm::BitstreamWriter &Stream) {

    auto Abbrev = std::make_shared<llvm::BitCodeAbbrev>();

    detail::emitOps<IDField, Fields...>(*Abbrev);

    return Stream.EmitAbbrev(std::move(Abbrev));

  }

  /// Emit a record identified by \p abbrCode to bitstream reader \p Stream,

  /// using \p buffer for scratch space.

  ///

  /// Note that even fixed arguments must be specified here. Blobs are passed

  /// as StringRefs, while arrays can be passed inline, as aggregates, or as

  /// pre-encoded StringRef data. Skipped values and empty arrays should use

  /// the special Nothing value.

  template <typename BufferTy, typename... Data>

  static void emitRecord(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                         unsigned abbrCode, unsigned recordID, Data &&...data) {

    static_assert(sizeof...(data) <= sizeof...(Fields) ||

                      detail::has_array<Fields...>::value,

                  "Too many record elements");

    static_assert(sizeof...(data) >= sizeof...(Fields),

                  "Too few record elements");

    buffer.clear();

    detail::BCRecordCoding<IDField, Fields...>::emit(

        Stream, buffer, abbrCode, recordID, std::forward<Data>(data)...);

  }

  /// Extract record data from \p buffer into the given data fields.

  ///

  /// Note that even fixed arguments must be specified here. Pass \c Nothing

  /// if you don't care about a particular parameter. Blob data is not included

  /// in the buffer and should be handled separately by the caller.

  template <typename ElementTy, typename... Data>

  static void readRecord(ArrayRef<ElementTy> buffer, Data &&...data) {

    static_assert(sizeof...(data) <= sizeof...(Fields),

                  "Too many record elements");

    static_assert(sizeof...(Fields) <=

                      sizeof...(data) + detail::has_blob<Fields...>::value,

                  "Too few record elements");

    return detail::BCRecordCoding<Fields...>::read(buffer,

                                                   std::forward<Data>(data)...);

  }

  /// Extract record data from \p buffer into the given data fields.

  ///

  /// Note that even fixed arguments must be specified here. Pass \c Nothing

  /// if you don't care about a particular parameter. Blob data is not included

  /// in the buffer and should be handled separately by the caller.

  template <typename BufferTy, typename... Data>

  static void readRecord(BufferTy &buffer, Data &&...data) {

    return readRecord(llvm::ArrayRef(buffer), std::forward<Data>(data)...);

  }

};

/// A record with a fixed record code.

template <unsigned RecordCode, typename... Fields>

class BCRecordLayout

    : public BCGenericRecordLayout<BCLiteral<RecordCode>, Fields...> {

  using Base = BCGenericRecordLayout<BCLiteral<RecordCode>, Fields...>;

public:

  enum : unsigned {

    /// The record code associated with this layout.

    Code = RecordCode

  };

  /// Create a layout and register it with the given bitstream writer.

  explicit BCRecordLayout(llvm::BitstreamWriter &Stream) : Base(Stream) {}

  /// Emit a record to the bitstream writer, using the given buffer for scratch

  /// space.

  ///

  /// Note that even fixed arguments must be specified here.

  template <typename BufferTy, typename... Data>

  void emit(BufferTy &buffer, Data &&...data) const {

    Base::emit(buffer, RecordCode, std::forward<Data>(data)...);

  }

  /// Emit a record identified by \p abbrCode to bitstream reader \p Stream,

  /// using \p buffer for scratch space.

  ///

  /// Note that even fixed arguments must be specified here. Currently, arrays

  /// and blobs can only be passed as StringRefs.

  template <typename BufferTy, typename... Data>

  static void emitRecord(llvm::BitstreamWriter &Stream, BufferTy &buffer,

                         unsigned abbrCode, Data &&...data) {

    Base::emitRecord(Stream, buffer, abbrCode, RecordCode,

                     std::forward<Data>(data)...);

  }

};

/// RAII object to pair entering and exiting a sub-block.

class BCBlockRAII {

  llvm::BitstreamWriter &Stream;

public:

  BCBlockRAII(llvm::BitstreamWriter &Stream, unsigned block, unsigned abbrev)

      : Stream(Stream) {

    Stream.EnterSubblock(block, abbrev);

  }

  ~BCBlockRAII() { Stream.ExitBlock(); }

};

} // namespace llvm

#endif