1//===-- Parser.h - Parser for LLVM IR text assembly files -------*- 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//  These classes are implemented by the lib/AsmParser library.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_ASMPARSER_PARSER_H
14#define LLVM_ASMPARSER_PARSER_H
15
16#include "llvm/Support/MemoryBuffer.h"
17
18namespace llvm {
19
20class Constant;
21class LLVMContext;
22class Module;
23class ModuleSummaryIndex;
24struct SlotMapping;
25class SMDiagnostic;
26class Type;
27
28/// This function is a main interface to the LLVM Assembly Parser. It parses
29/// an ASCII file that (presumably) contains LLVM Assembly code. It returns a
30/// Module (intermediate representation) with the corresponding features. Note
31/// that this does not verify that the generated Module is valid, so you should
32/// run the verifier after parsing the file to check that it is okay.
33/// Parse LLVM Assembly from a file
34/// \param Filename The name of the file to parse
35/// \param Err Error result info.
36/// \param Context Context in which to allocate globals info.
37/// \param Slots The optional slot mapping that will be initialized during
38///              parsing.
39/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
40///                         This option should only be set to false by llvm-as
41///                         for use inside the LLVM testuite!
42/// \param DataLayoutString Override datalayout in the llvm assembly.
43std::unique_ptr<Module>
44parseAssemblyFile(StringRef Filename, SMDiagnostic &Err, LLVMContext &Context,
45                  SlotMapping *Slots = nullptr, bool UpgradeDebugInfo = true,
46                  StringRef DataLayoutString = "");
47
48/// The function is a secondary interface to the LLVM Assembly Parser. It parses
49/// an ASCII string that (presumably) contains LLVM Assembly code. It returns a
50/// Module (intermediate representation) with the corresponding features. Note
51/// that this does not verify that the generated Module is valid, so you should
52/// run the verifier after parsing the file to check that it is okay.
53/// Parse LLVM Assembly from a string
54/// \param AsmString The string containing assembly
55/// \param Err Error result info.
56/// \param Context Context in which to allocate globals info.
57/// \param Slots The optional slot mapping that will be initialized during
58///              parsing.
59/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
60///                         This option should only be set to false by llvm-as
61///                         for use inside the LLVM testuite!
62/// \param DataLayoutString Override datalayout in the llvm assembly.
63std::unique_ptr<Module> parseAssemblyString(StringRef AsmString,
64                                            SMDiagnostic &Err,
65                                            LLVMContext &Context,
66                                            SlotMapping *Slots = nullptr,
67                                            bool UpgradeDebugInfo = true,
68                                            StringRef DataLayoutString = "");
69
70/// Holds the Module and ModuleSummaryIndex returned by the interfaces
71/// that parse both.
72struct ParsedModuleAndIndex {
73  std::unique_ptr<Module> Mod;
74  std::unique_ptr<ModuleSummaryIndex> Index;
75};
76
77/// This function is a main interface to the LLVM Assembly Parser. It parses
78/// an ASCII file that (presumably) contains LLVM Assembly code, including
79/// a module summary. It returns a Module (intermediate representation) and
80/// a ModuleSummaryIndex with the corresponding features. Note that this does
81/// not verify that the generated Module or Index are valid, so you should
82/// run the verifier after parsing the file to check that they are okay.
83/// Parse LLVM Assembly from a file
84/// \param Filename The name of the file to parse
85/// \param Err Error result info.
86/// \param Context Context in which to allocate globals info.
87/// \param Slots The optional slot mapping that will be initialized during
88///              parsing.
89/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
90///                         This option should only be set to false by llvm-as
91///                         for use inside the LLVM testuite!
92/// \param DataLayoutString Override datalayout in the llvm assembly.
93ParsedModuleAndIndex
94parseAssemblyFileWithIndex(StringRef Filename, SMDiagnostic &Err,
95                           LLVMContext &Context, SlotMapping *Slots = nullptr,
96                           bool UpgradeDebugInfo = true,
97                           StringRef DataLayoutString = "");
98
99/// This function is a main interface to the LLVM Assembly Parser. It parses
100/// an ASCII file that (presumably) contains LLVM Assembly code for a module
101/// summary. It returns a a ModuleSummaryIndex with the corresponding features.
102/// Note that this does not verify that the generated Index is valid, so you
103/// should run the verifier after parsing the file to check that it is okay.
104/// Parse LLVM Assembly Index from a file
105/// \param Filename The name of the file to parse
106/// \param Err Error result info.
107std::unique_ptr<ModuleSummaryIndex>
108parseSummaryIndexAssemblyFile(StringRef Filename, SMDiagnostic &Err);
109
110/// parseAssemblyFile and parseAssemblyString are wrappers around this function.
111/// Parse LLVM Assembly from a MemoryBuffer.
112/// \param F The MemoryBuffer containing assembly
113/// \param Err Error result info.
114/// \param Slots The optional slot mapping that will be initialized during
115///              parsing.
116/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
117///                         This option should only be set to false by llvm-as
118///                         for use inside the LLVM testuite!
119/// \param DataLayoutString Override datalayout in the llvm assembly.
120std::unique_ptr<Module> parseAssembly(MemoryBufferRef F, SMDiagnostic &Err,
121                                      LLVMContext &Context,
122                                      SlotMapping *Slots = nullptr,
123                                      bool UpgradeDebugInfo = true,
124                                      StringRef DataLayoutString = "");
125
126/// Parse LLVM Assembly including the summary index from a MemoryBuffer.
127///
128/// \param F The MemoryBuffer containing assembly with summary
129/// \param Err Error result info.
130/// \param Slots The optional slot mapping that will be initialized during
131///              parsing.
132/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
133///                         This option should only be set to false by llvm-as
134///                         for use inside the LLVM testuite!
135/// \param DataLayoutString Override datalayout in the llvm assembly.
136///
137/// parseAssemblyFileWithIndex is a wrapper around this function.
138ParsedModuleAndIndex parseAssemblyWithIndex(MemoryBufferRef F,
139                                            SMDiagnostic &Err,
140                                            LLVMContext &Context,
141                                            SlotMapping *Slots = nullptr,
142                                            bool UpgradeDebugInfo = true,
143                                            StringRef DataLayoutString = "");
144
145/// Parse LLVM Assembly for summary index from a MemoryBuffer.
146///
147/// \param F The MemoryBuffer containing assembly with summary
148/// \param Err Error result info.
149///
150/// parseSummaryIndexAssemblyFile is a wrapper around this function.
151std::unique_ptr<ModuleSummaryIndex>
152parseSummaryIndexAssembly(MemoryBufferRef F, SMDiagnostic &Err);
153
154/// This function is the low-level interface to the LLVM Assembly Parser.
155/// This is kept as an independent function instead of being inlined into
156/// parseAssembly for the convenience of interactive users that want to add
157/// recently parsed bits to an existing module.
158///
159/// \param F The MemoryBuffer containing assembly
160/// \param M The module to add data to.
161/// \param Index The index to add data to.
162/// \param Err Error result info.
163/// \param Slots The optional slot mapping that will be initialized during
164///              parsing.
165/// \return true on error.
166/// \param UpgradeDebugInfo Run UpgradeDebugInfo, which runs the Verifier.
167///                         This option should only be set to false by llvm-as
168///                         for use inside the LLVM testuite!
169/// \param DataLayoutString Override datalayout in the llvm assembly.
170bool parseAssemblyInto(MemoryBufferRef F, Module *M, ModuleSummaryIndex *Index,
171                       SMDiagnostic &Err, SlotMapping *Slots = nullptr,
172                       bool UpgradeDebugInfo = true,
173                       StringRef DataLayoutString = "");
174
175/// Parse a type and a constant value in the given string.
176///
177/// The constant value can be any LLVM constant, including a constant
178/// expression.
179///
180/// \param Slots The optional slot mapping that will restore the parsing state
181/// of the module.
182/// \return null on error.
183Constant *parseConstantValue(StringRef Asm, SMDiagnostic &Err, const Module &M,
184                             const SlotMapping *Slots = nullptr);
185
186/// Parse a type in the given string.
187///
188/// \param Slots The optional slot mapping that will restore the parsing state
189/// of the module.
190/// \return null on error.
191Type *parseType(StringRef Asm, SMDiagnostic &Err, const Module &M,
192                const SlotMapping *Slots = nullptr);
193
194/// Parse a string \p Asm that starts with a type.
195/// \p Read[out] gives the number of characters that have been read to parse
196/// the type in \p Asm.
197///
198/// \param Slots The optional slot mapping that will restore the parsing state
199/// of the module.
200/// \return null on error.
201Type *parseTypeAtBeginning(StringRef Asm, unsigned &Read, SMDiagnostic &Err,
202                           const Module &M, const SlotMapping *Slots = nullptr);
203
204} // End llvm namespace
205
206#endif
207