Halide  14.0.0
Halide compiler and libraries
Module.h
Go to the documentation of this file.
1 #ifndef HALIDE_MODULE_H
2 #define HALIDE_MODULE_H
3 
4 /** \file
5  *
6  * Defines Module, an IR container that fully describes a Halide program.
7  */
8 
9 #include <functional>
10 #include <map>
11 #include <memory>
12 #include <string>
13 
14 #include "Argument.h"
15 #include "Expr.h"
16 #include "ExternalCode.h"
17 #include "Function.h" // for NameMangling
18 #include "ModulusRemainder.h"
19 
20 namespace Halide {
21 
22 template<typename T, int Dims>
23 class Buffer;
24 struct Target;
25 
26 /** Enums specifying various kinds of outputs that can be produced from a Halide Pipeline. */
27 enum class OutputFileType {
28  assembly,
29  bitcode,
30  c_header,
31  c_source,
33  cpp_stub,
36  object,
40  schedule,
42  stmt,
43  stmt_html,
44 };
45 
46 class HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output") Output {
47 public:
48  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
49  static constexpr OutputFileType assembly = OutputFileType::assembly;
50  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
51  static constexpr OutputFileType bitcode = OutputFileType::bitcode;
52  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
53  static constexpr OutputFileType c_header = OutputFileType::c_header;
54  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
55  static constexpr OutputFileType c_source = OutputFileType::c_source;
56  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
57  static constexpr OutputFileType compiler_log = OutputFileType::compiler_log;
58  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
59  static constexpr OutputFileType cpp_stub = OutputFileType::cpp_stub;
60  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
61  static constexpr OutputFileType featurization = OutputFileType::featurization;
62  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
63  static constexpr OutputFileType llvm_assembly = OutputFileType::llvm_assembly;
64  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
65  static constexpr OutputFileType object = OutputFileType::object;
66  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
67  static constexpr OutputFileType python_extension = OutputFileType::python_extension;
68  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
69  static constexpr OutputFileType pytorch_wrapper = OutputFileType::pytorch_wrapper;
70  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
71  static constexpr OutputFileType registration = OutputFileType::registration;
72  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
73  static constexpr OutputFileType schedule = OutputFileType::schedule;
74  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
75  static constexpr OutputFileType static_library = OutputFileType::static_library;
76  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
77  static constexpr OutputFileType stmt = OutputFileType::stmt;
78  HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output")
79  static constexpr OutputFileType stmt_html = OutputFileType::stmt_html;
80 }; // namespace Output
81 
82 /** Type of linkage a function in a lowered Halide module can have.
83  Also controls whether auxiliary functions and metadata are generated. */
84 enum class LinkageType {
85  External, ///< Visible externally.
86  ExternalPlusMetadata, ///< Visible externally. Argument metadata and an argv wrapper are also generated.
87  ExternalPlusArgv, ///< Visible externally. Argv wrapper is generated but *not* argument metadata.
88  Internal, ///< Not visible externally, similar to 'static' linkage in C.
89 };
90 
91 namespace Internal {
92 
93 struct OutputInfo {
94  std::string name, extension;
95 
96  // `is_multi` indicates how these outputs are generated
97  // when using the compile_to_multitarget_xxx() APIs (or via the
98  // Generator command-line mode):
99  //
100  // - If `is_multi` is true, then a separate file of this Output type is
101  // generated for each target in the multitarget (e.g. object files,
102  // assembly files, etc). Each of the files will have a suffix appended
103  // that is based on the specific subtarget.
104  //
105  // - If `is_multi` is false, then only one file of this Output type
106  // regardless of how many targets are in the multitarget. No additional
107  // suffix will be appended to the filename.
108  //
109  bool is_multi{false};
110 };
111 std::map<OutputFileType, const OutputInfo> get_output_info(const Target &target);
112 
113 /** Definition of an argument to a LoweredFunc. This is similar to
114  * Argument, except it enables passing extra information useful to
115  * some targets to LoweredFunc. */
116 struct LoweredArgument : public Argument {
117  /** For scalar arguments, the modulus and remainder of this
118  * argument. */
120 
121  LoweredArgument() = default;
122  explicit LoweredArgument(const Argument &arg)
123  : Argument(arg) {
124  }
125  LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions, const ArgumentEstimates &argument_estimates)
126  : Argument(_name, _kind, _type, _dimensions, argument_estimates) {
127  }
128 };
129 
130 /** Definition of a lowered function. This object provides a concrete
131  * mapping between parameters used in the function body and their
132  * declarations in the argument list. */
133 struct LoweredFunc {
134  std::string name;
135 
136  /** Arguments referred to in the body of this function. */
137  std::vector<LoweredArgument> args;
138 
139  /** Body of this function. */
141 
142  /** The linkage of this function. */
144 
145  /** The name-mangling choice for the function. Defaults to using
146  * the Target. */
148 
149  LoweredFunc(const std::string &name,
150  const std::vector<LoweredArgument> &args,
151  Stmt body,
152  LinkageType linkage,
154  LoweredFunc(const std::string &name,
155  const std::vector<Argument> &args,
156  Stmt body,
157  LinkageType linkage,
159 };
160 
161 } // namespace Internal
162 
163 namespace Internal {
164 struct ModuleContents;
165 class CompilerLogger;
166 } // namespace Internal
167 
168 struct AutoSchedulerResults;
169 
170 /** A halide module. This represents IR containing lowered function
171  * definitions and buffers. */
172 class Module {
174 
175 public:
176  Module(const std::string &name, const Target &target);
177 
178  /** Get the target this module has been lowered for. */
179  const Target &target() const;
180 
181  /** The name of this module. This is used as the default filename
182  * for output operations. */
183  const std::string &name() const;
184 
185  /** If this Module had an auto-generated schedule, return a read-only pointer
186  * to the AutoSchedulerResults. If not, return nullptr. */
188 
189  /** Return whether this module uses strict floating-point anywhere. */
190  bool any_strict_float() const;
191 
192  /** The declarations contained in this module. */
193  // @{
194  const std::vector<Buffer<void>> &buffers() const;
195  const std::vector<Internal::LoweredFunc> &functions() const;
196  std::vector<Internal::LoweredFunc> &functions();
197  const std::vector<Module> &submodules() const;
198  const std::vector<ExternalCode> &external_code() const;
199  // @}
200 
201  /** Return the function with the given name. If no such function
202  * exists in this module, assert. */
203  Internal::LoweredFunc get_function_by_name(const std::string &name) const;
204 
205  /** Add a declaration to this module. */
206  // @{
207  void append(const Buffer<void> &buffer);
208  void append(const Internal::LoweredFunc &function);
209  void append(const Module &module);
210  void append(const ExternalCode &external_code);
211  // @}
212 
213  /** Compile a halide Module to variety of outputs, depending on
214  * the fields set in output_files. */
215  void compile(const std::map<OutputFileType, std::string> &output_files) const;
216 
217  /** Compile a halide Module to in-memory object code. Currently
218  * only supports LLVM based compilation, but should be extended to
219  * handle source code backends. */
221 
222  /** Return a new module with all submodules compiled to buffers on
223  * on the result Module. */
225 
226  /** When generating metadata from this module, remap any occurrences
227  * of 'from' into 'to'. */
228  void remap_metadata_name(const std::string &from, const std::string &to) const;
229 
230  /** Retrieve the metadata name map. */
231  std::map<std::string, std::string> get_metadata_name_map() const;
232 
233  /** Set the AutoSchedulerResults for the Module. It is an error to call this
234  * multiple times for a given Module. */
236 
237  /** Set whether this module uses strict floating-point directives anywhere. */
238  void set_any_strict_float(bool any_strict_float);
239 };
240 
241 /** Link a set of modules together into one module. */
242 Module link_modules(const std::string &name, const std::vector<Module> &modules);
243 
244 /** Create an object file containing the Halide runtime for a given target. For
245  * use with Target::NoRuntime. Standalone runtimes are only compatible with
246  * pipelines compiled by the same build of Halide used to call this function. */
247 void compile_standalone_runtime(const std::string &object_filename, const Target &t);
248 
249 /** Create an object and/or static library file containing the Halide runtime
250  * for a given target. For use with Target::NoRuntime. Standalone runtimes are
251  * only compatible with pipelines compiled by the same build of Halide used to
252  * call this function. Return a map with just the actual outputs filled in
253  * (typically, OutputFileType::object and/or OutputFileType::static_library).
254  */
255 std::map<OutputFileType, std::string> compile_standalone_runtime(const std::map<OutputFileType, std::string> &output_files, const Target &t);
256 
257 using ModuleFactory = std::function<Module(const std::string &fn_name, const Target &target)>;
258 using CompilerLoggerFactory = std::function<std::unique_ptr<Internal::CompilerLogger>(const std::string &fn_name, const Target &target)>;
259 
260 void compile_multitarget(const std::string &fn_name,
261  const std::map<OutputFileType, std::string> &output_files,
262  const std::vector<Target> &targets,
263  const std::vector<std::string> &suffixes,
264  const ModuleFactory &module_factory,
265  const CompilerLoggerFactory &compiler_logger_factory = nullptr);
266 
267 } // namespace Halide
268 
269 #endif
Defines a type used for expressing the type signature of a generated halide pipeline.
Base classes for Halide expressions (Halide::Expr) and statements (Halide::Internal::Stmt)
Defines the internal representation of a halide function and related classes.
Routines for statically determining what expressions are divisible by.
A Halide::Buffer is a named shared reference to a Halide::Runtime::Buffer.
Definition: Buffer.h:120
A halide module.
Definition: Module.h:172
std::map< std::string, std::string > get_metadata_name_map() const
Retrieve the metadata name map.
void append(const Buffer< void > &buffer)
Add a declaration to this module.
const AutoSchedulerResults * get_auto_scheduler_results() const
If this Module had an auto-generated schedule, return a read-only pointer to the AutoSchedulerResults...
const std::vector< Internal::LoweredFunc > & functions() const
Module(const std::string &name, const Target &target)
const std::vector< ExternalCode > & external_code() const
const std::vector< Buffer< void > > & buffers() const
The declarations contained in this module.
std::vector< Internal::LoweredFunc > & functions()
Buffer< uint8_t > compile_to_buffer() const
Compile a halide Module to in-memory object code.
void set_auto_scheduler_results(const AutoSchedulerResults &results)
Set the AutoSchedulerResults for the Module.
Module resolve_submodules() const
Return a new module with all submodules compiled to buffers on on the result Module.
void remap_metadata_name(const std::string &from, const std::string &to) const
When generating metadata from this module, remap any occurrences of 'from' into 'to'.
const std::string & name() const
The name of this module.
const std::vector< Module > & submodules() const
const Target & target() const
Get the target this module has been lowered for.
void compile(const std::map< OutputFileType, std::string > &output_files) const
Compile a halide Module to variety of outputs, depending on the fields set in output_files.
Internal::LoweredFunc get_function_by_name(const std::string &name) const
Return the function with the given name.
void append(const ExternalCode &external_code)
void append(const Module &module)
void set_any_strict_float(bool any_strict_float)
Set whether this module uses strict floating-point directives anywhere.
bool any_strict_float() const
Return whether this module uses strict floating-point anywhere.
void append(const Internal::LoweredFunc &function)
std::map< OutputFileType, const OutputInfo > get_output_info(const Target &target)
This file defines the class FunctionDAG, which is our representation of a Halide pipeline,...
LinkageType
Type of linkage a function in a lowered Halide module can have.
Definition: Module.h:84
@ ExternalPlusMetadata
Visible externally. Argument metadata and an argv wrapper are also generated.
@ ExternalPlusArgv
Visible externally. Argv wrapper is generated but not argument metadata.
@ Internal
Not visible externally, similar to 'static' linkage in C.
@ External
Visible externally.
class HALIDE_ATTRIBUTE_DEPRECATED("Use OutputFileType instead of Output") Output
Definition: Module.h:46
std::function< std::unique_ptr< Internal::CompilerLogger >(const std::string &fn_name, const Target &target)> CompilerLoggerFactory
Definition: Module.h:258
OutputFileType
Enums specifying various kinds of outputs that can be produced from a Halide Pipeline.
Definition: Module.h:27
NameMangling
An enum to specify calling convention for extern stages.
Definition: Function.h:24
@ Default
Match whatever is specified in the Target.
void compile_standalone_runtime(const std::string &object_filename, const Target &t)
Create an object file containing the Halide runtime for a given target.
void compile_multitarget(const std::string &fn_name, const std::map< OutputFileType, std::string > &output_files, const std::vector< Target > &targets, const std::vector< std::string > &suffixes, const ModuleFactory &module_factory, const CompilerLoggerFactory &compiler_logger_factory=nullptr)
Module link_modules(const std::string &name, const std::vector< Module > &modules)
Link a set of modules together into one module.
std::function< Module(const std::string &fn_name, const Target &target)> ModuleFactory
Definition: Module.h:257
unsigned __INT8_TYPE__ uint8_t
A struct representing an argument to a halide-generated function.
Definition: Argument.h:37
Kind
An argument is either a primitive type (for parameters), or a buffer pointer.
Definition: Argument.h:52
Definition of an argument to a LoweredFunc.
Definition: Module.h:116
ModulusRemainder alignment
For scalar arguments, the modulus and remainder of this argument.
Definition: Module.h:119
LoweredArgument(const Argument &arg)
Definition: Module.h:122
LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions, const ArgumentEstimates &argument_estimates)
Definition: Module.h:125
Definition of a lowered function.
Definition: Module.h:133
LoweredFunc(const std::string &name, const std::vector< LoweredArgument > &args, Stmt body, LinkageType linkage, NameMangling mangling=NameMangling::Default)
std::vector< LoweredArgument > args
Arguments referred to in the body of this function.
Definition: Module.h:137
LoweredFunc(const std::string &name, const std::vector< Argument > &args, Stmt body, LinkageType linkage, NameMangling mangling=NameMangling::Default)
NameMangling name_mangling
The name-mangling choice for the function.
Definition: Module.h:147
LinkageType linkage
The linkage of this function.
Definition: Module.h:143
Stmt body
Body of this function.
Definition: Module.h:140
The result of modulus_remainder analysis.
A reference-counted handle to a statement node.
Definition: Expr.h:417
A struct representing a target machine and os to generate code for.
Definition: Target.h:19
Types in the halide type system.
Definition: Type.h:266