Halide  12.0.1
Halide compiler and libraries
HalideRuntime.h
Go to the documentation of this file.
1 #ifndef HALIDE_HALIDERUNTIME_H
2 #define HALIDE_HALIDERUNTIME_H
3 
4 #ifndef COMPILING_HALIDE_RUNTIME
5 #ifdef __cplusplus
6 #include <cstddef>
7 #include <cstdint>
8 #include <cstring>
9 #else
10 #include <stdbool.h>
11 #include <stddef.h>
12 #include <stdint.h>
13 #include <string.h>
14 #endif
15 #else
16 #include "runtime_internal.h"
17 #endif
18 
19 #ifdef __cplusplus
20 // Forward declare type to allow naming typed handles.
21 // See Type.h for documentation.
22 template<typename T>
24 #endif
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 #ifdef _MSC_VER
31 // Note that (for MSVC) you should not use "inline" along with HALIDE_ALWAYS_INLINE;
32 // it is not necessary, and may produce warnings for some build configurations.
33 #define HALIDE_ALWAYS_INLINE __forceinline
34 #define HALIDE_NEVER_INLINE __declspec(noinline)
35 #else
36 // Note that (for Posixy compilers) you should always use "inline" along with HALIDE_ALWAYS_INLINE;
37 // otherwise some corner-case scenarios may erroneously report link errors.
38 #define HALIDE_ALWAYS_INLINE inline __attribute__((always_inline))
39 #define HALIDE_NEVER_INLINE __attribute__((noinline))
40 #endif
41 
42 #ifndef HALIDE_MUST_USE_RESULT
43 #ifdef __has_attribute
44 #if __has_attribute(nodiscard)
45 // C++17 or later
46 #define HALIDE_MUST_USE_RESULT [[nodiscard]]
47 #elif __has_attribute(warn_unused_result)
48 // Clang/GCC
49 #define HALIDE_MUST_USE_RESULT __attribute__((warn_unused_result))
50 #else
51 #define HALIDE_MUST_USE_RESULT
52 #endif
53 #else
54 #define HALIDE_MUST_USE_RESULT
55 #endif
56 #endif
57 
58 /** \file
59  *
60  * This file declares the routines used by Halide internally in its
61  * runtime. On platforms that support weak linking, these can be
62  * replaced with user-defined versions by defining an extern "C"
63  * function with the same name and signature.
64  *
65  * When doing Just In Time (JIT) compilation methods on the Func being
66  * compiled must be called instead. The corresponding methods are
67  * documented below.
68  *
69  * All of these functions take a "void *user_context" parameter as their
70  * first argument; if the Halide kernel that calls back to any of these
71  * functions has been compiled with the UserContext feature set on its Target,
72  * then the value of that pointer passed from the code that calls the
73  * Halide kernel is piped through to the function.
74  *
75  * Some of these are also useful to call when using the default
76  * implementation. E.g. halide_shutdown_thread_pool.
77  *
78  * Note that even on platforms with weak linking, some linker setups
79  * may not respect the override you provide. E.g. if the override is
80  * in a shared library and the halide object files are linked directly
81  * into the output, the builtin versions of the runtime functions will
82  * be called. See your linker documentation for more details. On
83  * Linux, LD_DYNAMIC_WEAK=1 may help.
84  *
85  */
86 
87 // Forward-declare to suppress warnings if compiling as C.
88 struct halide_buffer_t;
89 
90 /** Print a message to stderr. Main use is to support tracing
91  * functionality, print, and print_when calls. Also called by the default
92  * halide_error. This function can be replaced in JITed code by using
93  * halide_custom_print and providing an implementation of halide_print
94  * in AOT code. See Func::set_custom_print.
95  */
96 // @{
97 extern void halide_print(void *user_context, const char *);
98 extern void halide_default_print(void *user_context, const char *);
99 typedef void (*halide_print_t)(void *, const char *);
101 // @}
102 
103 /** Halide calls this function on runtime errors (for example bounds
104  * checking failures). This function can be replaced in JITed code by
105  * using Func::set_error_handler, or in AOT code by calling
106  * halide_set_error_handler. In AOT code on platforms that support
107  * weak linking (i.e. not Windows), you can also override it by simply
108  * defining your own halide_error.
109  */
110 // @{
111 extern void halide_error(void *user_context, const char *);
112 extern void halide_default_error(void *user_context, const char *);
113 typedef void (*halide_error_handler_t)(void *, const char *);
115 // @}
116 
117 /** Cross-platform mutex. Must be initialized with zero and implementation
118  * must treat zero as an unlocked mutex with no waiters, etc.
119  */
120 struct halide_mutex {
121  uintptr_t _private[1];
122 };
123 
124 /** Cross platform condition variable. Must be initialized to 0. */
125 struct halide_cond {
126  uintptr_t _private[1];
127 };
128 
129 /** A basic set of mutex and condition variable functions, which call
130  * platform specific code for mutual exclusion. Equivalent to posix
131  * calls. */
132 //@{
133 extern void halide_mutex_lock(struct halide_mutex *mutex);
134 extern void halide_mutex_unlock(struct halide_mutex *mutex);
135 extern void halide_cond_signal(struct halide_cond *cond);
136 extern void halide_cond_broadcast(struct halide_cond *cond);
137 extern void halide_cond_wait(struct halide_cond *cond, struct halide_mutex *mutex);
138 //@}
139 
140 /** Functions for constructing/destroying/locking/unlocking arrays of mutexes. */
141 struct halide_mutex_array;
142 //@{
143 extern struct halide_mutex_array *halide_mutex_array_create(int sz);
144 extern void halide_mutex_array_destroy(void *user_context, void *array);
145 extern int halide_mutex_array_lock(struct halide_mutex_array *array, int entry);
146 extern int halide_mutex_array_unlock(struct halide_mutex_array *array, int entry);
147 //@}
148 
149 /** Define halide_do_par_for to replace the default thread pool
150  * implementation. halide_shutdown_thread_pool can also be called to
151  * release resources used by the default thread pool on platforms
152  * where it makes sense. See Func::set_custom_do_task and
153  * Func::set_custom_do_par_for. Should return zero if all the jobs
154  * return zero, or an arbitrarily chosen return value from one of the
155  * jobs otherwise.
156  */
157 //@{
158 typedef int (*halide_task_t)(void *user_context, int task_number, uint8_t *closure);
159 extern int halide_do_par_for(void *user_context,
160  halide_task_t task,
161  int min, int size, uint8_t *closure);
162 extern void halide_shutdown_thread_pool();
163 //@}
164 
165 /** Set a custom method for performing a parallel for loop. Returns
166  * the old do_par_for handler. */
167 typedef int (*halide_do_par_for_t)(void *, halide_task_t, int, int, uint8_t *);
169 
170 /** An opaque struct representing a semaphore. Used by the task system for async tasks. */
173 };
174 
175 /** A struct representing a semaphore and a number of items that must
176  * be acquired from it. Used in halide_parallel_task_t below. */
179  int count;
180 };
181 extern int halide_semaphore_init(struct halide_semaphore_t *, int n);
182 extern int halide_semaphore_release(struct halide_semaphore_t *, int n);
183 extern bool halide_semaphore_try_acquire(struct halide_semaphore_t *, int n);
184 typedef int (*halide_semaphore_init_t)(struct halide_semaphore_t *, int);
185 typedef int (*halide_semaphore_release_t)(struct halide_semaphore_t *, int);
186 typedef bool (*halide_semaphore_try_acquire_t)(struct halide_semaphore_t *, int);
187 
188 /** A task representing a serial for loop evaluated over some range.
189  * Note that task_parent is a pass through argument that should be
190  * passed to any dependent taks that are invoked using halide_do_parallel_tasks
191  * underneath this call. */
192 typedef int (*halide_loop_task_t)(void *user_context, int min, int extent,
193  uint8_t *closure, void *task_parent);
194 
195 /** A parallel task to be passed to halide_do_parallel_tasks. This
196  * task may recursively call halide_do_parallel_tasks, and there may
197  * be complex dependencies between seemingly unrelated tasks expressed
198  * using semaphores. If you are using a custom task system, care must
199  * be taken to avoid potential deadlock. This can be done by carefully
200  * respecting the static metadata at the end of the task struct.*/
202  // The function to call. It takes a user context, a min and
203  // extent, a closure, and a task system pass through argument.
205 
206  // The closure to pass it
208 
209  // The name of the function to be called. For debugging purposes only.
210  const char *name;
211 
212  // An array of semaphores that must be acquired before the
213  // function is called. Must be reacquired for every call made.
216 
217  // The entire range the function should be called over. This range
218  // may be sliced up and the function called multiple times.
219  int min, extent;
220 
221  // A parallel task provides several pieces of metadata to prevent
222  // unbounded resource usage or deadlock.
223 
224  // The first is the minimum number of execution contexts (call
225  // stacks or threads) necessary for the function to run to
226  // completion. This may be greater than one when there is nested
227  // parallelism with internal producer-consumer relationships
228  // (calling the function recursively spawns and blocks on parallel
229  // sub-tasks that communicate with each other via semaphores). If
230  // a parallel runtime calls the function when fewer than this many
231  // threads are idle, it may need to create more threads to
232  // complete the task, or else risk deadlock due to committing all
233  // threads to tasks that cannot complete without more.
234  //
235  // FIXME: Note that extern stages are assumed to only require a
236  // single thread to complete. If the extern stage is itself a
237  // Halide pipeline, this may be an underestimate.
239 
240  // The calls to the function should be in serial order from min to min+extent-1, with only
241  // one executing at a time. If false, any order is fine, and
242  // concurrency is fine.
243  bool serial;
244 };
245 
246 /** Enqueue some number of the tasks described above and wait for them
247  * to complete. While waiting, the calling threads assists with either
248  * the tasks enqueued, or other non-blocking tasks in the task
249  * system. Note that task_parent should be NULL for top-level calls
250  * and the pass through argument if this call is being made from
251  * another task. */
252 extern int halide_do_parallel_tasks(void *user_context, int num_tasks,
253  struct halide_parallel_task_t *tasks,
254  void *task_parent);
255 
256 /** If you use the default do_par_for, you can still set a custom
257  * handler to perform each individual task. Returns the old handler. */
258 //@{
259 typedef int (*halide_do_task_t)(void *, halide_task_t, int, uint8_t *);
261 extern int halide_do_task(void *user_context, halide_task_t f, int idx,
262  uint8_t *closure);
263 //@}
264 
265 /** The version of do_task called for loop tasks. By default calls the
266  * loop task with the same arguments. */
267 // @{
268 typedef int (*halide_do_loop_task_t)(void *, halide_loop_task_t, int, int, uint8_t *, void *);
270 extern int halide_do_loop_task(void *user_context, halide_loop_task_t f, int min, int extent,
271  uint8_t *closure, void *task_parent);
272 //@}
273 
274 /** Provide an entire custom tasking runtime via function
275  * pointers. Note that do_task and semaphore_try_acquire are only ever
276  * called by halide_default_do_par_for and
277  * halide_default_do_parallel_tasks, so it's only necessary to provide
278  * those if you are mixing in the default implementations of
279  * do_par_for and do_parallel_tasks. */
280 // @{
281 typedef int (*halide_do_parallel_tasks_t)(void *, int, struct halide_parallel_task_t *,
282  void *task_parent);
291 // @}
292 
293 /** The default versions of the parallel runtime functions. */
294 // @{
295 extern int halide_default_do_par_for(void *user_context,
296  halide_task_t task,
297  int min, int size, uint8_t *closure);
299  int num_tasks,
300  struct halide_parallel_task_t *tasks,
301  void *task_parent);
302 extern int halide_default_do_task(void *user_context, halide_task_t f, int idx,
303  uint8_t *closure);
305  int min, int extent,
306  uint8_t *closure, void *task_parent);
307 extern int halide_default_semaphore_init(struct halide_semaphore_t *, int n);
308 extern int halide_default_semaphore_release(struct halide_semaphore_t *, int n);
309 extern bool halide_default_semaphore_try_acquire(struct halide_semaphore_t *, int n);
310 // @}
311 
312 struct halide_thread;
313 
314 /** Spawn a thread. Returns a handle to the thread for the purposes of
315  * joining it. The thread must be joined in order to clean up any
316  * resources associated with it. */
317 extern struct halide_thread *halide_spawn_thread(void (*f)(void *), void *closure);
318 
319 /** Join a thread. */
320 extern void halide_join_thread(struct halide_thread *);
321 
322 /** Set the number of threads used by Halide's thread pool. Returns
323  * the old number.
324  *
325  * n < 0 : error condition
326  * n == 0 : use a reasonable system default (typically, number of cpus online).
327  * n == 1 : use exactly one thread; this will always enforce serial execution
328  * n > 1 : use a pool of exactly n threads.
329  *
330  * (Note that this is only guaranteed when using the default implementations
331  * of halide_do_par_for(); custom implementations may completely ignore values
332  * passed to halide_set_num_threads().)
333  */
334 extern int halide_set_num_threads(int n);
335 
336 /** Halide calls these functions to allocate and free memory. To
337  * replace in AOT code, use the halide_set_custom_malloc and
338  * halide_set_custom_free, or (on platforms that support weak
339  * linking), simply define these functions yourself. In JIT-compiled
340  * code use Func::set_custom_allocator.
341  *
342  * If you override them, and find yourself wanting to call the default
343  * implementation from within your override, use
344  * halide_default_malloc/free.
345  *
346  * Note that halide_malloc must return a pointer aligned to the
347  * maximum meaningful alignment for the platform for the purpose of
348  * vector loads and stores. The default implementation uses 32-byte
349  * alignment, which is safe for arm and x86. Additionally, it must be
350  * safe to read at least 8 bytes before the start and beyond the
351  * end.
352  */
353 //@{
354 extern void *halide_malloc(void *user_context, size_t x);
355 extern void halide_free(void *user_context, void *ptr);
356 extern void *halide_default_malloc(void *user_context, size_t x);
357 extern void halide_default_free(void *user_context, void *ptr);
358 typedef void *(*halide_malloc_t)(void *, size_t);
359 typedef void (*halide_free_t)(void *, void *);
362 //@}
363 
364 /** Halide calls these functions to interact with the underlying
365  * system runtime functions. To replace in AOT code on platforms that
366  * support weak linking, define these functions yourself, or use
367  * the halide_set_custom_load_library() and halide_set_custom_get_library_symbol()
368  * functions. In JIT-compiled code, use JITSharedRuntime::set_default_handlers().
369  *
370  * halide_load_library and halide_get_library_symbol are equivalent to
371  * dlopen and dlsym. halide_get_symbol(sym) is equivalent to
372  * dlsym(RTLD_DEFAULT, sym).
373  */
374 //@{
375 extern void *halide_get_symbol(const char *name);
376 extern void *halide_load_library(const char *name);
377 extern void *halide_get_library_symbol(void *lib, const char *name);
378 extern void *halide_default_get_symbol(const char *name);
379 extern void *halide_default_load_library(const char *name);
380 extern void *halide_default_get_library_symbol(void *lib, const char *name);
381 typedef void *(*halide_get_symbol_t)(const char *name);
382 typedef void *(*halide_load_library_t)(const char *name);
383 typedef void *(*halide_get_library_symbol_t)(void *lib, const char *name);
387 //@}
388 
389 /** Called when debug_to_file is used inside %Halide code. See
390  * Func::debug_to_file for how this is called
391  *
392  * Cannot be replaced in JITted code at present.
393  */
394 extern int32_t halide_debug_to_file(void *user_context, const char *filename,
395  int32_t type_code,
396  struct halide_buffer_t *buf);
397 
398 /** Types in the halide type system. They can be ints, unsigned ints,
399  * or floats (of various bit-widths), or a handle (which is always 64-bits).
400  * Note that the int/uint/float values do not imply a specific bit width
401  * (the bit width is expected to be encoded in a separate value).
402  */
403 typedef enum halide_type_code_t
404 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
405  : uint8_t
406 #endif
407 {
408  halide_type_int = 0, ///< signed integers
409  halide_type_uint = 1, ///< unsigned integers
410  halide_type_float = 2, ///< IEEE floating point numbers
411  halide_type_handle = 3, ///< opaque pointer type (void *)
412  halide_type_bfloat = 4, ///< floating point numbers in the bfloat format
414 
415 // Note that while __attribute__ can go before or after the declaration,
416 // __declspec apparently is only allowed before.
417 #ifndef HALIDE_ATTRIBUTE_ALIGN
418 #ifdef _MSC_VER
419 #define HALIDE_ATTRIBUTE_ALIGN(x) __declspec(align(x))
420 #else
421 #define HALIDE_ATTRIBUTE_ALIGN(x) __attribute__((aligned(x)))
422 #endif
423 #endif
424 
425 /** A runtime tag for a type in the halide type system. Can be ints,
426  * unsigned ints, or floats of various bit-widths (the 'bits'
427  * field). Can also be vectors of the same (by setting the 'lanes'
428  * field to something larger than one). This struct should be
429  * exactly 32-bits in size. */
431  /** The basic type code: signed integer, unsigned integer, or floating point. */
432 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
434  halide_type_code_t code; // halide_type_code_t
435 #else
437  uint8_t code; // halide_type_code_t
438 #endif
439 
440  /** The number of bits of precision of a single scalar value of this type. */
443 
444  /** How many elements in a vector. This is 1 for scalar types. */
447 
448 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
449  /** Construct a runtime representation of a Halide type from:
450  * code: The fundamental type from an enum.
451  * bits: The bit size of one element.
452  * lanes: The number of vector elements in the type. */
454  : code(code), bits(bits), lanes(lanes) {
455  }
456 
457  /** Default constructor is required e.g. to declare halide_trace_event
458  * instances. */
460  : code((halide_type_code_t)0), bits(0), lanes(0) {
461  }
462 
464  return halide_type_t((halide_type_code_t)code, bits, new_lanes);
465  }
466 
467  /** Compare two types for equality. */
468  HALIDE_ALWAYS_INLINE bool operator==(const halide_type_t &other) const {
469  return as_u32() == other.as_u32();
470  }
471 
472  HALIDE_ALWAYS_INLINE bool operator!=(const halide_type_t &other) const {
473  return !(*this == other);
474  }
475 
476  HALIDE_ALWAYS_INLINE bool operator<(const halide_type_t &other) const {
477  return as_u32() < other.as_u32();
478  }
479 
480  /** Size in bytes for a single element, even if width is not 1, of this type. */
481  HALIDE_ALWAYS_INLINE int bytes() const {
482  return (bits + 7) / 8;
483  }
484 
485  HALIDE_ALWAYS_INLINE uint32_t as_u32() const {
486  uint32_t u;
487  memcpy(&u, this, sizeof(u));
488  return u;
489  }
490 #endif
491 };
492 
504 
506  /** The name of the Func or Pipeline that this event refers to */
507  const char *func;
508 
509  /** If the event type is a load or a store, this points to the
510  * value being loaded or stored. Use the type field to safely cast
511  * this to a concrete pointer type and retrieve it. For other
512  * events this is null. */
513  void *value;
514 
515  /** For loads and stores, an array which contains the location
516  * being accessed. For vector loads or stores it is an array of
517  * vectors of coordinates (the vector dimension is innermost).
518  *
519  * For realization or production-related events, this will contain
520  * the mins and extents of the region being accessed, in the order
521  * min0, extent0, min1, extent1, ...
522  *
523  * For pipeline-related events, this will be null.
524  */
526 
527  /** For halide_trace_tag, this points to a read-only null-terminated string
528  * of arbitrary text. For all other events, this will be null.
529  */
530  const char *trace_tag;
531 
532  /** If the event type is a load or a store, this is the type of
533  * the data. Otherwise, the value is meaningless. */
534  struct halide_type_t type;
535 
536  /** The type of event */
538 
539  /* The ID of the parent event (see below for an explanation of
540  * event ancestry). */
542 
543  /** If this was a load or store of a Tuple-valued Func, this is
544  * which tuple element was accessed. */
546 
547  /** The length of the coordinates array */
549 
550 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
551  // If we don't explicitly mark the default ctor as inline,
552  // certain build configurations can fail (notably iOS)
554 #endif
555 };
556 
557 /** Called when Funcs are marked as trace_load, trace_store, or
558  * trace_realization. See Func::set_custom_trace. The default
559  * implementation either prints events via halide_print, or if
560  * HL_TRACE_FILE is defined, dumps the trace to that file in a
561  * sequence of trace packets. The header for a trace packet is defined
562  * below. If the trace is going to be large, you may want to make the
563  * file a named pipe, and then read from that pipe into gzip.
564  *
565  * halide_trace returns a unique ID which will be passed to future
566  * events that "belong" to the earlier event as the parent id. The
567  * ownership hierarchy looks like:
568  *
569  * begin_pipeline
570  * +--trace_tag (if any)
571  * +--trace_tag (if any)
572  * ...
573  * +--begin_realization
574  * | +--produce
575  * | | +--load/store
576  * | | +--end_produce
577  * | +--consume
578  * | | +--load
579  * | | +--end_consume
580  * | +--end_realization
581  * +--end_pipeline
582  *
583  * Threading means that ownership cannot be inferred from the ordering
584  * of events. There can be many active realizations of a given
585  * function, or many active productions for a single
586  * realization. Within a single production, the ordering of events is
587  * meaningful.
588  *
589  * Note that all trace_tag events (if any) will occur just after the begin_pipeline
590  * event, but before any begin_realization events. All trace_tags for a given Func
591  * will be emitted in the order added.
592  */
593 // @}
594 extern int32_t halide_trace(void *user_context, const struct halide_trace_event_t *event);
596 typedef int32_t (*halide_trace_t)(void *user_context, const struct halide_trace_event_t *);
598 // @}
599 
600 /** The header of a packet in a binary trace. All fields are 32-bit. */
602  /** The total size of this packet in bytes. Always a multiple of
603  * four. Equivalently, the number of bytes until the next
604  * packet. */
606 
607  /** The id of this packet (for the purpose of parent_id). */
609 
610  /** The remaining fields are equivalent to those in halide_trace_event_t */
611  // @{
612  struct halide_type_t type;
617  // @}
618 
619 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
620  // If we don't explicitly mark the default ctor as inline,
621  // certain build configurations can fail (notably iOS)
623 
624  /** Get the coordinates array, assuming this packet is laid out in
625  * memory as it was written. The coordinates array comes
626  * immediately after the packet header. */
627  HALIDE_ALWAYS_INLINE const int *coordinates() const {
628  return (const int *)(this + 1);
629  }
630 
631  HALIDE_ALWAYS_INLINE int *coordinates() {
632  return (int *)(this + 1);
633  }
634 
635  /** Get the value, assuming this packet is laid out in memory as
636  * it was written. The packet comes immediately after the coordinates
637  * array. */
638  HALIDE_ALWAYS_INLINE const void *value() const {
639  return (const void *)(coordinates() + dimensions);
640  }
641 
642  HALIDE_ALWAYS_INLINE void *value() {
643  return (void *)(coordinates() + dimensions);
644  }
645 
646  /** Get the func name, assuming this packet is laid out in memory
647  * as it was written. It comes after the value. */
648  HALIDE_ALWAYS_INLINE const char *func() const {
649  return (const char *)value() + type.lanes * type.bytes();
650  }
651 
652  HALIDE_ALWAYS_INLINE char *func() {
653  return (char *)value() + type.lanes * type.bytes();
654  }
655 
656  /** Get the trace_tag (if any), assuming this packet is laid out in memory
657  * as it was written. It comes after the func name. If there is no trace_tag,
658  * this will return a pointer to an empty string. */
659  HALIDE_ALWAYS_INLINE const char *trace_tag() const {
660  const char *f = func();
661  // strlen may not be available here
662  while (*f++) {
663  // nothing
664  }
665  return f;
666  }
667 
668  HALIDE_ALWAYS_INLINE char *trace_tag() {
669  char *f = func();
670  // strlen may not be available here
671  while (*f++) {
672  // nothing
673  }
674  return f;
675  }
676 #endif
677 };
678 
679 /** Set the file descriptor that Halide should write binary trace
680  * events to. If called with 0 as the argument, Halide outputs trace
681  * information to stdout in a human-readable format. If never called,
682  * Halide checks the for existence of an environment variable called
683  * HL_TRACE_FILE and opens that file. If HL_TRACE_FILE is not defined,
684  * it outputs trace information to stdout in a human-readable
685  * format. */
686 extern void halide_set_trace_file(int fd);
687 
688 /** Halide calls this to retrieve the file descriptor to write binary
689  * trace events to. The default implementation returns the value set
690  * by halide_set_trace_file. Implement it yourself if you wish to use
691  * a custom file descriptor per user_context. Return zero from your
692  * implementation to tell Halide to print human-readable trace
693  * information to stdout. */
695 
696 /** If tracing is writing to a file. This call closes that file
697  * (flushing the trace). Returns zero on success. */
699 
700 /** All Halide GPU or device backend implementations provide an
701  * interface to be used with halide_device_malloc, etc. This is
702  * accessed via the functions below.
703  */
704 
705 /** An opaque struct containing per-GPU API implementations of the
706  * device functions. */
708 
709 /** Each GPU API provides a halide_device_interface_t struct pointing
710  * to the code that manages device allocations. You can access these
711  * functions directly from the struct member function pointers, or by
712  * calling the functions declared below. Note that the global
713  * functions are not available when using Halide as a JIT compiler.
714  * If you are using raw halide_buffer_t in that context you must use
715  * the function pointers in the device_interface struct.
716  *
717  * The function pointers below are currently the same for every GPU
718  * API; only the impl field varies. These top-level functions do the
719  * bookkeeping that is common across all GPU APIs, and then dispatch
720  * to more API-specific functions via another set of function pointers
721  * hidden inside the impl field.
722  */
725  const struct halide_device_interface_t *device_interface);
726  int (*device_free)(void *user_context, struct halide_buffer_t *buf);
727  int (*device_sync)(void *user_context, struct halide_buffer_t *buf);
729  const struct halide_device_interface_t *device_interface);
732  const struct halide_device_interface_t *device_interface);
734  const struct halide_device_interface_t *device_interface);
736  int (*buffer_copy)(void *user_context, struct halide_buffer_t *src,
737  const struct halide_device_interface_t *dst_device_interface, struct halide_buffer_t *dst);
738  int (*device_crop)(void *user_context, const struct halide_buffer_t *src,
739  struct halide_buffer_t *dst);
740  int (*device_slice)(void *user_context, const struct halide_buffer_t *src,
741  int slice_dim, int slice_pos, struct halide_buffer_t *dst);
743  int (*wrap_native)(void *user_context, struct halide_buffer_t *buf, uint64_t handle,
744  const struct halide_device_interface_t *device_interface);
746  int (*compute_capability)(void *user_context, int *major, int *minor);
748 };
749 
750 /** Release all data associated with the given device interface, in
751  * particular all resources (memory, texture, context handles)
752  * allocated by Halide. Must be called explicitly when using AOT
753  * compilation. This is *not* thread-safe with respect to actively
754  * running Halide code. Ensure all pipelines are finished before
755  * calling this. */
757  const struct halide_device_interface_t *device_interface);
758 
759 /** Copy image data from device memory to host memory. This must be called
760  * explicitly to copy back the results of a GPU-based filter. */
762 
763 /** Copy image data from host memory to device memory. This should not
764  * be called directly; Halide handles copying to the device
765  * automatically. If interface is NULL and the buf has a non-zero dev
766  * field, the device associated with the dev handle will be
767  * used. Otherwise if the dev field is 0 and interface is NULL, an
768  * error is returned. */
770  const struct halide_device_interface_t *device_interface);
771 
772 /** Copy data from one buffer to another. The buffers may have
773  * different shapes and sizes, but the destination buffer's shape must
774  * be contained within the source buffer's shape. That is, for each
775  * dimension, the min on the destination buffer must be greater than
776  * or equal to the min on the source buffer, and min+extent on the
777  * destination buffer must be less that or equal to min+extent on the
778  * source buffer. The source data is pulled from either device or
779  * host memory on the source, depending on the dirty flags. host is
780  * preferred if both are valid. The dst_device_interface parameter
781  * controls the destination memory space. NULL means host memory. */
782 extern int halide_buffer_copy(void *user_context, struct halide_buffer_t *src,
783  const struct halide_device_interface_t *dst_device_interface,
784  struct halide_buffer_t *dst);
785 
786 /** Give the destination buffer a device allocation which is an alias
787  * for the same coordinate range in the source buffer. Modifies the
788  * device, device_interface, and the device_dirty flag only. Only
789  * supported by some device APIs (others will return
790  * halide_error_code_device_crop_unsupported). Call
791  * halide_device_release_crop instead of halide_device_free to clean
792  * up resources associated with the cropped view. Do not free the
793  * device allocation on the source buffer while the destination buffer
794  * still lives. Note that the two buffers do not share dirty flags, so
795  * care must be taken to update them together as needed. Note that src
796  * and dst are required to have the same number of dimensions.
797  *
798  * Note also that (in theory) device interfaces which support cropping may
799  * still not support cropping a crop (instead, create a new crop of the parent
800  * buffer); in practice, no known implementation has this limitation, although
801  * it is possible that some future implementations may require it. */
803  const struct halide_buffer_t *src,
804  struct halide_buffer_t *dst);
805 
806 /** Give the destination buffer a device allocation which is an alias
807  * for a similar coordinate range in the source buffer, but with one dimension
808  * sliced away in the dst. Modifies the device, device_interface, and the
809  * device_dirty flag only. Only supported by some device APIs (others will return
810  * halide_error_code_device_crop_unsupported). Call
811  * halide_device_release_crop instead of halide_device_free to clean
812  * up resources associated with the sliced view. Do not free the
813  * device allocation on the source buffer while the destination buffer
814  * still lives. Note that the two buffers do not share dirty flags, so
815  * care must be taken to update them together as needed. Note that the dst buffer
816  * must have exactly one fewer dimension than the src buffer, and that slice_dim
817  * and slice_pos must be valid within src. */
819  const struct halide_buffer_t *src,
820  int slice_dim, int slice_pos,
821  struct halide_buffer_t *dst);
822 
823 /** Release any resources associated with a cropped/sliced view of another
824  * buffer. */
826  struct halide_buffer_t *buf);
827 
828 /** Wait for current GPU operations to complete. Calling this explicitly
829  * should rarely be necessary, except maybe for profiling. */
831 
832 /** Allocate device memory to back a halide_buffer_t. */
834  const struct halide_device_interface_t *device_interface);
835 
836 /** Free device memory. */
838 
839 /** Wrap or detach a native device handle, setting the device field
840  * and device_interface field as appropriate for the given GPU
841  * API. The meaning of the opaque handle is specific to the device
842  * interface, so if you know the device interface in use, call the
843  * more specific functions in the runtime headers for your specific
844  * device API instead (e.g. HalideRuntimeCuda.h). */
845 // @{
847  struct halide_buffer_t *buf,
848  uint64_t handle,
849  const struct halide_device_interface_t *device_interface);
851 // @}
852 
853 /** Selects which gpu device to use. 0 is usually the display
854  * device. If never called, Halide uses the environment variable
855  * HL_GPU_DEVICE. If that variable is unset, Halide uses the last
856  * device. Set this to -1 to use the last device. */
857 extern void halide_set_gpu_device(int n);
858 
859 /** Halide calls this to get the desired halide gpu device
860  * setting. Implement this yourself to use a different gpu device per
861  * user_context. The default implementation returns the value set by
862  * halide_set_gpu_device, or the environment variable
863  * HL_GPU_DEVICE. */
865 
866 /** Set the soft maximum amount of memory, in bytes, that the LRU
867  * cache will use to memoize Func results. This is not a strict
868  * maximum in that concurrency and simultaneous use of memoized
869  * reults larger than the cache size can both cause it to
870  * temporariliy be larger than the size specified here.
871  */
873 
874 /** Given a cache key for a memoized result, currently constructed
875  * from the Func name and top-level Func name plus the arguments of
876  * the computation, determine if the result is in the cache and
877  * return it if so. (The internals of the cache key should be
878  * considered opaque by this function.) If this routine returns true,
879  * it is a cache miss. Otherwise, it will return false and the
880  * buffers passed in will be filled, via copying, with memoized
881  * data. The last argument is a list if halide_buffer_t pointers which
882  * represents the outputs of the memoized Func. If the Func does not
883  * return a Tuple, there will only be one halide_buffer_t in the list. The
884  * tuple_count parameters determines the length of the list.
885  *
886  * The return values are:
887  * -1: Signals an error.
888  * 0: Success and cache hit.
889  * 1: Success and cache miss.
890  */
891 extern int halide_memoization_cache_lookup(void *user_context, const uint8_t *cache_key, int32_t size,
892  struct halide_buffer_t *realized_bounds,
893  int32_t tuple_count, struct halide_buffer_t **tuple_buffers);
894 
895 /** Given a cache key for a memoized result, currently constructed
896  * from the Func name and top-level Func name plus the arguments of
897  * the computation, store the result in the cache for futre access by
898  * halide_memoization_cache_lookup. (The internals of the cache key
899  * should be considered opaque by this function.) Data is copied out
900  * from the inputs and inputs are unmodified. The last argument is a
901  * list if halide_buffer_t pointers which represents the outputs of the
902  * memoized Func. If the Func does not return a Tuple, there will
903  * only be one halide_buffer_t in the list. The tuple_count parameters
904  * determines the length of the list.
905  *
906  * If there is a memory allocation failure, the store does not store
907  * the data into the cache.
908  *
909  * If has_eviction_key is true, the entry is marked with eviction_key to
910  * allow removing the key with halide_memoization_cache_evict.
911  */
912 extern int halide_memoization_cache_store(void *user_context, const uint8_t *cache_key, int32_t size,
913  struct halide_buffer_t *realized_bounds,
914  int32_t tuple_count,
915  struct halide_buffer_t **tuple_buffers,
916  bool has_eviction_key, uint64_t eviction_key);
917 
918 /** Evict all cache entries that were tagged with the given
919  * eviction_key in the memoize scheduling directive.
920  */
921 extern void halide_memoization_cache_evict(void *user_context, uint64_t eviction_key);
922 
923 /** If halide_memoization_cache_lookup succeeds,
924  * halide_memoization_cache_release must be called to signal the
925  * storage is no longer being used by the caller. It will be passed
926  * the host pointer of one the buffers returned by
927  * halide_memoization_cache_lookup. That is
928  * halide_memoization_cache_release will be called multiple times for
929  * the case where halide_memoization_cache_lookup is handling multiple
930  * buffers. (This corresponds to memoizing a Tuple in Halide.) Note
931  * that the host pointer must be sufficient to get to all information
932  * the release operation needs. The default Halide cache impleemntation
933  * accomplishes this by storing extra data before the start of the user
934  * modifiable host storage.
935  *
936  * This call is like free and does not have a failure return.
937  */
938 extern void halide_memoization_cache_release(void *user_context, void *host);
939 
940 /** Free all memory and resources associated with the memoization cache.
941  * Must be called at a time when no other threads are accessing the cache.
942  */
944 
945 /** Verify that a given range of memory has been initialized; only used when Target::MSAN is enabled.
946  *
947  * The default implementation simply calls the LLVM-provided __msan_check_mem_is_initialized() function.
948  *
949  * The return value should always be zero.
950  */
951 extern int halide_msan_check_memory_is_initialized(void *user_context, const void *ptr, uint64_t len, const char *name);
952 
953 /** Verify that the data pointed to by the halide_buffer_t is initialized (but *not* the halide_buffer_t itself),
954  * using halide_msan_check_memory_is_initialized() for checking.
955  *
956  * The default implementation takes pains to only check the active memory ranges
957  * (skipping padding), and sorting into ranges to always check the smallest number of
958  * ranges, in monotonically increasing memory order.
959  *
960  * Most client code should never need to replace the default implementation.
961  *
962  * The return value should always be zero.
963  */
964 extern int halide_msan_check_buffer_is_initialized(void *user_context, struct halide_buffer_t *buffer, const char *buf_name);
965 
966 /** Annotate that a given range of memory has been initialized;
967  * only used when Target::MSAN is enabled.
968  *
969  * The default implementation simply calls the LLVM-provided __msan_unpoison() function.
970  *
971  * The return value should always be zero.
972  */
973 extern int halide_msan_annotate_memory_is_initialized(void *user_context, const void *ptr, uint64_t len);
974 
975 /** Mark the data pointed to by the halide_buffer_t as initialized (but *not* the halide_buffer_t itself),
976  * using halide_msan_annotate_memory_is_initialized() for marking.
977  *
978  * The default implementation takes pains to only mark the active memory ranges
979  * (skipping padding), and sorting into ranges to always mark the smallest number of
980  * ranges, in monotonically increasing memory order.
981  *
982  * Most client code should never need to replace the default implementation.
983  *
984  * The return value should always be zero.
985  */
988 
989 /** The error codes that may be returned by a Halide pipeline. */
991  /** There was no error. This is the value returned by Halide on success. */
993 
994  /** An uncategorized error occurred. Refer to the string passed to halide_error. */
996 
997  /** A Func was given an explicit bound via Func::bound, but this
998  * was not large enough to encompass the region that is used of
999  * the Func by the rest of the pipeline. */
1001 
1002  /** The elem_size field of a halide_buffer_t does not match the size in
1003  * bytes of the type of that ImageParam. Probable type mismatch. */
1005 
1006  /** A pipeline would access memory outside of the halide_buffer_t passed
1007  * in. */
1009 
1010  /** A halide_buffer_t was given that spans more than 2GB of memory. */
1012 
1013  /** A halide_buffer_t was given with extents that multiply to a number
1014  * greater than 2^31-1 */
1016 
1017  /** Applying explicit constraints on the size of an input or
1018  * output buffer shrank the size of that buffer below what will be
1019  * accessed by the pipeline. */
1021 
1022  /** A constraint on a size or stride of an input or output buffer
1023  * was not met by the halide_buffer_t passed in. */
1025 
1026  /** A scalar parameter passed in was smaller than its minimum
1027  * declared value. */
1029 
1030  /** A scalar parameter passed in was greater than its minimum
1031  * declared value. */
1033 
1034  /** A call to halide_malloc returned NULL. */
1036 
1037  /** A halide_buffer_t pointer passed in was NULL. */
1039 
1040  /** debug_to_file failed to open or write to the specified
1041  * file. */
1043 
1044  /** The Halide runtime encountered an error while trying to copy
1045  * from device to host. Turn on -debug in your target string to
1046  * see more details. */
1048 
1049  /** The Halide runtime encountered an error while trying to copy
1050  * from host to device. Turn on -debug in your target string to
1051  * see more details. */
1053 
1054  /** The Halide runtime encountered an error while trying to
1055  * allocate memory on device. Turn on -debug in your target string
1056  * to see more details. */
1058 
1059  /** The Halide runtime encountered an error while trying to
1060  * synchronize with a device. Turn on -debug in your target string
1061  * to see more details. */
1063 
1064  /** The Halide runtime encountered an error while trying to free a
1065  * device allocation. Turn on -debug in your target string to see
1066  * more details. */
1068 
1069  /** Buffer has a non-zero device but no device interface, which
1070  * violates a Halide invariant. */
1072 
1073  /** An error occurred when attempting to initialize the Matlab
1074  * runtime. */
1076 
1077  /** The type of an mxArray did not match the expected type. */
1079 
1080  /** There is a bug in the Halide compiler. */
1082 
1083  /** The Halide runtime encountered an error while trying to launch
1084  * a GPU kernel. Turn on -debug in your target string to see more
1085  * details. */
1087 
1088  /** The Halide runtime encountered a host pointer that violated
1089  * the alignment set for it by way of a call to
1090  * set_host_alignment */
1092 
1093  /** A fold_storage directive was used on a dimension that is not
1094  * accessed in a monotonically increasing or decreasing fashion. */
1096 
1097  /** A fold_storage directive was used with a fold factor that was
1098  * too small to store all the values of a producer needed by the
1099  * consumer. */
1101 
1102  /** User-specified require() expression was not satisfied. */
1104 
1105  /** At least one of the buffer's extents are negative. */
1107 
1109 
1111 
1112  /** A specialize_fail() schedule branch was selected at runtime. */
1114 
1115  /** The Halide runtime encountered an error while trying to wrap a
1116  * native device handle. Turn on -debug in your target string to
1117  * see more details. */
1119 
1120  /** The Halide runtime encountered an error while trying to detach
1121  * a native device handle. Turn on -debug in your target string
1122  * to see more details. */
1124 
1125  /** The host field on an input or output was null, the device
1126  * field was not zero, and the pipeline tries to use the buffer on
1127  * the host. You may be passing a GPU-only buffer to a pipeline
1128  * which is scheduled to use it on the CPU. */
1130 
1131  /** A folded buffer was passed to an extern stage, but the region
1132  * touched wraps around the fold boundary. */
1134 
1135  /** Buffer has a non-null device_interface but device is 0, which
1136  * violates a Halide invariant. */
1138 
1139  /** Buffer has both host and device dirty bits set, which violates
1140  * a Halide invariant. */
1142 
1143  /** The halide_buffer_t * passed to a halide runtime routine is
1144  * nullptr and this is not allowed. */
1146 
1147  /** The Halide runtime encountered an error while trying to copy
1148  * from one buffer to another. Turn on -debug in your target
1149  * string to see more details. */
1151 
1152  /** Attempted to make cropped/sliced alias of a buffer with a device
1153  * field, but the device_interface does not support cropping. */
1155 
1156  /** Cropping/slicing a buffer failed for some other reason. Turn on -debug
1157  * in your target string. */
1159 
1160  /** An operation on a buffer required an allocation on a
1161  * particular device interface, but a device allocation already
1162  * existed on a different device interface. Free the old one
1163  * first. */
1165 
1166  /** The dimensions field of a halide_buffer_t does not match the dimensions of that ImageParam. */
1168 
1169  /** A buffer with the device_dirty flag set was passed to a
1170  * pipeline compiled with no device backends enabled, so it
1171  * doesn't know how to copy the data back from device memory to
1172  * host memory. Either call copy_to_host before calling the Halide
1173  * pipeline, or enable the appropriate device backend. */
1175 
1176 };
1177 
1178 /** Halide calls the functions below on various error conditions. The
1179  * default implementations construct an error message, call
1180  * halide_error, then return the matching error code above. On
1181  * platforms that support weak linking, you can override these to
1182  * catch the errors individually. */
1183 
1184 /** A call into an extern stage for the purposes of bounds inference
1185  * failed. Returns the error code given by the extern stage. */
1186 extern int halide_error_bounds_inference_call_failed(void *user_context, const char *extern_stage_name, int result);
1187 
1188 /** A call to an extern stage failed. Returned the error code given by
1189  * the extern stage. */
1190 extern int halide_error_extern_stage_failed(void *user_context, const char *extern_stage_name, int result);
1191 
1192 /** Various other error conditions. See the enum above for a
1193  * description of each. */
1194 // @{
1195 extern int halide_error_explicit_bounds_too_small(void *user_context, const char *func_name, const char *var_name,
1196  int min_bound, int max_bound, int min_required, int max_required);
1197 extern int halide_error_bad_type(void *user_context, const char *func_name,
1198  uint32_t type_given, uint32_t correct_type); // N.B. The last two args are the bit representation of a halide_type_t
1199 extern int halide_error_bad_dimensions(void *user_context, const char *func_name,
1200  int32_t dimensions_given, int32_t correct_dimensions);
1201 extern int halide_error_access_out_of_bounds(void *user_context, const char *func_name,
1202  int dimension, int min_touched, int max_touched,
1203  int min_valid, int max_valid);
1204 extern int halide_error_buffer_allocation_too_large(void *user_context, const char *buffer_name,
1205  uint64_t allocation_size, uint64_t max_size);
1206 extern int halide_error_buffer_extents_negative(void *user_context, const char *buffer_name, int dimension, int extent);
1207 extern int halide_error_buffer_extents_too_large(void *user_context, const char *buffer_name,
1208  int64_t actual_size, int64_t max_size);
1210  int dimension,
1211  int constrained_min, int constrained_extent,
1212  int required_min, int required_extent);
1213 extern int halide_error_constraint_violated(void *user_context, const char *var, int val,
1214  const char *constrained_var, int constrained_val);
1215 extern int halide_error_param_too_small_i64(void *user_context, const char *param_name,
1216  int64_t val, int64_t min_val);
1217 extern int halide_error_param_too_small_u64(void *user_context, const char *param_name,
1218  uint64_t val, uint64_t min_val);
1219 extern int halide_error_param_too_small_f64(void *user_context, const char *param_name,
1220  double val, double min_val);
1221 extern int halide_error_param_too_large_i64(void *user_context, const char *param_name,
1222  int64_t val, int64_t max_val);
1223 extern int halide_error_param_too_large_u64(void *user_context, const char *param_name,
1224  uint64_t val, uint64_t max_val);
1225 extern int halide_error_param_too_large_f64(void *user_context, const char *param_name,
1226  double val, double max_val);
1228 extern int halide_error_buffer_argument_is_null(void *user_context, const char *buffer_name);
1229 extern int halide_error_debug_to_file_failed(void *user_context, const char *func,
1230  const char *filename, int error_code);
1231 extern int halide_error_unaligned_host_ptr(void *user_context, const char *func_name, int alignment);
1232 extern int halide_error_host_is_null(void *user_context, const char *func_name);
1233 extern int halide_error_bad_fold(void *user_context, const char *func_name, const char *var_name,
1234  const char *loop_name);
1235 extern int halide_error_bad_extern_fold(void *user_context, const char *func_name,
1236  int dim, int min, int extent, int valid_min, int fold_factor);
1237 
1238 extern int halide_error_fold_factor_too_small(void *user_context, const char *func_name, const char *var_name,
1239  int fold_factor, const char *loop_name, int required_extent);
1240 extern int halide_error_requirement_failed(void *user_context, const char *condition, const char *message);
1241 extern int halide_error_specialize_fail(void *user_context, const char *message);
1245 extern int halide_error_buffer_is_null(void *user_context, const char *routine);
1246 extern int halide_error_device_dirty_with_no_device_support(void *user_context, const char *buffer_name);
1247 // @}
1248 
1249 /** Optional features a compilation Target can have.
1250  * Be sure to keep this in sync with the Feature enum in Target.h and the implementation of
1251  * get_runtime_compatible_target in Target.cpp if you add a new feature.
1252  */
1254  halide_target_feature_jit = 0, ///< Generate code that will run immediately inside the calling process.
1255  halide_target_feature_debug, ///< Turn on debug info and output for runtime code.
1256  halide_target_feature_no_asserts, ///< Disable all runtime checks, for slightly tighter code.
1257  halide_target_feature_no_bounds_query, ///< Disable the bounds querying functionality.
1258 
1259  halide_target_feature_sse41, ///< Use SSE 4.1 and earlier instructions. Only relevant on x86.
1260  halide_target_feature_avx, ///< Use AVX 1 instructions. Only relevant on x86.
1261  halide_target_feature_avx2, ///< Use AVX 2 instructions. Only relevant on x86.
1262  halide_target_feature_fma, ///< Enable x86 FMA instruction
1263  halide_target_feature_fma4, ///< Enable x86 (AMD) FMA4 instruction set
1264  halide_target_feature_f16c, ///< Enable x86 16-bit float support
1265 
1266  halide_target_feature_armv7s, ///< Generate code for ARMv7s. Only relevant for 32-bit ARM.
1267  halide_target_feature_no_neon, ///< Avoid using NEON instructions. Only relevant for 32-bit ARM.
1268 
1269  halide_target_feature_vsx, ///< Use VSX instructions. Only relevant on POWERPC.
1270  halide_target_feature_power_arch_2_07, ///< Use POWER ISA 2.07 new instructions. Only relevant on POWERPC.
1271 
1272  halide_target_feature_cuda, ///< Enable the CUDA runtime. Defaults to compute capability 2.0 (Fermi)
1273  halide_target_feature_cuda_capability30, ///< Enable CUDA compute capability 3.0 (Kepler)
1274  halide_target_feature_cuda_capability32, ///< Enable CUDA compute capability 3.2 (Tegra K1)
1275  halide_target_feature_cuda_capability35, ///< Enable CUDA compute capability 3.5 (Kepler)
1276  halide_target_feature_cuda_capability50, ///< Enable CUDA compute capability 5.0 (Maxwell)
1277  halide_target_feature_cuda_capability61, ///< Enable CUDA compute capability 6.1 (Pascal)
1278  halide_target_feature_cuda_capability70, ///< Enable CUDA compute capability 7.0 (Volta)
1279  halide_target_feature_cuda_capability75, ///< Enable CUDA compute capability 7.5 (Turing)
1280  halide_target_feature_cuda_capability80, ///< Enable CUDA compute capability 8.0 (Ampere)
1281 
1282  halide_target_feature_opencl, ///< Enable the OpenCL runtime.
1283  halide_target_feature_cl_doubles, ///< Enable double support on OpenCL targets
1284  halide_target_feature_cl_atomic64, ///< Enable 64-bit atomics operations on OpenCL targets
1285 
1286  halide_target_feature_openglcompute, ///< Enable OpenGL Compute runtime.
1287 
1288  halide_target_feature_user_context, ///< Generated code takes a user_context pointer as first argument
1289 
1290  halide_target_feature_matlab, ///< Generate a mexFunction compatible with Matlab mex libraries. See tools/mex_halide.m.
1291 
1292  halide_target_feature_profile, ///< Launch a sampling profiler alongside the Halide pipeline that monitors and reports the runtime used by each Func
1293  halide_target_feature_no_runtime, ///< Do not include a copy of the Halide runtime in any generated object file or assembly
1294 
1295  halide_target_feature_metal, ///< Enable the (Apple) Metal runtime.
1296 
1297  halide_target_feature_c_plus_plus_mangling, ///< Generate C++ mangled names for result function, et al
1298 
1299  halide_target_feature_large_buffers, ///< Enable 64-bit buffer indexing to support buffers > 2GB. Ignored if bits != 64.
1300 
1301  halide_target_feature_hvx_128, ///< Enable HVX 128 byte mode.
1302  halide_target_feature_hvx_v62, ///< Enable Hexagon v62 architecture.
1303  halide_target_feature_fuzz_float_stores, ///< On every floating point store, set the last bit of the mantissa to zero. Pipelines for which the output is very different with this feature enabled may also produce very different output on different processors.
1304  halide_target_feature_soft_float_abi, ///< Enable soft float ABI. This only enables the soft float ABI calling convention, which does not necessarily use soft floats.
1305  halide_target_feature_msan, ///< Enable hooks for MSAN support.
1306  halide_target_feature_avx512, ///< Enable the base AVX512 subset supported by all AVX512 architectures. The specific feature sets are AVX-512F and AVX512-CD. See https://en.wikipedia.org/wiki/AVX-512 for a description of each AVX subset.
1307  halide_target_feature_avx512_knl, ///< Enable the AVX512 features supported by Knight's Landing chips, such as the Xeon Phi x200. This includes the base AVX512 set, and also AVX512-CD and AVX512-ER.
1308  halide_target_feature_avx512_skylake, ///< Enable the AVX512 features supported by Skylake Xeon server processors. This adds AVX512-VL, AVX512-BW, and AVX512-DQ to the base set. The main difference from the base AVX512 set is better support for small integer ops. Note that this does not include the Knight's Landing features. Note also that these features are not available on Skylake desktop and mobile processors.
1309  halide_target_feature_avx512_cannonlake, ///< Enable the AVX512 features expected to be supported by future Cannonlake processors. This includes all of the Skylake features, plus AVX512-IFMA and AVX512-VBMI.
1310  halide_target_feature_avx512_sapphirerapids, ///< Enable the AVX512 features supported by Sapphire Rapids processors. This include all of the Cannonlake features, plus AVX512-VNNI and AVX512-BF16.
1312  halide_target_feature_trace_loads, ///< Trace all loads done by the pipeline. Equivalent to calling Func::trace_loads on every non-inlined Func.
1313  halide_target_feature_trace_stores, ///< Trace all stores done by the pipeline. Equivalent to calling Func::trace_stores on every non-inlined Func.
1314  halide_target_feature_trace_realizations, ///< Trace all realizations done by the pipeline. Equivalent to calling Func::trace_realizations on every non-inlined Func.
1315  halide_target_feature_trace_pipeline, ///< Trace the pipeline.
1316  halide_target_feature_hvx_v65, ///< Enable Hexagon v65 architecture.
1317  halide_target_feature_hvx_v66, ///< Enable Hexagon v66 architecture.
1318  halide_target_feature_cl_half, ///< Enable half support on OpenCL targets
1319  halide_target_feature_strict_float, ///< Turn off all non-IEEE floating-point optimization. Currently applies only to LLVM targets.
1320  halide_target_feature_tsan, ///< Enable hooks for TSAN support.
1321  halide_target_feature_asan, ///< Enable hooks for ASAN support.
1322  halide_target_feature_d3d12compute, ///< Enable Direct3D 12 Compute runtime.
1323  halide_target_feature_check_unsafe_promises, ///< Insert assertions for promises.
1324  halide_target_feature_hexagon_dma, ///< Enable Hexagon DMA buffers.
1325  halide_target_feature_embed_bitcode, ///< Emulate clang -fembed-bitcode flag.
1326  halide_target_feature_enable_llvm_loop_opt, ///< Enable loop vectorization + unrolling in LLVM. Overrides halide_target_feature_disable_llvm_loop_opt. (Ignored for non-LLVM targets.)
1327  halide_target_feature_disable_llvm_loop_opt, ///< Disable loop vectorization + unrolling in LLVM. (Ignored for non-LLVM targets.)
1328  halide_target_feature_wasm_simd128, ///< Enable +simd128 instructions for WebAssembly codegen.
1329  halide_target_feature_wasm_signext, ///< Enable +sign-ext instructions for WebAssembly codegen.
1330  halide_target_feature_wasm_sat_float_to_int, ///< Enable saturating (nontrapping) float-to-int instructions for WebAssembly codegen.
1331  halide_target_feature_wasm_threads, ///< Enable use of threads in WebAssembly codegen. Requires the use of a wasm runtime that provides pthread-compatible wrappers (typically, Emscripten with the -pthreads flag). Unsupported under WASI.
1332  halide_target_feature_wasm_bulk_memory, ///< Enable +bulk-memory instructions for WebAssembly codegen.
1333  halide_target_feature_sve, ///< Enable ARM Scalable Vector Extensions
1334  halide_target_feature_sve2, ///< Enable ARM Scalable Vector Extensions v2
1335  halide_target_feature_egl, ///< Force use of EGL support.
1336  halide_target_feature_arm_dot_prod, ///< Enable ARMv8.2-a dotprod extension (i.e. udot and sdot instructions)
1337  halide_llvm_large_code_model, ///< Use the LLVM large code model to compile
1338  halide_target_feature_rvv, ///< Enable RISCV "V" Vector Extension
1339  halide_target_feature_armv81a, ///< Enable ARMv8.1-a instructions
1340  halide_target_feature_end ///< A sentinel. Every target is considered to have this feature, and setting this feature does nothing.
1342 
1343 /** This function is called internally by Halide in some situations to determine
1344  * if the current execution environment can support the given set of
1345  * halide_target_feature_t flags. The implementation must do the following:
1346  *
1347  * -- If there are flags set in features that the function knows *cannot* be supported, return 0.
1348  * -- Otherwise, return 1.
1349  * -- Note that any flags set in features that the function doesn't know how to test should be ignored;
1350  * this implies that a return value of 1 means "not known to be bad" rather than "known to be good".
1351  *
1352  * In other words: a return value of 0 means "It is not safe to use code compiled with these features",
1353  * while a return value of 1 means "It is not obviously unsafe to use code compiled with these features".
1354  *
1355  * The default implementation simply calls halide_default_can_use_target_features.
1356  *
1357  * Note that `features` points to an array of `count` uint64_t; this array must contain enough
1358  * bits to represent all the currently known features. Any excess bits must be set to zero.
1359  */
1360 // @{
1361 extern int halide_can_use_target_features(int count, const uint64_t *features);
1362 typedef int (*halide_can_use_target_features_t)(int count, const uint64_t *features);
1364 // @}
1365 
1366 /**
1367  * This is the default implementation of halide_can_use_target_features; it is provided
1368  * for convenience of user code that may wish to extend halide_can_use_target_features
1369  * but continue providing existing support, e.g.
1370  *
1371  * int halide_can_use_target_features(int count, const uint64_t *features) {
1372  * if (features[halide_target_somefeature >> 6] & (1LL << (halide_target_somefeature & 63))) {
1373  * if (!can_use_somefeature()) {
1374  * return 0;
1375  * }
1376  * }
1377  * return halide_default_can_use_target_features(count, features);
1378  * }
1379  */
1380 extern int halide_default_can_use_target_features(int count, const uint64_t *features);
1381 
1382 typedef struct halide_dimension_t {
1383 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
1384  int32_t min = 0, extent = 0, stride = 0;
1385 
1386  // Per-dimension flags. None are defined yet (This is reserved for future use).
1387  uint32_t flags = 0;
1388 
1391  : min(m), extent(e), stride(s), flags(f) {
1392  }
1393 
1394  HALIDE_ALWAYS_INLINE bool operator==(const halide_dimension_t &other) const {
1395  return (min == other.min) &&
1396  (extent == other.extent) &&
1397  (stride == other.stride) &&
1398  (flags == other.flags);
1399  }
1400 
1401  HALIDE_ALWAYS_INLINE bool operator!=(const halide_dimension_t &other) const {
1402  return !(*this == other);
1403  }
1404 #else
1406 
1407  // Per-dimension flags. None are defined yet (This is reserved for future use).
1409 #endif
1411 
1412 #ifdef __cplusplus
1413 } // extern "C"
1414 #endif
1415 
1418 
1419 /**
1420  * The raw representation of an image passed around by generated
1421  * Halide code. It includes some stuff to track whether the image is
1422  * not actually in main memory, but instead on a device (like a
1423  * GPU). For a more convenient C++ wrapper, use Halide::Buffer<T>. */
1424 typedef struct halide_buffer_t {
1425  /** A device-handle for e.g. GPU memory used to back this buffer. */
1427 
1428  /** The interface used to interpret the above handle. */
1430 
1431  /** A pointer to the start of the data in main memory. In terms of
1432  * the Halide coordinate system, this is the address of the min
1433  * coordinates (defined below). */
1435 
1436  /** flags with various meanings. */
1438 
1439  /** The type of each buffer element. */
1440  struct halide_type_t type;
1441 
1442  /** The dimensionality of the buffer. */
1444 
1445  /** The shape of the buffer. Halide does not own this array - you
1446  * must manage the memory for it yourself. */
1448 
1449  /** Pads the buffer up to a multiple of 8 bytes */
1450  void *padding;
1451 
1452 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
1453  /** Convenience methods for accessing the flags */
1454  // @{
1455  HALIDE_ALWAYS_INLINE bool get_flag(halide_buffer_flags flag) const {
1456  return (flags & flag) != 0;
1457  }
1458 
1459  HALIDE_ALWAYS_INLINE void set_flag(halide_buffer_flags flag, bool value) {
1460  if (value) {
1461  flags |= flag;
1462  } else {
1463  flags &= ~flag;
1464  }
1465  }
1466 
1467  HALIDE_ALWAYS_INLINE bool host_dirty() const {
1468  return get_flag(halide_buffer_flag_host_dirty);
1469  }
1470 
1471  HALIDE_ALWAYS_INLINE bool device_dirty() const {
1472  return get_flag(halide_buffer_flag_device_dirty);
1473  }
1474 
1475  HALIDE_ALWAYS_INLINE void set_host_dirty(bool v = true) {
1476  set_flag(halide_buffer_flag_host_dirty, v);
1477  }
1478 
1479  HALIDE_ALWAYS_INLINE void set_device_dirty(bool v = true) {
1480  set_flag(halide_buffer_flag_device_dirty, v);
1481  }
1482  // @}
1483 
1484  /** The total number of elements this buffer represents. Equal to
1485  * the product of the extents */
1486  HALIDE_ALWAYS_INLINE size_t number_of_elements() const {
1487  size_t s = 1;
1488  for (int i = 0; i < dimensions; i++) {
1489  s *= dim[i].extent;
1490  }
1491  return s;
1492  }
1493 
1494  /** Offset to the element with the lowest address.
1495  * If all strides are positive, equal to zero.
1496  * Offset is in elements, not bytes.
1497  * Unlike begin(), this is ok to call on an unallocated buffer. */
1498  HALIDE_ALWAYS_INLINE ptrdiff_t begin_offset() const {
1499  ptrdiff_t index = 0;
1500  for (int i = 0; i < dimensions; i++) {
1501  const int stride = dim[i].stride;
1502  if (stride < 0) {
1503  index += stride * (ptrdiff_t)(dim[i].extent - 1);
1504  }
1505  }
1506  return index;
1507  }
1508 
1509  /** An offset to one beyond the element with the highest address.
1510  * Offset is in elements, not bytes.
1511  * Unlike end(), this is ok to call on an unallocated buffer. */
1512  HALIDE_ALWAYS_INLINE ptrdiff_t end_offset() const {
1513  ptrdiff_t index = 0;
1514  for (int i = 0; i < dimensions; i++) {
1515  const int stride = dim[i].stride;
1516  if (stride > 0) {
1517  index += stride * (ptrdiff_t)(dim[i].extent - 1);
1518  }
1519  }
1520  index += 1;
1521  return index;
1522  }
1523 
1524  /** A pointer to the element with the lowest address.
1525  * If all strides are positive, equal to the host pointer.
1526  * Illegal to call on an unallocated buffer. */
1527  HALIDE_ALWAYS_INLINE uint8_t *begin() const {
1528  return host + begin_offset() * type.bytes();
1529  }
1530 
1531  /** A pointer to one beyond the element with the highest address.
1532  * Illegal to call on an unallocated buffer. */
1533  HALIDE_ALWAYS_INLINE uint8_t *end() const {
1534  return host + end_offset() * type.bytes();
1535  }
1536 
1537  /** The total number of bytes spanned by the data in memory. */
1538  HALIDE_ALWAYS_INLINE size_t size_in_bytes() const {
1539  return (size_t)(end_offset() - begin_offset()) * type.bytes();
1540  }
1541 
1542  /** A pointer to the element at the given location. */
1543  HALIDE_ALWAYS_INLINE uint8_t *address_of(const int *pos) const {
1544  ptrdiff_t index = 0;
1545  for (int i = 0; i < dimensions; i++) {
1546  index += (ptrdiff_t)dim[i].stride * (pos[i] - dim[i].min);
1547  }
1548  return host + index * type.bytes();
1549  }
1550 
1551  /** Attempt to call device_sync for the buffer. If the buffer
1552  * has no device_interface (or no device_sync), this is a quiet no-op.
1553  * Calling this explicitly should rarely be necessary, except for profiling. */
1554  HALIDE_ALWAYS_INLINE int device_sync(void *ctx = nullptr) {
1556  return device_interface->device_sync(ctx, this);
1557  }
1558  return 0;
1559  }
1560 
1561  /** Check if an input buffer passed extern stage is a querying
1562  * bounds. Compared to doing the host pointer check directly,
1563  * this both adds clarity to code and will facilitate moving to
1564  * another representation for bounds query arguments. */
1565  HALIDE_ALWAYS_INLINE bool is_bounds_query() const {
1566  return host == nullptr && device == 0;
1567  }
1568 
1569 #endif
1571 
1572 #ifdef __cplusplus
1573 extern "C" {
1574 #endif
1575 
1576 #ifndef HALIDE_ATTRIBUTE_DEPRECATED
1577 #ifdef HALIDE_ALLOW_DEPRECATED
1578 #define HALIDE_ATTRIBUTE_DEPRECATED(x)
1579 #else
1580 #ifdef _MSC_VER
1581 #define HALIDE_ATTRIBUTE_DEPRECATED(x) __declspec(deprecated(x))
1582 #else
1583 #define HALIDE_ATTRIBUTE_DEPRECATED(x) __attribute__((deprecated(x)))
1584 #endif
1585 #endif
1586 #endif
1587 
1588 /** halide_scalar_value_t is a simple union able to represent all the well-known
1589  * scalar values in a filter argument. Note that it isn't tagged with a type;
1590  * you must ensure you know the proper type before accessing. Most user
1591  * code will never need to create instances of this struct; its primary use
1592  * is to hold def/min/max values in a halide_filter_argument_t. (Note that
1593  * this is conceptually just a union; it's wrapped in a struct to ensure
1594  * that it doesn't get anonymized by LLVM.)
1595  */
1597  union {
1598  bool b;
1607  float f32;
1608  double f64;
1609  void *handle;
1610  } u;
1611 #ifdef __cplusplus
1613  u.u64 = 0;
1614  }
1615 #endif
1616 };
1617 
1622 };
1623 
1624 /*
1625  These structs must be robust across different compilers and settings; when
1626  modifying them, strive for the following rules:
1627 
1628  1) All fields are explicitly sized. I.e. must use int32_t and not "int"
1629  2) All fields must land on an alignment boundary that is the same as their size
1630  3) Explicit padding is added to make that so
1631  4) The sizeof the struct is padded out to a multiple of the largest natural size thing in the struct
1632  5) don't forget that 32 and 64 bit pointers are different sizes
1633 */
1634 
1635 /**
1636  * Obsolete version of halide_filter_argument_t; only present in
1637  * code that wrote halide_filter_metadata_t version 0.
1638  */
1640  const char *name;
1643  struct halide_type_t type;
1644  const struct halide_scalar_value_t *def, *min, *max;
1645 };
1646 
1647 /**
1648  * halide_filter_argument_t is essentially a plain-C-struct equivalent to
1649  * Halide::Argument; most user code will never need to create one.
1650  */
1652  const char *name; // name of the argument; will never be null or empty.
1653  int32_t kind; // actually halide_argument_kind_t
1654  int32_t dimensions; // always zero for scalar arguments
1655  struct halide_type_t type;
1656  // These pointers should always be null for buffer arguments,
1657  // and *may* be null for scalar arguments. (A null value means
1658  // there is no def/min/max/estimate specified for this argument.)
1660  // This pointer should always be null for scalar arguments,
1661  // and *may* be null for buffer arguments. If not null, it should always
1662  // point to an array of dimensions*2 pointers, which will be the (min, extent)
1663  // estimates for each dimension of the buffer. (Note that any of the pointers
1664  // may be null as well.)
1665  int64_t const *const *buffer_estimates;
1666 };
1667 
1669 #ifdef __cplusplus
1670  static const int32_t VERSION = 1;
1671 #endif
1672 
1673  /** version of this metadata; currently always 1. */
1675 
1676  /** The number of entries in the arguments field. This is always >= 1. */
1678 
1679  /** An array of the filters input and output arguments; this will never be
1680  * null. The order of arguments is not guaranteed (input and output arguments
1681  * may come in any order); however, it is guaranteed that all arguments
1682  * will have a unique name within a given filter. */
1684 
1685  /** The Target for which the filter was compiled. This is always
1686  * a canonical Target string (ie a product of Target::to_string). */
1687  const char *target;
1688 
1689  /** The function name of the filter. */
1690  const char *name;
1691 };
1692 
1693 /** halide_register_argv_and_metadata() is a **user-defined** function that
1694  * must be provided in order to use the registration.cc files produced
1695  * by Generators when the 'registration' output is requested. Each registration.cc
1696  * file provides a static initializer that calls this function with the given
1697  * filter's argv-call variant, its metadata, and (optionally) and additional
1698  * textual data that the build system chooses to tack on for its own purposes.
1699  * Note that this will be called at static-initializer time (i.e., before
1700  * main() is called), and in an unpredictable order. Note that extra_key_value_pairs
1701  * may be nullptr; if it's not null, it's expected to be a null-terminated list
1702  * of strings, with an even number of entries. */
1704  int (*filter_argv_call)(void **),
1705  const struct halide_filter_metadata_t *filter_metadata,
1706  const char *const *extra_key_value_pairs);
1707 
1708 /** The functions below here are relevant for pipelines compiled with
1709  * the -profile target flag, which runs a sampling profiler thread
1710  * alongside the pipeline. */
1711 
1712 /** Per-Func state tracked by the sampling profiler. */
1714  /** Total time taken evaluating this Func (in nanoseconds). */
1716 
1717  /** The current memory allocation of this Func. */
1719 
1720  /** The peak memory allocation of this Func. */
1722 
1723  /** The total memory allocation of this Func. */
1725 
1726  /** The peak stack allocation of this Func's threads. */
1728 
1729  /** The average number of thread pool worker threads active while computing this Func. */
1731 
1732  /** The name of this Func. A global constant string. */
1733  const char *name;
1734 
1735  /** The total number of memory allocation of this Func. */
1737 };
1738 
1739 /** Per-pipeline state tracked by the sampling profiler. These exist
1740  * in a linked list. */
1742  /** Total time spent inside this pipeline (in nanoseconds) */
1744 
1745  /** The current memory allocation of funcs in this pipeline. */
1747 
1748  /** The peak memory allocation of funcs in this pipeline. */
1750 
1751  /** The total memory allocation of funcs in this pipeline. */
1753 
1754  /** The average number of thread pool worker threads doing useful
1755  * work while computing this pipeline. */
1757 
1758  /** The name of this pipeline. A global constant string. */
1759  const char *name;
1760 
1761  /** An array containing states for each Func in this pipeline. */
1763 
1764  /** The next pipeline_stats pointer. It's a void * because types
1765  * in the Halide runtime may not currently be recursive. */
1766  void *next;
1767 
1768  /** The number of funcs in this pipeline. */
1770 
1771  /** An internal base id used to identify the funcs in this pipeline. */
1773 
1774  /** The number of times this pipeline has been run. */
1775  int runs;
1776 
1777  /** The total number of samples taken inside of this pipeline. */
1778  int samples;
1779 
1780  /** The total number of memory allocation of funcs in this pipeline. */
1782 };
1783 
1784 /** The global state of the profiler. */
1785 
1787  /** Guards access to the fields below. If not locked, the sampling
1788  * profiler thread is free to modify things below (including
1789  * reordering the linked list of pipeline stats). */
1790  struct halide_mutex lock;
1791 
1792  /** The amount of time the profiler thread sleeps between samples
1793  * in milliseconds. Defaults to 1 */
1795 
1796  /** An internal id used for bookkeeping. */
1798 
1799  /** The id of the current running Func. Set by the pipeline, read
1800  * periodically by the profiler thread. */
1802 
1803  /** The number of threads currently doing work. */
1805 
1806  /** A linked list of stats gathered for each pipeline. */
1808 
1809  /** Retrieve remote profiler state. Used so that the sampling
1810  * profiler can follow along with execution that occurs elsewhere,
1811  * e.g. on a DSP. If null, it reads from the int above instead. */
1812  void (*get_remote_profiler_state)(int *func, int *active_workers);
1813 
1814  /** Sampling thread reference to be joined at shutdown. */
1815  struct halide_thread *sampling_thread;
1816 };
1817 
1818 /** Profiler func ids with special meanings. */
1819 enum {
1820  /// current_func takes on this value when not inside Halide code
1822  /// Set current_func to this value to tell the profiling thread to
1823  /// halt. It will start up again next time you run a pipeline with
1824  /// profiling enabled.
1826 };
1827 
1828 /** Get a pointer to the global profiler state for programmatic
1829  * inspection. Lock it before using to pause the profiler. */
1831 
1832 /** Get a pointer to the pipeline state associated with pipeline_name.
1833  * This function grabs the global profiler state's lock on entry. */
1834 extern struct halide_profiler_pipeline_stats *halide_profiler_get_pipeline_state(const char *pipeline_name);
1835 
1836 /** Reset profiler state cheaply. May leave threads running or some
1837  * memory allocated but all accumluated statistics are reset.
1838  * WARNING: Do NOT call this method while any halide pipeline is
1839  * running; halide_profiler_memory_allocate/free and
1840  * halide_profiler_stack_peak_update update the profiler pipeline's
1841  * state without grabbing the global profiler state's lock. */
1843 
1844 /** Reset all profiler state.
1845  * WARNING: Do NOT call this method while any halide pipeline is
1846  * running; halide_profiler_memory_allocate/free and
1847  * halide_profiler_stack_peak_update update the profiler pipeline's
1848  * state without grabbing the global profiler state's lock. */
1850 
1851 /** Print out timing statistics for everything run since the last
1852  * reset. Also happens at process exit. */
1854 
1855 /// \name "Float16" functions
1856 /// These functions operate of bits (``uint16_t``) representing a half
1857 /// precision floating point number (IEEE-754 2008 binary16).
1858 //{@
1859 
1860 /** Read bits representing a half precision floating point number and return
1861  * the float that represents the same value */
1863 
1864 /** Read bits representing a half precision floating point number and return
1865  * the double that represents the same value */
1867 
1868 // TODO: Conversion functions to half
1869 
1870 //@}
1871 
1872 // Allocating and freeing device memory is often very slow. The
1873 // methods below give Halide's runtime permission to hold onto device
1874 // memory to service future requests instead of returning it to the
1875 // underlying device API. The API does not manage an allocation pool,
1876 // all it does is provide access to a shared counter that acts as a
1877 // limit on the unused memory not yet returned to the underlying
1878 // device API. It makes callbacks to participants when memory needs to
1879 // be released because the limit is about to be exceeded (either
1880 // because the limit has been reduced, or because the memory owned by
1881 // some participant becomes unused).
1882 
1883 /** Tell Halide whether or not it is permitted to hold onto device
1884  * allocations to service future requests instead of returning them
1885  * eagerly to the underlying device API. Many device allocators are
1886  * quite slow, so it can be beneficial to set this to true. The
1887  * default value for now is false.
1888  *
1889  * Note that if enabled, the eviction policy is very simplistic. The
1890  * 32 most-recently used allocations are preserved, regardless of
1891  * their size. Additionally, if a call to cuMalloc results in an
1892  * out-of-memory error, the entire cache is flushed and the allocation
1893  * is retried. See https://github.com/halide/Halide/issues/4093
1894  *
1895  * If set to false, releases all unused device allocations back to the
1896  * underlying device APIs. For finer-grained control, see specific
1897  * methods in each device api runtime. */
1899 
1900 /** Determines whether on device_free the memory is returned
1901  * immediately to the device API, or placed on a free list for future
1902  * use. Override and switch based on the user_context for
1903  * finer-grained control. By default just returns the value most
1904  * recently set by the method above. */
1906 
1910 };
1911 
1912 /** Register a callback to be informed when
1913  * halide_reuse_device_allocations(false) is called, and all unused
1914  * device allocations must be released. The object passed should have
1915  * global lifetime, and its next field will be clobbered. */
1917 
1918 #ifdef __cplusplus
1919 } // End extern "C"
1920 #endif
1921 
1922 #if (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
1923 
1924 namespace {
1925 template<typename T>
1926 struct check_is_pointer;
1927 template<typename T>
1928 struct check_is_pointer<T *> {};
1929 } // namespace
1930 
1931 /** Construct the halide equivalent of a C type */
1932 template<typename T>
1933 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of() {
1934  // Create a compile-time error if T is not a pointer (without
1935  // using any includes - this code goes into the runtime).
1936  check_is_pointer<T> check;
1937  (void)check;
1938  return halide_type_t(halide_type_handle, 64);
1939 }
1940 
1941 template<>
1942 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<float>() {
1943  return halide_type_t(halide_type_float, 32);
1944 }
1945 
1946 template<>
1947 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<double>() {
1948  return halide_type_t(halide_type_float, 64);
1949 }
1950 
1951 template<>
1952 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<bool>() {
1953  return halide_type_t(halide_type_uint, 1);
1954 }
1955 
1956 template<>
1957 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<uint8_t>() {
1958  return halide_type_t(halide_type_uint, 8);
1959 }
1960 
1961 template<>
1962 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<uint16_t>() {
1963  return halide_type_t(halide_type_uint, 16);
1964 }
1965 
1966 template<>
1967 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<uint32_t>() {
1968  return halide_type_t(halide_type_uint, 32);
1969 }
1970 
1971 template<>
1972 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<uint64_t>() {
1973  return halide_type_t(halide_type_uint, 64);
1974 }
1975 
1976 template<>
1977 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<int8_t>() {
1978  return halide_type_t(halide_type_int, 8);
1979 }
1980 
1981 template<>
1982 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<int16_t>() {
1983  return halide_type_t(halide_type_int, 16);
1984 }
1985 
1986 template<>
1987 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<int32_t>() {
1988  return halide_type_t(halide_type_int, 32);
1989 }
1990 
1991 template<>
1992 HALIDE_ALWAYS_INLINE halide_type_t halide_type_of<int64_t>() {
1993  return halide_type_t(halide_type_int, 64);
1994 }
1995 
1996 #endif // (__cplusplus >= 201103L || _MSVC_LANG >= 201103L)
1997 
1998 #endif // HALIDE_HALIDERUNTIME_H
halide_error_handler_t halide_set_error_handler(halide_error_handler_t handler)
void halide_profiler_reset()
Reset profiler state cheaply.
void halide_set_custom_parallel_runtime(halide_do_par_for_t, halide_do_task_t, halide_do_loop_task_t, halide_do_parallel_tasks_t, halide_semaphore_init_t, halide_semaphore_try_acquire_t, halide_semaphore_release_t)
void *(* halide_get_library_symbol_t)(void *lib, const char *name)
int halide_memoization_cache_lookup(void *user_context, const uint8_t *cache_key, int32_t size, struct halide_buffer_t *realized_bounds, int32_t tuple_count, struct halide_buffer_t **tuple_buffers)
Given a cache key for a memoized result, currently constructed from the Func name and top-level Func ...
void *(* halide_malloc_t)(void *, size_t)
int halide_error_bad_extern_fold(void *user_context, const char *func_name, int dim, int min, int extent, int valid_min, int fold_factor)
int halide_device_sync(void *user_context, struct halide_buffer_t *buf)
Wait for current GPU operations to complete.
int halide_default_do_task(void *user_context, halide_task_t f, int idx, uint8_t *closure)
int halide_do_par_for(void *user_context, halide_task_t task, int min, int size, uint8_t *closure)
int halide_error_bad_fold(void *user_context, const char *func_name, const char *var_name, const char *loop_name)
int(* halide_semaphore_release_t)(struct halide_semaphore_t *, int)
void halide_cond_signal(struct halide_cond *cond)
int halide_do_loop_task(void *user_context, halide_loop_task_t f, int min, int extent, uint8_t *closure, void *task_parent)
halide_load_library_t halide_set_custom_load_library(halide_load_library_t user_load_library)
int halide_device_crop(void *user_context, const struct halide_buffer_t *src, struct halide_buffer_t *dst)
Give the destination buffer a device allocation which is an alias for the same coordinate range in th...
int halide_semaphore_init(struct halide_semaphore_t *, int n)
halide_get_symbol_t halide_set_custom_get_symbol(halide_get_symbol_t user_get_symbol)
double halide_float16_bits_to_double(uint16_t)
Read bits representing a half precision floating point number and return the double that represents t...
void * halide_default_get_symbol(const char *name)
int halide_msan_annotate_buffer_is_initialized(void *user_context, struct halide_buffer_t *buffer)
Mark the data pointed to by the halide_buffer_t as initialized (but not the halide_buffer_t itself),...
void * halide_get_symbol(const char *name)
Halide calls these functions to interact with the underlying system runtime functions.
void halide_default_print(void *user_context, const char *)
void * halide_get_library_symbol(void *lib, const char *name)
halide_target_feature_t
Optional features a compilation Target can have.
@ halide_target_feature_large_buffers
Enable 64-bit buffer indexing to support buffers > 2GB. Ignored if bits != 64.
@ halide_target_feature_fma
Enable x86 FMA instruction.
@ halide_target_feature_wasm_bulk_memory
Enable +bulk-memory instructions for WebAssembly codegen.
@ halide_target_feature_tsan
Enable hooks for TSAN support.
@ halide_target_feature_msan
Enable hooks for MSAN support.
@ halide_target_feature_wasm_threads
Enable use of threads in WebAssembly codegen. Requires the use of a wasm runtime that provides pthrea...
@ halide_target_feature_trace_loads
Trace all loads done by the pipeline. Equivalent to calling Func::trace_loads on every non-inlined Fu...
@ halide_target_feature_enable_llvm_loop_opt
Enable loop vectorization + unrolling in LLVM. Overrides halide_target_feature_disable_llvm_loop_opt....
@ halide_target_feature_no_asserts
Disable all runtime checks, for slightly tighter code.
@ halide_target_feature_cl_doubles
Enable double support on OpenCL targets.
@ halide_target_feature_rvv
Enable RISCV "V" Vector Extension.
@ halide_target_feature_openglcompute
Enable OpenGL Compute runtime.
@ halide_target_feature_avx2
Use AVX 2 instructions. Only relevant on x86.
@ halide_target_feature_trace_realizations
Trace all realizations done by the pipeline. Equivalent to calling Func::trace_realizations on every ...
@ halide_target_feature_c_plus_plus_mangling
Generate C++ mangled names for result function, et al.
@ halide_target_feature_no_runtime
Do not include a copy of the Halide runtime in any generated object file or assembly.
@ halide_target_feature_hvx_v65
Enable Hexagon v65 architecture.
@ halide_target_feature_debug
Turn on debug info and output for runtime code.
@ halide_target_feature_embed_bitcode
Emulate clang -fembed-bitcode flag.
@ halide_target_feature_wasm_simd128
Enable +simd128 instructions for WebAssembly codegen.
@ halide_target_feature_end
A sentinel. Every target is considered to have this feature, and setting this feature does nothing.
@ halide_llvm_large_code_model
Use the LLVM large code model to compile.
@ halide_target_feature_soft_float_abi
Enable soft float ABI. This only enables the soft float ABI calling convention, which does not necess...
@ halide_target_feature_sve2
Enable ARM Scalable Vector Extensions v2.
@ halide_target_feature_disable_llvm_loop_opt
Disable loop vectorization + unrolling in LLVM. (Ignored for non-LLVM targets.)
@ halide_target_feature_d3d12compute
Enable Direct3D 12 Compute runtime.
@ halide_target_feature_matlab
Generate a mexFunction compatible with Matlab mex libraries. See tools/mex_halide....
@ halide_target_feature_avx512_skylake
Enable the AVX512 features supported by Skylake Xeon server processors. This adds AVX512-VL,...
@ halide_target_feature_avx512_cannonlake
Enable the AVX512 features expected to be supported by future Cannonlake processors....
@ halide_target_feature_metal
Enable the (Apple) Metal runtime.
@ halide_target_feature_hvx_128
Enable HVX 128 byte mode.
@ halide_target_feature_cuda_capability70
Enable CUDA compute capability 7.0 (Volta)
@ halide_target_feature_fma4
Enable x86 (AMD) FMA4 instruction set.
@ halide_target_feature_wasm_sat_float_to_int
Enable saturating (nontrapping) float-to-int instructions for WebAssembly codegen.
@ halide_target_feature_cuda_capability30
Enable CUDA compute capability 3.0 (Kepler)
@ halide_target_feature_no_neon
Avoid using NEON instructions. Only relevant for 32-bit ARM.
@ halide_target_feature_cuda_capability61
Enable CUDA compute capability 6.1 (Pascal)
@ halide_target_feature_armv7s
Generate code for ARMv7s. Only relevant for 32-bit ARM.
@ halide_target_feature_trace_pipeline
Trace the pipeline.
@ halide_target_feature_cl_atomic64
Enable 64-bit atomics operations on OpenCL targets.
@ halide_target_feature_egl
Force use of EGL support.
@ halide_target_feature_profile
Launch a sampling profiler alongside the Halide pipeline that monitors and reports the runtime used b...
@ halide_target_feature_strict_float
Turn off all non-IEEE floating-point optimization. Currently applies only to LLVM targets.
@ halide_target_feature_cuda_capability35
Enable CUDA compute capability 3.5 (Kepler)
@ halide_target_feature_asan
Enable hooks for ASAN support.
@ halide_target_feature_cl_half
Enable half support on OpenCL targets.
@ halide_target_feature_arm_dot_prod
Enable ARMv8.2-a dotprod extension (i.e. udot and sdot instructions)
@ halide_target_feature_avx512_sapphirerapids
Enable the AVX512 features supported by Sapphire Rapids processors. This include all of the Cannonlak...
@ halide_target_feature_sse41
Use SSE 4.1 and earlier instructions. Only relevant on x86.
@ halide_target_feature_power_arch_2_07
Use POWER ISA 2.07 new instructions. Only relevant on POWERPC.
@ halide_target_feature_opencl
Enable the OpenCL runtime.
@ halide_target_feature_trace_stores
Trace all stores done by the pipeline. Equivalent to calling Func::trace_stores on every non-inlined ...
@ halide_target_feature_hexagon_dma
Enable Hexagon DMA buffers.
@ halide_target_feature_avx512
Enable the base AVX512 subset supported by all AVX512 architectures. The specific feature sets are AV...
@ halide_target_feature_avx512_knl
Enable the AVX512 features supported by Knight's Landing chips, such as the Xeon Phi x200....
@ halide_target_feature_cuda_capability50
Enable CUDA compute capability 5.0 (Maxwell)
@ halide_target_feature_hvx_v62
Enable Hexagon v62 architecture.
@ halide_target_feature_hvx_use_shared_object
Deprecated.
@ halide_target_feature_cuda
Enable the CUDA runtime. Defaults to compute capability 2.0 (Fermi)
@ halide_target_feature_armv81a
Enable ARMv8.1-a instructions.
@ halide_target_feature_cuda_capability80
Enable CUDA compute capability 8.0 (Ampere)
@ halide_target_feature_f16c
Enable x86 16-bit float support.
@ halide_target_feature_cuda_capability32
Enable CUDA compute capability 3.2 (Tegra K1)
@ halide_target_feature_jit
Generate code that will run immediately inside the calling process.
@ halide_target_feature_wasm_signext
Enable +sign-ext instructions for WebAssembly codegen.
@ halide_target_feature_avx
Use AVX 1 instructions. Only relevant on x86.
@ halide_target_feature_cuda_capability75
Enable CUDA compute capability 7.5 (Turing)
@ halide_target_feature_check_unsafe_promises
Insert assertions for promises.
@ halide_target_feature_vsx
Use VSX instructions. Only relevant on POWERPC.
@ halide_target_feature_user_context
Generated code takes a user_context pointer as first argument.
@ halide_target_feature_no_bounds_query
Disable the bounds querying functionality.
@ halide_target_feature_fuzz_float_stores
On every floating point store, set the last bit of the mantissa to zero. Pipelines for which the outp...
@ halide_target_feature_sve
Enable ARM Scalable Vector Extensions.
@ halide_target_feature_hvx_v66
Enable Hexagon v66 architecture.
void halide_free(void *user_context, void *ptr)
void halide_memoization_cache_cleanup()
Free all memory and resources associated with the memoization cache.
bool halide_semaphore_try_acquire(struct halide_semaphore_t *, int n)
halide_buffer_flags
@ halide_buffer_flag_device_dirty
@ halide_buffer_flag_host_dirty
void halide_profiler_shutdown()
Reset all profiler state.
bool halide_default_semaphore_try_acquire(struct halide_semaphore_t *, int n)
int halide_error_buffer_allocation_too_large(void *user_context, const char *buffer_name, uint64_t allocation_size, uint64_t max_size)
void halide_cond_wait(struct halide_cond *cond, struct halide_mutex *mutex)
int(* halide_do_par_for_t)(void *, halide_task_t, int, int, uint8_t *)
Set a custom method for performing a parallel for loop.
int halide_set_num_threads(int n)
Set the number of threads used by Halide's thread pool.
int halide_copy_to_host(void *user_context, struct halide_buffer_t *buf)
Copy image data from device memory to host memory.
int halide_default_do_par_for(void *user_context, halide_task_t task, int min, int size, uint8_t *closure)
The default versions of the parallel runtime functions.
int halide_msan_annotate_memory_is_initialized(void *user_context, const void *ptr, uint64_t len)
Annotate that a given range of memory has been initialized; only used when Target::MSAN is enabled.
struct halide_profiler_state * halide_profiler_get_state()
Get a pointer to the global profiler state for programmatic inspection.
halide_print_t halide_set_custom_print(halide_print_t print)
int halide_error_bad_dimensions(void *user_context, const char *func_name, int32_t dimensions_given, int32_t correct_dimensions)
int halide_mutex_array_unlock(struct halide_mutex_array *array, int entry)
int halide_error_constraint_violated(void *user_context, const char *var, int val, const char *constrained_var, int constrained_val)
int halide_default_do_loop_task(void *user_context, halide_loop_task_t f, int min, int extent, uint8_t *closure, void *task_parent)
int(* halide_task_t)(void *user_context, int task_number, uint8_t *closure)
Define halide_do_par_for to replace the default thread pool implementation.
void * halide_default_load_library(const char *name)
void halide_mutex_lock(struct halide_mutex *mutex)
A basic set of mutex and condition variable functions, which call platform specific code for mutual e...
halide_trace_event_code_t
@ halide_trace_consume
@ halide_trace_load
@ halide_trace_tag
@ halide_trace_store
@ halide_trace_begin_pipeline
@ halide_trace_end_pipeline
@ halide_trace_end_produce
@ halide_trace_produce
@ halide_trace_end_consume
@ halide_trace_end_realization
@ halide_trace_begin_realization
int halide_do_task(void *user_context, halide_task_t f, int idx, uint8_t *closure)
halide_malloc_t halide_set_custom_malloc(halide_malloc_t user_malloc)
int halide_error_device_dirty_with_no_device_support(void *user_context, const char *buffer_name)
int halide_default_semaphore_init(struct halide_semaphore_t *, int n)
void halide_msan_annotate_buffer_is_initialized_as_destructor(void *user_context, void *buffer)
void(* halide_error_handler_t)(void *, const char *)
void halide_device_release(void *user_context, const struct halide_device_interface_t *device_interface)
Release all data associated with the given device interface, in particular all resources (memory,...
int halide_error_bounds_inference_call_failed(void *user_context, const char *extern_stage_name, int result)
Halide calls the functions below on various error conditions.
void * halide_load_library(const char *name)
struct halide_mutex_array * halide_mutex_array_create(int sz)
struct halide_profiler_pipeline_stats * halide_profiler_get_pipeline_state(const char *pipeline_name)
Get a pointer to the pipeline state associated with pipeline_name.
int halide_error_buffer_extents_negative(void *user_context, const char *buffer_name, int dimension, int extent)
int halide_error_buffer_is_null(void *user_context, const char *routine)
void halide_mutex_unlock(struct halide_mutex *mutex)
void halide_shutdown_thread_pool()
int halide_error_constraints_make_required_region_smaller(void *user_context, const char *buffer_name, int dimension, int constrained_min, int constrained_extent, int required_min, int required_extent)
int32_t halide_debug_to_file(void *user_context, const char *filename, int32_t type_code, struct halide_buffer_t *buf)
Called when debug_to_file is used inside Halide code.
int halide_shutdown_trace()
If tracing is writing to a file.
int halide_error_out_of_memory(void *user_context)
int halide_error_no_device_interface(void *user_context)
void *(* halide_load_library_t)(const char *name)
int halide_error_debug_to_file_failed(void *user_context, const char *func, const char *filename, int error_code)
struct halide_dimension_t halide_dimension_t
int halide_error_requirement_failed(void *user_context, const char *condition, const char *message)
struct halide_thread * halide_spawn_thread(void(*f)(void *), void *closure)
Spawn a thread.
void halide_memoization_cache_release(void *user_context, void *host)
If halide_memoization_cache_lookup succeeds, halide_memoization_cache_release must be called to signa...
int(* halide_can_use_target_features_t)(int count, const uint64_t *features)
void halide_register_argv_and_metadata(int(*filter_argv_call)(void **), const struct halide_filter_metadata_t *filter_metadata, const char *const *extra_key_value_pairs)
halide_register_argv_and_metadata() is a user-defined function that must be provided in order to use ...
int halide_error_param_too_large_f64(void *user_context, const char *param_name, double val, double max_val)
int halide_msan_check_memory_is_initialized(void *user_context, const void *ptr, uint64_t len, const char *name)
Verify that a given range of memory has been initialized; only used when Target::MSAN is enabled.
int(* halide_do_loop_task_t)(void *, halide_loop_task_t, int, int, uint8_t *, void *)
The version of do_task called for loop tasks.
int halide_error_buffer_extents_too_large(void *user_context, const char *buffer_name, int64_t actual_size, int64_t max_size)
void * halide_default_malloc(void *user_context, size_t x)
int32_t halide_trace(void *user_context, const struct halide_trace_event_t *event)
Called when Funcs are marked as trace_load, trace_store, or trace_realization.
int halide_error_extern_stage_failed(void *user_context, const char *extern_stage_name, int result)
A call to an extern stage failed.
halide_can_use_target_features_t halide_set_custom_can_use_target_features(halide_can_use_target_features_t)
int halide_error_host_is_null(void *user_context, const char *func_name)
void halide_set_trace_file(int fd)
Set the file descriptor that Halide should write binary trace events to.
int halide_memoization_cache_store(void *user_context, const uint8_t *cache_key, int32_t size, struct halide_buffer_t *realized_bounds, int32_t tuple_count, struct halide_buffer_t **tuple_buffers, bool has_eviction_key, uint64_t eviction_key)
Given a cache key for a memoized result, currently constructed from the Func name and top-level Func ...
int halide_buffer_copy(void *user_context, struct halide_buffer_t *src, const struct halide_device_interface_t *dst_device_interface, struct halide_buffer_t *dst)
Copy data from one buffer to another.
int halide_error_fold_factor_too_small(void *user_context, const char *func_name, const char *var_name, int fold_factor, const char *loop_name, int required_extent)
int halide_error_param_too_small_f64(void *user_context, const char *param_name, double val, double min_val)
int halide_error_param_too_large_i64(void *user_context, const char *param_name, int64_t val, int64_t max_val)
int halide_error_param_too_small_u64(void *user_context, const char *param_name, uint64_t val, uint64_t min_val)
void(* halide_print_t)(void *, const char *)
Definition: HalideRuntime.h:99
halide_trace_t halide_set_custom_trace(halide_trace_t trace)
void halide_print(void *user_context, const char *)
Print a message to stderr.
bool(* halide_semaphore_try_acquire_t)(struct halide_semaphore_t *, int)
void halide_profiler_report(void *user_context)
Print out timing statistics for everything run since the last reset.
void halide_set_gpu_device(int n)
Selects which gpu device to use.
void halide_mutex_array_destroy(void *user_context, void *array)
int32_t halide_default_trace(void *user_context, const struct halide_trace_event_t *event)
@ halide_profiler_please_stop
Set current_func to this value to tell the profiling thread to halt.
@ halide_profiler_outside_of_halide
current_func takes on this value when not inside Halide code
int halide_default_can_use_target_features(int count, const uint64_t *features)
This is the default implementation of halide_can_use_target_features; it is provided for convenience ...
int halide_reuse_device_allocations(void *user_context, bool)
Tell Halide whether or not it is permitted to hold onto device allocations to service future requests...
int halide_error_param_too_small_i64(void *user_context, const char *param_name, int64_t val, int64_t min_val)
halide_type_code_t
Types in the halide type system.
@ halide_type_float
IEEE floating point numbers.
@ halide_type_handle
opaque pointer type (void *)
@ halide_type_bfloat
floating point numbers in the bfloat format
@ halide_type_int
signed integers
@ halide_type_uint
unsigned integers
int halide_device_malloc(void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
Allocate device memory to back a halide_buffer_t.
bool halide_can_reuse_device_allocations(void *user_context)
Determines whether on device_free the memory is returned immediately to the device API,...
int halide_mutex_array_lock(struct halide_mutex_array *array, int entry)
void(* halide_free_t)(void *, void *)
int(* halide_loop_task_t)(void *user_context, int min, int extent, uint8_t *closure, void *task_parent)
A task representing a serial for loop evaluated over some range.
int halide_error_specialize_fail(void *user_context, const char *message)
int halide_error_device_interface_no_device(void *user_context)
int halide_error_host_and_device_dirty(void *user_context)
int halide_error_access_out_of_bounds(void *user_context, const char *func_name, int dimension, int min_touched, int max_touched, int min_valid, int max_valid)
void *(* halide_get_symbol_t)(const char *name)
int halide_error_explicit_bounds_too_small(void *user_context, const char *func_name, const char *var_name, int min_bound, int max_bound, int min_required, int max_required)
Various other error conditions.
void * halide_malloc(void *user_context, size_t x)
Halide calls these functions to allocate and free memory.
void * halide_default_get_library_symbol(void *lib, const char *name)
int halide_error_buffer_argument_is_null(void *user_context, const char *buffer_name)
int halide_default_semaphore_release(struct halide_semaphore_t *, int n)
void halide_default_error(void *user_context, const char *)
int halide_device_slice(void *user_context, const struct halide_buffer_t *src, int slice_dim, int slice_pos, struct halide_buffer_t *dst)
Give the destination buffer a device allocation which is an alias for a similar coordinate range in t...
void halide_default_free(void *user_context, void *ptr)
void halide_memoization_cache_evict(void *user_context, uint64_t eviction_key)
Evict all cache entries that were tagged with the given eviction_key in the memoize scheduling direct...
halide_do_par_for_t halide_set_custom_do_par_for(halide_do_par_for_t do_par_for)
void halide_join_thread(struct halide_thread *)
Join a thread.
halide_error_code_t
The error codes that may be returned by a Halide pipeline.
@ halide_error_code_no_device_interface
Buffer has a non-zero device but no device interface, which violates a Halide invariant.
@ halide_error_code_bad_fold
A fold_storage directive was used on a dimension that is not accessed in a monotonically increasing o...
@ halide_error_code_fold_factor_too_small
A fold_storage directive was used with a fold factor that was too small to store all the values of a ...
@ halide_error_code_device_interface_no_device
Buffer has a non-null device_interface but device is 0, which violates a Halide invariant.
@ halide_error_code_param_too_large
A scalar parameter passed in was greater than its minimum declared value.
@ halide_error_code_param_too_small
A scalar parameter passed in was smaller than its minimum declared value.
@ halide_error_code_access_out_of_bounds
A pipeline would access memory outside of the halide_buffer_t passed in.
@ halide_error_code_specialize_fail
A specialize_fail() schedule branch was selected at runtime.
@ halide_error_code_requirement_failed
User-specified require() expression was not satisfied.
@ halide_error_code_bad_extern_fold
A folded buffer was passed to an extern stage, but the region touched wraps around the fold boundary.
@ halide_error_code_incompatible_device_interface
An operation on a buffer required an allocation on a particular device interface, but a device alloca...
@ halide_error_code_internal_error
There is a bug in the Halide compiler.
@ halide_error_code_buffer_extents_negative
At least one of the buffer's extents are negative.
@ halide_error_code_constraints_make_required_region_smaller
Applying explicit constraints on the size of an input or output buffer shrank the size of that buffer...
@ halide_error_code_unused_29
@ halide_error_code_copy_to_device_failed
The Halide runtime encountered an error while trying to copy from host to device.
@ halide_error_code_generic_error
An uncategorized error occurred.
@ halide_error_code_device_crop_failed
Cropping/slicing a buffer failed for some other reason.
@ halide_error_code_success
There was no error.
@ halide_error_code_copy_to_host_failed
The Halide runtime encountered an error while trying to copy from device to host.
@ halide_error_code_matlab_init_failed
An error occurred when attempting to initialize the Matlab runtime.
@ halide_error_code_device_sync_failed
The Halide runtime encountered an error while trying to synchronize with a device.
@ halide_error_code_buffer_argument_is_null
A halide_buffer_t pointer passed in was NULL.
@ halide_error_code_bad_dimensions
The dimensions field of a halide_buffer_t does not match the dimensions of that ImageParam.
@ halide_error_code_device_malloc_failed
The Halide runtime encountered an error while trying to allocate memory on device.
@ halide_error_code_host_and_device_dirty
Buffer has both host and device dirty bits set, which violates a Halide invariant.
@ halide_error_code_debug_to_file_failed
debug_to_file failed to open or write to the specified file.
@ halide_error_code_unused_30
@ halide_error_code_buffer_is_null
The halide_buffer_t * passed to a halide runtime routine is nullptr and this is not allowed.
@ halide_error_code_device_crop_unsupported
Attempted to make cropped/sliced alias of a buffer with a device field, but the device_interface does...
@ halide_error_code_device_buffer_copy_failed
The Halide runtime encountered an error while trying to copy from one buffer to another.
@ halide_error_code_device_free_failed
The Halide runtime encountered an error while trying to free a device allocation.
@ halide_error_code_buffer_allocation_too_large
A halide_buffer_t was given that spans more than 2GB of memory.
@ halide_error_code_bad_type
The elem_size field of a halide_buffer_t does not match the size in bytes of the type of that ImagePa...
@ halide_error_code_device_run_failed
The Halide runtime encountered an error while trying to launch a GPU kernel.
@ halide_error_code_device_dirty_with_no_device_support
A buffer with the device_dirty flag set was passed to a pipeline compiled with no device backends ena...
@ halide_error_code_explicit_bounds_too_small
A Func was given an explicit bound via Func::bound, but this was not large enough to encompass the re...
@ halide_error_code_buffer_extents_too_large
A halide_buffer_t was given with extents that multiply to a number greater than 2^31-1.
@ halide_error_code_device_detach_native_failed
The Halide runtime encountered an error while trying to detach a native device handle.
@ halide_error_code_out_of_memory
A call to halide_malloc returned NULL.
@ halide_error_code_matlab_bad_param_type
The type of an mxArray did not match the expected type.
@ halide_error_code_device_wrap_native_failed
The Halide runtime encountered an error while trying to wrap a native device handle.
@ halide_error_code_constraint_violated
A constraint on a size or stride of an input or output buffer was not met by the halide_buffer_t pass...
@ halide_error_code_unaligned_host_ptr
The Halide runtime encountered a host pointer that violated the alignment set for it by way of a call...
@ halide_error_code_host_is_null
The host field on an input or output was null, the device field was not zero, and the pipeline tries ...
void halide_memoization_cache_set_size(int64_t size)
Set the soft maximum amount of memory, in bytes, that the LRU cache will use to memoize Func results.
#define HALIDE_ALWAYS_INLINE
Definition: HalideRuntime.h:38
void halide_cond_broadcast(struct halide_cond *cond)
int halide_device_free(void *user_context, struct halide_buffer_t *buf)
Free device memory.
int halide_error_param_too_large_u64(void *user_context, const char *param_name, uint64_t val, uint64_t max_val)
int32_t(* halide_trace_t)(void *user_context, const struct halide_trace_event_t *)
int(* halide_do_task_t)(void *, halide_task_t, int, uint8_t *)
If you use the default do_par_for, you can still set a custom handler to perform each individual task...
halide_free_t halide_set_custom_free(halide_free_t user_free)
int halide_default_do_parallel_tasks(void *user_context, int num_tasks, struct halide_parallel_task_t *tasks, void *task_parent)
int halide_get_gpu_device(void *user_context)
Halide calls this to get the desired halide gpu device setting.
int(* halide_semaphore_init_t)(struct halide_semaphore_t *, int)
halide_do_loop_task_t halide_set_custom_do_loop_task(halide_do_loop_task_t do_task)
int halide_device_detach_native(void *user_context, struct halide_buffer_t *buf)
int halide_copy_to_device(void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
Copy image data from host memory to device memory.
halide_get_library_symbol_t halide_set_custom_get_library_symbol(halide_get_library_symbol_t user_get_library_symbol)
void halide_error(void *user_context, const char *)
Halide calls this function on runtime errors (for example bounds checking failures).
int halide_device_release_crop(void *user_context, struct halide_buffer_t *buf)
Release any resources associated with a cropped/sliced view of another buffer.
int halide_can_use_target_features(int count, const uint64_t *features)
This function is called internally by Halide in some situations to determine if the current execution...
int halide_error_bad_type(void *user_context, const char *func_name, uint32_t type_given, uint32_t correct_type)
halide_do_task_t halide_set_custom_do_task(halide_do_task_t do_task)
int halide_do_parallel_tasks(void *user_context, int num_tasks, struct halide_parallel_task_t *tasks, void *task_parent)
Enqueue some number of the tasks described above and wait for them to complete.
int halide_device_wrap_native(void *user_context, struct halide_buffer_t *buf, uint64_t handle, const struct halide_device_interface_t *device_interface)
Wrap or detach a native device handle, setting the device field and device_interface field as appropr...
int halide_get_trace_file(void *user_context)
Halide calls this to retrieve the file descriptor to write binary trace events to.
float halide_float16_bits_to_float(uint16_t)
Read bits representing a half precision floating point number and return the float that represents th...
int halide_error_unaligned_host_ptr(void *user_context, const char *func_name, int alignment)
void halide_register_device_allocation_pool(struct halide_device_allocation_pool *)
Register a callback to be informed when halide_reuse_device_allocations(false) is called,...
#define HALIDE_ATTRIBUTE_ALIGN(x)
int halide_msan_check_buffer_is_initialized(void *user_context, struct halide_buffer_t *buffer, const char *buf_name)
Verify that the data pointed to by the halide_buffer_t is initialized (but not the halide_buffer_t it...
int(* halide_do_parallel_tasks_t)(void *, int, struct halide_parallel_task_t *, void *task_parent)
Provide an entire custom tasking runtime via function pointers.
halide_argument_kind_t
@ halide_argument_kind_output_buffer
@ halide_argument_kind_input_scalar
@ halide_argument_kind_input_buffer
int halide_semaphore_release(struct halide_semaphore_t *, int n)
struct halide_buffer_t halide_buffer_t
The raw representation of an image passed around by generated Halide code.
Expr with_lanes(const Expr &x, int lanes)
Rewrite the expression x to have lanes lanes.
auto operator==(const Other &a, const GeneratorParam< T > &b) -> decltype(a==(T) b)
Equality comparison between GeneratorParam<T> and any type that supports operator== with T.
Definition: Generator.h:1138
auto operator<(const Other &a, const GeneratorParam< T > &b) -> decltype(a<(T) b)
Less than comparison between GeneratorParam<T> and any type that supports operator< with T.
Definition: Generator.h:1099
Expr min(const FuncRef &a, const FuncRef &b)
Explicit overloads of min and max for FuncRef.
Definition: Func.h:578
auto operator!=(const Other &a, const GeneratorParam< T > &b) -> decltype(a !=(T) b)
Inequality comparison between between GeneratorParam<T> and any type that supports operator!...
Definition: Generator.h:1151
Expr print(const std::vector< Expr > &values)
Create an Expr that prints out its value whenever it is evaluated.
char * buf
Definition: printer.h:32
char * dst
Definition: printer.h:32
void * user_context
Definition: printer.h:33
char * end
Definition: printer.h:32
unsigned __INT64_TYPE__ uint64_t
signed __INT64_TYPE__ int64_t
signed __INT32_TYPE__ int32_t
unsigned __INT8_TYPE__ uint8_t
__PTRDIFF_TYPE__ ptrdiff_t
unsigned __INT16_TYPE__ uint16_t
__SIZE_TYPE__ size_t
unsigned __INT32_TYPE__ uint32_t
signed __INT16_TYPE__ int16_t
signed __INT8_TYPE__ int8_t
void * memcpy(void *s1, const void *s2, size_t n)
The raw representation of an image passed around by generated Halide code.
void * padding
Pads the buffer up to a multiple of 8 bytes.
int32_t dimensions
The dimensionality of the buffer.
halide_dimension_t * dim
The shape of the buffer.
uint64_t device
A device-handle for e.g.
uint8_t * host
A pointer to the start of the data in main memory.
struct halide_type_t type
The type of each buffer element.
const struct halide_device_interface_t * device_interface
The interface used to interpret the above handle.
uint64_t flags
flags with various meanings.
Cross platform condition variable.
uintptr_t _private[1]
struct halide_device_allocation_pool * next
int(* release_unused)(void *user_context)
Each GPU API provides a halide_device_interface_t struct pointing to the code that manages device all...
int(* device_slice)(void *user_context, const struct halide_buffer_t *src, int slice_dim, int slice_pos, struct halide_buffer_t *dst)
int(* device_and_host_malloc)(void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
const struct halide_device_interface_impl_t * impl
int(* wrap_native)(void *user_context, struct halide_buffer_t *buf, uint64_t handle, const struct halide_device_interface_t *device_interface)
int(* compute_capability)(void *user_context, int *major, int *minor)
int(* device_release_crop)(void *user_context, struct halide_buffer_t *buf)
int(* device_crop)(void *user_context, const struct halide_buffer_t *src, struct halide_buffer_t *dst)
void(* device_release)(void *user_context, const struct halide_device_interface_t *device_interface)
int(* copy_to_host)(void *user_context, struct halide_buffer_t *buf)
int(* copy_to_device)(void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
int(* device_free)(void *user_context, struct halide_buffer_t *buf)
int(* device_sync)(void *user_context, struct halide_buffer_t *buf)
int(* detach_native)(void *user_context, struct halide_buffer_t *buf)
int(* device_and_host_free)(void *user_context, struct halide_buffer_t *buf)
int(* device_malloc)(void *user_context, struct halide_buffer_t *buf, const struct halide_device_interface_t *device_interface)
int(* buffer_copy)(void *user_context, struct halide_buffer_t *src, const struct halide_device_interface_t *dst_device_interface, struct halide_buffer_t *dst)
Obsolete version of halide_filter_argument_t; only present in code that wrote halide_filter_metadata_...
const struct halide_scalar_value_t * min
const struct halide_scalar_value_t * def
const struct halide_scalar_value_t * max
struct halide_type_t type
halide_filter_argument_t is essentially a plain-C-struct equivalent to Halide::Argument; most user co...
const struct halide_scalar_value_t * scalar_estimate
const struct halide_scalar_value_t * scalar_max
int64_t const *const * buffer_estimates
const struct halide_scalar_value_t * scalar_def
struct halide_type_t type
const struct halide_scalar_value_t * scalar_min
const char * name
The function name of the filter.
int32_t version
version of this metadata; currently always 1.
const struct halide_filter_argument_t * arguments
An array of the filters input and output arguments; this will never be null.
int32_t num_arguments
The number of entries in the arguments field.
const char * target
The Target for which the filter was compiled.
A type traits template to provide a halide_handle_cplusplus_type value from a C++ type.
Definition: Type.h:246
struct halide_mutex * array
Cross-platform mutex.
uintptr_t _private[1]
A parallel task to be passed to halide_do_parallel_tasks.
struct halide_semaphore_acquire_t * semaphores
halide_loop_task_t fn
The functions below here are relevant for pipelines compiled with the -profile target flag,...
uint64_t memory_peak
The peak memory allocation of this Func.
const char * name
The name of this Func.
uint64_t stack_peak
The peak stack allocation of this Func's threads.
int num_allocs
The total number of memory allocation of this Func.
uint64_t active_threads_numerator
The average number of thread pool worker threads active while computing this Func.
uint64_t memory_total
The total memory allocation of this Func.
uint64_t time
Total time taken evaluating this Func (in nanoseconds).
uint64_t memory_current
The current memory allocation of this Func.
Per-pipeline state tracked by the sampling profiler.
int samples
The total number of samples taken inside of this pipeline.
uint64_t time
Total time spent inside this pipeline (in nanoseconds)
const char * name
The name of this pipeline.
int first_func_id
An internal base id used to identify the funcs in this pipeline.
int num_allocs
The total number of memory allocation of funcs in this pipeline.
void * next
The next pipeline_stats pointer.
uint64_t memory_current
The current memory allocation of funcs in this pipeline.
int num_funcs
The number of funcs in this pipeline.
uint64_t memory_peak
The peak memory allocation of funcs in this pipeline.
struct halide_profiler_func_stats * funcs
An array containing states for each Func in this pipeline.
int runs
The number of times this pipeline has been run.
uint64_t memory_total
The total memory allocation of funcs in this pipeline.
uint64_t active_threads_numerator
The average number of thread pool worker threads doing useful work while computing this pipeline.
The global state of the profiler.
void(* get_remote_profiler_state)(int *func, int *active_workers)
Retrieve remote profiler state.
struct halide_thread * sampling_thread
Sampling thread reference to be joined at shutdown.
int sleep_time
The amount of time the profiler thread sleeps between samples in milliseconds.
int current_func
The id of the current running Func.
int first_free_id
An internal id used for bookkeeping.
struct halide_profiler_pipeline_stats * pipelines
A linked list of stats gathered for each pipeline.
struct halide_mutex lock
Guards access to the fields below.
int active_threads
The number of threads currently doing work.
halide_scalar_value_t is a simple union able to represent all the well-known scalar values in a filte...
union halide_scalar_value_t::@3 u
A struct representing a semaphore and a number of items that must be acquired from it.
struct halide_semaphore_t * semaphore
An opaque struct representing a semaphore.
uint64_t _private[2]
void * value
If the event type is a load or a store, this points to the value being loaded or stored.
int32_t * coordinates
For loads and stores, an array which contains the location being accessed.
const char * func
The name of the Func or Pipeline that this event refers to.
const char * trace_tag
For halide_trace_tag, this points to a read-only null-terminated string of arbitrary text.
struct halide_type_t type
If the event type is a load or a store, this is the type of the data.
int32_t value_index
If this was a load or store of a Tuple-valued Func, this is which tuple element was accessed.
enum halide_trace_event_code_t event
The type of event.
int32_t dimensions
The length of the coordinates array.
The header of a packet in a binary trace.
uint32_t size
The total size of this packet in bytes.
int32_t id
The id of this packet (for the purpose of parent_id).
enum halide_trace_event_code_t event
struct halide_type_t type
The remaining fields are equivalent to those in halide_trace_event_t.
A runtime tag for a type in the halide type system.
uint8_t bits
The number of bits of precision of a single scalar value of this type.
uint16_t lanes
How many elements in a vector.
uint8_t code
The basic type code: signed integer, unsigned integer, or floating point.