X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fuser.pod;h=de7eac4576f49ef45a28ec2c5866c4a336170e1d;hb=999b97bd04b351afdb131ffd7023fde5e6a716bf;hp=0d82edd70c1c55c20e933be4cf3c41999bb9aef9;hpb=fa527194c2d9eb4282d50fe468feaf411884b911;p=platform%2Fupstream%2Fisl.git diff --git a/doc/user.pod b/doc/user.pod index 0d82edd..de7eac4 100644 --- a/doc/user.pod +++ b/doc/user.pod @@ -160,6 +160,12 @@ dimension manipulation on the result. =item * The C option has been replaced by the C option. +=item * The first argument of C is now +an C instead of an C. +A call C can be replaced by + + isl_pw_aff_cond(isl_set_indicator_function(a), b, c) + =back =head1 Installation @@ -658,6 +664,8 @@ of the original object. __isl_keep isl_pw_multi_aff *pma); __isl_give isl_space *isl_pw_multi_aff_get_space( __isl_keep isl_pw_multi_aff *pma); + __isl_give isl_space *isl_union_pw_multi_aff_get_space( + __isl_keep isl_union_pw_multi_aff *upma); #include __isl_give isl_space *isl_point_get_space( @@ -676,11 +684,15 @@ using the following functions. __isl_give isl_id *isl_space_get_dim_id( __isl_keep isl_space *space, enum isl_dim_type type, unsigned pos); - __isl_give isl_space *isl_space_set_dim_name(__isl_take isl_space *space, - enum isl_dim_type type, unsigned pos, - __isl_keep const char *name); - __isl_keep const char *isl_space_get_dim_name(__isl_keep isl_space *space, - enum isl_dim_type type, unsigned pos); + __isl_give isl_space *isl_space_set_dim_name( + __isl_take isl_space *space, + enum isl_dim_type type, unsigned pos, + __isl_keep const char *name); + int isl_space_has_dim_name(__isl_keep isl_space *space, + enum isl_dim_type type, unsigned pos); + __isl_keep const char *isl_space_get_dim_name( + __isl_keep isl_space *space, + enum isl_dim_type type, unsigned pos); Note that C returns a pointer to some internal data structure, so the result can only be used while the @@ -1266,8 +1278,8 @@ C and C for sets and of C, C, C, C and C for relations. -A (basic) set or relation can also be constructed from a (piecewise) -(multiple) affine expression +A (basic or union) set or relation can also be constructed from a +(union) (piecewise) (multiple) affine expression or a list of affine expressions (See L<"Piecewise Quasi Affine Expressions"> and L<"Piecewise Multiple Quasi Affine Expressions">). @@ -1283,10 +1295,15 @@ L<"Piecewise Multiple Quasi Affine Expressions">). __isl_take isl_aff_list *list); __isl_give isl_basic_map *isl_basic_map_from_multi_aff( __isl_take isl_multi_aff *maff) + __isl_give isl_map *isl_map_from_multi_aff( + __isl_take isl_multi_aff *maff) __isl_give isl_set *isl_set_from_pw_multi_aff( __isl_take isl_pw_multi_aff *pma); __isl_give isl_map *isl_map_from_pw_multi_aff( __isl_take isl_pw_multi_aff *pma); + __isl_give isl_union_map * + isl_union_map_from_union_pw_multi_aff( + __isl_take isl_union_pw_multi_aff *upma); The C argument describes the domain of the resulting basic relation. It is required because the C may consist @@ -1573,6 +1590,8 @@ read off using the following functions. const char *isl_basic_set_get_dim_name( __isl_keep isl_basic_set *bset, enum isl_dim_type type, unsigned pos); + int isl_set_has_dim_name(__isl_keep isl_set *set, + enum isl_dim_type type, unsigned pos); const char *isl_set_get_dim_name( __isl_keep isl_set *set, enum isl_dim_type type, unsigned pos); @@ -1715,6 +1734,9 @@ i.e., whether both domain and range are nested relations. =item * Subset + int isl_basic_set_is_subset( + __isl_keep isl_basic_set *bset1, + __isl_keep isl_basic_set *bset2); int isl_set_is_subset(__isl_keep isl_set *set1, __isl_keep isl_set *set2); int isl_set_is_strict_subset( @@ -1856,12 +1878,20 @@ dimension has the fixed given value. __isl_give isl_basic_map *isl_basic_map_lower_bound_si( __isl_take isl_basic_map *bmap, enum isl_dim_type type, unsigned pos, int value); + __isl_give isl_set *isl_set_lower_bound( + __isl_take isl_set *set, + enum isl_dim_type type, unsigned pos, + isl_int value); __isl_give isl_set *isl_set_lower_bound_si( __isl_take isl_set *set, enum isl_dim_type type, unsigned pos, int value); __isl_give isl_map *isl_map_lower_bound_si( __isl_take isl_map *map, enum isl_dim_type type, unsigned pos, int value); + __isl_give isl_set *isl_set_upper_bound( + __isl_take isl_set *set, + enum isl_dim_type type, unsigned pos, + isl_int value); __isl_give isl_set *isl_set_upper_bound_si( __isl_take isl_set *set, enum isl_dim_type type, unsigned pos, int value); @@ -1870,7 +1900,7 @@ dimension has the fixed given value. enum isl_dim_type type, unsigned pos, int value); Intersect the set or relation with the half-space where the given -dimension has a value bounded the fixed given value. +dimension has a value bounded by the fixed given value. __isl_give isl_set *isl_set_equate(__isl_take isl_set *set, enum isl_dim_type type1, int pos1, @@ -1932,6 +1962,17 @@ basic set or relation. __isl_give isl_union_map *isl_union_map_coalesce( __isl_take isl_union_map *umap); +One of the methods for combining pairs of basic sets or relations +can result in coefficients that are much larger than those that appear +in the constraints of the input. By default, the coefficients are +not allowed to grow larger, but this can be changed by unsetting +the following option. + + int isl_options_set_coalesce_bounded_wrapping( + isl_ctx *ctx, int val); + int isl_options_get_coalesce_bounded_wrapping( + isl_ctx *ctx); + =item * Detecting equalities __isl_give isl_basic_set *isl_basic_set_detect_equalities( @@ -2098,6 +2139,15 @@ dualization algorithms or skip the elimination step. =item * Power + __isl_give isl_map *isl_map_fixed_power( + __isl_take isl_map *map, isl_int exp); + __isl_give isl_union_map *isl_union_map_fixed_power( + __isl_take isl_union_map *umap, isl_int exp); + +Compute the given power of C, where C is assumed to be non-zero. +If the exponent C is negative, then the -C th power of the inverse +of C is computed. + __isl_give isl_map *isl_map_power(__isl_take isl_map *map, int *exact); __isl_give isl_union_map *isl_union_map_power( @@ -2694,6 +2744,35 @@ Lists can be printed using __isl_take isl_printer *p, __isl_keep isl_set_list *list); +=head2 Vectors + +Vectors can be created, copied and freed using the following functions. + + #include + __isl_give isl_vec *isl_vec_alloc(isl_ctx *ctx, + unsigned size); + __isl_give isl_vec *isl_vec_copy(__isl_keep isl_vec *vec); + void isl_vec_free(__isl_take isl_vec *vec); + +Note that the elements of a newly created vector may have arbitrary values. +The elements can be changed and inspected using the following functions. + + isl_ctx *isl_vec_get_ctx(__isl_keep isl_vec *vec); + int isl_vec_size(__isl_keep isl_vec *vec); + int isl_vec_get_element(__isl_keep isl_vec *vec, + int pos, isl_int *v); + __isl_give isl_vec *isl_vec_set_element( + __isl_take isl_vec *vec, int pos, isl_int v); + __isl_give isl_vec *isl_vec_set_element_si( + __isl_take isl_vec *vec, int pos, int v); + __isl_give isl_vec *isl_vec_set(__isl_take isl_vec *vec, + isl_int v); + __isl_give isl_vec *isl_vec_set_si(__isl_take isl_vec *vec, + int v); + +C will return a negative value if anything went wrong. +In that case, the value of C<*v> is undefined. + =head2 Matrices Matrices can be created, copied and freed using the following functions. @@ -2755,6 +2834,13 @@ be created using the following functions. __isl_give isl_pw_aff *isl_pw_aff_from_aff( __isl_take isl_aff *aff); +A piecewise quasi affine expression that is equal to 1 on a set +and 0 outside the set can be created using the following function. + + #include + __isl_give isl_pw_aff *isl_set_indicator_function( + __isl_take isl_set *set); + Quasi affine expressions can be copied and freed using #include @@ -2819,6 +2905,7 @@ The expression can be inspected using __isl_give isl_aff *isl_aff_get_div( __isl_keep isl_aff *aff, int pos); + int isl_pw_aff_n_piece(__isl_keep isl_pw_aff *pwaff); int isl_pw_aff_foreach_piece(__isl_keep isl_pw_aff *pwaff, int (*fn)(__isl_take isl_set *set, __isl_take isl_aff *aff, @@ -3069,14 +3156,14 @@ of C where C is non-negative. #include __isl_give isl_pw_aff *isl_pw_aff_cond( - __isl_take isl_set *cond, + __isl_take isl_pw_aff *cond, __isl_take isl_pw_aff *pwaff_true, __isl_take isl_pw_aff *pwaff_false); The function C performs a conditional operator and returns an expression that is equal to C -for elements in C and equal to C for elements -not in C. +for elements where C is non-zero and equal to C for elements +where C is zero. #include __isl_give isl_pw_aff *isl_pw_aff_union_min( @@ -3127,16 +3214,39 @@ following function. __isl_take isl_space *space, __isl_take isl_aff_list *list); -An empty piecewise multiple quasi affine expression (one with no cells) or -a piecewise multiple quasi affine expression with a single cell can -be created using the following functions. +An empty piecewise multiple quasi affine expression (one with no cells), +the zero piecewise multiple quasi affine expression (with value zero +for each output dimension), +a piecewise multiple quasi affine expression with a single cell (with +either a universe or a specified domain) or +a zero-dimensional piecewise multiple quasi affine expression +on a given domain +can be created using the following functions. #include __isl_give isl_pw_multi_aff *isl_pw_multi_aff_empty( __isl_take isl_space *space); + __isl_give isl_multi_aff *isl_multi_aff_zero( + __isl_take isl_space *space); + __isl_give isl_pw_multi_aff * + isl_pw_multi_aff_from_multi_aff( + __isl_take isl_multi_aff *ma); __isl_give isl_pw_multi_aff *isl_pw_multi_aff_alloc( __isl_take isl_set *set, __isl_take isl_multi_aff *maff); + __isl_give isl_pw_multi_aff *isl_pw_multi_aff_from_domain( + __isl_take isl_set *set); + + __isl_give isl_union_pw_multi_aff * + isl_union_pw_multi_aff_empty( + __isl_take isl_space *space); + __isl_give isl_union_pw_multi_aff * + isl_union_pw_multi_aff_add_pw_multi_aff( + __isl_take isl_union_pw_multi_aff *upma, + __isl_take isl_pw_multi_aff *pma); + __isl_give isl_union_pw_multi_aff * + isl_union_pw_multi_aff_from_domain( + __isl_take isl_union_set *uset); A piecewise multiple quasi affine expression can also be initialized from an C or C, provided the C is a singleton @@ -3159,6 +3269,12 @@ Multiple quasi affine expressions can be copied and freed using void *isl_pw_multi_aff_free( __isl_take isl_pw_multi_aff *pma); + __isl_give isl_union_pw_multi_aff * + isl_union_pw_multi_aff_copy( + __isl_keep isl_union_pw_multi_aff *upma); + void *isl_union_pw_multi_aff_free( + __isl_take isl_union_pw_multi_aff *upma); + The expression can be inspected using #include @@ -3166,6 +3282,8 @@ The expression can be inspected using __isl_keep isl_multi_aff *maff); isl_ctx *isl_pw_multi_aff_get_ctx( __isl_keep isl_pw_multi_aff *pma); + isl_ctx *isl_union_pw_multi_aff_get_ctx( + __isl_keep isl_union_pw_multi_aff *upma); unsigned isl_multi_aff_dim(__isl_keep isl_multi_aff *maff, enum isl_dim_type type); unsigned isl_pw_multi_aff_dim( @@ -3200,9 +3318,17 @@ The expression can be inspected using __isl_take isl_multi_aff *maff, void *user), void *user); + int isl_union_pw_multi_aff_foreach_pw_multi_aff( + __isl_keep isl_union_pw_multi_aff *upma, + int (*fn)(__isl_take isl_pw_multi_aff *pma, + void *user), void *user); + It can be modified using #include + __isl_give isl_multi_aff *isl_multi_aff_set_aff( + __isl_take isl_multi_aff *multi, int pos, + __isl_take isl_aff *aff); __isl_give isl_multi_aff *isl_multi_aff_set_dim_name( __isl_take isl_multi_aff *maff, enum isl_dim_type type, unsigned pos, const char *s); @@ -3235,6 +3361,9 @@ Operations include __isl_give isl_pw_multi_aff *isl_pw_multi_aff_add( __isl_take isl_pw_multi_aff *pma1, __isl_take isl_pw_multi_aff *pma2); + __isl_give isl_union_pw_multi_aff *isl_union_pw_multi_aff_add( + __isl_take isl_union_pw_multi_aff *upma1, + __isl_take isl_union_pw_multi_aff *upma2); __isl_give isl_pw_multi_aff *isl_pw_multi_aff_union_add( __isl_take isl_pw_multi_aff *pma1, __isl_take isl_pw_multi_aff *pma2); @@ -3266,6 +3395,19 @@ Operations include __isl_take isl_set *set); __isl_give isl_set *isl_pw_multi_aff_domain( __isl_take isl_pw_multi_aff *pma); + __isl_give isl_union_set *isl_union_pw_multi_aff_domain( + __isl_take isl_union_pw_multi_aff *upma); + __isl_give isl_multi_aff *isl_multi_aff_flat_range_product( + __isl_take isl_multi_aff *ma1, + __isl_take isl_multi_aff *ma2); + __isl_give isl_pw_multi_aff * + isl_pw_multi_aff_flat_range_product( + __isl_take isl_pw_multi_aff *pma1, + __isl_take isl_pw_multi_aff *pma2); + __isl_give isl_union_pw_multi_aff * + isl_union_pw_multi_aff_flat_range_product( + __isl_take isl_union_pw_multi_aff *upma1, + __isl_take isl_union_pw_multi_aff *upma2); If the C argument of C is not C, then it is assigned the local space that lies at the basis of @@ -3288,6 +3430,9 @@ An expression can be printed using __isl_give isl_printer *isl_printer_print_pw_multi_aff( __isl_take isl_printer *p, __isl_keep isl_pw_multi_aff *pma); + __isl_give isl_printer *isl_printer_print_union_pw_multi_aff( + __isl_take isl_printer *p, + __isl_keep isl_union_pw_multi_aff *upma); =head2 Points @@ -3506,7 +3651,7 @@ functions. __isl_give isl_union_pw_qpolynomial *isl_union_pw_qpolynomial_copy( __isl_keep isl_union_pw_qpolynomial *upwqp); - void isl_union_pw_qpolynomial_free( + void *isl_union_pw_qpolynomial_free( __isl_take isl_union_pw_qpolynomial *upwqp); =head3 Inspecting (Piecewise) Quasipolynomials @@ -3765,7 +3910,7 @@ following functions. __isl_take isl_qpolynomial_fold *fold); void *isl_pw_qpolynomial_fold_free( __isl_take isl_pw_qpolynomial_fold *pwf); - void isl_union_pw_qpolynomial_fold_free( + void *isl_union_pw_qpolynomial_fold_free( __isl_take isl_union_pw_qpolynomial_fold *upwf); =head3 Printing Piecewise Quasipolynomial Reductions @@ -4083,7 +4228,7 @@ the following operation. Given a relation between sink iterations and potential soure iterations from a particular source domain, what is the last potential source iteration corresponding to each sink iteration. It can sometimes be convenient to adjust -the set of potential source iterations before each such operation. +the set of potential source iterations before or after each such operation. The prototypical example is fuzzy array dataflow analysis, where we need to analyze if, based on data-dependent constraints, the sink iteration can ever be executed without one or more of @@ -4095,29 +4240,63 @@ function. #include - typedef __isl_give isl_set *(*isl_access_restrict_sources)( - __isl_take isl_map *source_map, - void *sink_user, void *source_user); - __isl_give isl_access_info * - isl_access_info_set_restrict_sources( + typedef __isl_give isl_restriction *(*isl_access_restrict)( + __isl_keep isl_map *source_map, + __isl_keep isl_set *sink, void *source_user, + void *user); + __isl_give isl_access_info *isl_access_info_set_restrict( __isl_take isl_access_info *acc, - isl_access_restrict_sources fn); + isl_access_restrict fn, void *user); -The function C should be called -before C and registers a callback function +The function C should be called +before calling C and registers a callback function that will be called any time C is about to compute the last potential source. The first argument is the (reverse) proto-dependence, mapping sink iterations to potential source iterations. -The other two arguments are the tokens corresponding to the sink -and the source. The callback is expected to return a set -that restricts the source iterations. The potential source iterations -will be intersected with this set. If no restrictions are required -for a given C, then the callback should return +The second argument represents the sink iterations for which +we want to compute the last source iteration. +The third argument is the token corresponding to the source +and the final argument is the token passed to C. +The callback is expected to return a restriction on either the input or +the output of the operation computing the last potential source. +If the input needs to be restricted then restrictions are needed +for both the source and the sink iterations. The sink iterations +and the potential source iterations will be intersected with these sets. +If the output needs to be restricted then only a restriction on the source +iterations is required. +If any error occurs, the callback should return C. +An C object can be created and freed using the following +functions. - isl_set_universe( - isl_space_range(isl_map_get_space(source_map))); + #include -If any error occurs, the callback should return C. + __isl_give isl_restriction *isl_restriction_input( + __isl_take isl_set *source_restr, + __isl_take isl_set *sink_restr); + __isl_give isl_restriction *isl_restriction_output( + __isl_take isl_set *source_restr); + __isl_give isl_restriction *isl_restriction_none( + __isl_keep isl_map *source_map); + __isl_give isl_restriction *isl_restriction_empty( + __isl_keep isl_map *source_map); + void *isl_restriction_free( + __isl_take isl_restriction *restr); + +C and C are special +cases of C. C +is essentially equivalent to + + isl_restriction_input(isl_set_universe( + isl_space_range(isl_map_get_space(source_map))), + isl_set_universe( + isl_space_domain(isl_map_get_space(source_map)))); + +whereas C is essentially equivalent to + + isl_restriction_input(isl_set_empty( + isl_space_range(isl_map_get_space(source_map))), + isl_set_universe( + isl_space_domain(isl_map_get_space(source_map)))); =head2 Scheduling