X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fuser.pod;h=3f0ac7ffa0b0eac6449228ec5092d0b6403db9cc;hb=91dceca677c550ef4d9016a13b20a4a2a53d1405;hp=95adf2bffad633498bba490c414ad58018ae570c;hpb=e3bcdd8be8b68f18d82ed14cfd07747d672f4c61;p=platform%2Fupstream%2Fisl.git diff --git a/doc/user.pod b/doc/user.pod index 95adf2b..3f0ac7f 100644 --- a/doc/user.pod +++ b/doc/user.pod @@ -473,6 +473,8 @@ specification of the original object. #include __isl_give isl_dim *isl_qpolynomial_get_dim( __isl_keep isl_qpolynomial *qp); + __isl_give isl_dim *isl_qpolynomial_fold_get_dim( + __isl_keep isl_qpolynomial_fold *fold); __isl_give isl_dim *isl_pw_qpolynomial_get_dim( __isl_keep isl_pw_qpolynomial *pwqp); __isl_give isl_dim *isl_union_pw_qpolynomial_get_dim( @@ -480,6 +482,14 @@ specification of the original object. __isl_give isl_dim *isl_union_pw_qpolynomial_fold_get_dim( __isl_keep isl_union_pw_qpolynomial_fold *upwf); + #include + __isl_give isl_dim *isl_aff_get_dim( + __isl_keep isl_aff *aff); + + #include + __isl_give isl_dim *isl_point_get_dim( + __isl_keep isl_point *pnt); + The names of the individual dimensions may be set or read off using the following functions. @@ -546,6 +556,8 @@ specifications using the following functions. __isl_give isl_dim *isl_dim_reverse(__isl_take isl_dim *dim); __isl_give isl_dim *isl_dim_join(__isl_take isl_dim *left, __isl_take isl_dim *right); + __isl_give isl_dim *isl_dim_align_params( + __isl_take isl_dim *dim1, __isl_take isl_dim *dim2) __isl_give isl_dim *isl_dim_insert(__isl_take isl_dim *dim, enum isl_dim_type type, unsigned pos, unsigned n); __isl_give isl_dim *isl_dim_add(__isl_take isl_dim *dim, @@ -559,6 +571,54 @@ specifications using the following functions. Note that if dimensions are added or removed from a space, then the name and the internal structure are lost. +=head2 Local Spaces + +A local space is essentially a dimension specification with +zero or more existentially quantified variables. +The local space of a basic set or relation can be obtained +using the following functions. + + #include + __isl_give isl_local_space *isl_basic_set_get_local_space( + __isl_keep isl_basic_set *bset); + + #include + __isl_give isl_local_space *isl_basic_map_get_local_space( + __isl_keep isl_basic_map *bmap); + +A new local space can be created from a dimension specification using + + #include + __isl_give isl_local_space *isl_local_space_from_dim( + __isl_take isl_dim *dim); + +They can be inspected, copied and freed using the following functions. + + #include + isl_ctx *isl_local_space_get_ctx( + __isl_keep isl_local_space *ls); + int isl_local_space_dim(__isl_keep isl_local_space *ls, + enum isl_dim_type type); + const char *isl_local_space_get_dim_name( + __isl_keep isl_local_space *ls, + enum isl_dim_type type, unsigned pos); + __isl_give isl_dim *isl_local_space_get_dim( + __isl_keep isl_local_space *ls); + __isl_give isl_div *isl_local_space_get_div( + __isl_keep isl_local_space *ls, int pos); + __isl_give isl_local_space *isl_local_space_copy( + __isl_keep isl_local_space *ls); + void *isl_local_space_free(__isl_take isl_local_space *ls); + +Local spaces can be created from other local spaces +using the following functions. + + __isl_give isl_local_space *isl_local_space_from_domain( + __isl_take isl_local_space *ls); + __isl_give isl_local_space *isl_local_space_add_dim( + __isl_take isl_local_space *ls, + enum isl_dim_type type, unsigned n); + =head2 Input and Output C supports its own input/output format, which is similar @@ -679,6 +739,8 @@ The behavior of the printer can be modified in various ways __isl_take isl_printer *p, int output_format); __isl_give isl_printer *isl_printer_set_indent( __isl_take isl_printer *p, int indent); + __isl_give isl_printer *isl_printer_indent( + __isl_take isl_printer *p, int indent); __isl_give isl_printer *isl_printer_set_prefix( __isl_take isl_printer *p, const char *prefix); __isl_give isl_printer *isl_printer_set_suffix( @@ -687,12 +749,15 @@ The behavior of the printer can be modified in various ways The C may be either C, C, C, C or C and defaults to C. -Each line in the output is indented by C spaces +Each line in the output is indented by C (set by +C) spaces (default: 0), prefixed by C and suffixed by C. In the C format output, the coefficients of the existentially quantified variables appear between those of the set variables and those of the parameters. +The function C increases the indentation +by the specified amount (which may be negative). To actually print something, use @@ -865,7 +930,7 @@ from a universe set or relation, adding equality and/or inequality constraints and then projecting out the existentially quantified variables, if any. Constraints can be constructed, manipulated and -added to basic sets and relations using the following functions. +added to (basic) sets and relations using the following functions. #include __isl_give isl_constraint *isl_equality_alloc( @@ -883,6 +948,12 @@ added to basic sets and relations using the following functions. __isl_give isl_basic_set *isl_basic_set_add_constraint( __isl_take isl_basic_set *bset, __isl_take isl_constraint *constraint); + __isl_give isl_map *isl_map_add_constraint( + __isl_take isl_map *map, + __isl_take isl_constraint *constraint); + __isl_give isl_set *isl_set_add_constraint( + __isl_take isl_set *set, + __isl_take isl_constraint *constraint); For example, to create a set containing the even integers between 10 and 42, you would use the following code. @@ -950,6 +1021,19 @@ C and C for sets and of C, C, C, C and C for relations. +A basic relation can also be constructed from an affine expression +or a list of affine expressions (See L<"Quasi Affine Expressions">). + + __isl_give isl_basic_map *isl_basic_map_from_aff( + __isl_take isl_aff *aff); + __isl_give isl_basic_map *isl_basic_map_from_aff_list( + __isl_take isl_dim *domain_dim, + __isl_take isl_aff_list *list); + +The C argument describes the domain of the resulting +basic relation. It is required because the C may consist +of zero affine expressions. + =head2 Inspecting Sets and Relations Usually, the user should not have to care about the actual constraints @@ -1077,6 +1161,9 @@ the following functions. void isl_constraint_get_coefficient( __isl_keep isl_constraint *constraint, enum isl_dim_type type, int pos, isl_int *v); + int isl_constraint_involves_dims( + __isl_keep isl_constraint *constraint, + enum isl_dim_type type, unsigned first, unsigned n); The explicit representations of the existentially quantified variables can be inspected using the following functions. @@ -1358,6 +1445,29 @@ that maps (a wrapped version of) the input relation to its domain or range. Eliminate the coefficients for the given dimensions from the constraints, without removing the dimensions. +=item * Slicing + + __isl_give isl_basic_set *isl_basic_set_fix( + __isl_take isl_basic_set *bset, + enum isl_dim_type type, unsigned pos, + isl_int value); + __isl_give isl_basic_set *isl_basic_set_fix_si( + __isl_take isl_basic_set *bset, + enum isl_dim_type type, unsigned pos, int value); + __isl_give isl_set *isl_set_fix(__isl_take isl_set *set, + enum isl_dim_type type, unsigned pos, + isl_int value); + __isl_give isl_set *isl_set_fix_si(__isl_take isl_set *set, + enum isl_dim_type type, unsigned pos, int value); + __isl_give isl_basic_map *isl_basic_map_fix_si( + __isl_take isl_basic_map *bmap, + enum isl_dim_type type, unsigned pos, int value); + __isl_give isl_map *isl_map_fix_si(__isl_take isl_map *map, + enum isl_dim_type type, unsigned pos, int value); + +Intersect the set or relation with the hyperplane where the given +dimension has the fixed given value. + =item * Identity __isl_give isl_map *isl_set_identity( @@ -1491,6 +1601,20 @@ that contains the whole input set or relation. In case of union sets and relations, the polyhedral hull is computed per space. +=item * Optimization + + #include + enum isl_lp_result isl_basic_set_max( + __isl_keep isl_basic_set *bset, + __isl_keep isl_aff *obj, isl_int *opt) + enum isl_lp_result isl_set_max(__isl_keep isl_set *set, + __isl_keep isl_aff *obj, isl_int *opt); + +Compute the maximum of the integer affine expression C +over the points in C, returning the result in C. +The return value may be one of C, +C, C or C. + =item * Dual The following functions compute either the set of (rational) coefficient @@ -1585,6 +1709,10 @@ then the name of the space is also removed. __isl_take isl_basic_set *bset); __isl_give isl_set *isl_set_flatten( __isl_take isl_set *set); + __isl_give isl_basic_map *isl_basic_map_flatten_range( + __isl_take isl_basic_map *bmap); + __isl_give isl_map *isl_map_flatten_range( + __isl_take isl_map *map); __isl_give isl_basic_map *isl_basic_map_flatten( __isl_take isl_basic_map *bmap); __isl_give isl_map *isl_map_flatten( @@ -1806,6 +1934,15 @@ instead. __isl_give isl_set *isl_set_flat_product( __isl_take isl_set *set1, __isl_take isl_set *set2); + __isl_give isl_basic_map *isl_basic_map_flat_range_product( + __isl_take isl_basic_map *bmap1, + __isl_take isl_basic_map *bmap2); + __isl_give isl_map *isl_map_flat_range_product( + __isl_take isl_map *map1, + __isl_take isl_map *map2); + __isl_give isl_union_map *isl_union_map_flat_range_product( + __isl_take isl_union_map *umap1, + __isl_take isl_union_map *umap2); __isl_give isl_basic_map *isl_basic_map_flat_product( __isl_take isl_basic_map *bmap1, __isl_take isl_basic_map *bmap2); @@ -1935,6 +2072,44 @@ In case of union relations, the optimum is computed per space. __isl_give isl_union_map *isl_union_map_lexmax( __isl_take isl_union_map *umap); +=head2 Lists + +Lists are defined over several element types, including +C, C and C. +Here we take lists of Cs as an example. +Lists can be created, copied and freed using the following functions. + + #include + __isl_give isl_set_list *isl_set_list_alloc( + isl_ctx *ctx, int n); + __isl_give isl_set_list *isl_set_list_copy( + __isl_keep isl_set_list *list); + __isl_give isl_set_list *isl_set_list_add( + __isl_take isl_set_list *list, + __isl_take isl_set *el); + void isl_set_list_free(__isl_take isl_set_list *list); + +C creates an empty list with a capacity for +C elements. + +Lists can be inspected using the following functions. + + #include + isl_ctx *isl_set_list_get_ctx(__isl_keep isl_set_list *list); + int isl_set_list_n_set(__isl_keep isl_set_list *list); + __isl_give struct isl_set *isl_set_list_get_set( + __isl_keep isl_set_list *list, int index); + int isl_set_list_foreach(__isl_keep isl_set_list *list, + int (*fn)(__isl_take struct isl_set *el, void *user), + void *user); + +Lists can be printed using + + #include + __isl_give isl_printer *isl_printer_print_set_list( + __isl_take isl_printer *p, + __isl_keep isl_set_list *list); + =head2 Matrices Matrices can be created, copied and freed using the following functions. @@ -1974,6 +2149,103 @@ the original and the kernel (in that order) is the zero matrix. __isl_give isl_mat *isl_mat_right_kernel(__isl_take isl_mat *mat); +=head2 Quasi Affine Expressions + +The zero quasi affine expression can be created using + + __isl_give isl_aff *isl_aff_zero( + __isl_take isl_local_space *ls); + +Quasi affine expressions can be copied and free using + + #include + __isl_give isl_aff *isl_aff_copy(__isl_keep isl_aff *aff); + void *isl_aff_free(__isl_take isl_aff *aff); + +A (rational) bound on a dimension can be extracted from an C +using the following function. The constraint is required to have +a non-zero coefficient for the specified dimension. + + #include + __isl_give isl_aff *isl_constraint_get_bound( + __isl_keep isl_constraint *constraint, + enum isl_dim_type type, int pos); + +Conversely, an equality constraint equating +the affine expression to zero or an inequality constraint enforcing +the affine expression to be non-negative, can be constructed using + + __isl_give isl_constraint *isl_equality_from_aff( + __isl_take isl_aff *aff); + __isl_give isl_constraint *isl_inequality_from_aff( + __isl_take isl_aff *aff); + +The expression can be inspected using + + #include + isl_ctx *isl_aff_get_ctx(__isl_keep isl_aff *aff); + int isl_aff_dim(__isl_keep isl_aff *aff, + enum isl_dim_type type); + __isl_give isl_local_space *isl_aff_get_local_space( + __isl_keep isl_aff *aff); + const char *isl_aff_get_dim_name(__isl_keep isl_aff *aff, + enum isl_dim_type type, unsigned pos); + int isl_aff_get_constant(__isl_keep isl_aff *aff, + isl_int *v); + int isl_aff_get_coefficient(__isl_keep isl_aff *aff, + enum isl_dim_type type, int pos, isl_int *v); + int isl_aff_get_denominator(__isl_keep isl_aff *aff, + isl_int *v); + __isl_give isl_div *isl_aff_get_div( + __isl_keep isl_aff *aff, int pos); + +It can be modified using + + #include + __isl_give isl_aff *isl_aff_set_constant( + __isl_take isl_aff *aff, isl_int v); + __isl_give isl_aff *isl_aff_set_constant_si( + __isl_take isl_aff *aff, int v); + __isl_give isl_aff *isl_aff_set_coefficient( + __isl_take isl_aff *aff, + enum isl_dim_type type, int pos, isl_int v); + __isl_give isl_aff *isl_aff_set_coefficient_si( + __isl_take isl_aff *aff, + enum isl_dim_type type, int pos, int v); + __isl_give isl_aff *isl_aff_set_denominator( + __isl_take isl_aff *aff, isl_int v); + + __isl_give isl_aff *isl_aff_add_constant( + __isl_take isl_aff *aff, isl_int v); + __isl_give isl_aff *isl_aff_add_coefficient_si( + __isl_take isl_aff *aff, + enum isl_dim_type type, int pos, int v); + +Note that the C and C functions +set the I of the constant or coefficient, while +C and C add an integer value to +the possibly rational constant or coefficient. + +Operations include + + #include + __isl_give isl_aff *isl_aff_add(__isl_take isl_aff *aff1, + __isl_take isl_aff *aff2); + __isl_give isl_aff *isl_aff_sub(__isl_take isl_aff *aff1, + __isl_take isl_aff *aff2); + __isl_give isl_aff *isl_aff_neg(__isl_take isl_aff *aff); + __isl_give isl_aff *isl_aff_ceil(__isl_take isl_aff *aff); + __isl_give isl_aff *isl_aff_scale(__isl_take isl_aff *aff, + isl_int f); + __isl_give isl_aff *isl_aff_scale_down(__isl_take isl_aff *aff, + isl_int f); + +An expression can be printed using + + #include + __isl_give isl_printer *isl_printer_print_aff( + __isl_take isl_printer *p, __isl_keep isl_aff *aff); + =head2 Points Points are elements of a set. They can be used to construct @@ -1999,6 +2271,10 @@ using __isl_take isl_point *pnt, enum isl_dim_type type, int pos, unsigned val); +Other properties can be obtained using + + isl_ctx *isl_point_get_ctx(__isl_keep isl_point *pnt); + Points can be copied or freed using __isl_give isl_point *isl_point_copy( @@ -2139,6 +2415,8 @@ on the resulting quasipolynomials __isl_give isl_qpolynomial *isl_qpolynomial_var( __isl_take isl_dim *dim, enum isl_dim_type type, unsigned pos); + __isl_give isl_qpolynomial *isl_qpolynomial_from_aff( + __isl_take isl_aff *aff); The zero piecewise quasipolynomial or a piecewise quasipolynomial with a single cell can be created using the following functions. @@ -2701,7 +2979,74 @@ from an C using the following function. __isl_give isl_union_map *isl_schedule_get_map( __isl_keep isl_schedule *sched); -This mapping can also be obtained in pieces using the following functions. +A representation of the schedule can be printed using + + __isl_give isl_printer *isl_printer_print_schedule( + __isl_take isl_printer *p, + __isl_keep isl_schedule *schedule); + +A representation of the schedule as a forest of bands can be obtained +using the following function. + + __isl_give isl_band_list *isl_schedule_get_band_forest( + __isl_keep isl_schedule *schedule); + +The list can be manipulated as explained in L<"Lists">. +The bands inside the list can be copied and freed using the following +functions. + + #include + __isl_give isl_band *isl_band_copy( + __isl_keep isl_band *band); + void *isl_band_free(__isl_take isl_band *band); + +Each band contains zero or more scheduling dimensions. +These are referred to as the members of the band. +The section of the schedule that corresponds to the band is +referred to as the partial schedule of the band. +For those nodes that participate in a band, the outer scheduling +dimensions form the prefix schedule, while the inner scheduling +dimensions form the suffix schedule. +That is, if we take a cut of the band forest, then the union of +the concatenations of the prefix, partial and suffix schedules of +each band in the cut is equal to the entire schedule (modulo +some possible padding at the end with zero scheduling dimensions). +The properties of a band can be inspected using the following functions. + + #include + isl_ctx *isl_band_get_ctx(__isl_keep isl_band *band); + + int isl_band_has_children(__isl_keep isl_band *band); + __isl_give isl_band_list *isl_band_get_children( + __isl_keep isl_band *band); + + __isl_give isl_union_map *isl_band_get_prefix_schedule( + __isl_keep isl_band *band); + __isl_give isl_union_map *isl_band_get_partial_schedule( + __isl_keep isl_band *band); + __isl_give isl_union_map *isl_band_get_suffix_schedule( + __isl_keep isl_band *band); + + int isl_band_n_member(__isl_keep isl_band *band); + int isl_band_member_is_zero_distance( + __isl_keep isl_band *band, int pos); + +Note that a scheduling dimension is considered to be ``zero +distance'' if it does not carry any proximity dependences +within its band. +That is, if the dependence distances of the proximity +dependences are all zero in that direction (for fixed +iterations of outer bands). + +A representation of the band can be printed using + + #include + __isl_give isl_printer *isl_printer_print_band( + __isl_take isl_printer *p, + __isl_keep isl_band *band); + +Alternatively, the schedule mapping +can also be obtained in pieces using the following functions. int isl_schedule_n_band(__isl_keep isl_schedule *sched); __isl_give isl_union_map *isl_schedule_get_band(