Halide
12.0.1
Halide compiler and libraries
|
A class representing a Halide pipeline. More...
#include <Pipeline.h>
Classes | |
struct | RealizationArg |
Public Member Functions | |
Pipeline () | |
Make an undefined Pipeline object. More... | |
Pipeline (const Func &output) | |
Make a pipeline that computes the given Func. More... | |
Pipeline (const std::vector< Func > &outputs) | |
Make a pipeline that computes the givens Funcs as outputs. More... | |
std::vector< Argument > | infer_arguments (const Internal::Stmt &body) |
std::vector< Func > | outputs () const |
Get the Funcs this pipeline outputs. More... | |
AutoSchedulerResults | auto_schedule (const Target &target, const MachineParams &arch_params=MachineParams::generic()) |
Generate a schedule for the pipeline using the currently-default autoscheduler. More... | |
AutoSchedulerResults | auto_schedule (const std::string &autoscheduler_name, const Target &target, const MachineParams &arch_params=MachineParams::generic()) |
Generate a schedule for the pipeline using the specified autoscheduler. More... | |
Func | get_func (size_t index) |
Return handle to the index-th Func within the pipeline based on the topological order. More... | |
void | compile_to (const std::map< Output, std::string > &output_files, const std::vector< Argument > &args, const std::string &fn_name, const Target &target) |
Compile and generate multiple target files with single call. More... | |
void | compile_to_bitcode (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Statically compile a pipeline to llvm bitcode, with the given filename (which should probably end in .bc), type signature, and C function name. More... | |
void | compile_to_llvm_assembly (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Statically compile a pipeline to llvm assembly, with the given filename (which should probably end in .ll), type signature, and C function name. More... | |
void | compile_to_object (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Statically compile a pipeline with multiple output functions to an object file, with the given filename (which should probably end in .o or .obj), type signature, and C function name (which defaults to the same name as this halide function. More... | |
void | compile_to_header (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Emit a header file with the given filename for a pipeline. More... | |
void | compile_to_assembly (const std::string &filename, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Statically compile a pipeline to text assembly equivalent to the object file generated by compile_to_object. More... | |
void | compile_to_c (const std::string &filename, const std::vector< Argument > &, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Statically compile a pipeline to C source code. More... | |
void | compile_to_lowered_stmt (const std::string &filename, const std::vector< Argument > &args, StmtOutputFormat fmt=Text, const Target &target=get_target_from_environment()) |
Write out an internal representation of lowered code. More... | |
void | print_loop_nest () |
Write out the loop nests specified by the schedule for this Pipeline's Funcs. More... | |
void | compile_to_file (const std::string &filename_prefix, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Compile to object file and header pair, with the given arguments. More... | |
void | compile_to_static_library (const std::string &filename_prefix, const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment()) |
Compile to static-library file and header pair, with the given arguments. More... | |
void | compile_to_multitarget_static_library (const std::string &filename_prefix, const std::vector< Argument > &args, const std::vector< Target > &targets) |
Compile to static-library file and header pair once for each target; each resulting function will be considered (in order) via halide_can_use_target_features() at runtime, with the first appropriate match being selected for subsequent use. More... | |
void | compile_to_multitarget_object_files (const std::string &filename_prefix, const std::vector< Argument > &args, const std::vector< Target > &targets, const std::vector< std::string > &suffixes) |
Like compile_to_multitarget_static_library(), except that the object files are all output as object files (rather than bundled into a static library). More... | |
Module | compile_to_module (const std::vector< Argument > &args, const std::string &fn_name, const Target &target=get_target_from_environment(), LinkageType linkage_type=LinkageType::ExternalPlusMetadata) |
Create an internal representation of lowered code as a self contained Module suitable for further compilation. More... | |
void | compile_jit (const Target &target=get_jit_target_from_environment()) |
Eagerly jit compile the function to machine code. More... | |
void | set_error_handler (void(*handler)(void *, const char *)) |
Set the error handler function that be called in the case of runtime errors during halide pipelines. More... | |
void | set_custom_allocator (void *(*malloc)(void *, size_t), void(*free)(void *, void *)) |
Set a custom malloc and free for halide to use. More... | |
void | set_custom_do_task (int(*custom_do_task)(void *, int(*)(void *, int, uint8_t *), int, uint8_t *)) |
Set a custom task handler to be called by the parallel for loop. More... | |
void | set_custom_do_par_for (int(*custom_do_par_for)(void *, int(*)(void *, int, uint8_t *), int, int, uint8_t *)) |
Set a custom parallel for loop launcher. More... | |
void | set_custom_trace (int(*trace_fn)(void *, const halide_trace_event_t *)) |
Set custom routines to call when tracing is enabled. More... | |
void | set_custom_print (void(*handler)(void *, const char *)) |
Set the function called to print messages from the runtime. More... | |
void | set_jit_externs (const std::map< std::string, JITExtern > &externs) |
Install a set of external C functions or Funcs to satisfy dependencies introduced by HalideExtern and define_extern mechanisms. More... | |
const std::map< std::string, JITExtern > & | get_jit_externs () |
Return the map of previously installed externs. More... | |
const Internal::JITHandlers & | jit_handlers () |
Get a struct containing the currently set custom functions used by JIT. More... | |
template<typename T > | |
void | add_custom_lowering_pass (T *pass) |
Add a custom pass to be used during lowering. More... | |
void | add_custom_lowering_pass (Internal::IRMutator *pass, std::function< void()> deleter) |
Add a custom pass to be used during lowering, with the function that will be called to delete it also passed in. More... | |
void | clear_custom_lowering_passes () |
Remove all previously-set custom lowering passes. More... | |
const std::vector< CustomLoweringPass > & | custom_lowering_passes () |
Get the custom lowering passes. More... | |
Realization | realize (std::vector< int32_t > sizes={}, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
See Func::realize. More... | |
Realization | realize (int x_size, int y_size, int z_size, int w_size, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
Realization | realize (int x_size, int y_size, int z_size, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
Realization | realize (int x_size, int y_size, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
template<typename T , typename = typename std::enable_if<std::is_same<T, int>::value>::type> | |
HALIDE_ALWAYS_INLINE Realization | realize (T x_size, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
void | realize (RealizationArg output, const Target &target=Target(), const ParamMap ¶m_map=ParamMap::empty_map()) |
Evaluate this Pipeline into an existing allocated buffer or buffers. More... | |
void | infer_input_bounds (const std::vector< int32_t > &sizes, const Target &target=get_jit_target_from_environment(), const ParamMap ¶m_map=ParamMap::empty_map()) |
For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced. More... | |
void | infer_input_bounds (RealizationArg output, const Target &target=get_jit_target_from_environment(), const ParamMap ¶m_map=ParamMap::empty_map()) |
std::vector< Argument > | infer_arguments () |
Infer the arguments to the Pipeline, sorted into a canonical order: all buffers (sorted alphabetically by name), followed by all non-buffers (sorted alphabetically by name). More... | |
bool | defined () const |
Check if this pipeline object is defined. More... | |
void | invalidate_cache () |
Invalidate any internal cached state, e.g. More... | |
void | add_requirement (const Expr &condition, std::vector< Expr > &error) |
Add a top-level precondition to the generated pipeline, expressed as a boolean Expr. More... | |
void | trace_pipeline () |
Generate begin_pipeline and end_pipeline tracing calls for this pipeline. More... | |
template<typename... Args> | |
HALIDE_NO_USER_CODE_INLINE void | add_requirement (const Expr &condition, Args &&...args) |
Static Public Member Functions | |
static void | add_autoscheduler (const std::string &autoscheduler_name, const AutoSchedulerFn &autoscheduler) |
Add a new the autoscheduler method with the given name. More... | |
static void | set_default_autoscheduler_name (const std::string &autoscheduler_name) |
Globally set the default autoscheduler method to use whenever autoscheduling any Pipeline when no name is specified. More... | |
A class representing a Halide pipeline.
Constructed from the Func or Funcs that it outputs.
Definition at line 97 of file Pipeline.h.
Halide::Pipeline::Pipeline | ( | ) |
Make an undefined Pipeline object.
Halide::Pipeline::Pipeline | ( | const Func & | output | ) |
Halide::Pipeline::Pipeline | ( | const std::vector< Func > & | outputs | ) |
Make a pipeline that computes the givens Funcs as outputs.
Schedules the Funcs compute_root().
std::vector<Argument> Halide::Pipeline::infer_arguments | ( | const Internal::Stmt & | body | ) |
std::vector<Func> Halide::Pipeline::outputs | ( | ) | const |
Get the Funcs this pipeline outputs.
AutoSchedulerResults Halide::Pipeline::auto_schedule | ( | const Target & | target, |
const MachineParams & | arch_params = MachineParams::generic() |
||
) |
Generate a schedule for the pipeline using the currently-default autoscheduler.
AutoSchedulerResults Halide::Pipeline::auto_schedule | ( | const std::string & | autoscheduler_name, |
const Target & | target, | ||
const MachineParams & | arch_params = MachineParams::generic() |
||
) |
Generate a schedule for the pipeline using the specified autoscheduler.
|
static |
Add a new the autoscheduler method with the given name.
Does not affect the current default autoscheduler. It is an error to call this with the same name multiple times.
|
static |
Globally set the default autoscheduler method to use whenever autoscheduling any Pipeline when no name is specified.
If the autoscheduler_name isn't in the current table of known autoschedulers, assert-fail.
At this time, well-known autoschedulers include: "Mullapudi2016" – heuristics-based; the first working autoscheduler; currently built in to libHalide see http://graphics.cs.cmu.edu/projects/halidesched/ "Adams2019" – aka "the ML autoscheduler"; currently located in apps/autoscheduler see https://halide-lang.org/papers/autoscheduler2019.html "Li2018" – aka "the gradient autoscheduler"; currently located in apps/gradient_autoscheduler. see https://people.csail.mit.edu/tzumao/gradient_halide
Return handle to the index-th Func within the pipeline based on the topological order.
Referenced by apply_schedule_included_schedule_file(), and do_cost_model_schedule().
void Halide::Pipeline::compile_to | ( | const std::map< Output, std::string > & | output_files, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target | ||
) |
Compile and generate multiple target files with single call.
Deduces target files based on filenames specified in output_files map.
void Halide::Pipeline::compile_to_bitcode | ( | const std::string & | filename, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Statically compile a pipeline to llvm bitcode, with the given filename (which should probably end in .bc), type signature, and C function name.
If you're compiling a pipeline with a single output Func, see also Func::compile_to_bitcode.
void Halide::Pipeline::compile_to_llvm_assembly | ( | const std::string & | filename, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Statically compile a pipeline to llvm assembly, with the given filename (which should probably end in .ll), type signature, and C function name.
If you're compiling a pipeline with a single output Func, see also Func::compile_to_llvm_assembly.
void Halide::Pipeline::compile_to_object | ( | const std::string & | filename, |
const std::vector< Argument > & | , | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Statically compile a pipeline with multiple output functions to an object file, with the given filename (which should probably end in .o or .obj), type signature, and C function name (which defaults to the same name as this halide function.
You probably don't want to use this directly; call compile_to_static_library or compile_to_file instead.
void Halide::Pipeline::compile_to_header | ( | const std::string & | filename, |
const std::vector< Argument > & | , | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Emit a header file with the given filename for a pipeline.
The header will define a function with the type signature given by the second argument, and a name given by the third. You don't actually have to have defined any of these functions yet to call this. You probably don't want to use this directly; call compile_to_static_library or compile_to_file instead.
void Halide::Pipeline::compile_to_assembly | ( | const std::string & | filename, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Statically compile a pipeline to text assembly equivalent to the object file generated by compile_to_object.
This is useful for checking what Halide is producing without having to disassemble anything, or if you need to feed the assembly into some custom toolchain to produce an object file.
void Halide::Pipeline::compile_to_c | ( | const std::string & | filename, |
const std::vector< Argument > & | , | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Statically compile a pipeline to C source code.
This is useful for providing fallback code paths that will compile on many platforms. Vectorization will fail, and parallelization will produce serial code.
void Halide::Pipeline::compile_to_lowered_stmt | ( | const std::string & | filename, |
const std::vector< Argument > & | args, | ||
StmtOutputFormat | fmt = Text , |
||
const Target & | target = get_target_from_environment() |
||
) |
Write out an internal representation of lowered code.
Useful for analyzing and debugging scheduling. Can emit html or plain text.
void Halide::Pipeline::print_loop_nest | ( | ) |
Write out the loop nests specified by the schedule for this Pipeline's Funcs.
Helpful for understanding what a schedule is doing.
void Halide::Pipeline::compile_to_file | ( | const std::string & | filename_prefix, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Compile to object file and header pair, with the given arguments.
void Halide::Pipeline::compile_to_static_library | ( | const std::string & | filename_prefix, |
const std::vector< Argument > & | args, | ||
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() |
||
) |
Compile to static-library file and header pair, with the given arguments.
void Halide::Pipeline::compile_to_multitarget_static_library | ( | const std::string & | filename_prefix, |
const std::vector< Argument > & | args, | ||
const std::vector< Target > & | targets | ||
) |
Compile to static-library file and header pair once for each target; each resulting function will be considered (in order) via halide_can_use_target_features() at runtime, with the first appropriate match being selected for subsequent use.
This is typically useful for specializations that may vary unpredictably by machine (e.g., SSE4.1/AVX/AVX2 on x86 desktop machines). All targets must have identical arch-os-bits.
void Halide::Pipeline::compile_to_multitarget_object_files | ( | const std::string & | filename_prefix, |
const std::vector< Argument > & | args, | ||
const std::vector< Target > & | targets, | ||
const std::vector< std::string > & | suffixes | ||
) |
Like compile_to_multitarget_static_library(), except that the object files are all output as object files (rather than bundled into a static library).
suffixes
is an optional list of strings to use for as the suffix for each object file. If nonempty, it must be the same length as targets
. (If empty, Target::to_string() will be used for each suffix.)
Note that if targets.size()
> 1, the wrapper code (to select the subtarget) will be generated with the filename ${filename_prefix}_wrapper.o
Note that if targets.size()
> 1 and no_runtime
is not specified, the runtime will be generated with the filename ${filename_prefix}_runtime.o
Module Halide::Pipeline::compile_to_module | ( | const std::vector< Argument > & | args, |
const std::string & | fn_name, | ||
const Target & | target = get_target_from_environment() , |
||
LinkageType | linkage_type = LinkageType::ExternalPlusMetadata |
||
) |
Create an internal representation of lowered code as a self contained Module suitable for further compilation.
void Halide::Pipeline::compile_jit | ( | const Target & | target = get_jit_target_from_environment() | ) |
Eagerly jit compile the function to machine code.
This normally happens on the first call to realize. If you're running your halide pipeline inside time-sensitive code and wish to avoid including the time taken to compile a pipeline, then you can call this ahead of time. Default is to use the Target returned from Halide::get_jit_target_from_environment()
void Halide::Pipeline::set_error_handler | ( | void(*)(void *, const char *) | handler | ) |
Set the error handler function that be called in the case of runtime errors during halide pipelines.
If you are compiling statically, you can also just define your own function with signature
This will clobber Halide's version.
void Halide::Pipeline::set_custom_allocator | ( | void *(*)(void *, size_t) | malloc, |
void(*)(void *, void *) | free | ||
) |
Set a custom malloc and free for halide to use.
Malloc should return 32-byte aligned chunks of memory, and it should be safe for Halide to read slightly out of bounds (up to 8 bytes before the start or beyond the end). If compiling statically, routines with appropriate signatures can be provided directly
These will clobber Halide's versions. See HalideRuntime.h for declarations.
void Halide::Pipeline::set_custom_do_task | ( | int(*)(void *, int(*)(void *, int, uint8_t *), int, uint8_t *) | custom_do_task | ) |
Set a custom task handler to be called by the parallel for loop.
It is useful to set this if you want to do some additional bookkeeping at the granularity of parallel tasks. The default implementation does this:
If you are statically compiling, you can also just define your own version of the above function, and it will clobber Halide's version.
If you're trying to use a custom parallel runtime, you probably don't want to call this. See instead Func::set_custom_do_par_for .
void Halide::Pipeline::set_custom_do_par_for | ( | int(*)(void *, int(*)(void *, int, uint8_t *), int, int, uint8_t *) | custom_do_par_for | ) |
Set a custom parallel for loop launcher.
Useful if your app already manages a thread pool. The default implementation is equivalent to this:
However, notwithstanding the above example code, if one task fails, we may skip over other tasks, and if two tasks return different error codes, we may select one arbitrarily to return.
If you are statically compiling, you can also just define your own version of the above function, and it will clobber Halide's version.
void Halide::Pipeline::set_custom_trace | ( | int(*)(void *, const halide_trace_event_t *) | trace_fn | ) |
Set custom routines to call when tracing is enabled.
Call this on the output Func of your pipeline. This then sets custom routines for the entire pipeline, not just calls to this Func.
If you are statically compiling, you can also just define your own versions of the tracing functions (see HalideRuntime.h), and they will clobber Halide's versions.
void Halide::Pipeline::set_custom_print | ( | void(*)(void *, const char *) | handler | ) |
Set the function called to print messages from the runtime.
If you are compiling statically, you can also just define your own function with signature
This will clobber Halide's version.
void Halide::Pipeline::set_jit_externs | ( | const std::map< std::string, JITExtern > & | externs | ) |
Install a set of external C functions or Funcs to satisfy dependencies introduced by HalideExtern and define_extern mechanisms.
These will be used by calls to realize, infer_bounds, and compile_jit.
const std::map<std::string, JITExtern>& Halide::Pipeline::get_jit_externs | ( | ) |
Return the map of previously installed externs.
Is an empty map unless set otherwise.
const Internal::JITHandlers& Halide::Pipeline::jit_handlers | ( | ) |
Get a struct containing the currently set custom functions used by JIT.
|
inline |
Add a custom pass to be used during lowering.
It is run after all other lowering passes. Can be used to verify properties of the lowered Stmt, instrument it with extra code, or otherwise modify it. The Func takes ownership of the pass, and will call delete on it when the Func goes out of scope. So don't pass a stack object, or share pass instances between multiple Funcs.
Definition at line 468 of file Pipeline.h.
void Halide::Pipeline::add_custom_lowering_pass | ( | Internal::IRMutator * | pass, |
std::function< void()> | deleter | ||
) |
Add a custom pass to be used during lowering, with the function that will be called to delete it also passed in.
Set it to nullptr if you wish to retain ownership of the object.
void Halide::Pipeline::clear_custom_lowering_passes | ( | ) |
Remove all previously-set custom lowering passes.
const std::vector<CustomLoweringPass>& Halide::Pipeline::custom_lowering_passes | ( | ) |
Get the custom lowering passes.
Realization Halide::Pipeline::realize | ( | std::vector< int32_t > | sizes = {} , |
const Target & | target = Target() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
See Func::realize.
Referenced by Halide::Internal::GeneratorBase::realize(), and realize().
Realization Halide::Pipeline::realize | ( | int | x_size, |
int | y_size, | ||
int | z_size, | ||
int | w_size, | ||
const Target & | target = Target() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
Realization Halide::Pipeline::realize | ( | int | x_size, |
int | y_size, | ||
int | z_size, | ||
const Target & | target = Target() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
Realization Halide::Pipeline::realize | ( | int | x_size, |
int | y_size, | ||
const Target & | target = Target() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
|
inline |
Definition at line 504 of file Pipeline.h.
References realize().
void Halide::Pipeline::realize | ( | RealizationArg | output, |
const Target & | target = Target() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
Evaluate this Pipeline into an existing allocated buffer or buffers.
If the buffer is also one of the arguments to the function, strange things may happen, as the pipeline isn't necessarily safe to run in-place. The realization should contain one Buffer per tuple component per output Func. For each individual output Func, all Buffers must have the same shape, but the shape can vary across the different output Funcs. This form of realize does not automatically copy data back from the GPU.
void Halide::Pipeline::infer_input_bounds | ( | const std::vector< int32_t > & | sizes, |
const Target & | target = get_jit_target_from_environment() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
For a given size of output, or a given set of output buffers, determine the bounds required of all unbound ImageParams referenced.
Communicates the result by allocating new buffers of the appropriate size and binding them to the unbound ImageParams.
void Halide::Pipeline::infer_input_bounds | ( | RealizationArg | output, |
const Target & | target = get_jit_target_from_environment() , |
||
const ParamMap & | param_map = ParamMap::empty_map() |
||
) |
std::vector<Argument> Halide::Pipeline::infer_arguments | ( | ) |
Infer the arguments to the Pipeline, sorted into a canonical order: all buffers (sorted alphabetically by name), followed by all non-buffers (sorted alphabetically by name).
This lets you write things like:
bool Halide::Pipeline::defined | ( | ) | const |
Check if this pipeline object is defined.
That is, does it have any outputs?
void Halide::Pipeline::invalidate_cache | ( | ) |
Invalidate any internal cached state, e.g.
because Funcs have been rescheduled.
Add a top-level precondition to the generated pipeline, expressed as a boolean Expr.
The Expr may depend on parameters only, and may not call any Func or use a Var. If the condition is not true at runtime, the pipeline will call halide_error with the remaining arguments, and return halide_error_code_requirement_failed. Requirements are checked in the order added.
Referenced by add_requirement(), and Halide::Internal::GeneratorBase::add_requirement().
void Halide::Pipeline::trace_pipeline | ( | ) |
Generate begin_pipeline and end_pipeline tracing calls for this pipeline.
Referenced by Halide::Internal::GeneratorBase::trace_pipeline().
|
inline |
Definition at line 567 of file Pipeline.h.
References add_requirement(), and Halide::Internal::collect_print_args().