Halide
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 
11 #include "Argument.h"
12 #include "ExternalCode.h"
13 #include "IR.h"
14 #include "ModulusRemainder.h"
15 #include "Outputs.h"
16 #include "Target.h"
17 
18 namespace Halide {
19 namespace Internal {
20 
21 /** Definition of an argument to a LoweredFunc. This is similar to
22  * Argument, except it enables passing extra information useful to
23  * some targets to LoweredFunc. */
24 struct LoweredArgument : public Argument {
25  /** For scalar arguments, the modulus and remainder of this
26  * argument. */
28 
30  LoweredArgument(const Argument &arg) : Argument(arg) {}
31  LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions,
32  Expr _def = Expr(),
33  Expr _min = Expr(),
34  Expr _max = Expr()) : Argument(_name, _kind, _type, _dimensions, _def, _min, _max) {}
35 };
36 
37 /** Definition of a lowered function. This object provides a concrete
38  * mapping between parameters used in the function body and their
39  * declarations in the argument list. */
40 struct LoweredFunc {
41  std::string name;
42 
43  /** Arguments referred to in the body of this function. */
44  std::vector<LoweredArgument> args;
45 
46  /** Body of this function. */
48 
49  /** Type of linkage a function can have. */
50  enum LinkageType {
51  External, ///< Visible externally.
52  ExternalPlusMetadata, ///< Visible externally. Argument metadata and an argv wrapper are also generated.
53  Internal, ///< Not visible externally, similar to 'static' linkage in C.
54  };
55 
56  /** The linkage of this function. */
58 
59  /** The name-mangling choice for the function. Defaults to using
60  * the Target. */
62 
63  LoweredFunc(const std::string &name,
64  const std::vector<LoweredArgument> &args,
65  Stmt body,
66  LinkageType linkage,
68  LoweredFunc(const std::string &name,
69  const std::vector<Argument> &args,
70  Stmt body,
71  LinkageType linkage,
73 };
74 
75 }
76 
77 namespace Internal {
78 struct ModuleContents;
79 }
80 
81 /** A halide module. This represents IR containing lowered function
82  * definitions and buffers. */
83 class Module {
85 
86 public:
87  EXPORT Module(const std::string &name, const Target &target);
88 
89  /** Get the target this module has been lowered for. */
90  EXPORT const Target &target() const;
91 
92  /** The name of this module. This is used as the default filename
93  * for output operations. */
94  EXPORT const std::string &name() const;
95 
96  /** If this Module had an auto-generated schedule, this is the C++ source
97  * for that schedule. */
98  EXPORT const std::string &auto_schedule() const;
99 
100  /** The declarations contained in this module. */
101  // @{
102  EXPORT const std::vector<Buffer<>> &buffers() const;
103  EXPORT const std::vector<Internal::LoweredFunc> &functions() const;
104  EXPORT std::vector<Internal::LoweredFunc> &functions();
105  EXPORT const std::vector<Module> &submodules() const;
106  EXPORT const std::vector<ExternalCode> &external_code() const;
107  // @}
108 
109  /** Return the function with the given name. If no such function
110  * exists in this module, assert. */
111  EXPORT Internal::LoweredFunc get_function_by_name(const std::string &name) const;
112 
113  /** Add a declaration to this module. */
114  // @{
115  EXPORT void append(const Buffer<> &buffer);
116  EXPORT void append(const Internal::LoweredFunc &function);
117  EXPORT void append(const Module &module);
118  EXPORT void append(const ExternalCode &external_code);
119  // @}
120 
121  /** Compile a halide Module to variety of outputs, depending on
122  * the fields set in output_files. */
123  EXPORT void compile(const Outputs &output_files) const;
124 
125  /** Compile a halide Module to in-memory object code. Currently
126  * only supports LLVM based compilation, but should be extended to
127  * handle source code backends. */
128  EXPORT Buffer<uint8_t> compile_to_buffer() const;
129 
130  /** Return a new module with all submodules compiled to buffers on
131  * on the result Module. */
132  EXPORT Module resolve_submodules() const;
133 
134  /** When generating metadata from this module, remap any occurrences
135  * of 'from' into 'to'. */
136  EXPORT void remap_metadata_name(const std::string &from, const std::string &to) const;
137 
138  /** Retrieve the metadata name map. */
139  EXPORT std::map<std::string, std::string> get_metadata_name_map() const;
140 
141  /** Set the auto_schedule text for the Module. It is an error to call this
142  * multiple times for a given Module. */
143  EXPORT void set_auto_schedule(const std::string &auto_schedule);
144 };
145 
146 /** Link a set of modules together into one module. */
147 EXPORT Module link_modules(const std::string &name, const std::vector<Module> &modules);
148 
149 /** Create an object file containing the Halide runtime for a given
150  * target. For use with Target::NoRuntime. */
151 EXPORT void compile_standalone_runtime(const std::string &object_filename, Target t);
152 
153 /** Create an object and/or static library file containing the Halide runtime for a given
154  * target. For use with Target::NoRuntime. Return an Outputs with just the actual
155  * outputs filled in (typically, object_name and/or static_library_name).
156  */
157 EXPORT Outputs compile_standalone_runtime(const Outputs &output_files, Target t);
158 
159 typedef std::function<Module(const std::string &, const Target &)> ModuleProducer;
160 
161 EXPORT void compile_multitarget(const std::string &fn_name,
162  const Outputs &output_files,
163  const std::vector<Target> &targets,
164  ModuleProducer module_producer,
165  const std::map<std::string, std::string> &suffixes = {});
166 
167 }
168 
169 #endif
std::vector< LoweredArgument > args
Arguments referred to in the body of this function.
Definition: Module.h:44
A fragment of Halide syntax.
Definition: Expr.h:276
A reference-counted handle to a statement node.
Definition: Expr.h:356
The result of modulus_remainder analysis.
Routines for statically determining what expressions are divisible by.
A struct specifying a collection of outputs.
Definition: Outputs.h:16
A struct representing an argument to a halide-generated function.
Definition: Argument.h:22
A struct representing a target machine and os to generate code for.
Definition: Target.h:21
Visible externally. Argument metadata and an argv wrapper are also generated.
Definition: Module.h:52
std::function< Module(const std::string &, const Target &)> ModuleProducer
Definition: Module.h:159
Stmt body
Body of this function.
Definition: Module.h:47
Defines methods for manipulating and analyzing boolean expressions.
LinkageType linkage
The linkage of this function.
Definition: Module.h:57
NameMangling name_mangling
The name-mangling choice for the function.
Definition: Module.h:61
LoweredArgument(const Argument &arg)
Definition: Module.h:30
unsigned __INT8_TYPE__ uint8_t
Defines the structure that describes a Halide target.
EXPORT Module link_modules(const std::string &name, const std::vector< Module > &modules)
Link a set of modules together into one module.
A halide module.
Definition: Module.h:83
Definition of an argument to a LoweredFunc.
Definition: Module.h:24
Definition of a lowered function.
Definition: Module.h:40
Match whatever is specified in the Target.
EXPORT void compile_standalone_runtime(const std::string &object_filename, Target t)
Create an object file containing the Halide runtime for a given target.
LinkageType
Type of linkage a function can have.
Definition: Module.h:50
Provides output functions to enable writing out various build objects from Halide Module objects...
std::string name
The name of the argument.
Definition: Argument.h:24
Not visible externally, similar to &#39;static&#39; linkage in C.
Definition: Module.h:53
Subtypes for Halide expressions (Halide::Expr) and statements (Halide::Internal::Stmt) ...
Defines a type used for expressing the type signature of a generated halide pipeline.
EXPORT void compile_multitarget(const std::string &fn_name, const Outputs &output_files, const std::vector< Target > &targets, ModuleProducer module_producer, const std::map< std::string, std::string > &suffixes={})
Types in the halide type system.
Definition: Type.h:285
NameMangling
An enum to specify calling convention for extern stages.
Definition: Function.h:54
ModulusRemainder alignment
For scalar arguments, the modulus and remainder of this argument.
Definition: Module.h:27
#define EXPORT
Definition: Util.h:30
Kind
An argument is either a primitive type (for parameters), or a buffer pointer.
Definition: Argument.h:37
LoweredArgument(const std::string &_name, Kind _kind, const Type &_type, uint8_t _dimensions, Expr _def=Expr(), Expr _min=Expr(), Expr _max=Expr())
Definition: Module.h:31