LLVM 19.0.0git
BitstreamRemarkSerializer.h
Go to the documentation of this file.
1//===-- BitstreamRemarkSerializer.h - Bitstream serializer ------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file provides an implementation of the serializer using the LLVM
10// Bitstream format.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_REMARKS_BITSTREAMREMARKSERIALIZER_H
15#define LLVM_REMARKS_BITSTREAMREMARKSERIALIZER_H
16
20#include <optional>
21
22namespace llvm {
23namespace remarks {
24
25struct Remarks;
26
27/// Serialize the remarks to LLVM bitstream.
28/// This class provides ways to emit remarks in the LLVM bitstream format and
29/// its associated metadata.
30///
31/// * The separate model:
32/// Separate meta: | Container info
33/// | String table
34/// | External file
35///
36/// Separate remarks: | Container info
37/// | Remark version
38/// | Remark0
39/// | Remark1
40/// | Remark2
41/// | ...
42///
43/// * The standalone model: | Container info
44/// | String table
45/// | Remark version
46/// | Remark0
47/// | Remark1
48/// | Remark2
49/// | ...
50///
52 /// Buffer used for encoding the bitstream before writing it to the final
53 /// stream.
55 /// Buffer used to construct records and pass to the bitstream writer.
57 /// The Bitstream writer.
59 /// The type of the container we are serializing.
61
62 /// Abbrev IDs initialized in the block info block.
63 /// Note: depending on the container type, some IDs might be uninitialized.
64 /// Warning: When adding more abbrev IDs, make sure to update the
65 /// BlockCodeSize (in the call to EnterSubblock).
75
77
78 // Disable copy and move: Bitstream points to Encoded, which needs special
79 // handling during copy/move, but moving the vectors is probably useless
80 // anyway.
82 delete;
88
89 /// Set up the necessary block info entries according to the container type.
90 void setupBlockInfo();
91
92 /// Set up the block info for the metadata block.
93 void setupMetaBlockInfo();
94 /// The remark version in the metadata block.
96 void emitMetaRemarkVersion(uint64_t RemarkVersion);
97 /// The strtab in the metadata block.
98 void setupMetaStrTab();
99 void emitMetaStrTab(const StringTable &StrTab);
100 /// The external file in the metadata block.
102 void emitMetaExternalFile(StringRef Filename);
103
104 /// The block info for the remarks block.
106
107 /// Emit the metadata for the remarks.
108 void emitMetaBlock(uint64_t ContainerVersion,
109 std::optional<uint64_t> RemarkVersion,
110 std::optional<const StringTable *> StrTab = std::nullopt,
111 std::optional<StringRef> Filename = std::nullopt);
112
113 /// Emit a remark block. The string table is required.
114 void emitRemarkBlock(const Remark &Remark, StringTable &StrTab);
115 /// Finalize the writing to \p OS.
117 /// Finalize the writing to a buffer.
118 /// The contents of the buffer remain valid for the lifetime of the object.
119 /// Any call to any other function in this class will invalidate the buffer.
121};
122
123/// Implementation of the remark serializer using LLVM bitstream.
125 /// The file should contain:
126 /// 1) The block info block that describes how to read the blocks.
127 /// 2) The metadata block that contains various information about the remarks
128 /// in the file.
129 /// 3) A number of remark blocks.
130
131 /// We need to set up 1) and 2) first, so that we can emit 3) after. This flag
132 /// is used to emit the first two blocks only once.
133 bool DidSetUp = false;
134 /// The helper to emit bitstream.
136
137 /// Construct a serializer that will create its own string table.
139 /// Construct a serializer with a pre-filled string table.
142
143 /// Emit a remark to the stream. This also emits the metadata associated to
144 /// the remarks based on the SerializerMode specified at construction.
145 /// This writes the serialized output to the provided stream.
146 void emit(const Remark &Remark) override;
147 /// The metadata serializer associated to this remark serializer. Based on the
148 /// container type of the current serializer, the container type of the
149 /// metadata serializer will change.
150 std::unique_ptr<MetaSerializer> metaSerializer(
152 std::optional<StringRef> ExternalFilename = std::nullopt) override;
153
154 static bool classof(const RemarkSerializer *S) {
156 }
157};
158
159/// Serializer of metadata for bitstream remarks.
161 /// This class can be used with [1] a pre-constructed
162 /// BitstreamRemarkSerializerHelper, or with [2] one that is owned by the meta
163 /// serializer. In case of [1], we need to be able to store a reference to the
164 /// object, while in case of [2] we need to store the whole object.
165 std::optional<BitstreamRemarkSerializerHelper> TmpHelper;
166 /// The actual helper, that can point to \p TmpHelper or to an external helper
167 /// object.
169
170 std::optional<const StringTable *> StrTab;
171 std::optional<StringRef> ExternalFilename;
172
173 /// Create a new meta serializer based on \p ContainerType.
176 std::optional<const StringTable *> StrTab = std::nullopt,
177 std::optional<StringRef> ExternalFilename = std::nullopt)
178 : MetaSerializer(OS), TmpHelper(std::nullopt), Helper(nullptr),
180 TmpHelper.emplace(ContainerType);
181 Helper = &*TmpHelper;
182 }
183
184 /// Create a new meta serializer based on a previously built \p Helper.
187 std::optional<const StringTable *> StrTab = std::nullopt,
188 std::optional<StringRef> ExternalFilename = std::nullopt)
189 : MetaSerializer(OS), TmpHelper(std::nullopt), Helper(&Helper),
191
192 void emit() override;
193};
194
195} // end namespace remarks
196} // end namespace llvm
197
198#endif // LLVM_REMARKS_BITSTREAMREMARKSERIALIZER_H
dxil metadata emit
raw_pwrite_stream & OS
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small.
Definition: SmallVector.h:1209
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
This class implements an extremely fast bulk output stream that can only output to a stream.
Definition: raw_ostream.h:52
BitstreamRemarkContainerType
Type of the remark container.
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
Implement std::hash so that hash_code can be used in STL containers.
Definition: BitVector.h:858
Serializer of metadata for bitstream remarks.
BitstreamMetaSerializer(raw_ostream &OS, BitstreamRemarkContainerType ContainerType, std::optional< const StringTable * > StrTab=std::nullopt, std::optional< StringRef > ExternalFilename=std::nullopt)
Create a new meta serializer based on ContainerType.
std::optional< BitstreamRemarkSerializerHelper > TmpHelper
This class can be used with [1] a pre-constructed BitstreamRemarkSerializerHelper,...
BitstreamMetaSerializer(raw_ostream &OS, BitstreamRemarkSerializerHelper &Helper, std::optional< const StringTable * > StrTab=std::nullopt, std::optional< StringRef > ExternalFilename=std::nullopt)
Create a new meta serializer based on a previously built Helper.
std::optional< const StringTable * > StrTab
BitstreamRemarkSerializerHelper * Helper
The actual helper, that can point to TmpHelper or to an external helper object.
Serialize the remarks to LLVM bitstream.
SmallVector< char, 1024 > Encoded
Buffer used for encoding the bitstream before writing it to the final stream.
BitstreamWriter Bitstream
The Bitstream writer.
BitstreamRemarkSerializerHelper(const BitstreamRemarkSerializerHelper &)=delete
void setupMetaBlockInfo()
Set up the block info for the metadata block.
StringRef getBuffer()
Finalize the writing to a buffer.
SmallVector< uint64_t, 64 > R
Buffer used to construct records and pass to the bitstream writer.
BitstreamRemarkContainerType ContainerType
The type of the container we are serializing.
BitstreamRemarkSerializerHelper & operator=(const BitstreamRemarkSerializerHelper &)=delete
void setupRemarkBlockInfo()
The block info for the remarks block.
void emitMetaBlock(uint64_t ContainerVersion, std::optional< uint64_t > RemarkVersion, std::optional< const StringTable * > StrTab=std::nullopt, std::optional< StringRef > Filename=std::nullopt)
Emit the metadata for the remarks.
void setupMetaExternalFile()
The external file in the metadata block.
BitstreamRemarkSerializerHelper(BitstreamRemarkSerializerHelper &&)=delete
void setupBlockInfo()
Set up the necessary block info entries according to the container type.
void setupMetaRemarkVersion()
The remark version in the metadata block.
BitstreamRemarkSerializerHelper & operator=(BitstreamRemarkSerializerHelper &&)=delete
void emitRemarkBlock(const Remark &Remark, StringTable &StrTab)
Emit a remark block. The string table is required.
void setupMetaStrTab()
The strtab in the metadata block.
void flushToStream(raw_ostream &OS)
Finalize the writing to OS.
uint64_t RecordMetaContainerInfoAbbrevID
Abbrev IDs initialized in the block info block.
Implementation of the remark serializer using LLVM bitstream.
bool DidSetUp
The file should contain: 1) The block info block that describes how to read the blocks.
BitstreamRemarkSerializerHelper Helper
The helper to emit bitstream.
static bool classof(const RemarkSerializer *S)
std::unique_ptr< MetaSerializer > metaSerializer(raw_ostream &OS, std::optional< StringRef > ExternalFilename=std::nullopt) override
The metadata serializer associated to this remark serializer.
This is the base class for a remark metadata serializer.
raw_ostream & OS
The open raw_ostream that the metadata is emitted to.
This is the base class for a remark serializer.
Format SerializerFormat
The format of the serializer.
SerializerMode Mode
The serialization mode.
std::optional< StringTable > StrTab
The string table containing all the unique strings used in the output.
raw_ostream & OS
The open raw_ostream that the remark diagnostics are emitted to.
A remark type used for both emission and parsing.
Definition: Remark.h:97
The string table used for serializing remarks.