Halide 16.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 "Function.h" // for NameMangling
17#include "ModulusRemainder.h"
18
19namespace Halide {
20
21template<typename T, int Dims>
22class Buffer;
23struct Target;
24
25/** Enums specifying various kinds of outputs that can be produced from a Halide Pipeline. */
26enum class OutputFileType {
28 bitcode,
36 object,
42 stmt,
44};
45
46/** Type of linkage a function in a lowered Halide module can have.
47 Also controls whether auxiliary functions and metadata are generated. */
48enum class LinkageType {
49 External, ///< Visible externally.
50 ExternalPlusMetadata, ///< Visible externally. Argument metadata and an argv wrapper are also generated.
51 ExternalPlusArgv, ///< Visible externally. Argv wrapper is generated but *not* argument metadata.
52 Internal, ///< Not visible externally, similar to 'static' linkage in C.
53};
54
55namespace Internal {
56
57struct OutputInfo {
58 std::string name, extension;
59
60 // `is_multi` indicates how these outputs are generated
61 // when using the compile_to_multitarget_xxx() APIs (or via the
62 // Generator command-line mode):
63 //
64 // - If `is_multi` is true, then a separate file of this Output type is
65 // generated for each target in the multitarget (e.g. object files,
66 // assembly files, etc). Each of the files will have a suffix appended
67 // that is based on the specific subtarget.
68 //
69 // - If `is_multi` is false, then only one file of this Output type
70 // regardless of how many targets are in the multitarget. No additional
71 // suffix will be appended to the filename.
72 //
73 bool is_multi{false};
74};
75std::map<OutputFileType, const OutputInfo> get_output_info(const Target &target);
76
77/** Definition of an argument to a LoweredFunc. This is similar to
78 * Argument, except it enables passing extra information useful to
79 * some targets to LoweredFunc. */
80struct LoweredArgument : public Argument {
81 /** For scalar arguments, the modulus and remainder of this
82 * argument. */
84
85 LoweredArgument() = default;
86 explicit LoweredArgument(const Argument &arg)
87 : Argument(arg) {
88 }
89 LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions, const ArgumentEstimates &argument_estimates)
90 : Argument(_name, _kind, _type, _dimensions, argument_estimates) {
91 }
92};
93
94/** Definition of a lowered function. This object provides a concrete
95 * mapping between parameters used in the function body and their
96 * declarations in the argument list. */
98 std::string name;
99
100 /** Arguments referred to in the body of this function. */
101 std::vector<LoweredArgument> args;
102
103 /** Body of this function. */
105
106 /** The linkage of this function. */
108
109 /** The name-mangling choice for the function. Defaults to using
110 * the Target. */
112
113 LoweredFunc(const std::string &name,
114 const std::vector<LoweredArgument> &args,
115 Stmt body,
118 LoweredFunc(const std::string &name,
119 const std::vector<Argument> &args,
120 Stmt body,
123};
124
125} // namespace Internal
126
127namespace Internal {
128struct ModuleContents;
129class CompilerLogger;
130} // namespace Internal
131
132struct AutoSchedulerResults;
133
134using MetadataNameMap = std::map<std::string, std::string>;
135
136/** A halide module. This represents IR containing lowered function
137 * definitions and buffers. */
138class Module {
140
141public:
142 Module(const std::string &name, const Target &target, const MetadataNameMap &metadata_name_map = {});
143
144 /** Get the target this module has been lowered for. */
145 const Target &target() const;
146
147 /** The name of this module. This is used as the default filename
148 * for output operations. */
149 const std::string &name() const;
150
151 /** If this Module had an auto-generated schedule, return a read-only pointer
152 * to the AutoSchedulerResults. If not, return nullptr. */
154
155 /** Return whether this module uses strict floating-point anywhere. */
156 bool any_strict_float() const;
157
158 /** The declarations contained in this module. */
159 // @{
160 const std::vector<Buffer<void>> &buffers() const;
161 const std::vector<Internal::LoweredFunc> &functions() const;
162 std::vector<Internal::LoweredFunc> &functions();
163 const std::vector<Module> &submodules() const;
164 // @}
165
166 /** Return the function with the given name. If no such function
167 * exists in this module, assert. */
169
170 /** Add a declaration to this module. */
171 // @{
172 void append(const Buffer<void> &buffer);
173 void append(const Internal::LoweredFunc &function);
174 void append(const Module &module);
175 // @}
176
177 /** Compile a halide Module to variety of outputs, depending on
178 * the fields set in output_files. */
179 void compile(const std::map<OutputFileType, std::string> &output_files) const;
180
181 /** Compile a halide Module to in-memory object code. Currently
182 * only supports LLVM based compilation, but should be extended to
183 * handle source code backends. */
185
186 /** Return a new module with all submodules compiled to buffers on
187 * on the result Module. */
189
190 /** When generating metadata from this module, remap any occurrences
191 * of 'from' into 'to'. */
192 void remap_metadata_name(const std::string &from, const std::string &to) const;
193
194 /** Retrieve the metadata name map. */
196
197 /** Set the AutoSchedulerResults for the Module. It is an error to call this
198 * multiple times for a given Module. */
200
201 /** Set whether this module uses strict floating-point directives anywhere. */
203};
204
205/** Link a set of modules together into one module. */
206Module link_modules(const std::string &name, const std::vector<Module> &modules);
207
208/** Create an object file containing the Halide runtime for a given target. For
209 * use with Target::NoRuntime. Standalone runtimes are only compatible with
210 * pipelines compiled by the same build of Halide used to call this function. */
211void compile_standalone_runtime(const std::string &object_filename, const Target &t);
212
213/** Create an object and/or static library file containing the Halide runtime
214 * for a given target. For use with Target::NoRuntime. Standalone runtimes are
215 * only compatible with pipelines compiled by the same build of Halide used to
216 * call this function. Return a map with just the actual outputs filled in
217 * (typically, OutputFileType::object and/or OutputFileType::static_library).
218 */
219std::map<OutputFileType, std::string> compile_standalone_runtime(const std::map<OutputFileType, std::string> &output_files, const Target &t);
220
221using ModuleFactory = std::function<Module(const std::string &fn_name, const Target &target)>;
222using CompilerLoggerFactory = std::function<std::unique_ptr<Internal::CompilerLogger>(const std::string &fn_name, const Target &target)>;
223
224void compile_multitarget(const std::string &fn_name,
225 const std::map<OutputFileType, std::string> &output_files,
226 const std::vector<Target> &targets,
227 const std::vector<std::string> &suffixes,
228 const ModuleFactory &module_factory,
229 const CompilerLoggerFactory &compiler_logger_factory = nullptr);
230
231} // namespace Halide
232
233#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 module.
Definition: Module.h:138
void append(const Buffer< void > &buffer)
Add a declaration to this module.
MetadataNameMap get_metadata_name_map() const
Retrieve the metadata name map.
const std::string & name() const
The name of this module.
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 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< Buffer< void > > & buffers() const
The declarations contained in this module.
const std::vector< Internal::LoweredFunc > & functions() const
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.
Module(const std::string &name, const Target &target, const MetadataNameMap &metadata_name_map={})
const Target & target() const
Get the target this module has been lowered for.
Internal::LoweredFunc get_function_by_name(const std::string &name) const
Return the function with the given name.
const std::vector< Module > & submodules() const
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::vector< Internal::LoweredFunc > & functions()
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:48
@ 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.
std::map< std::string, std::string > MetadataNameMap
Definition: Module.h:134
std::function< std::unique_ptr< Internal::CompilerLogger >(const std::string &fn_name, const Target &target)> CompilerLoggerFactory
Definition: Module.h:222
OutputFileType
Enums specifying various kinds of outputs that can be produced from a Halide Pipeline.
Definition: Module.h:26
NameMangling
An enum to specify calling convention for extern stages.
Definition: Function.h:25
@ 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:221
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
ArgumentEstimates argument_estimates
Definition: Argument.h:72
Definition of an argument to a LoweredFunc.
Definition: Module.h:80
ModulusRemainder alignment
For scalar arguments, the modulus and remainder of this argument.
Definition: Module.h:83
LoweredArgument(const Argument &arg)
Definition: Module.h:86
LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions, const ArgumentEstimates &argument_estimates)
Definition: Module.h:89
Definition of a lowered function.
Definition: Module.h:97
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:101
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:111
LinkageType linkage
The linkage of this function.
Definition: Module.h:107
Stmt body
Body of this function.
Definition: Module.h:104
The result of modulus_remainder analysis.
A reference-counted handle to a statement node.
Definition: Expr.h:418
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:276