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