Halide  20.0.0
Halide compiler and libraries
Parameter.h
Go to the documentation of this file.
1 #ifndef HALIDE_PARAMETER_H
2 #define HALIDE_PARAMETER_H
3 
4 /** \file
5  * Defines the internal representation of parameters to halide piplines
6  */
7 #include <optional>
8 #include <string>
9 
10 #include "Buffer.h"
11 #include "IntrusivePtr.h"
12 #include "Type.h"
13 #include "Util.h" // for HALIDE_NO_USER_CODE_INLINE
14 #include "runtime/HalideRuntime.h" // for HALIDE_ALWAYS_INLINE
15 
16 namespace Halide {
17 
18 struct ArgumentEstimates;
19 struct Expr;
20 struct Type;
21 enum class MemoryType;
22 
26 };
27 
28 namespace Internal {
29 
30 #ifdef WITH_SERIALIZATION
31 class Deserializer;
32 class Serializer;
33 #endif
34 struct ParameterContents;
35 
36 } // namespace Internal
37 
38 /** A reference-counted handle to a parameter to a halide
39  * pipeline. May be a scalar parameter or a buffer */
40 class Parameter {
41  void check_defined() const;
42  void check_is_buffer() const;
43  void check_is_scalar() const;
44  void check_dim_ok(int dim) const;
45  void check_type(const Type &t) const;
46 
47 protected:
49 
50 #ifdef WITH_SERIALIZATION
51  friend class Internal::Deserializer; //< for scalar_data()
52  friend class Internal::Serializer; //< for scalar_data()
53 #endif
54  friend class Pipeline; //< for read_only_scalar_address()
55 
56  /** Get the raw currently-bound buffer. null if unbound */
57  const halide_buffer_t *raw_buffer() const;
58 
59  /** Get the pointer to the current value of the scalar
60  * parameter. For a given parameter, this address will never
61  * change. Note that this can only be used to *read* from -- it must
62  * not be written to, so don't cast away the constness. Only relevant when jitting. */
63  const void *read_only_scalar_address() const;
64 
65  /** If the Parameter is a scalar, and the scalar data is valid, return
66  * the scalar data. Otherwise, return nullopt. */
67  std::optional<halide_scalar_value_t> scalar_data() const;
68 
69  /** If the Parameter is a scalar and has a valid scalar value, return it.
70  * Otherwise, assert-fail. */
72 
73  /** If the Parameter is a scalar *of the given type* and has a valid scalar value, return it.
74  * Otherwise, assert-fail. */
76 
77  /** Construct a new buffer parameter via deserialization. */
78  Parameter(const Type &t, int dimensions, const std::string &name,
79  const Buffer<void> &buffer, int host_alignment, const std::vector<BufferConstraint> &buffer_constraints,
81 
82  /** Construct a new scalar parameter via deserialization. */
83  Parameter(const Type &t, int dimensions, const std::string &name,
84  const std::optional<halide_scalar_value_t> &scalar_data, const Expr &scalar_default, const Expr &scalar_min,
85  const Expr &scalar_max, const Expr &scalar_estimate);
86 
87 public:
88  /** Construct a new undefined handle */
89  Parameter() = default;
90 
91  /** Construct a new parameter of the given type. If the second
92  * argument is true, this is a buffer parameter of the given
93  * dimensionality, otherwise, it is a scalar parameter (and the
94  * dimensionality should be zero). The parameter will be given a
95  * unique auto-generated name. */
96  Parameter(const Type &t, bool is_buffer, int dimensions);
97 
98  /** Construct a new parameter of the given type with name given by
99  * the third argument. If the second argument is true, this is a
100  * buffer parameter, otherwise, it is a scalar parameter. The
101  * third argument gives the dimensionality of the buffer
102  * parameter. It should be zero for scalar parameters. If the
103  * fifth argument is true, the the name being passed in was
104  * explicitly specified (as opposed to autogenerated). */
105  Parameter(const Type &t, bool is_buffer, int dimensions, const std::string &name);
106 
107  Parameter(const Parameter &) = default;
108  Parameter &operator=(const Parameter &) = default;
109  Parameter(Parameter &&) = default;
110  Parameter &operator=(Parameter &&) = default;
111 
112  /** Get the type of this parameter */
113  Type type() const;
114 
115  /** Get the dimensionality of this parameter. Zero for scalars. */
116  int dimensions() const;
117 
118  /** Get the name of this parameter */
119  const std::string &name() const;
120 
121  /** Does this parameter refer to a buffer/image? */
122  bool is_buffer() const;
123 
124  /** If the parameter is a scalar parameter, get its currently
125  * bound value. Only relevant when jitting */
126  template<typename T>
128  static_assert(sizeof(T) <= sizeof(halide_scalar_value_t));
129  const auto sv = scalar_data_checked(type_of<T>());
130  T t;
131  memcpy(&t, &sv.u.u64, sizeof(t));
132  return t;
133  }
134 
135  /** This returns the current value of scalar<type()>() as an Expr.
136  * If the Parameter is not scalar, or its scalar data is not valid, this will assert-fail. */
137  Expr scalar_expr() const;
138 
139  /** This returns true if scalar_expr() would return a valid Expr,
140  * false if not. */
141  bool has_scalar_value() const;
142 
143  /** If the parameter is a scalar parameter, set its current
144  * value. Only relevant when jitting */
145  template<typename T>
148  memcpy(&sv.u.u64, &val, sizeof(val));
149  set_scalar(type_of<T>(), sv);
150  }
151 
152  /** If the parameter is a scalar parameter, set its current
153  * value. Only relevant when jitting */
154  void set_scalar(const Type &val_type, halide_scalar_value_t val);
155 
156  /** If the parameter is a buffer parameter, get its currently
157  * bound buffer. Only relevant when jitting */
159 
160  /** If the parameter is a buffer parameter, set its current
161  * value. Only relevant when jitting */
162  void set_buffer(const Buffer<void> &b);
163 
164  /** Tests if this handle is the same as another handle */
165  bool same_as(const Parameter &other) const;
166 
167  /** Tests if this handle is non-nullptr */
168  bool defined() const;
169 
170  /** Get and set constraints for the min, extent, stride, and estimates on
171  * the min/extent. */
172  //@{
173  void set_min_constraint(int dim, const Expr &e);
174  void set_extent_constraint(int dim, const Expr &e);
175  void set_stride_constraint(int dim, const Expr &e);
176  void set_min_constraint_estimate(int dim, const Expr &min);
177  void set_extent_constraint_estimate(int dim, const Expr &extent);
178  void set_host_alignment(int bytes);
179  Expr min_constraint(int dim) const;
180  Expr extent_constraint(int dim) const;
181  Expr stride_constraint(int dim) const;
184  int host_alignment() const;
185  //@}
186 
187  /** Get buffer constraints for all dimensions,
188  * only relevant when serializing. */
189  const std::vector<BufferConstraint> &buffer_constraints() const;
190 
191  /** Get and set constraints for scalar parameters. These are used
192  * directly by Param, so they must be exported. */
193  // @{
194  void set_min_value(const Expr &e);
195  Expr min_value() const;
196  void set_max_value(const Expr &e);
197  Expr max_value() const;
199  Expr estimate() const;
200  // @}
201 
202  /** Get and set the default values for scalar parameters. At present, these
203  * are used only to emit the default values in the metadata. There isn't
204  * yet a public API in Param<> for them (this is used internally by the
205  * Generator code). */
206  // @{
207  void set_default_value(const Expr &e);
209  // @}
210 
211  /** Order Parameters by their IntrusivePtr so they can be used
212  * to index maps. */
213  bool operator<(const Parameter &other) const {
214  return contents < other.contents;
215  }
216 
217  /** Get the ArgumentEstimates appropriate for this Parameter. */
219 
222 };
223 
224 namespace Internal {
225 
226 /** Validate arguments to a call to a func, image or imageparam. */
227 void check_call_arg_types(const std::string &name, std::vector<Expr> *args, int dims);
228 
229 } // namespace Internal
230 } // namespace Halide
231 
232 #endif
This file declares the routines used by Halide internally in its runtime.
Support classes for reference-counting via intrusive shared pointers.
Defines halide types.
Various utility functions used internally Halide.
#define HALIDE_NO_USER_CODE_INLINE
Definition: Util.h:47
A reference-counted handle to a parameter to a halide pipeline.
Definition: Parameter.h:40
const std::string & name() const
Get the name of this parameter.
void set_stride_constraint(int dim, const Expr &e)
void set_default_value(const Expr &e)
Get and set the default values for scalar parameters.
std::optional< halide_scalar_value_t > scalar_data() const
If the Parameter is a scalar, and the scalar data is valid, return the scalar data.
Buffer< void > buffer() const
If the parameter is a buffer parameter, get its currently bound buffer.
const void * read_only_scalar_address() const
Get the pointer to the current value of the scalar parameter.
void set_min_constraint_estimate(int dim, const Expr &min)
void store_in(MemoryType memory_type)
void set_extent_constraint_estimate(int dim, const Expr &extent)
Expr default_value() const
int dimensions() const
Get the dimensionality of this parameter.
Parameter & operator=(Parameter &&)=default
Expr estimate() const
void set_max_value(const Expr &e)
void set_min_constraint(int dim, const Expr &e)
Get and set constraints for the min, extent, stride, and estimates on the min/extent.
Expr max_value() const
void set_extent_constraint(int dim, const Expr &e)
Parameter(const Type &t, bool is_buffer, int dimensions, const std::string &name)
Construct a new parameter of the given type with name given by the third argument.
HALIDE_NO_USER_CODE_INLINE T scalar() const
If the parameter is a scalar parameter, get its currently bound value.
Definition: Parameter.h:127
bool defined() const
Tests if this handle is non-nullptr.
void set_buffer(const Buffer< void > &b)
If the parameter is a buffer parameter, set its current value.
Expr stride_constraint(int dim) const
Parameter(const Type &t, int dimensions, const std::string &name, const Buffer< void > &buffer, int host_alignment, const std::vector< BufferConstraint > &buffer_constraints, MemoryType memory_type)
Construct a new buffer parameter via deserialization.
void set_min_value(const Expr &e)
Get and set constraints for scalar parameters.
Expr min_constraint(int dim) const
bool has_scalar_value() const
This returns true if scalar_expr() would return a valid Expr, false if not.
halide_scalar_value_t scalar_data_checked(const Type &val_type) const
If the Parameter is a scalar of the given type and has a valid scalar value, return it.
bool is_buffer() const
Does this parameter refer to a buffer/image?
Expr min_value() const
HALIDE_NO_USER_CODE_INLINE void set_scalar(T val)
If the parameter is a scalar parameter, set its current value.
Definition: Parameter.h:146
void set_host_alignment(int bytes)
void set_estimate(Expr e)
Internal::IntrusivePtr< Internal::ParameterContents > contents
Definition: Parameter.h:48
Parameter(Parameter &&)=default
halide_scalar_value_t scalar_data_checked() const
If the Parameter is a scalar and has a valid scalar value, return it.
Type type() const
Get the type of this parameter.
Expr extent_constraint_estimate(int dim) const
ArgumentEstimates get_argument_estimates() const
Get the ArgumentEstimates appropriate for this Parameter.
const halide_buffer_t * raw_buffer() const
Get the raw currently-bound buffer.
Expr min_constraint_estimate(int dim) const
int host_alignment() const
MemoryType memory_type() const
Expr extent_constraint(int dim) const
void set_scalar(const Type &val_type, halide_scalar_value_t val)
If the parameter is a scalar parameter, set its current value.
Parameter(const Type &t, bool is_buffer, int dimensions)
Construct a new parameter of the given type.
Parameter(const Type &t, int dimensions, const std::string &name, const std::optional< halide_scalar_value_t > &scalar_data, const Expr &scalar_default, const Expr &scalar_min, const Expr &scalar_max, const Expr &scalar_estimate)
Construct a new scalar parameter via deserialization.
Expr scalar_expr() const
This returns the current value of scalar<type()>() as an Expr.
const std::vector< BufferConstraint > & buffer_constraints() const
Get buffer constraints for all dimensions, only relevant when serializing.
Parameter(const Parameter &)=default
Parameter & operator=(const Parameter &)=default
bool operator<(const Parameter &other) const
Order Parameters by their IntrusivePtr so they can be used to index maps.
Definition: Parameter.h:213
bool same_as(const Parameter &other) const
Tests if this handle is the same as another handle.
Parameter()=default
Construct a new undefined handle.
A class representing a Halide pipeline.
Definition: Pipeline.h:107
void check_call_arg_types(const std::string &name, std::vector< Expr > *args, int dims)
Validate arguments to a call to a func, image or imageparam.
This file defines the class FunctionDAG, which is our representation of a Halide pipeline,...
@ Internal
Not visible externally, similar to 'static' linkage in C.
Expr min(const FuncRef &a, const FuncRef &b)
Explicit overloads of min and max for FuncRef.
Definition: Func.h:597
MemoryType
An enum describing different address spaces to be used with Func::store_in.
Definition: Expr.h:353
void * memcpy(void *s1, const void *s2, size_t n)
A fragment of Halide syntax.
Definition: Expr.h:258
Types in the halide type system.
Definition: Type.h:283
The raw representation of an image passed around by generated Halide code.
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